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 file path (/var/run/st.sock, for UNIX sock‐
80 ets).
81 --gui-apikey=<string>
83 Override the API key needed to access the GUI / REST API.
84 --gui-password=<password|->
86 Specify new GUI authentication password, to update the config
87 file. Read from the standard input stream if only a single dash
88 (-) is given. The password is hashed before writing to the con‐
89 fig file. As a special case, giving the existing password hash
90 as password will leave it untouched.
91 --gui-user=<username>
93 Specify new GUI authentication user name, to update the config
94 file.
95 --help, -h
97 Show help text about command line usage. Context-sensitive de‐
98 pending on the given subcommand.
99 --home=<dir>
101 Set common configuration and data directory. The default config‐
102 uration directory is $HOME/.config/syncthing (Unix-like),
103 $HOME/Library/Application Support/Syncthing (Mac) and %LOCALAPP‐
104 DATA%\Syncthing (Windows).
105 --config=<dir>
107 Set configuration directory. Alternative to --home and must be
108 used together with --data.
109 --data=<dir>
111 Set data (e.g. database) directory. Alternative to --home and
112 must be used together with --config.
113 --logfile=<filename>
115 Set destination filename for logging (use "-" for stdout, which
116 is the default option).
117 --logflags=<flags>
119 Select information in log line prefix. The --logflags value is a
120 sum of the following:
121 • 1: Date
123 • 2: Time
125 • 4: Microsecond time
127 • 8: Long filename
129 • 16: Short filename
131 To prefix each log line with date and time, set --logflags=3 (1
133 + 2 from above). The value 0 is used to disable all of the
134 above. The default is to show time only (2).
135 --log-max-old-files=<num>
137 Number of old files to keep (zero to keep only current). Ap‐
138 plies only when log rotation is enabled through --log-max-size.
139 --log-max-size=<num>
141 Maximum size of any log file (zero to disable log rotation).
142 --no-browser
144 Do not start a browser.
145 --no-console
147 Hide the console window. (On Windows only)
148 --no-default-folder
150 Don’t create a default folder when generating an initial config‐
151 uration / starting for the first time.
152 --no-restart
154 Do not restart Syncthing when it exits. The monitor process will
155 still run to handle crashes and writing to logfiles (if config‐
156 ured to).
157 --no-upgrade
159 Disable automatic upgrades. Equivalent to the STNOUPGRADE envi‐
160 ronment variable, see below.
161 --paths
163 Print the paths used for configuration, keys, database, GUI
164 overrides, default sync folder and the log file.
165 --paused
167 Start with all devices and folders paused.
168 --reset-database
170 Reset the database, forcing a full rescan and resync. Create
171 .stfolder folders in each sync folder if they do not already ex‐
172 ist. Caution: Ensure that all sync folders which are mountpoints
173 are already mounted. Inconsistent versions may result if the
174 mountpoint is later mounted and contains older versions.
175 --reset-deltas
177 Reset delta index IDs, forcing a full index exchange.
178 --skip-port-probing
180 Don’t try to find unused random ports for the GUI and listen ad‐
181 dress when generating an initial configuration / starting for
182 the first time.
183 --unpaused
185 Start with all devices and folders unpaused.
186 --upgrade
188 Perform upgrade.
189 --upgrade-check
191 Check for available upgrade.
192 --upgrade-to=<url>
194 Force upgrade directly from specified URL.
195 --verbose
197 Print verbose log output.
198 --version
200 Show version.
201 --to=<dir>
203 Destination directory where files should be stored after decryp‐
204 tion.
205 --verify-only
207 Don’t write decrypted files to disk (but verify plaintext
208 hashes).
209 --password=<pw>
211 Folder password for decryption / verification. Can be passed
212 through the FOLDER_PASSWORD environment variable instead to
213 avoid recording in a shell’s history buffer or sniffing from the
214 running processes list.
215 --folder-id=<id>
217 Folder ID of the encrypted folder, if it cannot be determined
218 automatically.
219 --token-path=<file>
221 Path to the token file within the folder (used to determine
222 folder ID).
223 --continue
225 Continue processing next file in case of error, instead of
226 aborting.
227
229 0 Success / Shutdown
230 1 Error
232 2 Upgrade not available
234 3 Restarting
236 4 Upgrading
238 Exit codes over 125 are usually returned by the shell/binary loader/de‐
240 fault signal handler. Exit codes over 128+N on Unix usually represent
241 the signal which caused the process to exit. For example, 128 + 9
242 (SIGKILL) = 137.
243
245 The command line syntax actually supports different modes of operation
246 through several subcommands, specified as the first argument. If omit‐
247 ted, the default serve is assumed.
248 The initial setup of a device ID and default configuration can be
250 called explicitly with the generate subcommand. It can also update the
251 configured GUI authentication credentials, without going through the
252 REST API. An existing device certificate is left untouched. If the
253 configuration file already exists, it is validated and updated to the
254 latest configuration schema, including adding default values for any
255 new options.
256 The decrypt subcommand is used in conjunction with untrusted (en‐
258 crypted) devices, see the relevant section on decryption for details.
259 It does not depend on Syncthing to be running, but works on offline
260 data.
261 To work with the REST API for debugging or automating things in Sync‐
263 thing, the cli subcommand provides easy access to individual features.
264 It basically saves the hassle of handling HTTP connections and API au‐
265 thentication.
266 The available subcommands are grouped into several nested hierarchies
268 and some parts dynamically generated from the running Syncthing in‐
269 stance. On every level, the --help option lists the available proper‐
270 ties, actions and commands for the user to discover interactively. The
271 top-level groups are:
272 config Access the live configuration in a running instance over the
274 REST API to retrieve (get) or update (set) values in a
275 fine-grained way. The hierarchy is based on the same structure
276 as used in the JSON / XML representations.
277 show Show system properties and status of a running instance. The
279 output is passed on directly from the REST API response and
280 therefore requires parsing JSON format.
281 operations
283 Control the overall program operation such as restarting or han‐
284 dling upgrades, as well as triggering some actions on a
285 per-folder basis. Can also configure the default ignore pat‐
286 terns from a plain text ignore file.
287 errors Examine pending error conditions that need attention from the
289 user, or acknowledge (clear) them.
290 debug Various tools to aid in diagnosing problems or collection infor‐
292 mation for bug reports. Some of these commands access the data‐
293 base directly and can therefore only work when Syncthing is not
294 running.
295 - (a single dash)
297 Reads subsequent commands from the standard input stream, with‐
298 out needing to call the syncthing cli command over and over.
299 Exits on any invalid command or when EOF (end-of-file) is re‐
300 ceived.
301
303 Syncthing can use a SOCKS, HTTP, or HTTPS proxy to talk to the outside
304 world. The proxy is used for outgoing connections only - it is not pos‐
305 sible to accept incoming connections through the proxy. The proxy is
306 configured through the environment variable all_proxy. Somewhat unusu‐
307 ally, this variable must be named in lower case - it is not
308 “ALL_PROXY”. For example:
309 $ export all_proxy=socks://192.0.2.42:8081
311
313 The following environment variables modify Syncthing’s behavior in ways
314 that are mostly useful for developers. Use with care. If you start
315 Syncthing from within service managers like systemd or supervisor, path
316 expansion may not be supported.
317 STTRACE
319 Used to increase the debugging verbosity in specific or all fa‐
320 cilities, generally mapping to a Go package. Enabling any of
321 these also enables microsecond timestamps, file names plus line
322 numbers. Enter a comma-separated string of facilities to trace.
323 syncthing --help always outputs an up-to-date list. The valid
324 facility strings are:
325 Main and operational facilities:
327 config Configuration loading and saving.
329 db The database layer.
331 main Main package.
333 model The root hub; the largest chunk of the system.
335 File pulling, index transmission and requests for
336 chunks.
337 scanner
339 File change detection and hashing.
340 versioner
342 File versioning.
343 Networking facilities:
345 beacon Multicast and broadcast UDP discovery packets: Se‐
347 lected interfaces and addresses.
348 connections
350 Connection handling.
351 dialer Dialing connections.
353 discover
355 Remote device discovery requests, replies and reg‐
356 istration of devices.
357 nat NAT discovery and port mapping.
359 pmp NAT-PMP discovery and port mapping.
361 protocol
363 The BEP protocol.
364 relay Relay interaction (strelaysrv).
366 upnp UPnP discovery and port mapping.
368 Other facilities:
370 fs Filesystem access.
372 events Event generation and logging.
374 http REST API.
376 sha256 SHA256 hashing package (this facility currently
378 unused).
379 stats Persistent device and folder statistics.
381 sync Mutexes. Used for debugging race conditions and
383 deadlocks.
384 upgrade
386 Binary upgrades.
387 walkfs Filesystem access while walking.
389 all All of the above.
391 STBLOCKPROFILE
393 Write block profiles to block-$pid-$timestamp.pprof every 20
394 seconds.
395 STCPUPROFILE
397 Write a CPU profile to cpu-$pid.pprof on exit.
398 STDEADLOCKTIMEOUT
400 Used for debugging internal deadlocks; sets debug sensitivity.
401 Use only under direction of a developer.
402 STLOCKTHRESHOLD
404 Used for debugging internal deadlocks; sets debug sensitivity.
405 Use only under direction of a developer.
406 STGUIADDRESS
408 Override GUI listen address. Equivalent to passing
409 --gui-address.
410 STGUIAPIKEY
412 Override the API key needed to access the GUI / REST API.
413 Equivalent to passing --gui-apikey.
414 STGUIASSETS
416 Directory to load GUI assets from. Overrides compiled in assets.
417 Useful for developing webgui, commonly use STGUIASSETS=gui
418 bin/syncthing.
419 STHASHING
421 Specify which hashing package to use. Defaults to automatic
422 based on performance. Specify “minio” (compatibility) or “stan‐
423 dard” for the default Go implementation.
424 STHEAPPROFILE
426 Write heap profiles to heap-$pid-$timestamp.pprof each time heap
427 usage increases.
428 STNODEFAULTFOLDER
430 Don’t create a default folder when starting for the first time.
431 This variable will be ignored anytime after the first run.
432 Equivalent to the --no-default-folder flag.
433 STNORESTART
435 Equivalent to the --no-restart flag.
436 STNOUPGRADE
438 Disable automatic upgrades. Equivalent to the --no-upgrade
439 flag.
440 STPROFILER
442 Set to a listen address such as “127.0.0.1:9090” to start the
443 profiler with HTTP access, which then can be reached at
444 http://localhost:9090/debug/pprof. See go tool pprof for more
445 information.
446 STPERFSTATS
448 Write running performance statistics to perf-$pid.csv. Not sup‐
449 ported on Windows.
450 STRECHECKDBEVERY
452 Time before folder statistics (file, dir, … counts) are recalcu‐
453 lated from scratch. The given duration must be parseable by Go’s
454 time.ParseDuration. If missing or not parseable, the default
455 value of 1 month is used. To force recalculation on every
456 startup, set it to 1s.
457 STGCINDIRECTEVERY
459 Sets the time interval in between database garbage collection
460 runs. The given duration must be parseable by Go’s time.Parse‐
461 Duration.
462 GOMAXPROCS
464 Set the maximum number of CPU cores to use. Defaults to all
465 available CPU cores.
466 GOGC Percentage of heap growth at which to trigger GC. Default is
468 100. Lower numbers keep peak memory usage down, at the price of
469 CPU usage (i.e. performance).
470 LOGGER_DISCARD
472 Hack to completely disable logging, for example when running
473 benchmarks. Set to any nonempty value to use it.
474
476 syncthing-config(5), syncthing-stignore(5), syncthing-device-ids(7),
477 syncthing-security(7), syncthing-networking(7), syncthing-version‐
478 ing(7), syncthing-faq(7)
479
481 The Syncthing Authors
482
484 2014-2019, The Syncthing Authors
485v1.22.2 Dec 29, 2022 SYNCTHING(1)