diff --git a/build.go b/build.go index 135a9a8c3..f0244cae8 100644 --- a/build.go +++ b/build.go @@ -111,6 +111,7 @@ var targets = map[string]target{ {src: "cmd/stdiscosrv/README.md", dst: "deb/usr/share/doc/stdiscosrv/README.txt", perm: 0644}, {src: "cmd/stdiscosrv/LICENSE", dst: "deb/usr/share/doc/stdiscosrv/LICENSE.txt", perm: 0644}, {src: "AUTHORS", dst: "deb/usr/share/doc/stdiscosrv/AUTHORS.txt", perm: 0644}, + {src: "man/stdiscosrv.1", dst: "deb/usr/share/man/man1/stdiscosrv.1", perm: 0644}, }, tags: []string{"purego"}, }, @@ -129,6 +130,7 @@ var targets = map[string]target{ {src: "cmd/strelaysrv/README.md", dst: "deb/usr/share/doc/strelaysrv/README.txt", perm: 0644}, {src: "cmd/strelaysrv/LICENSE", dst: "deb/usr/share/doc/strelaysrv/LICENSE.txt", perm: 0644}, {src: "AUTHORS", dst: "deb/usr/share/doc/strelaysrv/AUTHORS.txt", perm: 0644}, + {src: "man/strelaysrv.1", dst: "deb/usr/share/man/man1/strelaysrv.1", perm: 0644}, }, }, "strelaypoolsrv": { diff --git a/man/refresh.sh b/man/refresh.sh index 40cb34bdf..c7598423b 100755 --- a/man/refresh.sh +++ b/man/refresh.sh @@ -3,6 +3,8 @@ base=http://docs.syncthing.net/man/ pages=( syncthing.1 + stdiscosrv.1 + strelaysrv.1 syncthing-config.5 syncthing-stignore.5 syncthing-device-ids.7 diff --git a/man/stdiscosrv.1 b/man/stdiscosrv.1 new file mode 100644 index 000000000..d996acb3a --- /dev/null +++ b/man/stdiscosrv.1 @@ -0,0 +1,308 @@ +.\" Man page generated from reStructuredText. +. +.TH "STDISCOSRV" "1" "July 24, 2016" "v0.14" "Syncthing" +.SH NAME +stdiscosrv \- Syncthing Discovery Server +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +stdiscosrv [\-cert=] [\-db\-backend=] [\-db\-dsn=] [\-debug] [\-http] [\-key=] + [\-limit\-avg=] [\-limit\-burst=] [\-limit\-cache=] [\-listen=
] + [\-stats\-file=] +.ft P +.fi +.UNINDENT +.UNINDENT +.SH DESCRIPTION +.sp +Syncthing relies on a discovery server to find peers on the internet. Anyone +can run a discovery server and point its syncthing installations to it. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-cert= +Certificate file (default "cert.pem"). +.UNINDENT +.INDENT 0.0 +.TP +.B \-db\-backend= +Database backend to use (default "ql"). +.UNINDENT +.INDENT 0.0 +.TP +.B \-db\-dsn= +Database DSN (default "memory://stdiscosrv"). +.UNINDENT +.INDENT 0.0 +.TP +.B \-debug +Enable debug output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-http +Listen on HTTP (behind an HTTPS proxy). +.UNINDENT +.INDENT 0.0 +.TP +.B \-key= +Key file (default "key.pem"). +.UNINDENT +.INDENT 0.0 +.TP +.B \-limit\-avg= +Allowed average package rate, per 10 s (default 5). +.UNINDENT +.INDENT 0.0 +.TP +.B \-limit\-burst= +Allowed burst size, packets (default 20). +.UNINDENT +.INDENT 0.0 +.TP +.B \-limit\-cache= +Limiter cache entries (default 10240). +.UNINDENT +.INDENT 0.0 +.TP +.B \-listen=
+Listen address (default ":8443"). +.UNINDENT +.INDENT 0.0 +.TP +.B \-stats\-file= +File to write periodic operation stats to. +.UNINDENT +.SH POINTING SYNCTHING AT YOUR DISCOVERY SERVER +.sp +By default, Syncthing uses a number of global discovery servers, signified by +the entry \fBdefault\fP in the list of discovery servers. To make Syncthing use +your own instance of stdiscosrv, open up Syncthing\(aqs web GUI. Go to settings, +Global Discovery Server and add stdiscosrv\(aqs host address to the comma\-separated +list, e.g. \fBhttps://disco.example.com:8443/v2/\fP\&. Note that stdiscosrv uses port +8443 by default. For stdiscosrv to be available over the internet with a dynamic +IP address, you will need a dynamic DNS service. +.sp +If you wish to use \fIonly\fP your own discovery server, remove the \fBdefault\fP +entry from the list. +.SH SETTING UP +.SS Description +.sp +This guide assumes that you have already set up Syncthing. If you +haven\(aqt yet, head over to getting\-started first. +.SS Installing +.sp +Go to \fI\%releases\fP <\fBhttps://github.com/syncthing/stdiscosrv/releases\fP> and +download the file appropriate for your operating system. Unpacking it will +yield a binary called \fBstdiscosrv\fP (or \fBstdiscosrv.exe\fP on Windows). Start +this in whatever way you are most comfortable with; double clicking should +work in any graphical environment. At first start, stdiscosrv will generate the +directory \fB/var/stdiscosrv\fP (\fBX:\evar\estdiscosrv\fP on Windows, where X is the +partition \fBstdiscosrv.exe\fP is executed from) with configuration. If the user +running \fBstdiscosrv\fP doesn\(aqt have permission to do so, create the directory +and set the owner appropriately or use the command line switches (see below) +to select a different location. +.SS Configuring +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If you are running an instance of syncthing on the discovery server, +you must either add that instance to other nodes using a static +address or bind the discovery server and syncthing instances to +different IP addresses. +.UNINDENT +.UNINDENT +.SS Certificates +.sp +The discovery server provides service over HTTPS. To ensure secure connections +from clients there are three options: +.INDENT 0.0 +.IP \(bu 2 +Use a CA\-signed certificate pair for the domain name you will use for the +discovery server. This is like any other HTTPS website; clients will +authenticate the server based on it\(aqs certificate and domain name. +.IP \(bu 2 +Use any certificate pair and let clients authenticate the server based on +it\(aqs "device ID" (similar to Syncthing\-to\-Syncthing authentication). In +this case, using \fBsyncthing \-generate\fP is a good option to create a +certificate pair. +.IP \(bu 2 +Pass the \fB\-http\fP flag if the discovery server is behind an SSL\-secured +reverse proxy. See below for configuration. +.UNINDENT +.sp +For the first two options, the discovery server must be given the paths to +the certificate and key at startup. This isn\(aqt necessary with the \fBhttp\fP flag: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ stdiscosrv \-cert /path/to/cert.pem \-key /path/to/key.pem +Server device ID is 7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The discovery server prints it\(aqs device ID at startup. In the case where you +are using a non CA signed certificate, this device ID (fingerprint) must be +given to the clients in the discovery server URL: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +https://disco.example.com:8443/v2/?id=7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Otherwise, the URL (note the trailing slash after the \fBv2\fP) will be: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +https://disco.example.com:8443/v2/ +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Reverse Proxy Setup +.sp +The discovery server can be run behind an SSL\-secured reverse proxy. This +allows: +.INDENT 0.0 +.IP \(bu 2 +Use of a subdomain name without requiring a port number added to the URL +.IP \(bu 2 +Sharing an SSL certificate with multiple services on the same server +.UNINDENT +.SS Requirements +.INDENT 0.0 +.IP \(bu 2 +Run the discovery server using the \-http flag \fBstdiscosrv \-http\fP\&. +.IP \(bu 2 +SSL certificate/key configured for the reverse proxy +.IP \(bu 2 +The "X\-Forwarded\-For" http header must be passed through with the client\(aqs +real IP address +.IP \(bu 2 +The "X\-SSL\-Cert" must be passed through with the PEM\-encoded client SSL +certificate +.IP \(bu 2 +The proxy must request the client SSL certificate but not require it to be +signed by a trusted CA. +.UNINDENT +.SS Nginx +.sp +These three lines in the configuration take care of the last three requirements +listed above: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +proxy_set_header X\-Forwarded\-For $proxy_add_x_forwarded_for; +proxy_set_header X\-SSL\-Cert $ssl_client_cert; +ssl_verify_client optional_no_ca; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The following is a complete example Nginx configuration file. With this setup, +clients can use \fI\%https://discovery.mydomain.com\fP as the discovery server URL in +the Syncthing settings. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# HTTP 1.1 support +proxy_http_version 1.1; +proxy_buffering off; +proxy_set_header Host $http_host; +proxy_set_header Upgrade $http_upgrade; +proxy_set_header Connection $proxy_connection; +proxy_set_header X\-Real\-IP $remote_addr; +proxy_set_header X\-Forwarded\-For $proxy_add_x_forwarded_for; +proxy_set_header X\-Forwarded\-Proto $proxy_x_forwarded_proto; +proxy_set_header X\-SSL\-Cert $ssl_client_cert; +upstream discovery.mydomain.com { + # Local IP address:port for discovery server + server 172.17.0.6:8443; +} +server { + server_name discovery.mydomain.com; + listen 80; + access_log /var/log/nginx/access.log vhost; + return 301 https://$host$request_uri; +} +server { + server_name discovery.mydomain.com; + listen 443 ssl http2; + access_log /var/log/nginx/access.log vhost; + ssl_protocols TLSv1 TLSv1.1 TLSv1.2; + ssl_ciphers ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-AES256\-GCM\-SHA384: DHE\-RSA\-AES128\-GCM\-SHA256:DHE\-DSS\-AES128\-GCM\-SHA256:kEDH+AESGCM:ECDHE\-RSA\-AES128\-SHA256:ECDHE\-ECDSA\-AES128\-SHA256:ECDHE\-RSA\-AES128\-SHA:E CDHE\-ECDSA\-AES128\-SHA:ECDHE\-RSA\-AES256\-SHA384:ECDHE\-ECDSA\-AES256\-SHA384:ECDHE\-RSA\-AES256\-SHA:ECDHE\-ECDSA\-AES256\-SHA:DHE\-RSA\-AES128\-SHA25 6:DHE\-RSA\-AES128\-SHA:DHE\-DSS\-AES128\-SHA256:DHE\-RSA\-AES256\-SHA256:DHE\-DSS\-AES256\-SHA:DHE\-RSA\-AES256\-SHA:AES128\-GCM\-SHA256:AES256\-GCM\-SHA3 84:AES128\-SHA256:AES256\-SHA256:AES128\-SHA:AES256\-SHA:AES:CAMELLIA:DES\-CBC3\-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH\-DSS \-DES\-CBC3\-SHA:!EDH\-RSA\-DES\-CBC3\-SHA:!KRB5\-DES\-CBC3\-SHA; + ssl_prefer_server_ciphers on; + ssl_session_timeout 5m; + ssl_session_cache shared:SSL:50m; + ssl_certificate /etc/nginx/certs/discovery.mydomain.com.crt; + ssl_certificate_key /etc/nginx/certs/discovery.mydomain.com.key; + ssl_dhparam /etc/nginx/certs/discovery.mydomain.com.dhparam.pem; + add_header Strict\-Transport\-Security "max\-age=31536000"; + ssl_verify_client optional_no_ca; + location / { + proxy_pass http://discovery.mydomain.com; + } +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +An example of automating the SSL certificates and reverse\-proxying the Discovery +Server and Syncthing using Nginx, \fI\%Let\(aqs Encrypt\fP <\fBhttps://letsencrypt.org/\fP> and Docker can be found \fI\%here\fP <\fBhttps://forum.syncthing.net/t/docker-syncthing-and-syncthing-discovery-behind-nginx-reverse-proxy-with-lets-encrypt/6880\fP>\&. +.SH SEE ALSO +.sp +\fIsyncthing\-networking(7)\fP, \fIsyncthing\-faq(7)\fP +.SH AUTHOR +The Syncthing Authors +.SH COPYRIGHT +2015, The Syncthing Authors +.\" Generated by docutils manpage writer. +. diff --git a/man/strelaysrv.1 b/man/strelaysrv.1 new file mode 100644 index 000000000..fc30facf9 --- /dev/null +++ b/man/strelaysrv.1 @@ -0,0 +1,205 @@ +.\" Man page generated from reStructuredText. +. +.TH "STRELAYSRV" "1" "July 24, 2016" "v0.14" "Syncthing" +.SH NAME +strelaysrv \- Syncthing Relay Server +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +strelaysrv [\-debug] [\-ext\-address=
] [\-global\-rate=] [\-keys=] [\-listen=] + [\-message\-timeout=] [\-network\-timeout=] [\-per\-session\-rate=] + [\-ping\-interval=] [\-pools=] [\-provided\-by=] [\-status\-srv=] +.ft P +.fi +.UNINDENT +.UNINDENT +.SH DESCRIPTION +.sp +Syncthing relies on a network of community\-contributed relay servers. Anyone +can run a relay server, and it will automatically join the relay pool and be +available to Syncthing users. The current list of relays can be found at +\fI\%https://relays.syncthing.net\fP\&. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-debug +Enable debug output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-ext\-address=
+An optional address to advertising as being available on. Allows listening +on an unprivileged port with port forwarding from e.g. 443, and be +connected to on port 443. +.UNINDENT +.INDENT 0.0 +.TP +.B \-global\-rate= +Global rate limit, in bytes/s. +.UNINDENT +.INDENT 0.0 +.TP +.B \-keys= +Directory where cert.pem and key.pem is stored (default "."). +.UNINDENT +.INDENT 0.0 +.TP +.B \-listen= +Protocol listen address (default ":22067"). +.UNINDENT +.INDENT 0.0 +.TP +.B \-message\-timeout= +Maximum amount of time we wait for relevant messages to arrive (default 1m0s). +.UNINDENT +.INDENT 0.0 +.TP +.B \-network\-timeout= +Timeout for network operations between the client and the relay. If no data +is received between the client and the relay in this period of time, the +connection is terminated. Furthermore, if no data is sent between either +clients being relayed within this period of time, the session is also +terminated. (default 2m0s) +.UNINDENT +.INDENT 0.0 +.TP +.B \-per\-session\-rate= +Per session rate limit, in bytes/s. +.UNINDENT +.INDENT 0.0 +.TP +.B \-ping\-interval= +How often pings are sent (default 1m0s). +.UNINDENT +.INDENT 0.0 +.TP +.B \-pools= +Comma separated list of relay pool addresses to join (default +"\fI\%https://relays.syncthing.net/endpoint\fP"). Blank to disable announcement to +a pool, thereby remaining a private relay. +.UNINDENT +.INDENT 0.0 +.TP +.B \-provided\-by= +An optional description about who provides the relay. +.UNINDENT +.INDENT 0.0 +.TP +.B \-status\-srv= +Listen address for status service (blank to disable) (default ":22070"). +.UNINDENT +.SH SETTING UP +.sp +Primarily, you need to decide on a directory to store the TLS key and +certificate and a listen port. The default listen port of 22067 works, but for +optimal compatibility a well known port for encrypted traffic such as 443 is +recommended. This may require additional setup to work without running +as root or a privileged user, see \fI\%Running on port 443 as an unprivileged user\fP +below. In principle something similar to this should work on a Linux/Unix +system: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ sudo useradd relaysrv +$ sudo mkdir /etc/relaysrv +$ sudo chown relaysrv /etc/relaysrv +$ sudo \-u relaysrv /usr/local/bin/relaysrv \-keys /etc/relaysrv +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This creates a user \fBrelaysrv\fP and a directory \fB/etc/relaysrv\fP to store +the keys. The keys are generated on first startup. The relay will join the +global relay pool, unless a \fB\-pools=""\fP argument is given. +.sp +To make the relay server start automatically at boot, use the recommended +procedure for your operating system. +.SS Running on port 443 as an unprivileged user +.sp +It is recommended that you run the relay on port 443 (or another port which is +commonly allowed through corporate firewalls), in order to maximise the chances +that people are able to connect. However, binding to ports below 1024 requires +root privileges, and running a relay as root is not recommended. Thankfully +there are a couple of approaches available to you. +.sp +One option is to run the relay on port 22067, and use an \fBiptables\fP rule +to forward traffic from port 443 to port 22067, for example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +iptables \-t nat \-A PREROUTING \-i eth0 \-p tcp \-\-dport 443 \-j REDIRECT \-\-to\-port 22067 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Or, if you\(aqre using \fBufw\fP, add the following to \fB/etc/ufw/before.rules\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +*nat +:PREROUTING ACCEPT [0:0] +:POSTROUTING ACCEPT [0:0] + +\-A PREROUTING \-i eth0 \-p tcp \-\-dport 443 \-j REDIRECT \-\-to\-port 22067 + +COMMIT +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +You will need to start \fBrelaysrv\fP with \fB\-ext\-address ":443"\fP\&. This tells +\fBrelaysrv\fP that it can be contacted on port 443, even though it is listening +on port 22067. You will also need to let both port 443 and 22067 through your +firewall. +.sp +Another option is \fI\%described here\fP <\fBhttps://wiki.apache.org/httpd/NonRootPortBinding\fP>, +although your milage may vary. +.SH SEE ALSO +.sp +\fIsyncthing\-relay(7)\fP, \fIsyncthing\-faq(7)\fP, +\fIsyncthing\-networking(7)\fP +.SH AUTHOR +The Syncthing Authors +.SH COPYRIGHT +2015, The Syncthing Authors +.\" Generated by docutils manpage writer. +.