docs: unwrap hand-wrapped prose repo-wide
Gates / frontend (push) Successful in 1m2s
Gates / test (push) Successful in 1m38s
Gates / package (push) Successful in 5m5s
Gates / test-aarch64 (push) Successful in 6m30s
Gates / container (push) Successful in 15s
CI / gates (push) Successful in 13m30s
Gates / frontend (push) Successful in 1m2s
Gates / test (push) Successful in 1m38s
Gates / package (push) Successful in 5m5s
Gates / test-aarch64 (push) Successful in 6m30s
Gates / container (push) Successful in 15s
CI / gates (push) Successful in 13m30s
This commit is contained in:
+11
-35
@@ -11,12 +11,9 @@ This directory is an nxdns release for one architecture. It holds:
|
||||
| `THIRD-PARTY-NOTICES` | Licences of everything compiled or bundled in |
|
||||
| `INSTALL.md` | This file |
|
||||
|
||||
The binary is statically linked against musl and needs nothing installed on the
|
||||
target host.
|
||||
The binary is statically linked against musl and needs nothing installed on the target host.
|
||||
|
||||
Verify the download before you trust it. `docs/how-to/verify-a-release.md` in
|
||||
the repository covers where the public key comes from, what fingerprint to
|
||||
expect, and what the signature does and does not prove.
|
||||
Verify the download before you trust it. `docs/how-to/verify-a-release.md` in the repository covers where the public key comes from, what fingerprint to expect, and what the signature does and does not prove.
|
||||
|
||||
## 1. Install the binary, the user and the unit
|
||||
|
||||
@@ -34,12 +31,9 @@ systemctl daemon-reload
|
||||
mkdir -p -m 0755 /etc/nxdns
|
||||
```
|
||||
|
||||
`nxdns.conf` ships under the name it is installed as, so there is no rename to
|
||||
get wrong.
|
||||
`nxdns.conf` ships under the name it is installed as, so there is no rename to get wrong.
|
||||
|
||||
Do not create `/var/lib/nxdns` or `/var/log/nxdns` by hand. The unit's
|
||||
`StateDirectory` and `LogsDirectory` settings make systemd create them on first
|
||||
start, `/var/lib/nxdns` at mode 0700 owned by `nxdns`.
|
||||
Do not create `/var/lib/nxdns` or `/var/log/nxdns` by hand. The unit's `StateDirectory` and `LogsDirectory` settings make systemd create them on first start, `/var/lib/nxdns` at mode 0700 owned by `nxdns`.
|
||||
|
||||
## 2. Write the configuration
|
||||
|
||||
@@ -53,20 +47,14 @@ nxdns will not start with nothing to forward to. Write `/etc/nxdns/config.zon`:
|
||||
}
|
||||
```
|
||||
|
||||
That file holds a password in plain text. Root's umask is 022 on most
|
||||
distributions, so restrict it as soon as you have written it:
|
||||
That file holds a password in plain text. Root's umask is 022 on most distributions, so restrict it as soon as you have written it:
|
||||
|
||||
```sh
|
||||
chown root:nxdns /etc/nxdns/config.zon
|
||||
chmod 0640 /etc/nxdns/config.zon
|
||||
```
|
||||
|
||||
0640 with group `nxdns` rather than 0600: the service runs as `nxdns`, and
|
||||
systemd leaves `/etc/nxdns` owned by root. Keep that group read bit for good.
|
||||
Under `run --config` the service reads this file on **every** start, not once,
|
||||
so tightening the mode after the first boot breaks the next restart. Under
|
||||
database authority it is `nxdns import` that reads the file, as whoever runs
|
||||
that command, and a bare `nxdns run` never reads it at all.
|
||||
0640 with group `nxdns` rather than 0600: the service runs as `nxdns`, and systemd leaves `/etc/nxdns` owned by root. Keep that group read bit for good. Under `run --config` the service reads this file on **every** start, not once, so tightening the mode after the first boot breaks the next restart. Under database authority it is `nxdns import` that reads the file, as whoever runs that command, and a bare `nxdns run` never reads it at all.
|
||||
|
||||
Check it before starting the service:
|
||||
|
||||
@@ -74,9 +62,7 @@ Check it before starting the service:
|
||||
nxdns check --config /etc/nxdns/config.zon
|
||||
```
|
||||
|
||||
A good file ends with `OK: no problems found`. Exit 2 means `check` found
|
||||
something to fix and printed every problem it found. The upstream probe sends a
|
||||
real query, so this needs working DNS on the host.
|
||||
A good file ends with `OK: no problems found`. Exit 2 means `check` found something to fix and printed every problem it found. The upstream probe sends a real query, so this needs working DNS on the host.
|
||||
|
||||
Load it into the database:
|
||||
|
||||
@@ -84,10 +70,7 @@ Load it into the database:
|
||||
nxdns import /etc/nxdns/config.zon
|
||||
```
|
||||
|
||||
The packaged unit runs `nxdns run` with no `--config`, so from here the database
|
||||
is the configuration and nothing reads the file again. `web.password` is hashed
|
||||
and the plaintext is never stored, so once you have logged in you can delete the
|
||||
file:
|
||||
The packaged unit runs `nxdns run` with no `--config`, so from here the database is the configuration and nothing reads the file again. `web.password` is hashed and the plaintext is never stored, so once you have logged in you can delete the file:
|
||||
|
||||
```sh
|
||||
rm /etc/nxdns/config.zon
|
||||
@@ -95,10 +78,7 @@ rm /etc/nxdns/config.zon
|
||||
|
||||
A kept file is not a backup. `nxdns export` is.
|
||||
|
||||
To keep the file as the configuration instead — converged at every start, with
|
||||
the UI refusing configuration edits — do not delete it, and add a drop-in that
|
||||
appends `--config=/etc/nxdns/config.zon` to `ExecStart`. See
|
||||
`docs/how-to/install-with-systemd.md`.
|
||||
To keep the file as the configuration instead — converged at every start, with the UI refusing configuration edits — do not delete it, and add a drop-in that appends `--config=/etc/nxdns/config.zon` to `ExecStart`. See `docs/how-to/install-with-systemd.md`.
|
||||
|
||||
## 3. Start it
|
||||
|
||||
@@ -107,9 +87,7 @@ systemctl enable --now nxdns
|
||||
journalctl -u nxdns -f
|
||||
```
|
||||
|
||||
A healthy start logs a line naming every socket it bound. Port 53 is
|
||||
privileged, and the unit grants `CAP_NET_BIND_SERVICE` through
|
||||
`AmbientCapabilities`.
|
||||
A healthy start logs a line naming every socket it bound. Port 53 is privileged, and the unit grants `CAP_NET_BIND_SERVICE` through `AmbientCapabilities`.
|
||||
|
||||
## 4. Confirm it answers
|
||||
|
||||
@@ -119,9 +97,7 @@ From another machine on the LAN:
|
||||
dig @<server-ip> example.com A +short
|
||||
```
|
||||
|
||||
The admin interface is on port 8080 by default; log in with the password from
|
||||
the configuration file. `http://<server-ip>:8080/api/health` reports upstream
|
||||
availability and disk state without a login.
|
||||
The admin interface is on port 8080 by default; log in with the password from the configuration file. `http://<server-ip>:8080/api/health` reports upstream availability and disk state without a login.
|
||||
|
||||
## More
|
||||
|
||||
|
||||
Reference in New Issue
Block a user