running admin authentication

Admin Authentication

You will learn the two admin authentication modes, how to set credentials, why disabling auth requires two flags, and how the fail-closed design protects you from misconfiguration.

Authentication modes

The daemon supports two modes, controlled by --admin-auth-mode:

Mode	Flag	Behavior
required (default)	--admin-auth-mode=required	Admin UI/API endpoints require HTTP Basic authentication. Missing or wrong credentials deny access.
disabled	--admin-auth-mode=disabled	Admin endpoints skip authentication. Requires a second safety flag.

GET /metrics is the exception. It is an admin-surface Prometheus scrape endpoint and is intentionally served without basic authentication. In split mode it is available only on the admin listener. In shared-listener mode it is available on the shared listener, so protect that listener with bind address, firewall, or network policy. The endpoint is bounded and may return 503 Service Unavailable when another scrape is active or collection times out.

Required mode

Set credentials through environment variables:

export UPDATE_IPSETS_ADMIN_USER=admin
export UPDATE_IPSETS_ADMIN_PASSWORD=your-strong-password
update-ipsets daemon --admin-auth-mode=required

With systemd, set them in the drop-in:

[Service]
Environment="UPDATE_IPSETS_ADMIN_USER=admin"
Environment="UPDATE_IPSETS_ADMIN_PASSWORD=your-strong-password"

Access the admin UI or API with HTTP Basic auth:

curl -u "$UPDATE_IPSETS_ADMIN_USER:$UPDATE_IPSETS_ADMIN_PASSWORD" http://127.0.0.1:18889/api/v1/admin/status

Browser access prompts for username and password when you visit /admin.

Fail-closed behavior

If UPDATE_IPSETS_ADMIN_USER or UPDATE_IPSETS_ADMIN_PASSWORD is missing when auth is required:

• admin UI/API endpoints return 503 (Service Unavailable)
• admin access is denied — it does not fall back to open access

The daemon does not guess, default, or silently disable authentication. A missing configuration variable is a hard deny, not a soft skip.

Disabled mode

Disabled mode skips authentication entirely. It is intended for local testing or trusted lab networks where you control all access.

To enable it, set both flags:

update-ipsets daemon \
  --admin-auth-mode=disabled \
  --allow-unauthenticated-admin

Why two flags

The --allow-unauthenticated-admin flag is a deliberate safety acknowledgment. Without it, --admin-auth-mode=disabled alone is not accepted.

This prevents these common mistakes:

• Copy-pasting a command from documentation without noticing auth is off
• Automation scripts that set the mode from a variable and accidentally request disabled auth

The two-flag design means a disabled-auth deployment needs both the disabled mode and a separate risk acknowledgment.

Installed service default

install.sh generates a systemd unit with disabled admin authentication and the unsafe acknowledgment flag already set. It binds admin to 127.0.0.1:18889, or to the Tailscale IPv4 address when Tailscale is available during install.

This is intentional for deployments where localhost or tailnet membership is the admin access-control layer. If the host is on a shared, untrusted, or internet-reachable network, override the unit with:

[Service]
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"

Bind address is not a safety signal

The daemon does not treat loopback or localhost bind addresses as "secure enough" to skip authentication.

Binding --admin-listen 127.0.0.1:18889 restricts network reachability, but:

• other local processes and users can still reach the port
• reverse proxies may forward external traffic to localhost
• SSH tunneling can expose localhost ports remotely

Network-level isolation and application-level authentication are separate layers. Use both.

Production recommendation

For production deployments:

1. Use --admin-auth-mode=required (the default).
2. Use split mode with --admin-listen 127.0.0.1:18889.
3. Set strong credentials in the systemd drop-in.
4. Restrict the admin port further with a firewall if possible.
5. Configure runtime.public_base_url for the public site; split mode will not start without it.

UPDATE_IPSETS_ADMIN_USER=admin \
UPDATE_IPSETS_ADMIN_PASSWORD=your-strong-password \
update-ipsets daemon \
  --config /opt/update-ipsets/etc/config \
  --listen :18888 \
  --admin-listen 127.0.0.1:18889 \
  --admin-auth-mode=required

This gives you:

• public site on :18888 with no admin content
• admin UI on localhost:18889 with authentication
• no admin routes accessible from the public listener (they return 404)

Quick reference

Goal	Flags
Local testing, no auth	--admin-auth-mode=disabled --allow-unauthenticated-admin
Installed private-network default	--admin-listen=<tailscale-ip>:18889 --admin-auth-mode=disabled --allow-unauthenticated-admin
Production, shared listener	--admin-auth-mode=required + environment credentials
Production, split listener	--admin-listen 127.0.0.1:18889 --admin-auth-mode=required + environment credentials + runtime.public_base_url

See also

• Daemon Reference — all flags
• Listener Topologies — shared versus split mode
• Environment Variables — credential and systemd variables