Configure your node

Most of your node's settings live in its database, and you change them in the wallet. A few belong to the server it runs on. Those are environment variables, and you set them with a systemd drop-in.

Where settings live

The node reads its environment once, when it starts, and checks every variable before it starts anything. A value it cannot use stops it with a message that names the variable.

systemd drop-ins

The installer puts the node's unit, dassie.service, in /etc/systemd/system/, and each update may replace it. Your own settings go in a drop-in beside it, which updates leave alone.

1. Open the drop-in in your editor:

   $sudo systemctl edit dassie

2. Add a [Service] section with your variables, one Environment= line each, and save:

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

3. Restart the node, so that it reads them:

   $sudo systemctl restart dassie

4. Check that it came up:

   $dassie status

   If it says Dassie is not running., the log says which variable it refused: journalctl -u dassie -n 20.

systemctl cat dassie shows the unit with every drop-in, so you can see what is set.

A value that holds double quotes, such as the JSON of a relay, goes in single quotes around the whole assignment: Environment='DASSIE_RELAY={"id":"…"}'.

On NixOS you set the same variables in your configuration instead: Dassie on NixOS.

Common settings

The full list, with every variable the node reads, is Environment variables. These are the ones operators change most.

How much it logs

DASSIE_LOG says what reaches the journal. It is a level, trace, debug, info, warn, error or off, or directives for parts of the node, separated by commas. The unit sets info.

To hear more from one part without the rest getting louder, name it. Parts the directives don't name stay at info:

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

The node's parts 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 and dassie::hub; dassie alone covers all of them. dassie::front_door and dassie::market_maker belong to dassie front-door and dassie market-maker, and dassie::desktop to the desktop app. The wallet's logs page always keeps the node's last lines at info and above, and also anything more detailed you turn on here.

A relay

A relay lets clients reach your node through another node, even when yours has no public address: a front door is one. A node without a domain name answers Open Payments at <node ID>.dassiepay.net, and the front door there reaches it only through the connection the node keeps to it as its relay.

That front door is the default relay, and it is built into Dassie. With DASSIE_RELAY unset, a node without a domain name connects to it by itself once it is set up, so it is reached at its name there with nothing to set. A node with a domain name answers under that name alone, so it keeps no connection to the default relay, and closes it when dassie init gives it a domain name.

The default has a cost, and it is yours to weigh. The front door at relay.dassiepay.net is a machine the Dassie project runs. It learns when your node is online, from which address, and since when. It also reads the Open Payments requests it passes on to your node, as every front door does. While it is down, nobody reaches your node at its name under dassiepay.net. Peering, sending and the wallet work without it.

To use another relay, name it in DASSIE_RELAY by an entry of four fields: its node ID, its URL and its two public keys. A front door logs its own entry when it starts. Copy it whole:

[Service]
Environment='DASSIE_RELAY={"id":"…","url":"https://relay.example.net","publicKey":"…","slhDsaPublicKey":"…"}'

The node keeps a relay you name whether or not it has a domain name. Its connection is pinned to the entry's keys, so nobody else can stand in for the relay. To keep no relay at all, set it empty:

[Service]
Environment=DASSIE_RELAY=

Then no Open Payments client reaches the node at its name under dassiepay.net. Peering and sending work as before. dassie status shows the relay the node keeps and whether it is connected to it (Uplinks and relay).

The wallet doesn't ask you about the relay yet: you choose it here, in the node's environment. A step in the wallet that explains the choice, and what the default costs, is planned. What's next

Why it works this way: a relay by default only for a node without a domain name, and what it costs.

Uplinks

A periphery node finds the core nodes it connects through, its uplinks, by itself. DASSIE_UPLINKS pins them instead: a comma-separated list of node IDs, at most 128, and the node asks only those.

[Service]
Environment=DASSIE_UPLINKS=sbegzgsyebannd6yz2emrvftva2hipgad57lm4i,i2yhz2nartbnlzgcjn4qavsyeefnpaxx5i6iyli

A node pinned to nodes it cannot reach waits for them and asks no other. A node with a domain name uses the list until it is promoted into the core, and ignores it from then on. More in A server without a public IP.

Extra certificate authorities

The node checks the certificate of every HTTPS and WebSocket server it connects to, such as XRP Ledger servers and Open Payments servers, front doors among them, against the system's trusted roots. Peers and relays need no roots: QUIC checks their node keys instead. DASSIE_EXTRA_CA_FILE names a PEM file of further roots to trust beside those, for a network that uses a certificate authority of its own.

[Service]
Environment=DASSIE_EXTRA_CA_FILE=/etc/dassie-roots.pem

The node runs as a user of its own, in a sandbox that hides home directories, so put the file under /etc and let every user read it (chmod 644).

A proxy

On a network that blocks UDP, a periphery node reaches its uplinks over a WebSocket on their HTTPS port. Only a node without a domain name does this: a core node needs UDP port 443. If it must go through an HTTP proxy for that, it reads https_proxy or HTTPS_PROXY, and no_proxy or NO_PROXY, as other programs do. Only an http:// proxy is used; anything the node cannot use, it warns about at start and goes on without.

Other settings

• DASSIE_PUBLIC_NAMES: more names a node without a domain name answers Open Payments to, separated by commas.
• DASSIE_BOOTSTRAP_NODES: the bootstrap nodes, as a JSON list of entries like a relay's. The testnet's four are built in, so leave it unset to join the testnet. Set it to replace the list, for a network of your own, or to [] to run alone.
• DASSIE_VALIDATOR_CONFIG: the file that turns on validating settlement hubs. See Validate a settlement hub.

Dev switches warn on a public node

Three variables exist for Dassie's own development and tests, and make a node unsafe on the internet:

If any of them is set while the node listens beyond loopback, it warns in its log at every start, naming the variable and what it does, and ending with It is for development; unset it on a public node. If you see that line, remove the variable from your drop-in.

Why it works this way