[tor-commits] [snowflake/master] README and documentation for server.

[dcf at torproject.org]

commit a936fc7e9b0c3bf81b56e8a2c6815bca949c23a1
Author: David Fifield <david at bamsoftware.com>
Date:   Sat Jan 21 14:53:09 2017 -0800

    README and documentation for server.
---
 server/README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 server/server.go | 11 +++-------
 server/torrc     |  8 +++-----
 3 files changed, 68 insertions(+), 13 deletions(-)

diff --git a/server/README.md b/server/README.md
new file mode 100644
index 0000000..d0fd91d
--- /dev/null
+++ b/server/README.md
@@ -0,0 +1,62 @@
+This is the server transport plugin for Snowflake.
+The actual transport protocol it uses is
+[WebSocket](https://tools.ietf.org/html/rfc6455).
+In Snowflake, the client connects to the proxy using WebRTC,
+and the proxy connects to the server (this program) using WebSocket.
+
+
+# Setup
+
+The server needs to be able to listen on port 443
+in order to generate its TLS certificates.
+On Linux, use the `setcap` program to enable
+the server to listen on port 443 without running as root:
+```
+setcap 'cap_net_bind_service=+ep' /usr/local/bin/snowflake-server
+```
+
+Here is a short example of configuring your torrc file
+to run the Snowflake server under Tor:
+```
+SocksPort 0
+ORPort 9001
+ExtORPort auto
+BridgeRelay 1
+
+ServerTransportListenAddr snowflake 0.0.0.0:443
+ServerTransportPlugin snowflake exec ./server --acme-hostnames snowflake.example --acme-email admin at snowflake.example --log /var/log/tor/snowflake-server.log
+```
+The domain names given to the `--acme-hostnames` option
+should resolve to the IP address of the server.
+You can give more than one, separated by commas.
+
+
+# TLS
+
+The server uses TLS WebSockets by default: wss:// not ws://.
+There is a `--disable-tls` option for testing purposes,
+but you should use TLS in production.
+
+The server automatically fetches certificates
+from [Let's Encrypt](https://en.wikipedia.org/wiki/Let's_Encrypt) as needed.
+Use the `--acme-hostnames` option to tell the server
+what hostnames it may request certificates for.
+You can optionally provide a contact email address,
+using the `--acme-email` option,
+so that Let's Encrypt can inform you of any problems.
+The server will cache TLS certificate data in the directory
+`pt_state/snowflake-certificate-cache` inside the tor state directory.
+
+In order to fetch certificates automatically,
+the server needs to listen on port 443.
+This is a requirement of the ACME protocol used by Let's Encrypt.
+If your `ServerTransportListenAddr` is not on port 443,
+the server will open an listener on port 443 in addition
+to the port you requested.
+The program will exit if it can't bind to port 443.
+On Linux, you can use the `setcap` program,
+part of libcap2, to enable the server to bind to low-numbered ports
+without having to run as root:
+```
+setcap 'cap_net_bind_service=+ep' /usr/local/bin/snowflake-server
+```
diff --git a/server/server.go b/server/server.go
index aec9b51..7229e06 100644
--- a/server/server.go
+++ b/server/server.go
@@ -1,11 +1,6 @@
-// Snowflake-specific websocket server plugin. This is the same as the websocket
-// server used by flash proxy, except that it reports the transport name as
-// "snowflake" and does not forward the remote address to the ExtORPort.
-//
-// Usage in torrc:
-// 	ExtORPort auto
-// 	ServerTransportListenAddr snowflake 0.0.0.0:9902
-// 	ServerTransportPlugin snowflake exec server
+// Snowflake-specific websocket server plugin. It reports the transport name as
+// "snowflake" and does not forward the (unknown) client address to the
+// ExtORPort.
 package main
 
 import (
diff --git a/server/torrc b/server/torrc
index ed71a39..5dc2008 100644
--- a/server/torrc
+++ b/server/torrc
@@ -1,9 +1,7 @@
-BridgeRelay 1
+SocksPort 0
 ORPort 9001
 ExtORPort auto
-SocksPort 0
-ExitPolicy reject *:*
-DataDirectory datadir
+BridgeRelay 1
 
 ServerTransportListenAddr snowflake 0.0.0.0:443
-ServerTransportPlugin snowflake exec ./server --acme-hostnames snowflake.example --acme-email admin at snowflake.example --log snowflake.log
+ServerTransportPlugin snowflake exec ./server --acme-hostnames snowflake.example --acme-email admin at snowflake.example --log /var/log/tor/snowflake-server.log