Running as a Service

Running as a Service

A service starts the server with the machine and restarts it after a crash. Both server downloads carry the files for this: avalanche-server.service (Linux) and windows-service.txt (Windows).

A service has no console: its input ends and the server runs on without it. Use the remote console to give it commands.

Linux (systemd)

As root, from the unpacked server download:

useradd --system --home-dir /var/lib/avalanche-server --shell /usr/sbin/nologin avalanche
install -D -m 0755 avalanche-server /opt/avalanche-server/avalanche-server
install -D -m 0644 server.toml.example /etc/avalanche-server/server.toml      # then edit it
install -D -m 0644 avalanche-server.service /etc/systemd/system/avalanche-server.service
install -d -o avalanche -g avalanche -m 0750 /var/lib/avalanche-server
sudo -u avalanche /opt/avalanche-server/avalanche-server setup /path/to/your/ssx.iso --out /var/lib/avalanche-server/data
sudo -u avalanche /opt/avalanche-server/avalanche-server check --config /etc/avalanche-server/server.toml --data /var/lib/avalanche-server/data
systemctl daemon-reload && systemctl enable --now avalanche-server

Task	Command
status	systemctl status avalanche-server
the log	journalctl -u avalanche-server, or /var/lib/avalanche-server/data/logs/server.log
apply a changed server.toml	systemctl restart avalanche-server
stop	systemctl stop avalanche-server

What the unit does:

• Runs the server as the avalanche user with run --config /etc/avalanche-server/server.toml --data /var/lib/avalanche-server/data. Resources go in /var/lib/avalanche-server/data/resources/.
• Stops gracefully. systemctl stop sends SIGTERM: a round under way may finish ([stop] round_end, 60 s by default), the riders are told, the server scripts stop and save, then the server exits. The unit waits 110 seconds before it kills the server: round_end and 50 seconds for the rest (the results 5 s and 2 s more, the riders 2 s, the server scripts up to 30 s, the port mappings up to 4 s, the master up to 3 s). If you raise round_end, raise TimeoutStopSec with it (round_end + 50).
• Restarts the server 5 seconds after a failure.
• Locks the server in: it may write only /var/lib/avalanche-server, sees no home folders, has no privileges and may use only IPv4, IPv6, netlink and local sockets.

Open UDP 27450, TCP 27450 and UDP 27451 in the firewall (Ports and Firewalls).

Windows

avalanche-server.exe is a console program, not a Windows service program. Run it through a service wrapper that starts it and stops it with Ctrl-C, the server's graceful stop. NSSM and WinSW both do; neither comes with Project Avalanche, so read their own documentation and licences.

1. Unpack the server download to C:\AvalancheServer and set it up once:

   cd C:\AvalancheServer
   .\avalanche-server.exe setup D:\path\to\your\ssx.iso --out data
   copy server.toml.example server.toml
   .\avalanche-server.exe check

2. With NSSM, from an administrator's console:

   nssm install AvalancheServer C:\AvalancheServer\avalanche-server.exe run --config C:\AvalancheServer\server.toml --data C:\AvalancheServer\data
   nssm set AvalancheServer AppDirectory C:\AvalancheServer
   nssm set AvalancheServer AppStopMethodConsole 110000
   nssm set AvalancheServer AppStdout C:\AvalancheServer\data\logs\service-output.log
   nssm set AvalancheServer AppStderr C:\AvalancheServer\data\logs\service-output.log
   nssm start AvalancheServer

   AppStopMethodConsole is how long NSSM waits after Ctrl-C before it ends the server the hard way, in milliseconds. 110 seconds is [stop] round_end (60 s by default) and 50 seconds for the rest of the graceful stop, as for the Linux unit above; with another round_end, use round_end + 50 seconds.

3. Run the service under an account of its own, not LocalSystem, and give that account full control of C:\AvalancheServer\data only.

4. Allow UDP 27450, TCP 27450 and UDP 27451 for avalanche-server.exe in Windows Defender Firewall.

The server's own log is C:\AvalancheServer\data\logs\server.log.

Back up

Back up the data folder's identity.key and netcode.key. Players' games remember the identity key and refuse a server whose key changed. acl.toml, bans.toml, script-data/ and your resources/ are worth keeping too. The rules data (big/) can always be made again from your disc.