Back to WG0A main page

Dire Wolf service management

Use systemd to start and supervise Dire Wolf

This page explains two working systemd unit files and why they are usually a better long-term choice for stability, supportability, and debuggability when running Dire Wolf on a Linux system. The single-instance service is simpler, while the multi-instance template service is more flexible.

Referenced gists

1) Single-instance service: direwolf.service gist

2) Multi-instance template service: direwolf@.service gist

Supportability and debuggability advantages

The biggest day-2 operations win with systemd is that service behavior, health, and logs are all visible through standard tools. This reduces hand-maintained scripts and the amount of "tribal knowledge" needed to support a station over time.

Topic systemd service crontab + script
Automatic restart Built in (Restart=always, RestartSec=15) Usually custom script logic or no restart
Boot ordering Explicit dependencies (After=network.target, After=rigctld.service) Harder to guarantee services are available when script runs
Logging journalctl -u ..., built-in history and follow mode Manual redirects, rotating logs, and troubleshooting overhead
Operational control start, stop, status, enable Often ad-hoc process management with shell commands and screen attach/detach
Least privilege Run as non-root user via User= and Group= Easy to accidentally run with broader privileges
Multi-instance support Native with template units like direwolf@.service Requires separate scripts and process tracking per instance
Operator handoff Any operator can run the same standard commands to see status, logs, and restart history. Operators must know the local script path, cron entry, and screen session naming convention.

Option A: Single-instance service

Use this when you have one Dire Wolf config and one running process. 

[Unit]
Description=Direwolf Sound Card-based AX.25 TNC
After=network.target
After=sound.target

[Service]
Type=simple
User=pi
Group=pi
WorkingDirectory=/opt/direwolf/
ExecStart=/usr/local/bin/direwolf -t 1 -a 600 -c direwolf.conf
Restart=always
RestartSec=15

[Install]
WantedBy=multi-user.target

Example: starting direwolf uses /opt/direwolf/direwolf.conf.

Option B: Multi-instance template service

Use this when you want multiple named Dire Wolf instances with different config files. 

[Unit]
Description=Direwolf %i Service
Documentation=https://github.com/wb2osz/direwolf/blob/dev/doc/README.md
After=network-online.target
Wants=rigctld.service
After=rigctld.service

[Service]
Type=simple
User=pi
Group=pi
WorkingDirectory=/opt/direwolf/
ExecStart=/usr/local/bin/direwolf -a 200 -qd -c direwolf-%i.conf
Restart=always
RestartSec=15

[Install]
WantedBy=multi-user.target

Example: starting direwolf@vhf uses /opt/direwolf/direwolf-vhf.conf.

For a second instance, direwolf@hf uses /opt/direwolf/direwolf-hf.conf.

Using Wants=rigctld.service makes rigctld optional. Dire Wolf will still start if rigctld is not installed or not enabled.

Install and enable

For single instance

sudo cp direwolf.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now direwolf
sudo systemctl status direwolf

For template instances

sudo cp "direwolf@.service" /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now direwolf@vhf
sudo systemctl status direwolf@vhf

Logs and troubleshooting

# Single instance logs
journalctl -u direwolf -f

# Template instance logs
journalctl -u direwolf@vhf -f

Keep After=rigctld.service when PTT depends on rigctld. Use Requires=rigctld.service only if you want Dire Wolf startup to fail when rigctld is unavailable.

Seeing terminal-style text with journalctl

If you like the colored terminal view from screen, you can keep most of that experience with systemd and journalctl. 

# 1) Keep -t 1 in ExecStart so Dire Wolf emits ANSI color
ExecStart=/usr/local/bin/direwolf -t 1 -a 600 -c direwolf.conf

# 2) Follow logs in a cleaner, terminal-like format
journalctl -u direwolf -f -o cat --all

# 3) For template instances
journalctl -u direwolf@vhf -f -o cat --all

If colors do not appear, try --no-pager and confirm your terminal emulator supports ANSI colors.

Systemd vs screen session debugging

Running Dire Wolf under screen can work, but debugging typically spans several moving parts: cron invocation, shell script logic, process state, and terminal multiplexing. Systemd centralizes those signals into one service record.

A key supportability advantage: if Dire Wolf exits, the screen session may disappear with the error text that was on screen. With systemd, stdout/stderr is captured in journald and remains available after the process exits.

Debug task systemd workflow crontab + screen workflow
Did startup fail? systemctl status direwolf immediately shows exit code, last logs, and unit state. Check cron fired, check script path/permissions, verify screen session exists, then inspect script output if captured.
Find recent errors journalctl -u direwolf --since "-15 min" gives a time-bounded log view. Need to locate cron logs, shell history, screen scrollback, and any custom log files.
Follow live behavior journalctl -u direwolf -f is the standard live tail. Must attach to the correct screen session and detach safely; output can be missed if the session is recreated.
Post-crash evidence retention journalctl -u direwolf --since "-1 hour" preserves crash messages even after service exit/restart. If Dire Wolf exits and the screen session terminates, error output can be lost unless separately redirected to a log file.
Root-cause restart loops Restart policy and cadence are explicit in one place (Restart=always, RestartSec=15). Restart behavior often buried in script logic, making loops harder to reason about.
See which command actually started systemctl show direwolf -p ExecStart,FragmentPath shows exact unit command and source file. Need to inspect crontab, then inspect dw-start.sh, then inspect any nested shell calls from that script.
Dependency visibility Unit declares ordering/dependencies with After=/Wants=/Requires=. Script usually has implicit assumptions (network, audio, rigctld) with less clear failure signals. 
# Fast systemd debug checklist
systemctl status direwolf@vhf
journalctl -u direwolf@vhf --since "-30 min"
journalctl -u direwolf@vhf -f
systemctl show direwolf@vhf -p ActiveState,SubState,ExecMainStatus,FragmentPath

# Equivalent screen-oriented checks often needed for comparison
crontab -l
screen -ls
ps -ef | grep "[d]irewolf"

Migrating from cron and dw-start.sh

Before trying to start Dire Wolf with systemd, make sure any old crontab entries that launch Dire Wolf through dw-start.sh are removed or commented out. Running both methods together can create duplicate processes and audio/PTT conflicts.