Run your node as a service

1Before you start

This page is for Linux computers that use systemd, which includes Ubuntu, Debian and Fedora. We tested it on Ubuntu 22.04. You need sudo rights.

You also need a node that already runs when you start it by hand. If you have not got that far, follow Install IronDivi or Install the Divi node first, then stop the node before you go on.

You need three facts for the service file. Find them now:

whoami                      # the user the node runs as
command -v irondivid divid  # where the program is, if it is on your PATH
ls -d ~/.irondivi ~/.divi   # the data folder

Below, alice stands for your user name and /home/alice for your home folder. Replace both everywhere, and use full paths: a service does not know what ~ means.

2A service file for IronDivi

Create the file with sudo nano /etc/systemd/system/irondivid.service and paste:

[Unit]
Description=IronDivi node (testnet)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=alice
ExecStart=/home/alice/irondivi/irondivi-x86_64-linux-musl/irondivid --testnet --datadir /home/alice/.irondivi/testnet
KillSignal=SIGTERM
TimeoutStopSec=120
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

• After and Wants wait for the network before starting the node.
• User runs the node as you, not as root, so it can read your data folder.
• ExecStart is the command you used by hand. For the real network leave out --testnet and use /home/alice/.irondivi.
• KillSignal=SIGTERM is the polite stop signal. IronDivi saves its work and exits when it gets it. irondivi-cli stop does not stop IronDivi 0.2.5, so the service does not use it.
• TimeoutStopSec=120 gives the node two minutes to finish before systemd kills it.
• Restart=on-failure starts the node again 10 seconds after a crash, but not after you stop it yourself.
• WantedBy=multi-user.target is what makes it start at boot once you enable it.

3A service file for the original node

For divid, create /etc/systemd/system/divid.service instead:

[Unit]
Description=Divi node (testnet)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=alice
ExecStart=/home/alice/divi/divi-3.0.0/bin/divid -datadir=/home/alice/.divi -daemon=0
ExecStop=/home/alice/divi/divi-3.0.0/bin/divi-cli -datadir=/home/alice/.divi stop
TimeoutStopSec=300
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

The network comes from divi.conf: testnet=1 in the file means testnet. Two lines differ from IronDivi's file:

• -daemon=0 keeps the node in the foreground. Many guides put daemon=1 in divi.conf. Under systemd that breaks the service: the node hands itself to a background copy and exits, systemd thinks the service has finished, and it stops the background copy too. We tried it, and within seconds the service was inactive (dead) and no node was running. -daemon=0 on the command line wins over the file.
• ExecStop stops the node with divi-cli stop, which works on the original node. TimeoutStopSec=300 gives it five minutes, because it can take far longer to stop than IronDivi.

4Switch it on

Make sure the node you started by hand is stopped. Then:

sudo systemctl daemon-reload
sudo systemctl enable --now irondivid     # or divid
systemctl status irondivid

daemon-reload makes systemd read the new file. enable starts the node at every boot and --now also starts it straight away. The status should say active (running).

Check the node answers, exactly as before:

irondivi-cli --testnet --datadir /home/alice/.irondivi/testnet getblockcount

We did not reboot our test machine, because other services run on it. enable is the standard way to start a service at boot, and systemctl is-enabled irondivid printing enabled confirms it is set.

5Status, logs, stop and start

systemctl status irondivid            # running or not, since when, main process
sudo systemctl stop irondivid         # stop the node properly
sudo systemctl start irondivid        # start it again
sudo systemctl restart irondivid      # both, for example after editing the settings file
journalctl -u irondivid -n 50         # the last 50 lines systemd recorded

How long a stop took on our testnet nodes:

Both logs ended with a clean shutdown: IronDivi wrote IronDivi shutdown complete, and the original node started next time with Last shutdown was prepared: true.

The journal holds only what the node prints. IronDivi writes its real log to debug.log in the data folder and the original node writes to debug.log in its network folder, so look there for detail. The original node does print its startup errors to the journal, which helps with the next section.

6What happens after a crash

We crashed both nodes on purpose with kill -9, the signal a program cannot catch. That is close to what a power cut does.

IronDivi was started again 10 seconds later and carried on from the same height. NRestarts went to 1.

The original node behaved differently depending on timing:

• Killed six seconds after a start, before any new block arrived, it came back cleanly on the first restart.
• Killed after it had been running for two minutes and taken in new blocks, the first restart failed. The journal showed:

divid[984302]: Error: Error loading block database : Block database corruption detected! Failed to find best block in block index
tutf-divid.service: Main process exited, code=exited, status=1/FAILURE
tutf-divid.service: Scheduled restart job, restart counter is at 3.

Ten seconds later systemd tried again, and that start succeeded. The node caught up, and divi-cli verifychain 3 1000 answered true.

journalctl -u divid | grep -i corruption

To see how many times systemd restarted a node:

systemctl show -p NRestarts irondivid

7Remove the service

sudo systemctl disable --now irondivid
sudo rm /etc/systemd/system/irondivid.service
sudo systemctl daemon-reload

This stops the node and stops it from starting at boot. It does not touch the data folder or the wallet.

If something goes wrong

Next: upgrade a node without losing anything, or run it in Docker instead.