Files, ports and sockets

Where Dassie keeps what it keeps, and where it listens. Use it to open your firewall, plan a backup, or find a file when something goes wrong.

Ports

A server node, as the installer sets it up, listens on four ports:

QUIC listens at the same port number as HTTPS, since peers dial QUIC at the port in the node's URL. Under systemd the node stops at start if the two differ. Open all four in your firewall, inbound, on IPv4 and IPv6. On NixOS, services.dassie.openFirewall does it.

Run standalone, with dassie daemon --runtime standalone, a node binds the same ports itself, or those --http-port, --https-port and --feed-listen give. QUIC then follows the HTTPS port, and the snapshot's socket listens on the HTTPS listener's address at port 7768.

Going out

A node also makes connections of its own:

• QUIC over UDP to other nodes, at the port in each one's URL, usually 443.
• QUIC over UDP to its relay: by default, while the node has no hostname, the front door at relay.dassiepay.net, on port 443.
• A WebSocket over TCP 443 to its XRP Ledger server, by default the project's proof servers.
• HTTPS to the testnet faucet, to validator list publishers, to Let's Encrypt, and, for dassie update, to get.dassie.land.
• HTTPS to the Open Payments servers of the wallets you pay, on any host.

A node without a public IP needs no inbound port at all: it dials out to its uplinks, and to its relay, relay.dassiepay.net unless DASSIE_RELAY names another or none. Where UDP does not get through, it carries QUIC over a WebSocket on TCP 443 instead, through an HTTP proxy if https_proxy names one. Only a node without a hostname falls back this way; a node with one needs UDP. See A server without a public IP.

The desktop app

The desktop app's node listens for HTTPS on localhost only, at a port it picks once and keeps, so that the wallet's address stays the same. If another program took that port, it picks a new one. It has no HTTP listener and no socket for snapshot requests. QUIC listens on every address, at a port the system picks, and only dials out: to its uplinks, and to its relay, relay.dassiepay.net by default. See How others reach you.

A front door

dassie front-door listens on TCP 443 for HTTPS and on UDP 443 for the nodes it relays, unless DASSIE_FRONT_DOOR_HTTPS_LISTEN and DASSIE_FRONT_DOOR_QUIC_LISTEN say otherwise.

The IPC socket

The dassie command talks to the node over a Unix socket. Whoever may use it administers the node.

The command tries DASSIE_IPC_SOCKET_PATH alone if it is set, and otherwise /run/dassie.sock, then $XDG_RUNTIME_DIR/dassie.sock. So dassie status finds a desktop app's node too.

The data directory

Everything that is your node lives in one directory: its key, its certificate and its books. Under the installer's unit that is /var/lib/dassie. systemd runs the node as a user it makes for it, so the files really sit in /var/lib/private/dassie, which /var/lib/dassie links to. Run any other way, the node uses DASSIE_STATE_DIRECTORY, then systemd's STATE_DIRECTORY, then $XDG_DATA_HOME/dassie, then ~/.local/share/dassie. The desktop app's node uses the same, so its data is usually in ~/.local/share/dassie.

The directory is 0700 and the database 0600; the node tightens looser modes at start.

dassie.sqlite3

The database: the node key, the TLS key and certificate, the ACME account, the books, the peers and every setting from the wallet. SQLite keeps dassie.sqlite3-wal and dassie.sqlite3-shm beside it while it runs.

dassie.lock

Held by the running node, so that a second node on the same directory refuses to start. The lock goes with the process, so a crash leaves none behind.

dassie.sqlite3.pre-migration

A copy of the database from just before a new version changed its layout, which a rollback may put back.

dassie.sqlite3.rolled-back

After a rollback that put the copy back: the database the new version left, kept for you to look at.

dassie.sqlite3.rolling-back

Only while a rollback runs. If you find it without a dassie.sqlite3, a rollback stopped halfway. The node then refuses to start, rather than start afresh with a new identity, until you put a database in place as dassie.sqlite3 or remove this file.

events.jsonl, events.jsonl.1 to .4

Only if you set DASSIE_EVENT_LOG to a relative path, here events.jsonl: the event log and its rotated files, 0600, a record of the payments through your node.

Your recovery phrase is not in it: the node gets only the key derived from it. How to copy the directory safely is in Back up and move a node.

Install layout

What the installer puts where:

/opt/dassie/<version>/

One directory per version: bin/dassie, the one binary, and share/systemd/, that version's units. An update keeps the version it came from beside the new one, for a rollback, and removes older ones.

/opt/dassie/current

A link to the version that runs, switched in one step. The units run what it names.

/opt/dassie/last-update

How the last update went, which dassie status shows.

/opt/dassie/.update.lock

Held by dassie update and the installer, so that only one of them runs at a time.

/usr/local/bin/dassie

A link to /opt/dassie/current/bin/dassie.

/etc/systemd/system/

The units: dassie.service, its five sockets dassie-http.socket, dassie-https.socket, dassie-ipc.socket, dassie-quic.socket and dassie-feed.socket, and dassie-update.service with dassie-update.timer, which looks for an update once a day, at a random time in the hour after 03:20. Your own changes go in drop-ins, which updates leave alone. With install.sh --no-service, the installer puts no units here, for a host that runs the node under units of its own; then dassie update --unit restarts those.

The group dassie-users

Its members may use the IPC socket.

Uninstalling removes all of these but the group, and leaves the data directory where it is; see Uninstall. On NixOS the binary and units come from the Nix store, there is no /opt/dassie and no updater, and the data directory is the same; see Dassie on NixOS.

Why the layout never changes

Desktop app files

Besides its node's data directory, the desktop app keeps its own files, readable by you alone:

~/.local/share/land.dassie.desktop/

The app's data directory: ports, the HTTPS port it keeps, start-at-login, your choice whether it starts when you log in, and the window's cookies, cache and storage. The session cookie lets whoever reads it use your wallet, so the app keeps this directory at 0700.

~/.config/autostart/land.dassie.desktop.desktop

The entry that starts the app in the tray when you log in, under $XDG_CONFIG_HOME if you set it.

Front door files

The unit in resources/front-door/ runs a front door as the user dassie-front-door, with its key in /var/lib/dassie-front-door/front-door.key and its certificate in /etc/dassie-front-door/tls/fullchain.pem and privkey.pem. See Run a front door.