From 2ea22b18503f7e0c2fbed0f7c68f58f609125e5f Mon Sep 17 00:00:00 2001 From: Jakob Borg Date: Tue, 17 May 2016 12:02:44 +0000 Subject: [PATCH] gui, man: Update docs & translations GitHub-Pull-Request: https://github.com/syncthing/syncthing/pull/3101 --- gui/default/assets/lang/lang-fr.json | 4 +- gui/default/assets/lang/lang-fy.json | 2 +- man/syncthing-bep.7 | 6 +- man/syncthing-config.5 | 176 +++++++++++++++++++-------- man/syncthing-device-ids.7 | 2 +- man/syncthing-event-api.7 | 2 +- man/syncthing-faq.7 | 11 +- man/syncthing-globaldisco.7 | 6 +- man/syncthing-localdisco.7 | 2 +- man/syncthing-networking.7 | 2 +- man/syncthing-relay.7 | 4 +- man/syncthing-rest-api.7 | 2 +- man/syncthing-security.7 | 2 +- man/syncthing-stignore.5 | 2 +- man/syncthing-versioning.7 | 2 +- man/syncthing.1 | 2 +- 16 files changed, 155 insertions(+), 72 deletions(-) diff --git a/gui/default/assets/lang/lang-fr.json b/gui/default/assets/lang/lang-fr.json index 0b44e04e..2774a325 100644 --- a/gui/default/assets/lang/lang-fr.json +++ b/gui/default/assets/lang/lang-fr.json @@ -152,7 +152,7 @@ "Reused": "Réutilisé", "Save": "Sauver", "Scan Time Remaining": "Intervalle entre chaque analyse", - "Scanning": "En cours d'analyse", + "Scanning": "Analyse en cours", "Select the devices to share this folder with.": "Sélectionner les machines avec qui partager ce dossier.", "Select the folders to share with this device.": "Sélectionner les dossiers à partager avec cette machine.", "Settings": "Configuration", @@ -179,7 +179,7 @@ "Stopped": "Arrêté", "Support": "Aide", "Sync Protocol Listen Addresses": "Adresse d'écoute du protocole de synchronisation", - "Syncing": "En cours de synchronisation", + "Syncing": "Synchronisation en cours", "Syncthing has been shut down.": "Syncthing a été éteint.", "Syncthing includes the following software or portions thereof:": "Syncthing intègre les logiciels suivants (ou des éléments provenant de ces logiciels) :", "Syncthing is restarting.": "Syncthing est cours de redémarrage.", diff --git a/gui/default/assets/lang/lang-fy.json b/gui/default/assets/lang/lang-fy.json index f5dfde4a..f31aa4d4 100644 --- a/gui/default/assets/lang/lang-fy.json +++ b/gui/default/assets/lang/lang-fy.json @@ -55,7 +55,7 @@ "Edit Device": "Apparaat bewurkje", "Edit Folder": "Map bewurkje", "Editing": "Bewurkjen", - "Enable NAT traversal": "Enable NAT traversal", + "Enable NAT traversal": "NAT-trochkruse ynskeakelje", "Enable Relaying": "Trochjaan tastean", "Enable UPnP": "UPnP oansette", "Enter comma separated (\"tcp://ip:port\", \"tcp://host:port\") addresses or \"dynamic\" to perform automatic discovery of the address.": "Fier troch komma's skieden (\"tcp://ip:port\", \"tcp://host:port\") adressen yn of \"dynamic\" om automatyske ûntdekking fan it adres út te fieren.", diff --git a/man/syncthing-bep.7 b/man/syncthing-bep.7 index 4d0daa8e..86635eb3 100644 --- a/man/syncthing-bep.7 +++ b/man/syncthing-bep.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-BEP" "7" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING-BEP" "7" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing-bep \- Block Exchange Protocol v1 . @@ -232,7 +232,7 @@ For C=1: The Length field contains the length, in bytes, of the compressed message data plus a four byte uncompressed length field. .IP \(bu 2 -The compressed message data is preceeded by a 32 bit field denoting +The compressed message data is preceded by a 32 bit field denoting the length of the uncompressed message. .IP \(bu 2 The message data is compressed using the LZ4 format and algorithm @@ -1149,7 +1149,7 @@ is no longer available, therefore the list of block indexes should be truncated. Messages with \fBForget\fP bit set MUST NOT have any block indexes. .sp Any update message which is being sent for a different \fBVersion\fP of the same -file name must be preceeded with an update message for the old version of that +file name must be preceded with an update message for the old version of that file with the \fBForget\fP bit set. .sp As a safeguard on the receiving side, value of \fBVersion\fP changing between diff --git a/man/syncthing-config.5 b/man/syncthing-config.5 index abe7071e..51497fde 100644 --- a/man/syncthing-config.5 +++ b/man/syncthing-config.5 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-CONFIG" "5" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING-CONFIG" "5" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing-config \- Syncthing Configuration . @@ -81,8 +81,8 @@ The following shows the default configuration file: .sp .nf .ft C - - + + 1 @@ -94,34 +94,35 @@ The following shows the default configuration file: 0 0 0 - 0 + \-1 + false + false
dynamic
 -
127.0.0.1:52620
+
127.0.0.1:8384
k1dnz1Dd0rzTBjjFFh7CXPnrF12C49B1 + default - tcp://0.0.0.0:22000 + default default true true 21027 [ff12::8384]:21027 - dynamic+https://relays.syncthing.net/endpoint 0 0 60 true 10 - false true - true - 60 - 30 - 10 + true + 60 + 30 + 10 0 https://data.syncthing.net/newdata @@ -130,13 +131,14 @@ The following shows the default configuration file: true 12 24 - true + false 5 true false - 0 1 https://api.github.com/repos/syncthing/syncthing/releases?per_page=30 + false + 10 .ft P @@ -158,7 +160,7 @@ migration from previous formats. .sp .nf .ft C - + 1 @@ -170,7 +172,9 @@ migration from previous formats. 0 0 0 - 0 + \-1 + false + false .ft P .fi @@ -185,13 +189,25 @@ element: .B id The folder ID, must be unique. (mandatory) .TP +.B label +The label of a folder is a human readable and descriptive local name. +Can be different on each device. (optional) +.TP .B path The path to the directory where the folder is stored on this device; not sent to other devices. (mandatory) .TP -.B ro -True if the folder is read only (Master mode; will not be modified by -Syncthing) on this device. +.B type +Controls how the folder is handled by Syncthing. Possible values are: +.INDENT 7.0 +.TP +.B readwrite +The folder is in default mode. Sending local and accepting remote changes. +.TP +.B readonly +The folder is in "master" mode \-\- it will not be modified by +syncthing on this device. +.UNINDENT .TP .B rescanIntervalS The rescan interval, in seconds. Can be set to zero to disable when external @@ -274,6 +290,16 @@ what you\(aqre doing. The maximum number of conflict copies to keep around for any given file. The default, \-1, means an unlimited number. Setting this to zero disables conflict copies altogether. +.TP +.B disableSparseFiles +By default, blocks containing all zeroes are not written, causing files +to be sparse on filesystems that support the concept. When set to true, +sparse files will not be created. +.TP +.B disableTempIndexes +By default, devices exchange information about blocks available in +transfers that are still in progress. When set to true, such information +is not exchanged for this folder. .UNINDENT .SH DEVICE ELEMENT .INDENT 0.0 @@ -384,6 +410,7 @@ This optional element lists device IDs that have been specifically ignored. One
127.0.0.1:8384
l7jSbCqPD95JYZ0g8vi4ZLAMg3ulnN1b + default .ft P .fi @@ -402,6 +429,9 @@ If not \fBtrue\fP, the GUI and API will not be started. If set to \fBtrue\fP, TLS (HTTPS) will be enforced. Non\-HTTPS requests will be redirected to HTTPS. When this is set to \fBfalse\fP, TLS connections are still possible but it is not mandatory. +.TP +.B theme +The name of the theme to use. .UNINDENT .sp The following child elements may be present: @@ -415,16 +445,10 @@ Allowed address formats are: .B IPv4 address and port (\fB127.0.0.1:8384\fP) The address and port is used as given. .TP -.B IPv4 wildcard and port (\fBtcp4://0.0.0.0\fP, \fBtcp4://:8384\fP) -These are equivalent and will result in Syncthing listening on all interfaces via IPv4 only. -.TP .B IPv6 address and port (\fB[::1]:8384\fP) The address and port is used as given. The address must be enclosed in square brackets. .TP -.B IPv6 wildcard and port (\fBtcp6://[::]:8384\fP, \fBtcp6://:8384\fP) -These are equivalent and will result in Syncthing listening on all interfaces via IPv6 only. -.TP .B Wildcard and port (\fB0.0.0.0:12345\fP, \fB[::]:12345\fP, \fB:12345\fP) These are equivalent and will result in Syncthing listening on all interfaces via both IPv4 and IPv6. @@ -446,24 +470,22 @@ If set, this is the API key that enables usage of the REST interface. .nf .ft C - tcp://0.0.0.0:22000 + default default true true 21027 [ff12::8384]:21027 - dynamic+https://relays.syncthing.net/endpoint 0 0 60 true 10 - false true - true - 60 - 30 - 10 + true + 60 + 30 + 10 0 https://data.syncthing.net/newdata @@ -472,13 +494,14 @@ If set, this is the API key that enables usage of the REST interface. true 12 24 - true + false 5 true false - 0 1 https://api.github.com/repos/syncthing/syncthing/releases?per_page=30 + false + 10 .ft P .fi @@ -489,10 +512,8 @@ The \fBoptions\fP element contains all other global configuration options. .INDENT 0.0 .TP .B listenAddress -The listen address for incoming sync connections. See the \fBaddress\fP -element under the \fI\%GUI Element\fP for allowed syntax, with the addition -that the address must have a protocol scheme prefix. Currently \fBtcp://\fP -is the only supported protocol scheme. +The listen address for incoming sync connections. See +\fI\%Listen Addresses\fP for allowed syntax. .TP .B globalAnnounceServer A URI to a global announce (discovery) server, or the word \fBdefault\fP to @@ -539,25 +560,20 @@ When true, relays will be connected to and potentially used for device to device .B relayReconnectIntervalM Sets the interval, in minutes, between relay reconnect attempts. .TP -.B relayWithoutGlobalAnn -When set to true, relay connections will be attempted even when global -discovery is disabled. This is useful only in the case where devices are -known to be connected to the same relays. The default is \fBfalse\fP\&. -.TP .B startBrowser Whether to attempt to start a browser to show the GUI when Syncthing starts. .TP -.B upnpEnabled -Whether to attempt to perform an UPnP port mapping for incoming sync -connections. +.B natEnabled +Whether to attempt to perform an UPnP and NAT\-PMP port mapping for +incoming sync connections. .TP -.B upnpLeaseMinutes +.B natLeaseMinutes Request a lease for this many minutes; zero to request a permanent lease. .TP -.B upnpRenewalMinutes +.B natRenewalMinutes Attempt to renew the lease after this many minutes. .TP -.B upnpTimeoutSeconds +.B natTimeoutSeconds When scanning for UPnP devices, wait this long for responses. .TP .B urAccepted @@ -594,8 +610,9 @@ Keep temporary failed transfers for this many hours. While the temporaries are kept, the data they contain need not be transferred again. .TP .B cacheIgnoredFiles -Whether to cache the results of ignore pattern evaluation. Performance at -the price of memory. +Whether to cache the results of ignore pattern evaluation. Performance +at the price of memory. Defaults to \fBfalse\fP as the cost for evaluating +ignores is usually not significant. .TP .B progressUpdateIntervalS How often in seconds the progress of ongoing downloads is made available to @@ -626,6 +643,63 @@ the configuration and index. .TP .B releasesURL The URL from which release information is loaded, for automatic upgrades. +.TP +.B overwriteRemoteDeviceNamesOnConnect +If set, device names will always be overwritten with the name given by +remote on each connection. By default, the name that the remote device +announces will only be adopted when a name has not already been set. +.TP +.B tempIndexMinBlocks +When exchanging index information for incomplete transfers, only take +into account files that have at least this many blocks. +.UNINDENT +.SS Listen Addresses +.sp +The following address types are accepted in sync protocol listen addresses: +.INDENT 0.0 +.TP +.B TCP wildcard and port (\fBtcp://0.0.0.0:22000\fP, \fBtcp://:22000\fP) +These are equivalent and will result in Syncthing listening on all +interfaces, IPv4 and IPv6, on the specified port. +.TP +.B TCP IPv4 wildcard and port (\fBtcp4://0.0.0.0:22000\fP, \fBtcp4://:22000\fP) +These are equivalent and will result in Syncthing listening on all +interfaces via IPv4 only. +.TP +.B TCP IPv4 address and port (\fBtcp4://192.0.2.1:22000\fP) +These are equivalent and will result in Syncthing listening on the +specified address and port only. +.TP +.B TCP IPv6 wildcard and port (\fBtcp6://[::]:22000\fP, \fBtcp6://:22000\fP) +These are equivalent and will result in Syncthing listening on all +interfaces via IPv6 only. +.TP +.B TCP IPv6 address and port (\fBtcp6://[2001:db8::42]:22000\fP) +These are equivalent and will result in Syncthing listening on the +specified address and port only. +.TP +.B Static relay address (\fBrelay://192.0.2.42:22067?id=abcd123...\fP) +Syncthing will connect to and listen for incoming connections via the +specified relay address. +.INDENT 7.0 +.INDENT 3.5 +.SS Todo +.sp +Document available URL parameters. +.UNINDENT +.UNINDENT +.TP +.B Dynamic relay pool (\fBdynamic+https://192.0.2.42/relays\fP) +Syncthing will fetch the specified HTTPS URL, parse it for a JSON payload +describing relays, select a relay from the available ones and listen via +that as if specified as a static relay above. +.INDENT 7.0 +.INDENT 3.5 +.SS Todo +.sp +Document available URL parameters. +.UNINDENT +.UNINDENT .UNINDENT .SH SYNCING CONFIGURATION FILES .sp diff --git a/man/syncthing-device-ids.7 b/man/syncthing-device-ids.7 index 35045c30..c39207f4 100644 --- a/man/syncthing-device-ids.7 +++ b/man/syncthing-device-ids.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-DEVICE-IDS" "7" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING-DEVICE-IDS" "7" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing-device-ids \- Understanding Device IDs . diff --git a/man/syncthing-event-api.7 b/man/syncthing-event-api.7 index 3c0f4b20..93d5d21c 100644 --- a/man/syncthing-event-api.7 +++ b/man/syncthing-event-api.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-EVENT-API" "7" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING-EVENT-API" "7" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing-event-api \- Event API . diff --git a/man/syncthing-faq.7 b/man/syncthing-faq.7 index 21f031bc..e383d7f2 100644 --- a/man/syncthing-faq.7 +++ b/man/syncthing-faq.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-FAQ" "7" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING-FAQ" "7" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing-faq \- Frequently Asked Questions . @@ -152,6 +152,11 @@ encrypted using AES\-128. When receiving data, it must be decrypted. .IP 3. 3 There is a certain amount of housekeeping that must be done to track the current and available versions of each file in the index database. +.IP 4. 3 +By default Syncthing uses periodic scanning every 60 seconds to detect +file changes. This means checking every file\(aqs modification time and +comparing it to the database. This can cause spikes of CPU usage for large +folders. .UNINDENT .sp Hashing, compression and encryption cost CPU time. Also, using the GUI @@ -164,6 +169,10 @@ environment variable \fBGOMAXPROCS\fP to the maximum number of CPU cores Syncthing should use at any given moment. For example, \fBGOMAXPROCS=2\fP on a machine with four cores will limit Syncthing to no more than half the system\(aqs CPU power. +.sp +To reduce CPU spikes from scanning activity, use a filesystem notifications +plugin. This is delivered by default via Synctrayzor, Syncthing\-GTK and on +Android. For other setups, consider using \fI\%syncthing\-inotify\fP <\fBhttps://github.com/syncthing/syncthing-inotify\fP>\&. .SS Should I keep my device IDs secret? .sp No. The IDs are not sensitive. Given a device ID it\(aqs possible to find the IP diff --git a/man/syncthing-globaldisco.7 b/man/syncthing-globaldisco.7 index 4a2d680d..75fade84 100644 --- a/man/syncthing-globaldisco.7 +++ b/man/syncthing-globaldisco.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-GLOBALDISCO" "7" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING-GLOBALDISCO" "7" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing-globaldisco \- Global Discovery Protocol v3 . @@ -67,7 +67,7 @@ certificate was presented, status \fB403\fP (Forbidden) is returned. If the posted data doesn\(aqt conform to the expected format, \fB400\fP (Bad Request) is returned. .sp -In successfull responses, the server may return a \fBReannounce\-After\fP header +In successful responses, the server may return a \fBReannounce\-After\fP header containing the number of seconds after which the client should perform a new announcement. .sp @@ -84,7 +84,7 @@ Queries are performed as HTTPS GET requests to the announce server URL. The requested device ID is passed as the query parameter "device", in canonical string form, i.e. \fBhttps://announce.syncthing.net/?device=ABC12345\-....\fP .sp -Successfull responses will have status code \fB200\fP (OK) and carry a JSON payload +Successful responses will have status code \fB200\fP (OK) and carry a JSON payload of the same format as the announcement above. The response will not contain empty or unspecified addresses. .sp diff --git a/man/syncthing-localdisco.7 b/man/syncthing-localdisco.7 index c8975fb3..9be2c0e2 100644 --- a/man/syncthing-localdisco.7 +++ b/man/syncthing-localdisco.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-LOCALDISCO" "7" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING-LOCALDISCO" "7" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing-localdisco \- Local Discovery Protocol v3 . diff --git a/man/syncthing-networking.7 b/man/syncthing-networking.7 index b76d92da..c9b67d6c 100644 --- a/man/syncthing-networking.7 +++ b/man/syncthing-networking.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-NETWORKING" "7" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING-NETWORKING" "7" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing-networking \- Firewall Setup . diff --git a/man/syncthing-relay.7 b/man/syncthing-relay.7 index ee8dad34..c5a64cd4 100644 --- a/man/syncthing-relay.7 +++ b/man/syncthing-relay.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-RELAY" "7" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING-RELAY" "7" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing-relay \- Relay Protocol v1 . @@ -337,7 +337,7 @@ _ .TE .SH MESSAGES .sp -All messages are preceeded by a header message. Header message contains the +All messages are preceded by a header message. Header message contains the magic value 0x9E79BC40, message type integer, and message length. .sp \fBWARNING:\fP diff --git a/man/syncthing-rest-api.7 b/man/syncthing-rest-api.7 index 0469e35c..9f357e4f 100644 --- a/man/syncthing-rest-api.7 +++ b/man/syncthing-rest-api.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-REST-API" "7" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING-REST-API" "7" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing-rest-api \- REST API . diff --git a/man/syncthing-security.7 b/man/syncthing-security.7 index 944b9fd0..42c9e686 100644 --- a/man/syncthing-security.7 +++ b/man/syncthing-security.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-SECURITY" "7" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING-SECURITY" "7" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing-security \- Security Principles . diff --git a/man/syncthing-stignore.5 b/man/syncthing-stignore.5 index d0d22424..645fac35 100644 --- a/man/syncthing-stignore.5 +++ b/man/syncthing-stignore.5 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-STIGNORE" "5" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING-STIGNORE" "5" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing-stignore \- Prevent files from being synchronized to other nodes . diff --git a/man/syncthing-versioning.7 b/man/syncthing-versioning.7 index 7f7a623e..795a70d3 100644 --- a/man/syncthing-versioning.7 +++ b/man/syncthing-versioning.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "TODO" "7" "May 01, 2016" "v0.12" "Syncthing" +.TH "TODO" "7" "May 17, 2016" "v0.12" "Syncthing" .SH NAME Todo \- Keep automatic backups of deleted files by other nodes . diff --git a/man/syncthing.1 b/man/syncthing.1 index a07ab413..55247d25 100644 --- a/man/syncthing.1 +++ b/man/syncthing.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING" "1" "May 01, 2016" "v0.12" "Syncthing" +.TH "SYNCTHING" "1" "May 17, 2016" "v0.12" "Syncthing" .SH NAME syncthing \- Syncthing .