Back up and move a node

Your node keeps everything in one directory, and your recovery phrase brings back what matters most. This page shows what to keep safe, and how to move a node to a new server.

Your phrase and your data

Two things make up a node:

• Your recovery phrase, which only you keep. The node's identity derives from it: its node ID, and the keys of its accounts on the XRP Ledger and in its settlement hubs. Set up a new node with the same phrase, and it is the same node to the network, with the same accounts. Your recovery phrase explains it.
• The node's data, which the node keeps. It holds everything else: the node's books with each peer, its payments, its peerings, the ledgers and hubs it uses, your settings, grants, API keys and paired devices, and its certificate.

So keep your phrase safe above all, and back up the data too: the phrase alone brings the node back with empty books.

The data directory

On a server set up with the installer, the data is in /var/lib/dassie. systemd runs the node as a user it makes for it, so that path links to /var/lib/private/dassie, where the files really are. Only that user, and root, can read them.

The desktop app keeps the same files in your home, in ~/.local/share/dassie. A node started by hand looks for DASSIE_STATE_DIRECTORY first. Files, ports and sockets lists every file.

If you turned on the event log with a relative path, it lives in the same directory, and a backup carries it too: up to five times DASSIE_EVENT_LOG_MAX_BYTES of records of the payments through your node. Leave it out with --exclude='dassie/events.jsonl*' if you named it so.

The data holds the node key

The node has to sign and settle while nobody watches, so it needs the key at hand; a key to unlock it, stored next to it, would protect nothing. What the node can keep as hashes, it does: the tokens of your wallet sessions, of BTP clients and of Open Payments grants. The directory is readable by the node's user alone, and the database file too.

Why it works this way

Make a backup

Stop the node, so that the copy is whole, and copy the directory. The node is socket-activated: systemd starts it again when a connection arrives, so stop its sockets as well, and the updater, so that no update starts meanwhile:

$sudo systemctl stop dassie-update.timer dassie.service dassie-http.socket dassie-https.socket dassie-ipc.socket dassie-quic.socket dassie-feed.socket
$sudo tar -C /var/lib/private -czpf /root/dassie-data.tar.gz dassie
$sudo systemctl start dassie.service dassie-update.timer

Starting dassie.service starts its sockets too. The node is down for as long as the copy takes, which for a small database is a few seconds. Packets that were on their way through it fail, as in any restart.

Move the archive somewhere safe, encrypted, over SSH or another channel you trust, and remove it from the server once you have.

Move a node with its data

This moves the node whole: the new server runs the same node, with its books, peerings and settings.

1. On the new server, install Dassie as in the Quick Start, but don't run dassie init or set the node up. Then stop it:

   $sudo systemctl stop dassie-update.timer dassie.service dassie-http.socket dassie-https.socket dassie-ipc.socket dassie-quic.socket dassie-feed.socket

2. On the old server, stop the node and copy its data, as in Make a backup, but don't start it again. Disable it, so that a reboot doesn't start it either:

   $sudo systemctl disable dassie-update.timer dassie.service dassie-http.socket dassie-https.socket dassie-ipc.socket dassie-quic.socket dassie-feed.socket

3. Copy the archive to the new server, and put it in place of the empty node the install made:

   $sudo rm -rf /var/lib/private/dassie
   $sudo tar -C /var/lib/private -xzpf dassie-data.tar.gz
   $sudo systemctl start dassie.service dassie-update.timer

   systemd gives the files to the node's user as it starts.

4. Point your domain name at the new server. The certificate came along in the database, and renews there once the name points at it. If the node gets a new domain name, set it with sudo dassie init --hostname <name> (Changing the domain name).

5. Check that it is the same node: dassie status shows the node ID it had before.

6. Once the new server runs well, uninstall Dassie from the old one and delete its data there.

If you set environment variables in a drop-in, such as DASSIE_RELAY or DASSIE_UPLINKS, copy the drop-in too: it lives in /etc/systemd/system/dassie.service.d/, not in the data.

The new server may run a newer release than the old one: it reads an older node's database and brings it up to date. The other way round doesn't work, since a release refuses a database newer than it knows. Data from the releases before 0.3.0, which ran the early test network, doesn't carry over at all: a node from those releases is set up again with a new phrase, and starts with empty books (A node from the 0.2 releases).

Start again from your phrase

If the data is lost, set up a new node with your recovery phrase. Install as in the Quick Start, and when the setup page asks for a phrase, enter yours rather than making a new one; or, on a node nobody logs in to, use dassie setup (Headless setup).

This works with a phrase of 20 words. A phrase of 12 or 24 words is from a release before 0.3.0, which reset the test network. The wallet and dassie setup refuse it, as they refuse every phrase in the BIP-39 format other wallets use. That node can't be brought back: set one up with a new phrase instead.

The new node has:

• the same node ID, so the network knows it as the node it was;
• the same XRP Ledger accounts, with what they hold, and the same keys for its accounts in settlement hubs;
• the same Open Payments key, so other wallets know it as before.

It starts with empty books: no peerings, no record of what peers owed it or it owed them, no payment history, and none of your settings, grants, API keys or paired devices. Add your ledgers and hubs again, and give the node your domain name again with dassie init. On the test network, dassie setup joins the XRP hub for you, unless you name other hubs with --hub.

Make sure the old node is gone for good first: a node set up from the same phrase is the same node, and two of them must never run at once.

How the database works, and why one directory holds one node.