mirror of
https://github.com/octoleo/syncthing.git
synced 2024-12-22 10:58:57 +00:00
400 lines
13 KiB
Groff
400 lines
13 KiB
Groff
.\" Man page generated from reStructuredText.
|
||
.
|
||
.
|
||
.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
|
||
..
|
||
.TH "STDISCOSRV" "1" "Nov 30, 2024" "v1.28.0" "Syncthing"
|
||
.SH NAME
|
||
stdiscosrv \- Syncthing Discovery Server
|
||
.SH SYNOPSIS
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.EX
|
||
stdiscosrv [\-\-debug] [\-\-http] [\-\-compression] [\-\-version]
|
||
[\-\-cert=<file>] [\-\-key=<string>]
|
||
[\-\-listen=<address>] [\-\-metrics\-listen=<address>]
|
||
[\-\-db\-dir=<string>] [\-\-db\-flush\-interval=<string>]
|
||
.EE
|
||
.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 Syncthing installations to it. The
|
||
Syncthing project also maintains a global cluster for public use.
|
||
.SH OPTIONS
|
||
.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 \-\-version
|
||
Print the current version number and exit.
|
||
.UNINDENT
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \-\-compression
|
||
Enable GZIP compression of HTTP responses.
|
||
.UNINDENT
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \-\-cert=<file>
|
||
Certificate file (default “./cert.pem”). Unused in –http mode.
|
||
.UNINDENT
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \-\-key=<file>
|
||
Key file (default “./key.pem”). Unused in –http mode.
|
||
.UNINDENT
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \-\-listen=<address>
|
||
Listen address (default “:8443”).
|
||
.UNINDENT
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \-\-metrics\-listen=<address>
|
||
Prometheus compatible metrics endpoint listen address (default
|
||
disabled).
|
||
.UNINDENT
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \-\-db\-dir=<string>
|
||
Database directory, where data is stored (default “.”).
|
||
.UNINDENT
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \-\-db\-flush\-interval=<string>
|
||
Interval at which the in\-memory database is flushed to disk (default
|
||
“5m”).
|
||
.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’s web GUI. Go to settings,
|
||
Global Discovery Server and add stdiscosrv’s host address to the comma\-separated
|
||
list, e.g. \fBhttps://disco.example.com:8443/\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
|
||
Deprecated since version v0.14.44: Prior versions need \fB/v2/\fP appended to the discovery
|
||
server address, e.g. \fBhttps://disco.example.com:8443/v2/\fP\&.
|
||
|
||
.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’t yet, head over to \fI\%Getting Started\fP first.
|
||
.SS Installing
|
||
.sp
|
||
Go to \X'tty: link https://github.com/syncthing/discosrv/releases'\fI\%releases\fP <\fBhttps://github.com/syncthing/discosrv/releases\fP>\X'tty: link' 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 certificate files and database in the current directory unless
|
||
given flags to the contrary.
|
||
.sp
|
||
The discovery server can also be obtained through apt, the Debian/Ubuntu package
|
||
manager. Recent releases can be found at syncthing’s
|
||
\X'tty: link https://apt.syncthing.net/'\fI\%apt repository\fP <\fBhttps://apt.syncthing.net/\fP>\X'tty: link'\&. The name of the package is
|
||
syncthing\-discosrv.
|
||
.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 devices 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 its certificate and domain name.
|
||
.IP \(bu 2
|
||
Use any certificate pair and let clients authenticate the server based on
|
||
its “device ID” (similar to Syncthing\-to\-Syncthing authentication). This
|
||
option can be used with the certificate automatically generated by the
|
||
discovery server.
|
||
.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’t necessary with the \fBhttp\fP flag:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.EX
|
||
$ stdiscosrv \-\-cert=/path/to/cert.pem \-\-key=/path/to/key.pem
|
||
Server device ID is 7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA
|
||
.EE
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
The discovery server prints its device ID at startup. In case 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
|
||
.EX
|
||
https://disco.example.com:8443/?id=7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA
|
||
.EE
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
Otherwise, the URL will be:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.EX
|
||
https://disco.example.com:8443/
|
||
.EE
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS Reverse Proxy Setup
|
||
.sp
|
||
Added in version 1.8.0: A new “X\-Client\-Port” HTTP header was added.
|
||
|
||
.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
|
||
.sp
|
||
Note that after this configuration, if the proxy uses a valid HTTPS
|
||
certificate, \fBclients should omit the\fP \fB?id=...\fP \fBparameter from the
|
||
discovery server URL on their configuration\fP\&. Client\-side validation will be
|
||
done by checking the visible proxy server’s HTTPS certificate. If, however, the
|
||
proxy uses a self\-signed or somehow invalid certificate, clients must still set
|
||
the \fB?id=...\fP parameter with the computed hash of the proxy’s
|
||
certificate. Using such setup is discouraged and is not covered in this page.
|
||
Always favour using valid and widely recognised certificates.
|
||
.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’s
|
||
real IP address.
|
||
.IP \(bu 2
|
||
The “X\-Client\-Port” HTTP header should be passed through, containing the client’s real connection port.
|
||
.IP \(bu 2
|
||
The “X\-SSL\-Cert” HTTP header must be passed through with the PEM\-encoded
|
||
client SSL certificate. This will be present in POST requests and may be empty
|
||
in GET requests from clients. If you see syncthing\-discosrv outputting
|
||
\fBno certificates\fP when receiving POST requests, that’s because the proxy
|
||
is not passing this header through.
|
||
.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 lines in the configuration take care of the last four requirements
|
||
listed above:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.EX
|
||
proxy_set_header X\-Forwarded\-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X\-Client\-Port $remote_port;
|
||
proxy_set_header X\-SSL\-Cert $ssl_client_cert;
|
||
ssl_verify_client optional_no_ca;
|
||
.EE
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
The following is a complete example Nginx configuration file. With this setup,
|
||
clients can use \X'tty: link https://discovery.example.com'\fI\%https://discovery.example.com\fP\X'tty: link' as the discovery server URL in
|
||
the Syncthing settings.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.EX
|
||
# 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 $http_connection;
|
||
proxy_set_header X\-Real\-IP $remote_addr;
|
||
proxy_set_header X\-Client\-Port $remote_port;
|
||
proxy_set_header X\-Forwarded\-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X\-Forwarded\-Proto $http_x_forwarded_proto;
|
||
proxy_set_header X\-SSL\-Cert $ssl_client_cert;
|
||
upstream discovery.example.com {
|
||
# Local IP address:port for discovery server
|
||
server 192.0.2.1:8443;
|
||
}
|
||
server {
|
||
server_name discovery.example.com;
|
||
listen 80;
|
||
access_log /var/log/nginx/access.log vhost;
|
||
return 301 https://$host$request_uri;
|
||
}
|
||
server {
|
||
server_name discovery.example.com;
|
||
|
||
listen 443 ssl http2;
|
||
access_log /var/log/nginx/access.log vhost;
|
||
|
||
# Mozilla Intermediate configuration (https://wiki.mozilla.org/Security/Server_Side_TLS)
|
||
ssl_protocols TLSv1.2 TLSv1.3;
|
||
ssl_ciphers ECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES256\-GCM\-SHA384:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-CHACHA20\-POLY1305:ECDHE\-RSA\-CHACHA20\-POLY1305:DHE\-RSA\-AES128\-GCM\-SHA256:DHE\-RSA\-AES256\-GCM\-SHA384;
|
||
ssl_prefer_server_ciphers off;
|
||
ssl_session_tickets off;
|
||
ssl_session_timeout 5m;
|
||
ssl_session_cache shared:SSL:50m;
|
||
ssl_verify_client optional_no_ca;
|
||
|
||
# OCSP stapling
|
||
ssl_stapling on;
|
||
ssl_stapling_verify on;
|
||
|
||
# Certificates
|
||
ssl_certificate /etc/nginx/certs/discovery.example.com.crt;
|
||
ssl_certificate_key /etc/nginx/certs/discovery.example.com.key;
|
||
|
||
# curl https://ssl\-config.mozilla.org/ffdhe2048.txt > /path/to/dhparam
|
||
ssl_dhparam /path/to/dhparam;
|
||
|
||
# HSTS (ngx_http_headers_module is required) (63072000 seconds)
|
||
add_header Strict\-Transport\-Security \(dqmax\-age=63072000\(dq always;
|
||
|
||
location / {
|
||
proxy_pass http://discovery.example.com;
|
||
}
|
||
}
|
||
.EE
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
An example of automating the SSL certificates and reverse\-proxying the Discovery
|
||
Server and Syncthing using Nginx, \X'tty: link https://letsencrypt.org/'\fI\%Let’s Encrypt\fP <\fBhttps://letsencrypt.org/\fP>\X'tty: link' and Docker can be found \X'tty: link https://forum.syncthing.net/t/docker-syncthing-and-syncthing-discovery-behind-nginx-reverse-proxy-with-lets-encrypt/6880'\fI\%here\fP <\fBhttps://forum.syncthing.net/t/docker-syncthing-and-syncthing-discovery-behind-nginx-reverse-proxy-with-lets-encrypt/6880\fP>\X'tty: link'\&.
|
||
.SS Apache
|
||
.sp
|
||
The following lines must be added to the configuration:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.EX
|
||
SSLProxyEngine On
|
||
SSLVerifyClient optional_no_ca
|
||
RequestHeader set X\-SSL\-Cert \(dq%{SSL_CLIENT_CERT}s\(dq
|
||
.EE
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
The following was observed to not be required at least under
|
||
Apache httpd 2.4.38, as the proxy module adds the needed header by default.
|
||
If you need to explicitly add the following directive, make sure to issue
|
||
\fBa2enmod remoteip\fP first. Then, add the following to your Apache httpd
|
||
configuration:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.EX
|
||
RemoteIPHeader X\-Forwarded\-For
|
||
.EE
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS Caddy
|
||
.sp
|
||
The following lines must be added to the Caddyfile:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.EX
|
||
discovery.example.com {
|
||
reverse_proxy 192.0.2.1:8443 {
|
||
header_up X\-Forwarded\-For {http.request.remote.host}
|
||
header_up X\-Client\-Port {http.request.remote.port}
|
||
header_up X\-Tls\-Client\-Cert\-Der\-Base64 {http.request.tls.client.certificate_der_base64}
|
||
}
|
||
|
||
tls {
|
||
client_auth {
|
||
mode request
|
||
}
|
||
}
|
||
}
|
||
.EE
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.EX
|
||
|
||
.EE
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
For more details, see also the recommendations in the
|
||
\X'tty: link https://docs.syncthing.net/users/reverseproxy.html'\fI\%Reverse Proxy Setup\fP <\fBhttps://docs.syncthing.net/users/reverseproxy.html\fP>\X'tty: link'
|
||
page. Note that that page is directed at setting up a proxy for the
|
||
Syncthing web UI. You should do the proper path and port adjustments to proxying
|
||
the discovery server and your particular setup.
|
||
.SH SEE ALSO
|
||
.sp
|
||
\fBsyncthing\-networking(7)\fP, \fBsyncthing\-faq(7)\fP
|
||
.SH AUTHOR
|
||
The Syncthing Authors
|
||
.SH COPYRIGHT
|
||
2014-2019, The Syncthing Authors
|
||
.\" Generated by docutils manpage writer.
|
||
.
|