Documentation / Run your own

Headless daemon

The daemon is easysync running in the background without a window: on a server, on a home lab machine or in a container. It is a full device. Other devices pair with it and send it files, and you operate it with the same command line.

Run it #

easysync daemon

The command runs in the foreground and serves the local interface until you stop it. Under a service manager, start it from the unit:

[Unit]
Description=easysync daemon

[Service]
ExecStart=/usr/local/bin/easysync daemon
Restart=on-failure

[Install]
WantedBy=default.target

This unit is an example, not a hardened product. Run the daemon as the user whose files and clipboard it should handle, not as root. To stop a running daemon:

easysync daemon stop

Other commands, such as easysync pair or easysync send, talk to a running daemon. When there is none, a command starts an engine of its own for the time it runs.

One engine per account #

Exactly one engine owns the state of a user account at a time: the keys, the database and the listening port. A second engine reports that the state is in use. The commands recognise a running daemon on their own.

Keys on a machine without a desktop #

The key store is chosen explicitly. By default easysync uses the key store of the operating system, which on Linux is the Secret Service of a desktop session. A server has none. Select the key file instead:

EASYSYNC_KEY_STORE=file easysync daemon

The file keys.cbor is then created in the state directory with mode 0600. Treat that directory like a private key: restrict access to it and keep it out of backups that others can read. On Linux you can set key_store = "file" in config.toml instead. easysync never falls back to another store when the chosen one is unavailable, so the store cannot change unnoticed.

Options #

These options belong to the commands that start an engine, the daemon first:

  • --listen <address> sets the address of the QUIC listener. The default is the preferred port on all addresses, or any free port. The same setting exists as listen in config.toml.
  • --no-discovery switches off discovery on the local network. This is discovery = false in config.toml.
  • --no-clipboard stops the daemon from using a desktop clipboard. This is clipboard = false in config.toml. A daemon in a container or on a server has no clipboard to use.
  • --incoming-dir <folder> sets the folder for accepted files. It is also the run-time setting incoming_dir.
  • --relay-ca <file> adds a certificate authority for relays with a private certificate (What the relay sees says what a relay sees). It may be given more than once.

The precedence is: an option, then an environment variable, then config.toml, then the built-in default. The file is read once at start. Configuration file lists the keys.

The local interface #

The daemon serves a local interface for the command line and the apps: a Unix socket (on Linux in the runtime directory of your session, or in the state directory when there is none; on macOS in the state directory) and a named pipe on Windows. The commands check that the endpoint belongs to your user account before they send anything to it.

In a container #

The pipeline builds a daemon image that runs easysync daemon as a non-root user and stores everything below one volume. What is published of the images is stated on the page Relay. The volume is the secret of the device. See the notes on running the daemon in Hardening and the ports in Network and ports.