123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623 |
- .\" 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 "SYNCTHING" "1" "Jun 02, 2024" "v1.27.7" "Syncthing"
- .SH NAME
- syncthing \- Syncthing
- .SH SYNOPSIS
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- syncthing [serve]
- [\-\-audit] [\-\-auditfile=<file|\-|\-\->] [\-\-browser\-only] [\-\-device\-id]
- [\-\-generate=<dir>] [\-\-gui\-address=<address>] [\-\-gui\-apikey=<key>]
- [\-\-home=<dir> | \-\-config=<dir> \-\-data=<dir>]
- [\-\-logfile=<filename>] [\-\-logflags=<flags>]
- [\-\-log\-max\-old\-files=<num>] [\-\-log\-max\-size=<num>]
- [\-\-no\-browser] [\-\-no\-console] [\-\-no\-restart] [\-\-paths] [\-\-paused]
- [\-\-no\-default\-folder] [\-\-skip\-port\-probing]
- [\-\-reset\-database] [\-\-reset\-deltas] [\-\-unpaused] [\-\-allow\-newer\-config]
- [\-\-upgrade] [\-\-no\-upgrade] [\-\-upgrade\-check] [\-\-upgrade\-to=<url>]
- [\-\-verbose] [\-\-version] [\-\-help] [\-\-debug\-*]
- syncthing generate
- [\-\-home=<dir> | \-\-config=<dir>]
- [\-\-gui\-user=<username>] [\-\-gui\-password=<password|\->]
- [\-\-no\-default\-folder] [\-\-skip\-port\-probing] [\-\-no\-console]
- [\-\-help]
- syncthing decrypt (\-\-to=<dir> | \-\-verify\-only)
- [\-\-password=<pw>] [\-\-folder\-id=<id>] [\-\-token\-path=<file>]
- [\-\-continue] [\-\-verbose] [\-\-version] [\-\-help]
- <path>
- syncthing cli
- [\-\-home=<dir> | \-\-config=<dir> \-\-data=<dir>]
- [\-\-gui\-address=<address>] [\-\-gui\-apikey=<key>]
- [\-\-help]
- <command> [command options...] [arguments...]
- .EE
- .UNINDENT
- .UNINDENT
- .SH DESCRIPTION
- .sp
- Syncthing lets you synchronize your files bidirectionally across multiple
- devices. This means the creation, modification or deletion of files on one
- machine will automatically be replicated to your other devices. We believe your
- data is your data alone and you deserve to choose where it is stored. Therefore
- Syncthing does not upload your data to the cloud but exchanges your data across
- your machines as soon as they are online at the same time.
- .sp
- The \fBsyncthing\fP core application is a command\-line program which usually runs
- in the background and handles the synchronization. It provides a built\-in, HTML
- and JavaScript based user interface to be controlled from a web browser. This
- frontend communicates with the core application through some HTTP APIs, which
- other apps like graphical system integration helpers can use as well, for
- greatest flexibility. A link to reach the GUI and API is printed among the first
- few log messages.
- .SH OPTIONS
- .INDENT 0.0
- .TP
- .B \-\-allow\-newer\-config
- Try loading a config file written by a newer program version, instead of
- failing immediately.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-audit
- Write events to timestamped file \fBaudit\-YYYYMMDD\-HHMMSS.log\fP\&.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-auditfile=<file|\-|\-\->
- Use specified file or stream (\fB\(dq\-\(dq\fP for stdout, \fB\(dq\-\-\(dq\fP for stderr) for
- audit events, rather than the timestamped default file name.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-browser\-only
- Open the web UI in a browser for an already running Syncthing instance.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-device\-id
- Print device ID to command line.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-generate=<dir>
- Generate key and config in specified dir, then exit.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-gui\-address=<address>
- Override GUI listen address. Set this to an address (\fB0.0.0.0:8384\fP)
- or a URL (\fBhttp://0.0.0.0:8384\fP). Supported schemes are \fBhttp\fP for
- plain HTTP, \fBhttps\fP for HTTP over TLS, \fBunix\fP for plain Unix sockets
- or \fBunixs\fP for TLS over Unix sockets. A Unix socket could look like this:
- \fBunix:///run/syncthing/syncthing.socket\fP (notice the three slashes: two
- as part of the URL structure, one to specify an absolute path).
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-gui\-apikey=<string>
- Override the API key needed to access the GUI / REST API.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-gui\-password=<password|\->
- Specify new GUI authentication password, to update the config file. Read
- from the standard input stream if only a single dash (\fB\-\fP) is given. A
- plaintext password is hashed before writing to the config file, but an
- already bcrypt\-hashed input is stored verbatim. As a special case, giving
- the existing password hash as password will leave it untouched.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-gui\-user=<username>
- Specify new GUI authentication user name, to update the config file.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-help, \-h
- Show help text about command line usage. Context\-sensitive depending on the
- given subcommand.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-home=<dir>
- Set common configuration and data directory. The default configuration
- directory is \fB$XDG_STATE_HOME/syncthing\fP or
- \fB$HOME/.local/state/syncthing\fP (Unix\-like),
- \fB$HOME/Library/Application Support/Syncthing\fP (Mac) and
- \fB%LOCALAPPDATA%\eSyncthing\fP (Windows).
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-config=<dir>
- Set configuration directory. Alternative to \fB\-\-home\fP and must be used
- together with \fB\-\-data\fP\&.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-data=<dir>
- Set data (e.g. database) directory. Alternative to \fB\-\-home\fP and must be used
- together with \fB\-\-config\fP\&.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-logfile=<filename>
- Set destination filename for logging (use \fB\(dq\-\(dq\fP for stdout, which is the
- default option).
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-logflags=<flags>
- Select information in log line prefix. The \fB\-\-logflags\fP value is a sum of
- the following:
- .INDENT 7.0
- .IP \(bu 2
- 1: Date
- .IP \(bu 2
- 2: Time
- .IP \(bu 2
- 4: Microsecond time
- .IP \(bu 2
- 8: Long filename
- .IP \(bu 2
- 16: Short filename
- .UNINDENT
- .sp
- To prefix each log line with date and time, set \fB\-\-logflags=3\fP (1 + 2 from
- above). The value 0 is used to disable all of the above. The default is to
- show time only (2).
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-log\-max\-old\-files=<num>
- Number of old files to keep (zero to keep only current). Applies only when
- log rotation is enabled through \fB\-\-log\-max\-size\fP\&.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-log\-max\-size=<num>
- Maximum size of any log file (zero to disable log rotation).
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-no\-browser
- Do not start a browser.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-no\-console
- Hide the console window. (On Windows only)
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-no\-default\-folder
- Don’t create a default folder when generating an initial configuration /
- starting for the first time.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-no\-restart
- Do not restart Syncthing when it exits. The monitor process will still run
- to handle crashes and writing to logfiles (if configured to).
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-no\-upgrade
- Disable automatic upgrades. Equivalent to the \fBSTNOUPGRADE\fP environment
- variable, see below.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-paths
- Print the paths used for configuration, keys, database, GUI overrides,
- default sync folder and the log file.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-paused
- Start with all devices and folders paused.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-reset\-database
- Reset the database, forcing a full rescan and resync. Create \fI\&.stfolder\fP
- folders in each sync folder if they do not already exist. \fBCaution\fP:
- Ensure that all sync folders which are mountpoints are already mounted.
- Inconsistent versions may result if the mountpoint is later mounted and
- contains older versions.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-reset\-deltas
- Reset delta index IDs, forcing a full index exchange.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-skip\-port\-probing
- Don’t try to find unused random ports for the GUI and listen address when
- generating an initial configuration / starting for the first time.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-unpaused
- Start with all devices and folders unpaused.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-upgrade
- Perform upgrade.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-upgrade\-check
- Check for available upgrade.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-upgrade\-to=<url>
- Force upgrade directly from specified URL.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-verbose
- Print verbose log output.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-version
- Show version.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-to=<dir>
- Destination directory where files should be stored after decryption.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-verify\-only
- Don’t write decrypted files to disk (but verify plaintext hashes).
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-password=<pw>
- Folder password for decryption / verification. Can be passed through the
- \fBFOLDER_PASSWORD\fP environment variable instead to avoid recording in a
- shell’s history buffer or sniffing from the running processes list.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-folder\-id=<id>
- Folder ID of the encrypted folder, if it cannot be determined automatically.
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-token\-path=<file>
- Path to the token file within the folder (used to determine folder ID).
- .UNINDENT
- .INDENT 0.0
- .TP
- .B \-\-continue
- Continue processing next file in case of error, instead of aborting.
- .UNINDENT
- .SH EXIT CODES
- .INDENT 0.0
- .TP
- .B 0
- Success / Shutdown
- .TP
- .B 1
- Error
- .TP
- .B 2
- Upgrade not available
- .TP
- .B 3
- Restarting
- .TP
- .B 4
- Upgrading
- .UNINDENT
- .sp
- Exit codes over 125 are usually returned by the shell/binary loader/default
- signal handler. Exit codes over 128+N on Unix usually represent the signal which
- caused the process to exit. For example, \fB128 + 9 (SIGKILL) = 137\fP\&.
- .SH SUBCOMMANDS
- .sp
- The command line syntax actually supports different modes of operation through
- several subcommands, specified as the first argument. If omitted, the default
- \fBserve\fP is assumed.
- .sp
- The initial setup of a device ID and default configuration can be called
- explicitly with the \fBgenerate\fP subcommand. It can also update the configured
- GUI authentication credentials, without going through the REST API. An existing
- device certificate is left untouched. If the configuration file already exists,
- it is validated and updated to the latest configuration schema, including adding
- default values for any new options.
- .sp
- The \fBdecrypt\fP subcommand is used in conjunction with untrusted (encrypted)
- devices, see the relevant section on \X'tty: link #untrusted-decrypt'\fI\%decryption\fP\X'tty: link' for
- details. It does not depend on Syncthing to be running, but works on offline
- data.
- .sp
- To work with the REST API for debugging or automating things in Syncthing, the
- \fBcli\fP subcommand provides easy access to individual features. It basically
- saves the hassle of handling HTTP connections and API authentication.
- .sp
- The available subcommands are grouped into several nested hierarchies and some
- parts dynamically generated from the running Syncthing instance. On every
- level, the \fB\-\-help\fP option lists the available properties, actions and
- commands for the user to discover interactively. The top\-level groups are:
- .INDENT 0.0
- .TP
- .B config
- Access the live configuration in a running instance over the REST API to
- retrieve (get) or update (set) values in a fine\-grained way. The hierarchy
- is based on the same structure as used in the JSON / XML representations.
- .TP
- .B show
- Show system properties and status of a running instance. The output is
- passed on directly from the REST API response and therefore requires parsing
- JSON format.
- .TP
- .B operations
- Control the overall program operation such as restarting or handling
- upgrades, as well as triggering some actions on a per\-folder basis. Can
- also configure the default ignore patterns from a plain text ignore file.
- .TP
- .B errors
- Examine pending error conditions that need attention from the user, or
- acknowledge (clear) them.
- .TP
- .B debug
- Various tools to aid in diagnosing problems or collection information for
- bug reports. Some of these commands access the database directly and can
- therefore only work when Syncthing is not running.
- .TP
- .B \fB\-\fP (a single dash)
- Reads subsequent commands from the standard input stream, without needing to
- call the \fBsyncthing cli\fP command over and over. Exits on any invalid
- command or when EOF (end\-of\-file) is received.
- .UNINDENT
- .SH PROXIES
- .sp
- Syncthing can use a SOCKS, HTTP, or HTTPS proxy to talk to the outside
- world. The proxy is used for outgoing connections only \- it is not possible
- to accept incoming connections through the proxy. The proxy is configured
- through the environment variable \fBall_proxy\fP\&. Somewhat unusually, this
- variable must be named in lower case \- it is not “ALL_PROXY”. For
- example:
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- $ export all_proxy=socks://192.0.2.42:8081
- .EE
- .UNINDENT
- .UNINDENT
- .SH DEVELOPMENT SETTINGS
- .sp
- The following environment variables modify Syncthing’s behavior in ways that
- are mostly useful for developers. Use with care.
- If you start Syncthing from within service managers like systemd or supervisor,
- path expansion may not be supported.
- .INDENT 0.0
- .TP
- .B STTRACE
- Used to increase the debugging verbosity in specific or all facilities,
- generally mapping to a Go package. Enabling any of these also enables
- microsecond timestamps, file names plus line numbers. Enter a
- comma\-separated string of facilities to trace. \fBsyncthing \-\-help\fP always
- outputs an up\-to\-date list. The valid facility strings are:
- .INDENT 7.0
- .TP
- .B Main and operational facilities:
- .INDENT 7.0
- .TP
- .B config
- Configuration loading and saving.
- .TP
- .B db
- The database layer.
- .TP
- .B main
- Main package.
- .TP
- .B model
- The root hub; the largest chunk of the system. File pulling, index
- transmission and requests for chunks.
- .TP
- .B scanner
- File change detection and hashing.
- .TP
- .B versioner
- File versioning.
- .UNINDENT
- .TP
- .B Networking facilities:
- .INDENT 7.0
- .TP
- .B beacon
- Multicast and broadcast UDP discovery packets: Selected interfaces
- and addresses.
- .TP
- .B connections
- Connection handling.
- .TP
- .B dialer
- Dialing connections.
- .TP
- .B discover
- Remote device discovery requests, replies and registration of
- devices.
- .TP
- .B nat
- NAT discovery and port mapping.
- .TP
- .B pmp
- NAT\-PMP discovery and port mapping.
- .TP
- .B protocol
- The BEP protocol.
- .TP
- .B relay
- Relay interaction (\fBstrelaysrv\fP).
- .TP
- .B upnp
- UPnP discovery and port mapping.
- .UNINDENT
- .TP
- .B Other facilities:
- .INDENT 7.0
- .TP
- .B fs
- Filesystem access.
- .TP
- .B events
- Event generation and logging.
- .TP
- .B http
- REST API.
- .TP
- .B sha256
- SHA256 hashing package (this facility currently unused).
- .TP
- .B stats
- Persistent device and folder statistics.
- .TP
- .B sync
- Mutexes. Used for debugging race conditions and deadlocks.
- .TP
- .B upgrade
- Binary upgrades.
- .TP
- .B walkfs
- Filesystem access while walking.
- .TP
- .B all
- All of the above.
- .UNINDENT
- .UNINDENT
- .TP
- .B STBLOCKPROFILE
- Write block profiles to \fBblock\-$pid\-$timestamp.pprof\fP every 20 seconds.
- .TP
- .B STCPUPROFILE
- Write a CPU profile to \fBcpu\-$pid.pprof\fP on exit.
- .TP
- .B STDEADLOCKTIMEOUT
- Used for debugging internal deadlocks; sets debug sensitivity. Use only
- under direction of a developer.
- .TP
- .B STLOCKTHRESHOLD
- Used for debugging internal deadlocks; sets debug sensitivity. Use only
- under direction of a developer.
- .TP
- .B STGUIADDRESS
- Override GUI listen address. Equivalent to passing \fI\%\-\-gui\-address\fP\&.
- .TP
- .B STGUIAPIKEY
- Override the API key needed to access the GUI / REST API. Equivalent to
- passing \fI\%\-\-gui\-apikey\fP\&.
- .TP
- .B STGUIASSETS
- Directory to load GUI assets from. Overrides compiled in assets. Useful for
- developing webgui, commonly use \fBSTGUIASSETS=gui bin/syncthing\fP\&.
- .TP
- .B STHASHING
- Specify which hashing package to use. Defaults to automatic based on
- performance. Specify “minio” (compatibility) or “standard” for the default
- Go implementation.
- .TP
- .B STHEAPPROFILE
- Write heap profiles to \fBheap\-$pid\-$timestamp.pprof\fP each time heap usage
- increases.
- .TP
- .B STNODEFAULTFOLDER
- Don’t create a default folder when starting for the first time. This
- variable will be ignored anytime after the first run. Equivalent to the
- \fI\%\-\-no\-default\-folder\fP flag.
- .TP
- .B STNORESTART
- Equivalent to the \fI\%\-\-no\-restart\fP flag.
- .TP
- .B STNOUPGRADE
- Disable automatic upgrades. Equivalent to the \fI\%\-\-no\-upgrade\fP flag.
- .TP
- .B STPROFILER
- Set to a listen address such as “127.0.0.1:9090” to start the profiler with
- HTTP access, which then can be reached at
- \X'tty: link http://localhost:9090/debug/pprof'\fI\%http://localhost:9090/debug/pprof\fP\X'tty: link'\&. See \fBgo tool pprof\fP for more
- information.
- .TP
- .B STPERFSTATS
- Write running performance statistics to \fBperf\-$pid.csv\fP\&. Not supported on
- Windows.
- .TP
- .B STRECHECKDBEVERY
- Time before folder statistics (file, dir, … counts) are recalculated from
- scratch. The given duration must be parseable by Go’s \fBtime.ParseDuration\fP\&. If
- missing or not parseable, the default value of 1 month is used. To force
- recalculation on every startup, set it to \fB1s\fP\&.
- .TP
- .B STGCINDIRECTEVERY
- Sets the time interval in between database garbage collection runs. The
- given duration must be parseable by Go’s \fBtime.ParseDuration\fP\&.
- .TP
- .B GOMAXPROCS
- Set the maximum number of CPU cores to use. Defaults to all available CPU
- cores.
- .TP
- .B GOGC
- Percentage of heap growth at which to trigger GC. Default is 100. Lower
- numbers keep peak memory usage down, at the price of CPU usage
- (i.e. performance).
- .TP
- .B LOGGER_DISCARD
- Hack to completely disable logging, for example when running benchmarks.
- Set to any nonempty value to use it.
- .UNINDENT
- .SH SEE ALSO
- .sp
- \fBsyncthing\-config(5)\fP, \fBsyncthing\-stignore(5)\fP,
- \fBsyncthing\-device\-ids(7)\fP, \fBsyncthing\-security(7)\fP,
- \fBsyncthing\-networking(7)\fP, \fBsyncthing\-versioning(7)\fP,
- \fBsyncthing\-faq(7)\fP
- .SH AUTHOR
- The Syncthing Authors
- .SH COPYRIGHT
- 2014-2019, The Syncthing Authors
- .\" Generated by docutils manpage writer.
- .
|