# Loading on an interface

> Attach moat rules to a network interface with moat load, swap them without a gap with reload, use audit mode, keep them across reboots with enable, and read the exit codes.

Source: https://moatfw.dev/docs/loading

These commands need Linux and root. Run `sudo moat doctor --iface eth0`
first: it says whether the machine and the interface's driver are ready.
See [Install](https://moatfw.dev/docs/install#check-the-machine).

```sh
$ moat load rules.moat --iface eth0 [--mode native|generic] [--audit] [--dry-run]
$ moat reload rules.moat --iface eth0 [--dry-run]
$ moat unload --iface eth0 [--keep-sets]
$ moat status [--iface eth0] [--json]
$ moat audit on|off --iface eth0
$ moat enable rules.moat --iface eth0
$ moat disable --iface eth0
```

- `load` compiles the rules, attaches them through a pinned XDP link and
  fills sets that come from files. `--dry-run` only runs the kernel
  verifier. `--audit` starts in audit mode.
- `reload` swaps the program in place: there is no moment without a
  program. Sets whose definition is unchanged keep their contents, and
  sets loaded from a file are made equal to the file again. Counters
  start again from zero.
- After the interface was removed and came back, which is what the unit
  `moat enable` installs runs into, `load` and `reload` attach afresh and
  keep the sets: "the previous program had come off eth0 (the interface
  was removed); attached afresh, keeping sets".
- `unload` detaches the program and removes its state. With
  `--keep-sets` the sets stay for the next `load`.
- `audit on` makes rules that drop count the packet and let it pass;
  `stats` then shows them as "would drop".
- `enable` copies the rules and their set files to `/etc/moat/IFACE/`
  and enables `moat@IFACE.service`, which loads them whenever the
  interface appears, at boot or later.
- `status` names any pinned map that has gone missing, for example
  "pinned map moat_counters in /sys/fs/bpf/moat/eth0 is missing; run moat
  unload to clean up, then moat load".

`stats`, `status`, `var list`, `set list` and `set show` wait, up to 10
seconds, while a load, a reload or a set change runs, so they never mix
one program's rule names with another program's counters.

## Another XDP program on the interface

An interface runs one XDP program at a time. When another tool already
attached one, `moat load` stops and says so:

```sh
$ sudo moat load rules.moat --iface eth0
eth0 already runs an XDP program that moat did not attach; remove it with the tool that attached it, or with ip link set dev eth0 xdp off (moat doctor --iface eth0 shows it)
```

`moat doctor --iface eth0` shows the same before loading, with the
program's name and id.

## Where state lives

Pinned link and maps are in `/sys/fs/bpf/moat/IFACE/`, the manifest in
`/var/lib/moat/IFACE/manifest.json`. `MOAT_BPFFS`, `MOAT_STATE`,
`MOAT_ETC` and `MOAT_SYSTEMD` move these directories.

> In another network namespace, enter it with `nsenter --net=...` rather
> than `ip netns exec`, which hides the BPF filesystem behind a fresh
> `/sys`.

Exit codes: 0 success, 1 errors in the rules, 2 wrong usage or state, 3
the kernel verifier or clang refused the program. The verifier is the
usual cause of 3.