1. pipx (recommended)

Isolated from system Python, and puts the lanfence launcher on your PATH. The scan extra pulls in scapy (GPL-2.0-only, see Security & trust) — needed for scan/monitor to actually send and receive ARP packets. Without it, allow, report and check still work.

pipx install "lanfence[scan]"

# already installed without the extra? add it in place:
pipx inject lanfence scapy

Then put the launcher on root's PATH and confirm the host is ready:

lanfence link     # re-execs under sudo itself, prompts for your password
lanfence check

Skip lanfence link and sudo lanfence scan gives command not found — a pipx / pip install --user install puts the launcher in ~/.local/bin, which sudo does not see by default (it resets PATH to a fixed secure_path). You can also run it ad hoc with sudo "$(which lanfence)" scan. lanfence link --remove undoes the link.

2. pip / venv (any Debian / Ubuntu / RPi OS host)

python3 -m venv ~/.venvs/lanfence
~/.venvs/lanfence/bin/pip install 'lanfence[scan]'

Scanning needs raw-socket access, so scan/monitor typically need sudo (or CAP_NET_RAW on the interpreter).

3. From a checkout (development)

git clone https://github.com/rosscooney/lanfence && cd lanfence
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev,scan]"
pytest

Running unattended

LAN Fence does not ship its own scheduler; use systemd (recommended on a Pi) or cron. A sample unit is included at packaging/lanfence.service:

[Unit]
Description=LAN Fence continuous monitoring
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/lanfence monitor --config /etc/lanfence/config.yaml
Restart=on-failure
User=root

[Install]
WantedBy=multi-user.target

sudo cp packaging/lanfence.service /etc/systemd/system/
sudo systemctl enable --now lanfence

Or a daily report via cron (sudo crontab -e):

0 7 * * * /usr/local/bin/lanfence report --since 24h --format json > /var/log/lanfence/daily.json

Upgrading

Let LAN Fence do it — lanfence upgrade queries PyPI directly (so a stale pip cache can't hide a release), works out how this copy was installed, and runs the right command with the cache bypassed.

lanfence upgrade            # check + install
lanfence upgrade --check    # report only, don't install

# or by hand:
pipx install --force "lanfence[scan]"==0.3.0   # pin or roll back to a specific release

The changelog and the GitHub releases call out any change to signatures or config fields.

Verify your install

lanfence --version
lanfence check

Before you rely on it

Run LAN Fence on a Linux box that stays powered and connected to the network you actually want to watch. Active/passive scanning needs raw-socket access — run with sudo, or grant CAP_NET_RAW to the interpreter for a non-root service user. Findings are leads, not verdicts: verify before you act on one.