systemd setup

Systemd Setup

You will learn how to manage the update-ipsets systemd service, apply configuration through drop-in overrides, and understand the difference between reload and restart.

The installed unit

The installer writes /etc/systemd/system/update-ipsets.service. This unit:

• Runs as User=iplists and Group=iplists
• Sets UMask=0077 so generated artifacts are private to the service user
• Starts the daemon with --enable-all and --verbose
• Sets all path variables to point under /opt/update-ipsets/
• Configures systemd notify and watchdog support
• Enables OpenTelemetry export to the local Netdata instance
• Restricts filesystem writes to the mutable directories under /opt/update-ipsets/: data, cache, lib, web, run, and tmp
• Writes logs to the iplists journal namespace
• Restarts automatically on failure (after 30 seconds)

Do not edit this file directly. The installer overwrites it on every reinstall. Use drop-in overrides instead.

Installed listener defaults

By default, the generated unit sets:

• public listener: 127.0.0.1:18888
• admin listener: 127.0.0.1:18889
• admin authentication: disabled with --allow-unauthenticated-admin

If Tailscale is installed and tailscale ip -4 returns an address, the installer writes the admin listener as <tailscale-ip>:18889 instead of 127.0.0.1:18889. This is intended for deployments where tailnet membership is the admin access-control layer.

The Tailscale address is detected at install time. If Tailscale is added later or its address changes, rerun ./install.sh or set UPDATE_IPSETS_ADMIN_LISTEN_ARG in a drop-in.

On shared, untrusted, or internet-reachable networks, override these defaults with a drop-in that enables admin authentication.

Drop-in overrides

Drop-in files live under /etc/systemd/system/update-ipsets.service.d/. They survive reinstalls and layer on top of the shipped unit.

Create the directory:

sudo mkdir -p /etc/systemd/system/update-ipsets.service.d

Example: separate admin listener with authentication

Create /etc/systemd/system/update-ipsets.service.d/override.conf:

[Service]
Environment="UPDATE_IPSETS_LISTEN=:18888"
Environment="UPDATE_IPSETS_ADMIN_LISTEN_ARG=--admin-listen=127.0.0.1:18889"
Environment="UPDATE_IPSETS_ADMIN_AUTH_ARG=--admin-auth-mode=required"
Environment="UPDATE_IPSETS_ALLOW_UNAUTHENTICATED_ADMIN_ARG="
Environment="UPDATE_IPSETS_ADMIN_USER=admin"
Environment="UPDATE_IPSETS_ADMIN_PASSWORD=change-this-secret"

This places the public site on port 18888 and the admin dashboard on 127.0.0.1:18889 with basic auth.

Before enabling this drop-in, set runtime.public_base_url in the active catalog to the externally visible public site URL. The daemon rejects split-listener startup without it.

Example: custom listen port

[Service]
Environment="UPDATE_IPSETS_LISTEN=:9090"

Example: disable OpenTelemetry

[Service]
Environment="UPDATE_IPSETS_OTEL=0"

Example: memory limits

[Service]
MemoryHigh=512M
MemoryMax=768M
Environment="GOMEMLIMIT=512MiB"

After creating or editing a drop-in, reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart update-ipsets

Service management commands

Action	Command
Start	sudo systemctl start update-ipsets
Stop	sudo systemctl stop update-ipsets
Restart	sudo systemctl restart update-ipsets
Reload catalog	sudo systemctl kill -s HUP update-ipsets
Status	systemctl status update-ipsets
Enable on boot	sudo systemctl enable update-ipsets
View logs	journalctl --namespace=iplists -u update-ipsets -f
View recent logs	journalctl --namespace=iplists -u update-ipsets --since "1 hour ago"

Reload vs restart

The daemon supports live configuration reload via SIGHUP. This re-reads the config directory without restarting the process.

sudo systemctl kill -s HUP update-ipsets

Use reload when you changed feed configuration files in /opt/update-ipsets/etc/config/ and want to pick up the changes without dropping in-flight work.

Use restart when you changed:

• Environment variables (drop-in overrides)
• Memory or resource limits
• Listen addresses or TLS certificates

Reload fails safely: an invalid config leaves the previous configuration active. The daemon logs the reload outcome.

Next steps

• TLS configuration — enable HTTPS
• Memory planning — size resource limits for your catalog