gui, man, authors: Update docs, translations, and contributors
This commit is contained in:
Jakob Borg
+432
-1
@@ -1 +1,432 @@
|
||||
404 Not Found
|
||||
.\" Man page generated from reStructuredText.
|
||||
.
|
||||
.TH "STDISCOSRV" "1" "Jun 19, 2020" "v1" "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=<file>] [\-db\-dir=<string>] [\-debug] [\-http] [\-key=<string>]
|
||||
[\-listen=<address>] [\-metrics\-listen=<address>]
|
||||
[\-replicate=<peers>] [\-replication\-listen=<address>]
|
||||
.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 Syncthing installations to it. The
|
||||
Syncthing project also maintains a global cluster for public use.
|
||||
.SH OPTIONS
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-cert=<file>
|
||||
Certificate file (default “./cert.pem”).
|
||||
.UNINDENT
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-db\-dir=<string>
|
||||
Database directory, where data is stored (default “./discovery.db”).
|
||||
.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=<file>
|
||||
Key file (default “./key.pem”).
|
||||
.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 \-replicate=<peers>
|
||||
Replication peers, \fI\%id@address\fP <\fBid@address\fP>, comma separated
|
||||
.UNINDENT
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-replication\-listen=<address>
|
||||
Listen address for incoming replication connections (default “:19200”).
|
||||
.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 getting\-started first.
|
||||
.SS Installing
|
||||
.sp
|
||||
Go to \fI\%releases\fP <\fBhttps://github.com/syncthing/discosrv/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 certificate files and database in the current directory unless
|
||||
given flags to the contrary.
|
||||
.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
|
||||
.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 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
|
||||
.nf
|
||||
.ft C
|
||||
https://disco.example.com:8443/?id=7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
Otherwise, the URL will be:
|
||||
.INDENT 0.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
https://disco.example.com:8443/
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.SS Replication
|
||||
.sp
|
||||
The discovery server can be deployed in a redundant, load sharing fashion.
|
||||
In this mode announcements are replicated from the server that receives them
|
||||
to other peer servers and queries can be answered equally by all servers.
|
||||
.sp
|
||||
Replication connections are encrypted and authenticated using TLS. The
|
||||
certificate is selected by the \fB\-cert\fP and \fB\-key\fP options and is thus
|
||||
shared with the main discovery API. If the \fB\-http\fP mode is used the
|
||||
certificate is not used for client requests but only for replication
|
||||
connections.
|
||||
.sp
|
||||
Authentication of replication connections is done using \fI\%Syncthing\-style
|
||||
device IDs\fP <\fBhttps://docs.syncthing.net/dev/device-ids.html#id1\fP> only \- CA
|
||||
verification is not available. The device IDs in question are those printed
|
||||
by the discovery server on startup.
|
||||
.sp
|
||||
Replication connections are unidirectional \- announcements are replication
|
||||
from the \fBsender\fP to a \fBlistener\fP\&. In order to have a bidirectional
|
||||
replication relationship between two servers both need to be configured as
|
||||
sender and listener.
|
||||
.sp
|
||||
As an example, lets assume two discovery servers:
|
||||
.INDENT 0.0
|
||||
.IP \(bu 2
|
||||
Server one is on 192.0.2.20 and has certificate ID I6K…H76
|
||||
.IP \(bu 2
|
||||
Server two is on 192.0.2.55 and has certificate ID MRI…7OK
|
||||
.UNINDENT
|
||||
.sp
|
||||
In order for both to replicate to the other and thus form a redundant pair,
|
||||
use the following commands.
|
||||
.sp
|
||||
On server one:
|
||||
.INDENT 0.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
$ stdiscosrv \-replicate=MRI...7OK@192.0.2.55:19200 <other options>
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
On server two:
|
||||
.INDENT 0.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
$ stdiscosrv \-replicate=I6K...H76@192.0.2.20:19200 <other options>
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
The \fB\-replicate\fP directive sets which remote device IDs are expected and
|
||||
allowed for both outgoing (sending) and incoming (listening) connections,
|
||||
and which addresses to use when connecting out to those peers. Both IP and
|
||||
port must be specified in peer addresses.
|
||||
.sp
|
||||
It is possible to only allow incoming connections from a peer without
|
||||
establishing an outgoing replication connection. To do so, give only the
|
||||
device ID without “@ip:port” address:
|
||||
.INDENT 0.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
$ stdiscosrv \-replicate=I6K...H76 <other options>
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
Discosrv will listen on the replication port only when \fB\-replicate\fP is
|
||||
given. The default replication listen address is “:19200”.
|
||||
.sp
|
||||
To achieve load balancing over two mutually replicating discovery server
|
||||
instances, add multiple A / AAAA DNS records for a given name and point
|
||||
Syncthing towards this name. The same certificate must be used on both
|
||||
discovery servers.
|
||||
.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
|
||||
.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\-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 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.example.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 $http_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 $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;
|
||||
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.example.com.crt;
|
||||
ssl_certificate_key /etc/nginx/certs/discovery.example.com.key;
|
||||
ssl_dhparam /etc/nginx/certs/discovery.example.com.dhparam.pem;
|
||||
add_header Strict\-Transport\-Security "max\-age=31536000";
|
||||
ssl_verify_client optional_no_ca;
|
||||
location / {
|
||||
proxy_pass http://discovery.example.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’s 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>\&.
|
||||
.SS Apache
|
||||
.sp
|
||||
The following lines must be added to the configuration:
|
||||
.INDENT 0.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
SSLProxyEngine On
|
||||
SSLVerifyClient optional_no_ca
|
||||
RequestHeader set X\-SSL\-Cert "%{SSL_CLIENT_CERT}s"
|
||||
.ft P
|
||||
.fi
|
||||
.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
|
||||
.nf
|
||||
.ft C
|
||||
RemoteIPHeader X\-Forwarded\-For
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
For more details, see also the recommendations in the
|
||||
\fI\%Reverse Proxy Setup\fP <\fBhttps://docs.syncthing.net/users/reverseproxy.html\fP>
|
||||
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.
|
||||
.
|
||||
|
||||
Reference in New Issue
Block a user