Environment variables

Most of a node's settings live in its database, and you change them in the wallet. A few are read from the environment when the node starts. This page lists every one, what it does, and its default.

Setting them

The node reads its environment once, at start, and checks every variable before anything else runs. A value it cannot use stops it with a message that names the variable, so you see the mistake at once rather than later. After a change, restart the node.

On a server installed with the installer, put variables in a drop-in for dassie.service, which updates leave alone. sudo systemctl edit dassie opens one:

[Service]
Environment=DASSIE_LOG=info,dassie::peer=debug

$sudo systemctl restart dassie

On NixOS, use services.dassie.environment and services.dassie.log; see NixOS module options. The desktop app reads the same variables as a server node, from the environment it was started in.

For the node, a path that is set but empty counts as unset. A switch is 1 for on and 0 or unset for off; anything else stops the node. dassie update takes its variables as they are, so leave one of them unset rather than empty: an empty DASSIE_MIRROR_URL is an error there.

The node

Read by dassie daemon and the desktop app. The commands that talk to the node read DASSIE_IPC_SOCKET_PATH too.

DASSIE_LOG

What the node writes to standard output. A level for everything: trace, debug, info, warn, error or off. Or, separated by commas, a level for a part of the node, as <target>=<level>, beside a level for the rest: info,dassie::peer=debug. A directive for a target covers everything beneath it, so dassie=debug turns up all of Dassie's own lines but not its libraries'. At most 64 directives.

The targets are dassie::daemon, dassie::database, dassie::http, dassie::ipc, dassie::acme, dassie::auth, dassie::rpc, dassie::systemd, dassie::engine, dassie::btp, dassie::peer, dassie::routing, dassie::payment, dassie::settlement, dassie::hub, dassie::front_door, dassie::market_maker and dassie::desktop.

Default: info. The installer's unit sets info. The wallet's log page shows info and above whatever this says. Also read by dassie front-door and dassie market-maker.

DASSIE_STATE_DIRECTORY

The data directory, which holds the database with the node's key and books. If unset, the node takes systemd's STATE_DIRECTORY (its first entry), then $XDG_DATA_HOME/dassie, then ~/.local/share/dassie. Under the installer's unit that is /var/lib/dassie.

dassie update reads it too, as the data directory of dassie.service, whose database a rollback may put back. There its default is /var/lib/dassie.

DASSIE_IPC_SOCKET_PATH

The IPC socket the node listens on when it binds its own sockets, and the one the dassie command connects to. If unset, a standalone node uses $XDG_RUNTIME_DIR/dassie.sock, or else /run/dassie.sock, and the command tries /run/dassie.sock, then $XDG_RUNTIME_DIR/dassie.sock. Under systemd the socket unit decides: /run/dassie.sock.

DASSIE_BOOTSTRAP_NODES

The nodes the node asks about the network, and whose name lists it reads. A JSON list of at most 64 entries, each naming a node by its ID, its URL and its two public keys:

[{"id":"<node ID>","url":"https://boot.example.net","publicKey":"<base64url>","slhDsaPublicKey":"<base64url>"}]

The URL must be https://, and each ID must be the one its keys give, or the node does not start. So does a node listed twice. [] makes the node run alone. A front door reads it too, for the registrars whose name lists it reads.

Default: the public testnet's five bootstrap nodes, boot1.dassie.xyz to boot5.dassie.xyz, built into the binary. Leave it unset to join the testnet.

DASSIE_RELAY

The relay the node keeps a connection to, so that others reach it through the relay, even without a public address. A node keeps one relay at a time. A relay is named by one entry in the format of DASSIE_BOOTSTRAP_NODES, without the brackets; a front door prints its own with dassie front-door --make-key.

• Unset, the default: the dassiepay.net front door, at relay.dassiepay.net, whose entry is built into the release. The node keeps it only while it has no hostname, so that it is reached at <node ID>.dassiepay.net and at its names there. The desktop app's node and a server without a public IP keep it. A node you give a hostname with dassie init closes the connection, and dials again if the hostname is cleared.
• An entry: that relay, kept whether or not the node has a hostname. If it names a relay outside dassiepay.net, the dassiepay.net front door no longer reaches the node, and the wallet says so beside its dassiepay.net address.
• Empty: no relay. The node still dials its uplinks and pays, but no payment reaches it at its dassiepay.net names, and the wallet says so.

An entry naming the node itself keeps none and says so in the log. dassie status shows the relay the node keeps, and whether it is connected.

What the default costs. The front door is a machine the project runs. While your node keeps it, that machine learns when your node is online, and from which address. It also reads the Open Payments requests and answers it passes on, as every front door does. Your node signs its answers, so a client that checks the signature can tell if the front door made one up. Other Open Payments clients take what the front door passes on. If that isn't for you, set DASSIE_RELAY empty, or name a front door you trust.

Why there is a default relay

DASSIE_PUBLIC_NAMES

For a node without a hostname: more names it answers Open Payments under, beside its name at the default front door. Host names, separated by commas, each once, at most 16, such as another front door's name for the node, or a domain of yours that a front door passes on. A node with a hostname answers under that alone. Default: none.

DASSIE_UPLINKS

For a periphery node: the only core nodes it asks to be its uplinks, by node ID, separated by commas, each once, at most 128. The node looks for as many uplinks as you name, and asks no other node. A node with a domain name uses the list until it is promoted into the core; a core node ignores it. A market maker's node names the core nodes it trades through here. Default: none, so the node picks its uplinks itself. See A server without a public IP.

DASSIE_VALIDATOR_CONFIG

A JSON file, at most 256 KiB, that has the node validate settlement hubs: the sponsors it validates for, the XRP Ledger network, the XRP Ledger server it follows escrows on, the validator list publishers, and hubs written in by hand. It is read and checked at start; a file that is wrong stops the node. A network of real money is refused. Default: unset, and the node validates nothing. See Validate a settlement hub.

DASSIE_EVENT_LOG

A file to which the node appends every packet it handles and every event of its settlement hubs, one JSON object per line, for an owner who chooses to record their own node's traffic: to debug it, show it or study a network. It records the amounts, addresses and peers of other people's payments through your node, so it is off unless you set it, and no release, installer or dassie setup turns it on. A relative path is taken in the state directory, so events.jsonl works under the installer's unit. The file is readable by the node's user alone (0600). Once it would grow past DASSIE_EVENT_LOG_MAX_BYTES, it is renamed to <file>.1, the older ones move up to <file>.4, and the oldest is deleted, so the log takes at most five times that. Writing never holds up a payment: what the node cannot write in time it counts in a lost line. A file the node cannot open stops it at start. Default: unset, and nothing is recorded. The line format is in the spec.

DASSIE_EVENT_LOG_MAX_BYTES

The size, in bytes, at which the event log is rotated: from 1 MiB (1048576) to 64 GiB. Default: 64 MiB (67108864).

Installer and updater

Read by install.sh and dassie update.

DASSIE_MIRROR_URL

The mirror releases come from, https:// only. The --mirror option overrides it. Default: https://get.dassie.land. Whatever the mirror, releases must be signed with the release key built into the binary; see Release mirror and key.

DASSIE_MIRROR_CA_FILE

A PEM file of more root certificates to trust the mirror's HTTPS by, beside the system's: for a mirror of your own with a private CA. dassie update only. Default: none.

DASSIE_SYSTEMD_UNIT_DIR

Where dassie update installs a release's systemd units. Default: /etc/systemd/system.

Front door

Read by dassie front-door, beside DASSIE_LOG, DASSIE_BOOTSTRAP_NODES, DASSIE_DEV_TIMINGS and DASSIE_PEER_ALLOW_PRIVATE. Each DASSIE_FRONT_DOOR_* variable below has an option that overrides it. See Run a front door.

DASSIE_FRONT_DOOR_DOMAIN

The domain it serves nodes under, as <node ID>.<domain>, of at least two labels. Default: dassiepay.net.

DASSIE_FRONT_DOOR_HTTPS_LISTEN

The address and TCP port for HTTPS. Default: [::]:443.

DASSIE_FRONT_DOOR_QUIC_LISTEN

The address and UDP port nodes reach it at over QUIC. Default: [::]:443.

DASSIE_FRONT_DOOR_CERTIFICATE

Required. The PEM certificate chain for *.<domain>, leaf first.

DASSIE_FRONT_DOOR_CERTIFICATE_KEY

Required. The certificate's PEM key.

DASSIE_FRONT_DOOR_KEY_FILE

The front door's own key, which its node ID comes from. Default: front-door.key in systemd's STATE_DIRECTORY; without either, it does not start.

DASSIE_FRONT_DOOR_RELAY_URL

The URL nodes dial its QUIC endpoint at, as https://host[:port], which goes into the entry it prints for DASSIE_RELAY. Default: https://relay.<domain>.

Testing and development

These make a node trust or reach what a public node should not. If DASSIE_PEER_ALLOW_PRIVATE, DASSIE_DEV_TIMINGS or DASSIE_DEV_LIVE_REALM is set while the node listens beyond loopback, it warns at start, naming the variable; a front door warns of the first two. A node serving DASSIE_DEV_WALLET_DIR says so in its log.

DASSIE_ACME_CA_FILE

A PEM file of a root the node's ACME client trusts, for a test CA such as Pebble. Default: none.

DASSIE_EXTRA_CA_FILE

A PEM file of roots the node trusts, beside the system's, for the HTTPS and WebSocket servers it reaches: ledger servers, rate sources and Open Payments servers, front doors among them. Peers and relays need none, since QUIC checks their node keys. For a dev or test CA. Default: none.

DASSIE_PEER_ALLOW_PRIVATE

Dev only. 1 lets the node reach peers, ledgers and other servers at private and loopback addresses, such as localhost. Default: off.

DASSIE_DEV_TIMINGS

Dev only. 1 runs the peer protocol and the peg guard on dev timers, polling, settling and reading pools every second. Default: off.

DASSIE_DEV_LIVE_REALM

Dev only. 1 lets a node be set up in the live realm, for development and tests against a fake ledger. Only a build with debug assertions takes it. A release refuses to start with it set, since the live realm is not supported yet.

DASSIE_DEV_CORE_NODES

Dev only. Node IDs, separated by commas, that a dev network counts as core nodes from the start, without the time it takes to be promoted. Every node of the network is given the same list. Only a build with debug assertions takes it. A release refuses to start with it set. Default: none.

DASSIE_DEV_WALLET_DIR

Dev only. An absolute path to a directory that exists, holding a build of the wallet, which the node serves instead of the one built into the binary. The dev environment points it at a watch build. Default: none.

The local dev network sets these for you.

Build time

Read when the binary is built, not when it runs. See Contributing.

DASSIE_BUILD_VERSION

The version the binary names, as a release build stamps it. Without it, the workspace's version.

DASSIE_RELEASE_KEY

A minisign public key file the binary trusts for updates. Without it, resources/minisign.pub. A key that is missing or does not parse fails the build.

DASSIE_WALLET_DIST

The wallet's build output, which the binary embeds. A binary built without it fails dassie verify-install.

Other variables

Variables the node reads that other programs set too.

Why dev switches warn