Set up admin authentication

The web interface is protected by a single password. With no password set, anyone who can reach the web port can change nxdns’s configuration, so set one before you let other machines reach it.

Set the password in the web interface

In database mode, open System, type the new password into password and confirm password under Web, and press Save. The interface logs you out at once, and every other session ends with it; log back in with the new password.

To change the password later, do the same again.

Set it in the configuration file

In file mode, or for a first configuration you import, put the password under web:

    .web = .{ .password = "choose-a-real-password" },

nxdns stores only an argon2id hash of it, in web.password_hash, and never logs it. Applying the file, at the next start in file mode or with nxdns import, logs:

web authentication is now enabled

Put a hash in the file instead

A configuration file kept in git or in the Nix store should not hold a plaintext password. Set the password once, then copy the hash out of an export:

nxdns export | grep password

        .password = null,
        .password_hash = "$argon2id$v=19$m=19456,t=2,p=1$…",

Put that .password_hash line in your file in place of .password. The hash installs the same password without revealing it. A file that sets both fields is refused:

web.password: password and password_hash are both set; ambiguity in a security setting is refused

What the file’s password fields do

The file says	What happens to the stored password
Neither field	Nothing. It stays as it was.
.password = "…"	Sets that password.
.password_hash = "$argon2id$…"	Sets the password that hash belongs to.
.password_hash = ""	Removes the password and turns authentication off.
.password = ""	Refused.

Leaving both fields out keeps the password, so deleting the hash line from a file before you commit it never opens the interface by accident. Turning authentication off takes the explicit empty hash, and logs:

web authentication is now disabled

If you have lost the password

The web interface cannot help, so go through the database. Stop nxdns first: a running server keeps checking logins against the hash it read when it started.

systemctl stop nxdns
nxdns export --out /root/nxdns-rekey.zon

In the web section of /root/nxdns-rekey.zon, set .password to the new password and delete the .password_hash line, so only one password field is left:

        .password = "a-new-password",

Then load it and start again:

nxdns import /root/nxdns-rekey.zon
systemctl start nxdns
rm /root/nxdns-rekey.zon

imported /root/nxdns-rekey.zon

In file mode, change the password in your configuration file and restart instead.

Sessions

A login lasts web.session_ttl_hours, 24 hours by default. Sessions are kept in memory, so restarting nxdns logs everyone out. Up to 32 sessions are open at once; a 33rd login ends the one used least recently.

Each login is logged with the address it came from, never with the password:

info(web_auth): web login accepted for 192.168.1.20:34040
warning(web_auth): web login refused for 192.168.1.20:59670

Logins count against web.api_rate_limit_per_min, which limits how fast anyone can guess. Requests from the nxdns machine itself are exempt by default (web.api_localhost_exempt).

Behind a reverse proxy

A reverse proxy on the same machine connects from 127.0.0.1, so every request it forwards would be exempt from the rate limit. List the proxy in web.trusted_proxies, and nxdns reads each client’s real address from the X-Forwarded-For header the proxy adds:

    .web = .{ .trusted_proxies = "127.0.0.1" },

The proxy must add its own entry to that header rather than pass on whatever the client sent. If it cannot, turn web.api_localhost_exempt off instead.

The configuration reference lists every web setting.