docs: improve proxy CLI param descriptions

Since the proxy component is the most dedicated for public use,
more comprehensive docs are good.

client/snowflake.go

@@ -169,8 +169,8 @@ func main() {
 	sqsCredsStr := flag.String("sqscreds", "", "credentials to access SQS Queue")
 	logFilename := flag.String("log", "", "name of log file")
 	logToStateDir := flag.Bool("log-to-state-dir", false, "resolve the log file relative to tor's pt state dir")
-	keepLocalAddresses := flag.Bool("keep-local-addresses", false, "keep local LAN address ICE candidates")
+	keepLocalAddresses := flag.Bool("keep-local-addresses", false, "keep local LAN address ICE candidates.\nThis is usually pointless because Snowflake proxies don't usually reside on the same local network as the client.")
-	unsafeLogging := flag.Bool("unsafe-logging", false, "prevent logs from being scrubbed")
+	unsafeLogging := flag.Bool("unsafe-logging", false, "keep IP addresses and other sensitive info in the logs")
 	max := flag.Int("max", DefaultSnowflakeCapacity,
 		"capacity for number of multiplexed WebRTC peers")
 	versionFlag := flag.Bool("version", false, "display version info to stderr and quit")

proxy/README.md

@@ -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$")
+        this proxy will only be allowed to forward client connections to relays (servers) whose URL matches this pattern.
-  -broker string
+        Note that a pattern "example.com$" will match "subdomain.example.com" as well as "other-domain-example.com".
-        broker URL (default "https://snowflake-broker.torproject.net/")
+        In order to only match "example.com", prefix the pattern with "^": "^example.com$" (default "snowflake.torproject.net$")
-  -poll-interval duration
+  -broker URL
-        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)
+        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
+  -ephemeral-ports-range range
-        ICE UDP ephemeral ports range (format:"<min>:<max>")
+        Set the range of ports used for client connections (format:"<min>:<max>").
-  -enableMetrics
+        If omitted, the ports will be chosen automatically.
-        enable the exposing mechanism for stats using metrics at "/internal/metrics"
   -keep-local-addresses
-        keep local LAN address ICE candidates
+        keep local LAN address ICE candidates.
-  -log string
+        This is usually pointless because Snowflake clients don't usually reside on the same local network as the proxy.
-        log filename
+  -log filename
-  -metricsAddress string
+        log filename. If not specified, logs will be output to stderr (console).
-        set listening address for metrics service by either hostname or ip-address (default localhost)
+  -metrics
-  -metricsPort
+        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)
+        the time interval between NAT type is retests (see "nat-probe-server"). 0s disables retest. Valid time units are "s", "m", "h". (default 24h0m0s)
-  -relay string
+  -outbound-address address
-        websocket relay URL (default "wss://snowflake.torproject.net/")
+        prefer the given address as outbound address for client connections
-  -outbound-address string
+  -poll-interval duration
-        bind a specific outbound address. Replace all host candidates with this address without validation. 
+        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)
-  -probeURL string
+  -relay URL
-        NAT check probe server URL (default "https://snowflake-broker.torproject.net:8443/probe")
+        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 string
+  -stun URL
-        stun URL (default "stun:stun.l.google.com:19302")
+        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

proxy/lib/snowflake.go

@@ -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

proxy/main.go

@@ -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")
+	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")
+	logFilename := flag.String("log", "", "log `filename`. If not specified, logs will be output to stderr (console).")
-	rawBrokerURL := flag.String("broker", sf.DefaultBrokerURL, "broker URL")
+	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, "prevent logs from being scrubbed")
+	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")
+	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, "websocket relay URL")
+	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, "NAT check probe server 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")
+	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$", "a pattern to specify allowed hostname pattern for relay URL.")
+	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}