mirror of
https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake.git
synced 2025-10-13 20:11:19 -04:00
docs: improve proxy CLI param descriptions
Since the proxy component is the most dedicated for public use, more comprehensive docs are good.
This commit is contained in:
WofWca
Shelikhoo
parent
15b3f64a3a
commit
9b04728809
4 changed files with 54 additions and 44 deletions
|
|
@ -27,49 +27,58 @@ go build
|
|||
### Running a standalone Snowflake proxy
|
||||
|
||||
The Snowflake proxy can be run with the following options:
|
||||
|
||||
<!-- These are generated with `go run . --help` -->
|
||||
|
||||
```
|
||||
Usage of ./proxy:
|
||||
-allow-non-tls-relay
|
||||
allow relay without tls encryption
|
||||
allow this proxy to pass client's data to the relay in an unencrypted form.
|
||||
This is only useful if the relay doesn't support encryption, e.g. for testing / development purposes.
|
||||
-allow-proxying-to-private-addresses
|
||||
allow forwarding client connections to private IP addresses.
|
||||
Useful when a Snowflake server (relay) is hosted on the same private network as this proxy.
|
||||
-allowed-relay-hostname-pattern string
|
||||
a pattern to specify allowed hostname pattern for relay URL. (default "snowflake.torproject.net$")
|
||||
-broker string
|
||||
broker URL (default "https://snowflake-broker.torproject.net/")
|
||||
-poll-interval duration
|
||||
how often to ask the broker for a new client. Keep in mind that asking for a client will not always result in getting one. Minumum value is 2s. Valid time units are "ms", "s", "m", "h". (default 5s)
|
||||
this proxy will only be allowed to forward client connections to relays (servers) whose URL matches this pattern.
|
||||
Note that a pattern "example.com$" will match "subdomain.example.com" as well as "other-domain-example.com".
|
||||
In order to only match "example.com", prefix the pattern with "^": "^example.com$" (default "snowflake.torproject.net$")
|
||||
-broker URL
|
||||
The URL of the broker server that the proxy will be using to find clients (default "https://snowflake-broker.torproject.net/")
|
||||
-capacity uint
|
||||
maximum concurrent clients (default is to accept an unlimited number of clients)
|
||||
-disableStatsLogger
|
||||
-disable-stats-logger
|
||||
disable the exposing mechanism for stats using logs
|
||||
-ephemeral-ports-range string
|
||||
ICE UDP ephemeral ports range (format:"<min>:<max>")
|
||||
-enableMetrics
|
||||
enable the exposing mechanism for stats using metrics at "/internal/metrics"
|
||||
-ephemeral-ports-range range
|
||||
Set the range of ports used for client connections (format:"<min>:<max>").
|
||||
If omitted, the ports will be chosen automatically.
|
||||
-keep-local-addresses
|
||||
keep local LAN address ICE candidates
|
||||
-log string
|
||||
log filename
|
||||
-metricsAddress string
|
||||
set listening address for metrics service by either hostname or ip-address (default localhost)
|
||||
-metricsPort
|
||||
keep local LAN address ICE candidates.
|
||||
This is usually pointless because Snowflake clients don't usually reside on the same local network as the proxy.
|
||||
-log filename
|
||||
log filename. If not specified, logs will be output to stderr (console).
|
||||
-metrics
|
||||
enable the exposing mechanism for stats using metrics
|
||||
-metrics-address address
|
||||
set listen address for metrics service (default "localhost")
|
||||
-metrics-port int
|
||||
set port for the metrics service (default 9999)
|
||||
-nat-probe-server URL
|
||||
The URL of the server that this proxy will use to check its network NAT type.
|
||||
Determining NAT type helps to understand whether this proxy is compatible with certain clients' NAT (default "https://snowflake-broker.torproject.net:8443/probe")
|
||||
-nat-retest-interval duration
|
||||
the time interval in second before NAT type is retested, 0s disables retest. Valid time units are "s", "m", "h". (default 24h0m0s)
|
||||
-relay string
|
||||
websocket relay URL (default "wss://snowflake.torproject.net/")
|
||||
-outbound-address string
|
||||
bind a specific outbound address. Replace all host candidates with this address without validation.
|
||||
-probeURL string
|
||||
NAT check probe server URL (default "https://snowflake-broker.torproject.net:8443/probe")
|
||||
-stun string
|
||||
stun URL (default "stun:stun.l.google.com:19302")
|
||||
the time interval between NAT type is retests (see "nat-probe-server"). 0s disables retest. Valid time units are "s", "m", "h". (default 24h0m0s)
|
||||
-outbound-address address
|
||||
prefer the given address as outbound address for client connections
|
||||
-poll-interval duration
|
||||
how often to ask the broker for a new client. Keep in mind that asking for a client will not always result in getting one. Minumum value is 2s. Valid time units are "ms", "s", "m", "h". (default 5s)
|
||||
-relay URL
|
||||
The default URL of the server (relay) that this proxy will forward client connections to, in case the broker itself did not specify the said URL (default "wss://snowflake.torproject.net/")
|
||||
-stun URL
|
||||
STUN server `URL` that this proxy will use will use to, among some other things, determine its public IP address (default "stun:stun.l.google.com:19302")
|
||||
-summary-interval duration
|
||||
the time interval to output summary, 0s disables summaries. Valid time units are "s", "m", "h". (default 1h0m0s)
|
||||
the time interval between summary log outputs, 0s disables summaries. Valid time units are "s", "m", "h". (default 1h0m0s)
|
||||
-unsafe-logging
|
||||
prevent logs from being scrubbed
|
||||
keep IP addresses and other sensitive info in the logs
|
||||
-verbose
|
||||
increase log verbosity
|
||||
-version
|
||||
|
|
|
|||
|
|
@ -116,6 +116,7 @@ var (
|
|||
|
||||
// SnowflakeProxy is used to configure an embedded
|
||||
// Snowflake in another Go application.
|
||||
// For some more info also see CLI parameter descriptions in README.
|
||||
type SnowflakeProxy struct {
|
||||
// How often to ask the broker for a new client
|
||||
PollInterval time.Duration
|
||||
|
|
|
|||
|
|
@ -23,27 +23,27 @@ func main() {
|
|||
pollInterval := flag.Duration("poll-interval", sf.DefaultPollInterval,
|
||||
fmt.Sprint("how often to ask the broker for a new client. Keep in mind that asking for a client will not always result in getting one. Minumum value is ", minPollInterval, ". Valid time units are \"ms\", \"s\", \"m\", \"h\"."))
|
||||
capacity := flag.Uint("capacity", 0, "maximum concurrent clients (default is to accept an unlimited number of clients)")
|
||||
stunURL := flag.String("stun", sf.DefaultSTUNURL, "STUN URL")
|
||||
logFilename := flag.String("log", "", "log filename")
|
||||
rawBrokerURL := flag.String("broker", sf.DefaultBrokerURL, "broker URL")
|
||||
unsafeLogging := flag.Bool("unsafe-logging", false, "prevent logs from being scrubbed")
|
||||
keepLocalAddresses := flag.Bool("keep-local-addresses", false, "keep local LAN address ICE candidates")
|
||||
defaultRelayURL := flag.String("relay", sf.DefaultRelayURL, "websocket relay URL")
|
||||
probeURL := flag.String("nat-probe-server", sf.DefaultNATProbeURL, "NAT check probe server URL")
|
||||
outboundAddress := flag.String("outbound-address", "", "prefer the given address as outbound address")
|
||||
allowedRelayHostNamePattern := flag.String("allowed-relay-hostname-pattern", "snowflake.torproject.net$", "a pattern to specify allowed hostname pattern for relay URL.")
|
||||
stunURL := flag.String("stun", sf.DefaultSTUNURL, "STUN server `URL` that this proxy will use will use to, among some other things, determine its public IP address")
|
||||
logFilename := flag.String("log", "", "log `filename`. If not specified, logs will be output to stderr (console).")
|
||||
rawBrokerURL := flag.String("broker", sf.DefaultBrokerURL, "The `URL` of the broker server that the proxy will be using to find clients")
|
||||
unsafeLogging := flag.Bool("unsafe-logging", false, "keep IP addresses and other sensitive info in the logs")
|
||||
keepLocalAddresses := flag.Bool("keep-local-addresses", false, "keep local LAN address ICE candidates.\nThis is usually pointless because Snowflake clients don't usually reside on the same local network as the proxy.")
|
||||
defaultRelayURL := flag.String("relay", sf.DefaultRelayURL, "The default `URL` of the server (relay) that this proxy will forward client connections to, in case the broker itself did not specify the said URL")
|
||||
probeURL := flag.String("nat-probe-server", sf.DefaultNATProbeURL, "The `URL` of the server that this proxy will use to check its network NAT type.\nDetermining NAT type helps to understand whether this proxy is compatible with certain clients' NAT")
|
||||
outboundAddress := flag.String("outbound-address", "", "prefer the given `address` as outbound address for client connections")
|
||||
allowedRelayHostNamePattern := flag.String("allowed-relay-hostname-pattern", "snowflake.torproject.net$", "this proxy will only be allowed to forward client connections to relays (servers) whose URL matches this pattern.\nNote that a pattern \"example.com$\" will match \"subdomain.example.com\" as well as \"other-domain-example.com\".\nIn order to only match \"example.com\", prefix the pattern with \"^\": \"^example.com$\"")
|
||||
allowProxyingToPrivateAddresses := flag.Bool("allow-proxying-to-private-addresses", false, "allow forwarding client connections to private IP addresses.\nUseful when a Snowflake server (relay) is hosted on the same private network as this proxy.")
|
||||
allowNonTLSRelay := flag.Bool("allow-non-tls-relay", false, "allow relay without tls encryption")
|
||||
allowNonTLSRelay := flag.Bool("allow-non-tls-relay", false, "allow this proxy to pass client's data to the relay in an unencrypted form.\nThis is only useful if the relay doesn't support encryption, e.g. for testing / development purposes.")
|
||||
NATTypeMeasurementInterval := flag.Duration("nat-retest-interval", time.Hour*24,
|
||||
"the time interval in second before NAT type is retested, 0s disables retest. Valid time units are \"s\", \"m\", \"h\". ")
|
||||
"the time interval between NAT type is retests (see \"nat-probe-server\"). 0s disables retest. Valid time units are \"s\", \"m\", \"h\".")
|
||||
summaryInterval := flag.Duration("summary-interval", time.Hour,
|
||||
"the time interval to output summary, 0s disables summaries. Valid time units are \"s\", \"m\", \"h\". ")
|
||||
"the time interval between summary log outputs, 0s disables summaries. Valid time units are \"s\", \"m\", \"h\".")
|
||||
disableStatsLogger := flag.Bool("disable-stats-logger", false, "disable the exposing mechanism for stats using logs")
|
||||
enableMetrics := flag.Bool("metrics", false, "enable the exposing mechanism for stats using metrics")
|
||||
metricsAddress := flag.String("metrics-address", "localhost", "set listen address for metrics service")
|
||||
metricsAddress := flag.String("metrics-address", "localhost", "set listen `address` for metrics service")
|
||||
metricsPort := flag.Int("metrics-port", 9999, "set port for the metrics service")
|
||||
verboseLogging := flag.Bool("verbose", false, "increase log verbosity")
|
||||
ephemeralPortsRangeFlag := flag.String("ephemeral-ports-range", "", "ICE UDP ephemeral ports range (format:\"<min>:<max>\")")
|
||||
ephemeralPortsRangeFlag := flag.String("ephemeral-ports-range", "", "Set the `range` of ports used for client connections (format:\"<min>:<max>\").\nIf omitted, the ports will be chosen automatically.")
|
||||
versionFlag := flag.Bool("version", false, "display version info to stderr and quit")
|
||||
|
||||
var ephemeralPortsRange []uint16 = []uint16{0, 0}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue