1SYNCTHING(1) Syncthing SYNCTHING(1)
2
6 syncthing - Syncthing
7
9 syncthing [serve]
10 [--audit] [--auditfile=<file|-|-->] [--browser-only] [--device-id]
11 [--generate=<dir>] [--gui-address=<address>] [--gui-apikey=<key>]
12 [--home=<dir> | --config=<dir> --data=<dir>]
13 [--logfile=<filename>] [--logflags=<flags>]
14 [--log-max-old-files=<num>] [--log-max-size=<num>]
15 [--no-browser] [--no-console] [--no-restart] [--paths] [--paused]
16 [--no-default-folder] [--skip-port-probing]
17 [--reset-database] [--reset-deltas] [--unpaused] [--allow-newer-config]
18 [--upgrade] [--no-upgrade] [--upgrade-check] [--upgrade-to=<url>]
19 [--verbose] [--version] [--help] [--debug-*]
20 syncthing generate
22 [--home=<dir> | --config=<dir>]
23 [--gui-user=<username>] [--gui-password=<password|->]
24 [--no-default-folder] [--skip-port-probing] [--no-console]
25 [--help]
26 syncthing decrypt (--to=<dir> | --verify-only)
28 [--password=<pw>] [--folder-id=<id>] [--token-path=<file>]
29 [--continue] [--verbose] [--version] [--help]
30 <path>
31 syncthing cli
33 [--home=<dir> | --config=<dir> --data=<dir>]
34 [--gui-address=<address>] [--gui-apikey=<key>]
35 [--help]
36 <command> [command options...] [arguments...]
37
39 Syncthing lets you synchronize your files bidirectionally across multi‐
40 ple devices. This means the creation, modification or deletion of files
41 on one machine will automatically be replicated to your other devices.
42 We believe your data is your data alone and you deserve to choose where
43 it is stored. Therefore Syncthing does not upload your data to the
44 cloud but exchanges your data across your machines as soon as they are
45 online at the same time.
46 The syncthing core application is a command-line program which usually
48 runs in the background and handles the synchronization. It provides a
49 built-in, HTML and JavaScript based user interface to be controlled
50 from a web browser. This frontend communicates with the core applica‐
51 tion through some HTTP APIs, which other apps like graphical system in‐
52 tegration helpers can use as well, for greatest flexibility. A link to
53 reach the GUI and API is printed among the first few log messages.
54
56 --allow-newer-config
57 Try loading a config file written by a newer program version,
58 instead of failing immediately.
59 --audit
61 Write events to timestamped file audit-YYYYMMDD-HHMMSS.log.
62 --auditfile=<file|-|-->
64 Use specified file or stream ("-" for stdout, "--" for stderr)
65 for audit events, rather than the timestamped default file name.
66 --browser-only
68 Open the web UI in a browser for an already running Syncthing
69 instance.
70 --device-id
72 Print device ID to command line.
73 --generate=<dir>
75 Generate key and config in specified dir, then exit.
76 --gui-address=<address>
78 Override GUI listen address. Set this to an address
79 (0.0.0.0:8384) or a URL (http://0.0.0.0:8384). Supported schemes
80 are http for plain HTTP, https for HTTP over TLS, unix for plain
81 Unix sockets or unixs for TLS over Unix sockets. A Unix socket
82 could look like this: unix:///run/syncthing/syncthing.socket
83 (notice the three slashes: two as part of the URL structure, one
84 to specify an absolute path).
85 --gui-apikey=<string>
87 Override the API key needed to access the GUI / REST API.
88 --gui-password=<password|->
90 Specify new GUI authentication password, to update the config
91 file. Read from the standard input stream if only a single dash
92 (-) is given. A plaintext password is hashed before writing to
93 the config file, but an already bcrypt-hashed input is stored
94 verbatim. As a special case, giving the existing password hash
95 as password will leave it untouched.
96 --gui-user=<username>
98 Specify new GUI authentication user name, to update the config
99 file.
100 --help, -h
102 Show help text about command line usage. Context-sensitive de‐
103 pending on the given subcommand.
104 --home=<dir>
106 Set common configuration and data directory. The default config‐
107 uration directory is $HOME/.config/syncthing (Unix-like),
108 $HOME/Library/Application Support/Syncthing (Mac) and %LOCALAPP‐
109 DATA%\Syncthing (Windows).
110 --config=<dir>
112 Set configuration directory. Alternative to --home and must be
113 used together with --data.
114 --data=<dir>
116 Set data (e.g. database) directory. Alternative to --home and
117 must be used together with --config.
118 --logfile=<filename>
120 Set destination filename for logging (use "-" for stdout, which
121 is the default option).
122 --logflags=<flags>
124 Select information in log line prefix. The --logflags value is a
125 sum of the following:
126 • 1: Date
128 • 2: Time
130 • 4: Microsecond time
132 • 8: Long filename
134 • 16: Short filename
136 To prefix each log line with date and time, set --logflags=3 (1
138 + 2 from above). The value 0 is used to disable all of the
139 above. The default is to show time only (2).
140 --log-max-old-files=<num>
142 Number of old files to keep (zero to keep only current). Ap‐
143 plies only when log rotation is enabled through --log-max-size.
144 --log-max-size=<num>
146 Maximum size of any log file (zero to disable log rotation).
147 --no-browser
149 Do not start a browser.
150 --no-console
152 Hide the console window. (On Windows only)
153 --no-default-folder
155 Don’t create a default folder when generating an initial config‐
156 uration / starting for the first time.
157 --no-restart
159 Do not restart Syncthing when it exits. The monitor process will
160 still run to handle crashes and writing to logfiles (if config‐
161 ured to).
162 --no-upgrade
164 Disable automatic upgrades. Equivalent to the STNOUPGRADE envi‐
165 ronment variable, see below.
166 --paths
168 Print the paths used for configuration, keys, database, GUI
169 overrides, default sync folder and the log file.
170 --paused
172 Start with all devices and folders paused.
173 --reset-database
175 Reset the database, forcing a full rescan and resync. Create
176 .stfolder folders in each sync folder if they do not already ex‐
177 ist. Caution: Ensure that all sync folders which are mountpoints
178 are already mounted. Inconsistent versions may result if the
179 mountpoint is later mounted and contains older versions.
180 --reset-deltas
182 Reset delta index IDs, forcing a full index exchange.
183 --skip-port-probing
185 Don’t try to find unused random ports for the GUI and listen ad‐
186 dress when generating an initial configuration / starting for
187 the first time.
188 --unpaused
190 Start with all devices and folders unpaused.
191 --upgrade
193 Perform upgrade.
194 --upgrade-check
196 Check for available upgrade.
197 --upgrade-to=<url>
199 Force upgrade directly from specified URL.
200 --verbose
202 Print verbose log output.
203 --version
205 Show version.
206 --to=<dir>
208 Destination directory where files should be stored after decryp‐
209 tion.
210 --verify-only
212 Don’t write decrypted files to disk (but verify plaintext
213 hashes).
214 --password=<pw>
216 Folder password for decryption / verification. Can be passed
217 through the FOLDER_PASSWORD environment variable instead to
218 avoid recording in a shell’s history buffer or sniffing from the
219 running processes list.
220 --folder-id=<id>
222 Folder ID of the encrypted folder, if it cannot be determined
223 automatically.
224 --token-path=<file>
226 Path to the token file within the folder (used to determine
227 folder ID).
228 --continue
230 Continue processing next file in case of error, instead of
231 aborting.
232
234 0 Success / Shutdown
235 1 Error
237 2 Upgrade not available
239 3 Restarting
241 4 Upgrading
243 Exit codes over 125 are usually returned by the shell/binary loader/de‐
245 fault signal handler. Exit codes over 128+N on Unix usually represent
246 the signal which caused the process to exit. For example, 128 + 9
247 (SIGKILL) = 137.
248
250 The command line syntax actually supports different modes of operation
251 through several subcommands, specified as the first argument. If omit‐
252 ted, the default serve is assumed.
253 The initial setup of a device ID and default configuration can be
255 called explicitly with the generate subcommand. It can also update the
256 configured GUI authentication credentials, without going through the
257 REST API. An existing device certificate is left untouched. If the
258 configuration file already exists, it is validated and updated to the
259 latest configuration schema, including adding default values for any
260 new options.
261 The decrypt subcommand is used in conjunction with untrusted (en‐
263 crypted) devices, see the relevant section on decryption for details.
264 It does not depend on Syncthing to be running, but works on offline
265 data.
266 To work with the REST API for debugging or automating things in Sync‐
268 thing, the cli subcommand provides easy access to individual features.
269 It basically saves the hassle of handling HTTP connections and API au‐
270 thentication.
271 The available subcommands are grouped into several nested hierarchies
273 and some parts dynamically generated from the running Syncthing in‐
274 stance. On every level, the --help option lists the available proper‐
275 ties, actions and commands for the user to discover interactively. The
276 top-level groups are:
277 config Access the live configuration in a running instance over the
279 REST API to retrieve (get) or update (set) values in a
280 fine-grained way. The hierarchy is based on the same structure
281 as used in the JSON / XML representations.
282 show Show system properties and status of a running instance. The
284 output is passed on directly from the REST API response and
285 therefore requires parsing JSON format.
286 operations
288 Control the overall program operation such as restarting or han‐
289 dling upgrades, as well as triggering some actions on a
290 per-folder basis. Can also configure the default ignore pat‐
291 terns from a plain text ignore file.
292 errors Examine pending error conditions that need attention from the
294 user, or acknowledge (clear) them.
295 debug Various tools to aid in diagnosing problems or collection infor‐
297 mation for bug reports. Some of these commands access the data‐
298 base directly and can therefore only work when Syncthing is not
299 running.
300 - (a single dash)
302 Reads subsequent commands from the standard input stream, with‐
303 out needing to call the syncthing cli command over and over.
304 Exits on any invalid command or when EOF (end-of-file) is re‐
305 ceived.
306
308 Syncthing can use a SOCKS, HTTP, or HTTPS proxy to talk to the outside
309 world. The proxy is used for outgoing connections only - it is not pos‐
310 sible to accept incoming connections through the proxy. The proxy is
311 configured through the environment variable all_proxy. Somewhat unusu‐
312 ally, this variable must be named in lower case - it is not
313 “ALL_PROXY”. For example:
314 $ export all_proxy=socks://192.0.2.42:8081
316
318 The following environment variables modify Syncthing’s behavior in ways
319 that are mostly useful for developers. Use with care. If you start
320 Syncthing from within service managers like systemd or supervisor, path
321 expansion may not be supported.
322 STTRACE
324 Used to increase the debugging verbosity in specific or all fa‐
325 cilities, generally mapping to a Go package. Enabling any of
326 these also enables microsecond timestamps, file names plus line
327 numbers. Enter a comma-separated string of facilities to trace.
328 syncthing --help always outputs an up-to-date list. The valid
329 facility strings are:
330 Main and operational facilities:
332 config Configuration loading and saving.
334 db The database layer.
336 main Main package.
338 model The root hub; the largest chunk of the system.
340 File pulling, index transmission and requests for
341 chunks.
342 scanner
344 File change detection and hashing.
345 versioner
347 File versioning.
348 Networking facilities:
350 beacon Multicast and broadcast UDP discovery packets: Se‐
352 lected interfaces and addresses.
353 connections
355 Connection handling.
356 dialer Dialing connections.
358 discover
360 Remote device discovery requests, replies and reg‐
361 istration of devices.
362 nat NAT discovery and port mapping.
364 pmp NAT-PMP discovery and port mapping.
366 protocol
368 The BEP protocol.
369 relay Relay interaction (strelaysrv).
371 upnp UPnP discovery and port mapping.
373 Other facilities:
375 fs Filesystem access.
377 events Event generation and logging.
379 http REST API.
381 sha256 SHA256 hashing package (this facility currently
383 unused).
384 stats Persistent device and folder statistics.
386 sync Mutexes. Used for debugging race conditions and
388 deadlocks.
389 upgrade
391 Binary upgrades.
392 walkfs Filesystem access while walking.
394 all All of the above.
396 STBLOCKPROFILE
398 Write block profiles to block-$pid-$timestamp.pprof every 20
399 seconds.
400 STCPUPROFILE
402 Write a CPU profile to cpu-$pid.pprof on exit.
403 STDEADLOCKTIMEOUT
405 Used for debugging internal deadlocks; sets debug sensitivity.
406 Use only under direction of a developer.
407 STLOCKTHRESHOLD
409 Used for debugging internal deadlocks; sets debug sensitivity.
410 Use only under direction of a developer.
411 STGUIADDRESS
413 Override GUI listen address. Equivalent to passing
414 --gui-address.
415 STGUIAPIKEY
417 Override the API key needed to access the GUI / REST API.
418 Equivalent to passing --gui-apikey.
419 STGUIASSETS
421 Directory to load GUI assets from. Overrides compiled in assets.
422 Useful for developing webgui, commonly use STGUIASSETS=gui
423 bin/syncthing.
424 STHASHING
426 Specify which hashing package to use. Defaults to automatic
427 based on performance. Specify “minio” (compatibility) or “stan‐
428 dard” for the default Go implementation.
429 STHEAPPROFILE
431 Write heap profiles to heap-$pid-$timestamp.pprof each time heap
432 usage increases.
433 STNODEFAULTFOLDER
435 Don’t create a default folder when starting for the first time.
436 This variable will be ignored anytime after the first run.
437 Equivalent to the --no-default-folder flag.
438 STNORESTART
440 Equivalent to the --no-restart flag.
441 STNOUPGRADE
443 Disable automatic upgrades. Equivalent to the --no-upgrade
444 flag.
445 STPROFILER
447 Set to a listen address such as “127.0.0.1:9090” to start the
448 profiler with HTTP access, which then can be reached at
449 http://localhost:9090/debug/pprof. See go tool pprof for more
450 information.
451 STPERFSTATS
453 Write running performance statistics to perf-$pid.csv. Not sup‐
454 ported on Windows.
455 STRECHECKDBEVERY
457 Time before folder statistics (file, dir, … counts) are recalcu‐
458 lated from scratch. The given duration must be parseable by Go’s
459 time.ParseDuration. If missing or not parseable, the default
460 value of 1 month is used. To force recalculation on every
461 startup, set it to 1s.
462 STGCINDIRECTEVERY
464 Sets the time interval in between database garbage collection
465 runs. The given duration must be parseable by Go’s time.Parse‐
466 Duration.
467 GOMAXPROCS
469 Set the maximum number of CPU cores to use. Defaults to all
470 available CPU cores.
471 GOGC Percentage of heap growth at which to trigger GC. Default is
473 100. Lower numbers keep peak memory usage down, at the price of
474 CPU usage (i.e. performance).
475 LOGGER_DISCARD
477 Hack to completely disable logging, for example when running
478 benchmarks. Set to any nonempty value to use it.
479
481 syncthing-config(5), syncthing-stignore(5), syncthing-device-ids(7),
482 syncthing-security(7), syncthing-networking(7), syncthing-version‐
483 ing(7), syncthing-faq(7)
484
486 The Syncthing Authors
487
489 2014-2019, The Syncthing Authors
490v1.25.0 Oct 05, 2023 SYNCTHING(1)