jarl/docs/install.md

# Installing Jarl and adopting an existing BIND server

This guide targets Debian/Ubuntu with BIND 9.20 (`bind9` package,
`/etc/bind`, user and group `bind`, AppArmor). Other layouts work too: every
path is configurable in `/etc/jarl/jarl.yaml` (see
[configuration.md](configuration.md)).

The migration is designed to be safe. Your current configuration is
imported into Jarl and checked with `named-checkconf` before named is
touched. Adopting keeps a copy of the old `named.conf`, and if named fails
to load Jarl's configuration the old one is put back automatically.

## 1. Build

Jarl is two static binaries with no runtime dependencies (SQLite is
compiled in). Building needs Go 1.27 or newer, on any machine:

```sh
make            # bin/jarld and bin/jarl
make test       # optional: unit and integration tests
make dist       # optional: dist/jarl-<version>-linux-{amd64,arm64}.tar.gz
```

If you build on another machine, copy the binaries plus the `deploy/`,
`docs/` and `contrib/` directories to the DNS server, or build a Debian
package (below) and copy that.

## 2. Install the files

There are two ways: a Debian package, which is easiest to upgrade and
remove, or `make install`.

### With the Debian package

```sh
make deb                                  # dist/jarl_0.1.0_amd64.deb
make deb DEB_ARCH=arm64                   # for another architecture (also armhf, i386, ...)
sudo apt install ./dist/jarl_0.1.0_amd64.deb
```

`make deb` needs only `dpkg-deb` (no root, no debhelper) and cross-builds
for any architecture Go supports. apt also installs `bind9` (recommended)
if it's missing. Installing the package:

* puts the binaries in `/usr/bin`, bash completion in
  `/usr/share/bash-completion/completions`, the systemd unit in
  `/usr/lib/systemd/system/jarl.service`, the sysusers and tmpfiles files
  in `/usr/lib`, and the docs and contrib files in `/usr/share/doc/jarl`;
* creates the `jarl` user (in group `bind`) and Jarl's directories, and
  writes `/etc/jarl/jarl.yaml` from the example on the first install. No
  file in `/etc` belongs to the package, so your configuration is never
  replaced or asked about on upgrades;
* doesn't start jarld: continue with [3. Configure](#3-configure), then
  `systemctl enable --now jarl` in step 8.

**Upgrading**: build and install the newer package the same way. A running
jarld is restarted, and upgrades its database as it starts.

**Removing** (`sudo apt remove jarl`) stops jarld and removes the program,
but named keeps running with the configuration Jarl last wrote. Even
`apt purge jarl` keeps `/etc/jarl`, `/var/lib/jarl` (the database) and the
files in `/etc/bind/jarl`, `/var/lib/bind/jarl` and `/var/cache/bind/jarl`,
since named.conf may still include them. Remove them by hand once named no
longer uses them.

### With make install

On the DNS server, as root:

```sh
make install           # or: make install PREFIX=/usr
```

This installs:

| File | Purpose |
|------|---------|
| `/usr/local/bin/jarld`, `/usr/local/bin/jarl` | daemon and CLI |
| `/usr/local/share/bash-completion/completions/jarl`, `.../jarld` | bash completion (loaded automatically by the `bash-completion` package) |
| `/etc/systemd/system/jarl.service` | systemd unit (`Type=notify`, sandboxed) |
| `/usr/lib/sysusers.d/jarl.conf` | creates the `jarl` system user and adds it to group `bind` |
| `/usr/lib/tmpfiles.d/jarl.conf` | creates `/etc/jarl`, `/var/lib/jarl`, `/etc/bind/jarl`, `/var/lib/bind/jarl`, `/var/cache/bind/jarl` |
| `/etc/jarl/jarl.yaml` | example configuration (only if none exists) |
| `/usr/local/share/doc/jarl/` | these docs and the acme.sh hook |

Then create the user and directories:

```sh
systemd-sysusers jarl.conf
systemd-tmpfiles --create jarl.conf
chgrp jarl /etc/jarl/jarl.yaml
systemctl daemon-reload
```

Without `make` (from a release tarball), the same steps are:

```sh
install -m 0755 jarld jarl /usr/local/bin/
install -m 0644 deploy/systemd/jarl.service /etc/systemd/system/
install -m 0644 deploy/sysusers.d/jarl.conf /usr/lib/sysusers.d/
install -m 0644 deploy/tmpfiles.d/jarl.conf /usr/lib/tmpfiles.d/
systemd-sysusers jarl.conf && systemd-tmpfiles --create jarl.conf
jarld config --example > /etc/jarl/jarl.yaml
chgrp jarl /etc/jarl/jarl.yaml && chmod 0640 /etc/jarl/jarl.yaml
systemctl daemon-reload
```

### Why the jarl user is in group bind

jarld runs as `jarl`, not root. Membership of `bind` lets it read named's
configuration and `/etc/bind/rndc.key` (for `named-checkconf` and `rndc`),
and give the files it generates to group `bind` so named can read them.
named in turn can't write Jarl's configuration (`/etc/bind/jarl` is 2750),
but it can write journals in `/var/lib/bind/jarl` (2770).

## 3. Configure

Edit `/etc/jarl/jarl.yaml`. The defaults match Debian's BIND 9.20 layout,
so usually only `listen` and `tls` need changes:

```yaml
listen:
  - "127.0.0.1:8053"     # always keep localhost for the local CLI and hooks
  - "192.168.1.2:8053"   # a management address for the web UI
tls:
  cert_file: /etc/jarl/tls/fullchain.pem
  key_file: /etc/jarl/tls/privkey.pem
```

Keep the web UI and API **off the internet**: listen on localhost and a
management network only, and restrict the port in your firewall. When the
server becomes internet-facing for DNS, that changes nothing for Jarl.

A plain-HTTP listener is fine on localhost. Anything reachable over the
network should use TLS, either with `tls:` above or behind a reverse proxy
that terminates TLS (set `trusted_proxies` so client IPs in the audit log
are right). See "TLS certificate from Let's Encrypt" below.

Check the result with `jarld config` (prints the effective configuration).

## 4. Back up BIND

Jarl keeps a copy of `named.conf`, but take your own backup anyway:

```sh
tar czf /root/bind-before-jarl-$(date +%F).tgz /etc/bind /var/lib/bind /var/cache/bind
```

## 5. Create the database and the first administrator

```sh
sudo -u jarl jarld init --token \
    --nameservers ns1.adbraun.lol. --contact hostmaster@adbraun.lol
```

It asks for the administrator's password (user `admin`, change it with
`-u NAME`). `--token` also prints an API token for the CLI, shown only
once. `--nameservers` and `--contact` are the defaults for zones you create
later, and you can change them in the UI or with `jarl settings set`.

## 6. Import the current configuration

```sh
sudo -u jarl jarld import --dry-run   # see what would be imported
sudo -u jarl jarld import
```

The importer reads `/etc/bind/named.conf` and everything it includes: ACLs,
keys, options, logging, views, zones, and every primary zone file (with
comments, `$TTL`, `$ORIGIN` and `$INCLUDE`; `$GENERATE` ranges are expanded
into individual records). It converts legacy
spellings (`master`/`slave`/`masters`) and keeps `rndc.key` as an include.

If everything validates, the import is applied as changeset #2. Jarl writes
its files into `/etc/bind/jarl` and `/var/lib/bind/jarl`, but **named keeps
running on the old configuration**. If there are problems, the import is
left as an open changeset to fix in the web UI or CLI first, and the
command tells you what is wrong.

Look at what Jarl generated before going further:

```sh
less /etc/bind/jarl/named.conf
ls -R /var/lib/bind/jarl
sudo -u jarl jarld check    # validation + named-checkconf -z
```

## 7. Adopt: switch named over to Jarl

```sh
sudo jarld adopt
```

This needs root because it rewrites `/etc/bind/named.conf`:

1. bumps the serial of every primary zone, so secondaries and caches notice
   the change,
2. saves `named.conf` as `named.conf.pre-jarl-<date>` and replaces it with a
   single `include "/etc/bind/jarl/named.conf";`,
3. runs `named-checkconf`, `rndc reconfig` and reloads every zone,
4. checks that named serves every zone with the new serial.

If any step fails, the previous `named.conf` is restored and named is
reloaded. Afterwards, check that the answers match:

```sh
dig @127.0.0.1 adbraun.lol SOA +short
dig @127.0.0.1 -x 192.168.1.1 +short
```

From now on, change DNS only through Jarl. Hand edits to the generated
files are detected as drift and are never silently overwritten (see
[operations.md](operations.md)).

**Going back.** `cp /etc/bind/named.conf.pre-jarl-<date> /etc/bind/named.conf && rndc reconfig`
restores the old setup. Your old zone files were never modified.

## 8. Start the daemon

```sh
systemctl enable --now jarl
systemctl status jarl
journalctl -u jarl -f
```

Open `https://<management-address>:8053/` and log in as `admin`.

## 9. Set up the CLI

On the server itself, root needs nothing: `sudo jarl status` and every
other command use jarld's local socket without a token
([cli.md](cli.md#on-the-server-itself)).

On other machines, or as an ordinary user, give the CLI a server and a
token:

```sh
jarl config set server https://ns1.adbraun.lol:8053
jarl config set token          # paste the token from 'jarld init' at the prompt
jarl status
jarl zone list
```

The CLI's settings are stored in `~/.config/jarl/config.yaml` (mode 0600).
`JARL_SERVER` and `JARL_TOKEN` override them, which is handy in scripts.
Create more tokens in the web UI (Account → API tokens) or with
`jarl token create NAME`. See [cli.md](cli.md).

## Optional: query statistics

To see query volume, top names and clients in the UI and CLI, set
`stats: {enabled: true}` in `/etc/jarl/jarl.yaml` and restart jarl. See
[stats.md](stats.md).

## TLS certificate from Let's Encrypt

Jarl can publish the DNS-01 challenge for its own certificate. On the DNS
server, run certbot with the hooks against the local listener:

```sh
# As yourself (with an admin token configured): a service account and a
# token that can only touch _acme-challenge TXT records.
jarl user create certbot --no-password --role acme
jarl token create certbot --user certbot --role acme -q > certbot.token
sudo install -m 0600 certbot.token /etc/jarl/certbot.token && rm certbot.token

# certbot runs as root and reads the token from the file.
sudo certbot certonly --manual --preferred-challenges dns \
  --manual-auth-hook 'jarl --server http://127.0.0.1:8053 --token @/etc/jarl/certbot.token acme certbot-auth' \
  --manual-cleanup-hook 'jarl --server http://127.0.0.1:8053 --token @/etc/jarl/certbot.token acme certbot-cleanup' \
  -d ns1.adbraun.lol
```

certbot keeps its keys readable only by root, so give jarld a copy after
each renewal with a deploy hook, `/etc/letsencrypt/renewal-hooks/deploy/jarl`:

```sh
#!/bin/sh
set -e
install -d -m 0750 -g jarl /etc/jarl/tls
install -m 0640 -g jarl "$RENEWED_LINEAGE/fullchain.pem" "$RENEWED_LINEAGE/privkey.pem" /etc/jarl/tls/
systemctl reload jarl
```

`systemctl reload jarl` sends SIGHUP, and jarld rereads the certificate
without dropping connections. More in [acme.md](acme.md).

## Upgrading

```sh
make && sudo make install
sudo systemctl restart jarl
```

Database migrations run automatically at startup. Before an upgrade, back
up the database (it is safe while jarld runs):

```sh
sudo -u jarl jarld backup /var/lib/jarl/jarl-$(date +%F).db
```

## Uninstalling

```sh
cp /etc/bind/named.conf.pre-jarl-<date> /etc/bind/named.conf   # or write a named.conf that includes Jarl's files
rndc reconfig
systemctl disable --now jarl
make uninstall
```

`/etc/bind/jarl` and `/var/lib/bind/jarl` contain plain named.conf and zone
files that keep working without Jarl. `make uninstall` leaves them and
Jarl's database in place.