Documentation / Run your own

Hardening

Recommendations for people who run a relay or a daemon for others or on exposed machines. They restate the rules that the software and the container images follow; they do not replace reading the documentation of your operating system and of your container platform.

What easysync does for itself #

Every easysync program that holds keys or relay tokens turns off core dumps at its start, before it reads a key or opens the network, and on Linux and Android also refuses attachment by unprivileged processes of the same user (a process with root rights is not stopped). There is no switch to turn this off. On macOS and iOS attaching is not refused. On Windows the protection against dumps is not in place in this version, and the page Limits and open items lists this. Keep this in mind when you decide which machine holds an identity.

Relay #

What an operator and everybody on the path can see is on What the relay sees.

  • Use TLS. Let the relay terminate TLS, or put a reverse proxy in front and set allow_plain_ws = true only then, on a network that nobody else can reach. A relay with neither refuses to start, so a forgotten certificate cannot expose the access token.
  • Keep the token secret. The token is a file, not an argument or a variable. Make it from at least 16 random bytes and give the file mode 0400. Rotate it by adding a second token file, restarting the relay, moving the devices to the new token and then removing the old file.
  • Keep the health port on loopback. It is plain HTTP and serves nothing else. The relay refuses an address that is not loopback.
  • Run it with as few rights as possible. The image runs as a non-root user with a read-only root file system and no capabilities. If you run the binary under systemd, use these restrictions: a dynamic user, no new privileges, a private temporary directory, a strict file system view, no address families beyond IP and Unix sockets, a system call filter, and limits on memory and file handles.
  • Size the memory. The memory the relay can use is bounded by the buffer per direction of each pipe times the number of pipes. Set docker run --memory or MemoryMax from your max_sessions and pipe_buffer_bytes.
  • Mind your logs. The relay writes no payload and no identifiers to its logs, only start-up messages, errors and counters. A reverse proxy or a host may log more. Configure a proxy not to log the paths of WebSocket upgrades nor the header that carries a browser's token. If you keep such logs, tell your users: they are metadata about who connects to the relay and when.
  • Limits. The defaults limit connections, rates and sessions. Per-source limits apply to the address of your proxy when one is in front.
  • One instance. The relay keeps its state in memory.

Daemon #

  • The state directory is a secret. It holds the database and, when the key file is in use, the identity. Give it to one user, mode 0700; keep it out of shared backups. In the image the volume is the secret of the device.
  • The local interface belongs to its user. The socket or pipe can be used only by the same account. Do not change its permissions and do not forward it to other machines.
  • Do not share an account. Anyone who can run commands as the same user can read what the device receives and change who it trusts.
  • Containers. Run the image with a read-only root file system, --cap-drop ALL, --security-opt no-new-privileges and a writable /tmp for temporary files of the database.
  • Reset before you hand a machine on. Uninstalling the desktop app or the daemon package does not delete keys or state. See Reset and recovery.