Set up a Raspberry Pi 5 gateway¶

This page sets up a Raspberry Pi 5 as a gateway. It starts with a blank SD card. It ends with a working gateway with an agent behind it.

• For the home network (house segment), refer to home_network.md.
• For a gateway on Wi-Fi that you do not control, refer to public_wifi.md.
• To enrol a credential and claim it on the agent, refer to getting_started.md steps 3-4.

This page stops when the agent can reach the internet through the gateway.

1. What you need¶

The agent machine is a Linux machine or VM. Its only network path is the gateway. Install curl and ca-certificates on it before you put it behind the gateway. If you do not, its package manager fails TLS (HTTPS encryption) checks. It fails until it trusts the certificate authority (CA) of the gateway.

2. Flash and first boot¶

Desktop:

sudo apt install -y rpi-imager

• Set a hostname, your username, and a strong password.
• Do not configure Wi-Fi.
• Set your timezone.
• Enable SSH with public-key login only.

Then:

1. Write the card.
2. Connect the Pi to your ISP router through the onboard Ethernet port.
3. Keep all USB adapters disconnected.
4. Start the Pi.

Then, from the desktop:

ssh <user>@<pi-hostname>.local

Pi:

sudo apt update && sudo apt full-upgrade -y
sudo apt install -y --no-install-recommends nftables dnsmasq curl tcpdump iproute2 ca-certificates dnsutils conntrack rsync
sudo rfkill block wifi bluetooth   # skip this line for a Wi-Fi uplink, step 3 option B
echo nf_conntrack | sudo tee /etc/modules-load.d/pi-fortress.conf
sudo modprobe nf_conntrack
sudo reboot

Steps 3 to 5 run pf. Thus, install pf first, with step 6. The pf installer proposes the uplink and agent ports itself. Steps 3 to 5 explain these choices and how to change them.

3. Choose the uplink¶

"Uplink" and "agent link" are roles. They are not fixed physical ports:

• WAN_IF is the interface that has the default route (your path to the internet).
• INT_IF is the interface that has the agent address (PI_IP, below).

You can pin each of them, and not use detection. Use the table in step 4.

Option A: wired uplink, USB adapter for the agent (recommended).

1. Connect the USB gigabit adapter.
2. Find its name with ip -br link (for example eth1).
3. Configure it as the agent network:

Pi:

sudo nmcli con add type ethernet ifname <nic> con-name agent-net ipv4.method manual ipv4.addresses 10.77.0.1/24 ipv4.never-default yes ipv6.method disabled connection.autoconnect yes
sudo nmcli con up agent-net
ip -4 -o addr show to 10.77.0.1

Option B: Wi-Fi uplink, onboard Ethernet to the agent. You do not need a USB adapter. But the Wi-Fi throughput is lower, and Wi-Fi can drop silently. Do not run rfkill block wifi in step 2. Your SSH session uses the onboard port. Thus, start Wi-Fi first, from that same session:

Pi:

sudo rfkill unblock wifi
sudo nmcli dev wifi connect "<ssid>" password "<password>" ifname wlan0
ip -4 -br addr show wlan0

Pi:

sudo nmcli con mod "Wired connection 1" connection.autoconnect no
sudo nmcli con add type ethernet ifname eth0 con-name agent-net ipv4.method manual ipv4.addresses 10.77.0.1/24 ipv4.never-default yes ipv6.method disabled connection.autoconnect yes
sudo nmcli con up agent-net
ip -4 route show default

4. Agent network values¶

These are the network defaults. Each software update writes them again. To keep a value across updates, put it in /etc/pi-fortress/net.env.local on the Pi. Put only the keys that you want to override in this file. sudo pf tui, System → Settings, writes this file for you for these keys:

• The DNS keys.
• UNTRUSTED_UPLINK.
• AGENT_DNS.
• FAKEIP_NET.
• The connection limits.

The TUI refuses a value that the gateway cannot use.

Connection limits¶

Each connection through the gateway uses a slot in one table. The Pi shares this table between all its networks and its own connections, SSH also. The connection limits above stop one device from filling the table. For example, a faulty agent or a home device can open connections in a loop. The gateway refuses these connections, and all other traffic continues to work. The blocked events of that device show a refused connection as conn_limit.

The gateway refuses a limit value that it cannot use:

• Below 16 connections per device.
• Below 64 per network.
• Below 5 new connections a second.

These values break a usual web page. They do not stop abuse.

Spending limits per credential¶

The gateway counts what each credential slot uses in the last hour:

• The number of requests into which it put a live credential.
• The megabytes of request body that went out with these requests.

An agent can be persuaded to run in a loop, or to upload your repository to a different location. Such an agent shows a number far above the number for your own work.

• A warn sends you one alert. It changes nothing.
• A stop disables the slot. This is the same as x in Agent network → Keys. The agent gets the same refusal as for all disabled credentials. After you examine the problem, restore the slot with R. A restore also clears the hour. Thus the next request does not trigger the same limit again.

The counters are in memory. Thus a restart of the gateway starts the hour again. Agent network → Keys shows the last hour of each slot next to its last use.

Headers a credential may go in¶

The gateway writes a live credential only into Authorization and X-Api-Key. It does this only for the hosts to which core.hosts binds the kind of the credential. This covers all the kinds that come with the gateway. A placeholder in a different header, for example User-Agent or Referer, makes the gateway refuse the full request. Reason: a provider logs these headers and can show them back.

If a provider wants its key in a different header:

1. Bind the kind to the host of the provider in core.hosts.local.
2. Name the header when you mint.

The two files are in /opt/pi-fortress/vm/policy/. core.hosts.local is your file. An upgrade replaces core.hosts next to it, and keeps core.hosts.local. (pf apply builds /etc/pi-fortress/core.hosts from the two files. Do not edit it.)

echo 'gitlab.com GITLAB_TOKEN' | sudo tee -a /opt/pi-fortress/vm/policy/core.hosts.local
sudo pf enroll mint --kind GITLAB_TOKEN --value '...' --header PRIVATE-TOKEN
sudo pf apply

Then mint adds gitlab.com GITLAB_TOKEN:PRIVATE-TOKEN to core.hosts.local for each host that has the kind. If no host has the kind yet, mint refuses. You can never name these headers: User-Agent, Referer, Origin, Host, Via, Forwarded, X-Forwarded-*, X-Real-IP, Content-*, Transfer-Encoding, Connection, Keep-Alive, Upgrade, TE, Trailer and Proxy-*. pf apply refuses a line that tries to name one.

5. Cable the agent¶

Direct cable. Connect a cable directly from the agent port of the Pi to the network card of the agent machine. Or bridge the network card of a VM onto that port (step 7).

Give each agent a static address. The agent network has no DHCP. This is intentional:

• The gateway drops all traffic from outside AGENT_NET.
• SSH into the agent network opens only to fixed addresses.

The first agent is 10.77.0.10/24 (AGENT_IP). Its gateway and DNS are 10.77.0.1. More agents use .11, .12, and so on. On an agent with NetworkManager, run these commands. <nic> is the port with the cable to the Pi.

Agent:

sudo nmcli con add type ethernet ifname <nic> con-name pf-agent ipv4.method manual ipv4.addresses 10.77.0.10/24 ipv4.gateway 10.77.0.1 ipv4.dns 10.77.0.1 ipv6.method disabled connection.autoconnect yes
sudo nmcli con up pf-agent
ping -c 1 10.77.0.1

One VLAN trunk for agent and desk traffic. A VLAN (virtual LAN) uses tags to divide one physical cable into several separate networks. If the desktop also needs its own network through the Pi, use one cable. Divide it with 802.1Q tags (the VLAN tag standard):

• VLAN 20 for the agent segment.
• VLAN 79 as a plain segment for the desktop itself. This segment gets NAT, isolation, and the DNS and connection filters of step 8. TLS inspection and the credential fence are an option for this segment (step 8). NAT (network address translation) lets several devices share one address.

The commands below use eth0 as the agent port of the Pi, as in option B of step 3. With option A, use the name of the USB adapter. Apply refuses a VLAN on the uplink.

On the Pi, add a segment file. Step 8 below explains the keys:

Pi:

sudo install -d -m 0755 /etc/pi-fortress/segments.d
sudo nano /etc/pi-fortress/segments.d/desk.env

IF=eth0.79
NET=10.79.0.0/30
IP=10.79.0.1
ADMIN=yes

sudo nmcli con delete agent-net
sudo nmcli con add type vlan con-name agent-net ifname eth0.20 dev eth0 id 20 ipv4.method manual ipv4.addresses 10.77.0.1/24 ipv4.never-default yes ipv6.method disabled connection.autoconnect yes
sudo nmcli con up agent-net
sudo pf apply --local

On the desktop side, this split needs three changes:

1. Tag the network card of the desktop into the two VLANs.
2. Move the default route of the desktop onto the desk VLAN.
3. Stop the desktop from forwarding traffic between the VLANs.

The last change is important. A desktop that forwards traffic can carry the traffic of an agent around the Pi. The desk setup script does all three changes. The script is in the desk folder of the source, which is published with the public release. On the desktop, clone the release tag that you installed (git clone --depth 1 --branch <tag> https://github.com/nrnjn42/pi-fortress). Run the script from that folder. <nic> is the card of the desktop with the cable to the Pi. Test between the steps:

Desktop:

sudo PARENT=<nic> ./setup.sh net       # tag <nic>: VLAN 20 with no address, VLAN 79 at 10.79.0.2/30
sudo PARENT=<nic> ./setup.sh default   # move the default route to the Pi, 10.79.0.1
sudo PARENT=<nic> ./setup.sh lock      # no forwarding; nothing in or out on <nic> or VLAN 20
sudo PARENT=<nic> ./setup.sh status

• net and lock install this command.
• It needs no clone and no DNS.
• It undoes default and lock, keeps the VLAN profiles, and starts the Wi-Fi uplink again.

The only uplink of the desktop must be the Pi. Disable Wi-Fi in the BIOS or remove the Wi-Fi card. Disconnect all other network cables. Traffic that leaves on a different path goes around all the rules on the Pi. Thus the lock step refuses a desktop that still has one of these paths:

• A different default route. The full tunnel or exit node of a VPN is such a route.
• Wi-Fi that is on.
• A different wired port with a route.

The lock step names each path, with the command that closes it. The uplinks step of the desk setup script does the same check by itself. Its status step includes the check. PF_DESK_ALLOW_SECOND_UPLINK=1 makes lock continue anyway. It is for a development machine that keeps Wi-Fi as a fallback. A desk that you rely on should not need it.

The desk lock does the same check again two minutes after each boot. At that time it only warns (journalctl -b -u pf-desk-uplink-check, and the status of the desk setup script under "uplinks at boot"). To disable Wi-Fi, use nmcli radio wifi off or sudo rfkill block wifi. The command ip link set … down does not stay in effect after a reboot.

6. Install and update pf¶

A key that never touches the Pi signs each release. Set V to the newest release tag. Then, on the Pi:

V=v1.2.3
sudo apt-get update && sudo apt-get install -y curl   # a minimal image may not have it
curl -fsSLO https://raw.githubusercontent.com/nrnjn42/pi-fortress/$V/install.sh
sudo PF_RELEASE_URL=https://github.com/nrnjn42/pi-fortress/releases/download PF_VERSION=$V bash install.sh

1. It checks the Pi model and the OS.
2. It downloads the bundle.
3. It verifies the signature of the bundle.
4. It runs pf install. pf install proposes the uplink and agent ports and asks you to confirm them.

If you already know the ports, add -wan eth0 -agent eth1 to the last line. You can safely run the command again. If pf install stops at its apply or health check, correct the cause. Then run the same command again. It applies the installed version again.

To update, give the tag. pf install kept the PF_RELEASE_URL above in /etc/pi-fortress/release.url. After an offline PF_BUNDLE install, write the URL into that file yourself first.

sudo pf upgrade -version v1.3.0
sudo pf upgrade -confirm

sudo pf rollback goes back one version manually, to the release before this one. You cannot go back further. If rollback cannot run because a different apply is running, it tells you. It then exits non-zero and keeps the pending upgrade armed. Run it again.

A rollback does not change the block lists and the other lists that you edit. An upgrade also does not change them. Thus a rollback does not undo an edit or a removal that you made after the upgrade. Always give a tag: latest does not match the release download paths.

pf version on the Pi shows the version that runs now.

7. Bring agents up¶

A physical agent machine: connect it to the agent port with a cable. Give it its address (step 5). Then go to the last paragraph of this step.

Agent VMs on the desktop:

1. Make a Linux VM in a hypervisor of your choice.
2. Install curl and ca-certificates in the VM while it still has its own path out.
3. Give the VM only one network card. Bridge it onto the desktop interface that connects to the agent port of the Pi:
4. On a direct cable, this is the card.
5. On a trunk, this is the VLAN 20 child without an address (<nic>.20).
6. Remove all NAT cards and second cards from the VM. Such a card is a path around the Pi.
7. In the VM, set the static address from step 5.

More agents use consecutive addresses from AGENT_IP: 10.77.0.10, .11, .12. (Contributors can build the same VMs with the Vagrant lab. Its manual is published with the source.)

Then, on each agent, continue with getting_started.md steps 2 to 4:

1. Run setup.sh of the agent against the gateway.
2. Check the block-test canaries.
3. Enrol and claim a credential.

8. Add another plain network¶

A plain segment is a separate network that the gateway serves, for example the desk. The gateway assumes that a machine on a plain segment can be compromised. Thus the segment gets almost the same rules as the agent network. By default, it gets no TLS inspection:

• It resolves names through the gateway, with the block lists of the agent network. The gateway refuses DNS to all other servers. It drops DNS over TLS, the known DNS-over-HTTPS servers, and QUIC.
• A new connection on any port or protocol, or a ping, goes only to an address that the DNS of the segment gave recently.
• No local addresses: the segment cannot reach the LAN of the uplink, the admin page of the router, or other private ranges, on all ports.
• The ports are the strict set of the house (web, the encrypted mail and push ports, time, ping), unless EGRESS sets a different value. With strict, outgoing SSH goes only to the addresses in ssh_allow.ips.
• The shared IP blacklist applies. The segment is isolated from the agents, the house, and other segments.

Without INSPECT=on, a plain segment does not get:

• TLS inspection.
• A check of the site name that a connection sends.
• Credential substitution.

Thus keep live credentials off a desk, or turn on the credential fence on the desk.

To add a segment, put a file in /etc/pi-fortress/segments.d/. Give the file the name of the segment. These names are not permitted:

• house, agent, pi, or broker.
• Two names that are different only by - and _.

Pi:

sudo nano /etc/pi-fortress/segments.d/<name>.env

Pi:

sudo pf apply --local

The uplink can itself be a VLAN, for example an ISP VLAN such as WAN_IF=eth0.35. Then all of its cable belongs to the uplink. Apply then also refuses a segment, INT_IF, or HOUSE_IF in these locations:

• On a sibling VLAN of the uplink (eth0.30).
• Untagged on its parent (eth0).

Correct the file and apply again.

A segment can also be a VLAN on the house port. Use one VLAN per SSID of a Wi-Fi access point that tags each SSID. For example, use IF=eth1.30 for an IoT network next to HOUSE_IF=eth1. These tags are only as strong as the access point. A device on any SSID, or a compromised access point, can tag its traffic into any VLAN on that cable. Thus, for a segment that shares the cable of the house port, apply:

• Refuses ADMIN=yes and SSH_TO.
• Refuses the agent network on that cable completely.
• Warns on each apply that the segment is only as isolated as the access point or switch.

SSH_FROM is still permitted. DHCP=on is also permitted, because most IoT devices need it. The VLAN tutorial has the example and the reasons.

When the segment exists, sudo pf tui has a menu entry for it. The entry has the same Devices, Filtering, Activity, and Settings as the other networks:

• Filtering shows the lists of the agent network, read-only. A segment resolves with these lists.
• In Settings, Enter changes the value of ADMIN, BLOCK_DIRECT_IP, PARANOID, and DHCP. For SSH_TO, Enter asks for a value.
• Enter on one end of the DHCP range asks for the two ends, because apply refuses one end without the other. Thus set the range before you set DHCP to on.
• The TUI refuses a value that apply would refuse. It then does not change the file.
• With DHCP on, the row below it gives the name of the reservations file. You edit this file manually.
• A runs the apply --local that makes the change take effect.
• When you set ADMIN to off, the TUI asks you first. Reason: your session often comes in through that same segment.
• The TUI shows IF, NET, and IP, but you cannot edit them there. To move a segment, you must also change the machine at the other end of the cable. Thus a move stays an edit to the file and a reboot.
• Activity has a New destinations tab. It shows each destination that a device on the segment reached for the first time. The name comes from the DNS of the segment. A query that has a key, or that looks like a DNS tunnel, makes an alert, as on the agent network.

To remove a segment, delete its file and apply:

Pi:

sudo rm /etc/pi-fortress/segments.d/<name>.env
sudo pf apply --local

• Removes the firewall rules and the DHCP server of the segment.
• Deletes the seg-<name> NetworkManager profile that it made. Thus the interface releases the address of the segment.
• Prints one pruned NetworkManager profile line for each profile.

When you move a segment to a different IF, apply does the same to the old profile before it makes the new profile. It does not change other connections.

A segment that was untagged on its own port, for example IF=eth2, leaves an inert pf-parked-eth2 profile on that port. This profile has no address, no DHCP, and no route. Thus the Pi never asks the device on that port for an address or a default route. Apply tells you this in one line. Apply removes the profile again when a segment, the house, or the agent network uses that port. Apply removes a VLAN child, for example eth1.30, completely. The allowlist and reservations files of the segment, next to segments.d, are your files. They stay until you delete them.

One exception prevents a lockout. An SSH session into the Pi can come through the profile that apply would delete. For example, you remove or move the desk while you are logged in over the desk. Then apply keeps that profile, prints a warning, and still succeeds. The firewall rules of the segment have already changed. Thus:

1. Keep the session open.
2. Get access in a different way (the house admin device, or a keyboard on the Pi).
3. Remove the profile manually with sudo nmcli con delete seg-<name> and sudo pf apply --local.

The FAQ ("What breaks on the desk?") lists what a strict desk breaks, and the key that repairs each problem.

The credential fence on the desk¶

With INSPECT=on in the file of the desk, the desk gets the fence of the agent network. All HTTPS of the desk goes through the engine and the broker. The tools on the desk hold placeholders. The gateway puts in the real key only for the service of that key, and it removes live keys in known formats. Thus an agent that escapes to the desk finds no real keys there.

The Pi must run a release that has the INSPECT key. An older release refuses the key with unknown key 'INSPECT' and changes nothing. If you see that, update pf first (step 6).

1. Copy the certificate of the gateway CA to a file that your user can read on the Pi. Copy only the certificate. The key of the CA stays on the Pi. -t gives sudo a terminal, so that it can ask for your password. Write down the sha256 that the command shows.

   Desktop:

   ssh -t <user>@10.79.0.1 'sudo install -m 0644 /var/lib/pi-fortress/engine/ca-cert.pem /tmp/pf-ca.pem && sha256sum /tmp/pf-ca.pem'
   

   Do not use ssh <user>@10.79.0.1 sudo cat ... > pf-ca.pem. Without a terminal, sudo cannot ask for the password. The command then fails and leaves an empty file.

2. Copy the file to the desktop. Then remove the copy on the Pi. The copy belongs to root, thus the removal needs sudo.

   Desktop:

   scp <user>@10.79.0.1:/tmp/pf-ca.pem ~/pf-ca.pem
   ssh -t <user>@10.79.0.1 sudo rm /tmp/pf-ca.pem
   sha256sum ~/pf-ca.pem
   

   The sha256 must be the same as in step 1. The file must start with -----BEGIN CERTIFICATE-----.

3. Install the certificate on the desktop. Use the desk setup script from the source, and the sha256 from step 1. Run it with sudo from your own user, not from a root shell. If not, Chrome does not get the certificate. For Chrome and Chromium, first install certutil (sudo apt install libnss3-tools).

   Desktop:

   sudo <source>/vm/desk/setup.sh ca ~/pf-ca.pem <sha256>
   

   The step refuses a file that holds a private key, a certificate that is not a CA, and a wrong sha256. Each line of its output tells you one location:

   Output line	Meaning
   system store: /usr/local/share/ca-certificates/pi-fortress-desk.crt	Go, curl, git, and the Python ssl module trust the gateway CA
   environment: /etc/profile.d/... (shells), /etc/environment.d/... (desktop apps)	NODE_EXTRA_CA_CERTS for Node. SSL_CERT_FILE, REQUESTS_CA_BUNDLE, and PIP_CERT for Python requests, httpx, and pip. Log out and log in again to get them
   Chrome and Chromium: added to ~/.pki/nssdb	Chrome and Chromium trust the gateway CA. Restart the browser
   Chrome and Chromium: install libnss3-tools (certutil) and run this again	Chrome and Chromium do not trust the CA yet. Install libnss3-tools, and run step 3 again. The step is safe to run again
   Firefox: policy /etc/firefox/policies/policies.json	Firefox trusts the gateway CA after a restart
   Firefox: ... has other policies	You already have a Firefox policy file. Add /etc/pi-fortress/desk-ca.pem to Certificates.Install in that file
   Java and tools with their own roots need the CA in their own store	Import /etc/pi-fortress/desk-ca.pem into each such store manually

   The certificate has no effect until you set INSPECT=on in the next step. To remove all of it, run sudo <source>/vm/desk/setup.sh ca-remove.

4. Turn on the fence. Do step 3 first: without the CA, all HTTPS from the desk fails.

   Pi:

   sudo sed -i '/^INSPECT=/d' /etc/pi-fortress/segments.d/desk.env && echo INSPECT=on | sudo tee -a /etc/pi-fortress/segments.d/desk.env
   sudo pf apply --local
   

   Then, on the desktop, make sure that HTTPS goes through the gateway. The output must show issuer: CN=pi-fortress:

   Desktop:

   curl -sv -o /dev/null https://example.com 2>&1 | grep issuer
   

5. Enrol each key on the gateway (getting started, step 3). The claim code of step 4 there is for an agent, because it also runs the setup of the agent. On the desk, put the placeholder pf_<slot>_<KIND> (sudo pf enroll list) in the tool, in the place of the real key. Examples:

   • An environment variable: GITHUB_TOKEN, ANTHROPIC_API_KEY, OPENAI_API_KEY.
   • git: https://x-access-token:pf_<slot>_GITHUB_TOKEN@github.com in ~/.git-credentials.
   • A Claude subscription: copy ~/.claude/.credentials.json from an agent that claimed the slot. The file holds only placeholders.

6. Delete the real keys from the desk. Revoke each key that was on the desk before, and enrol a new one.

To turn the fence off:

Pi:

sudo sed -i 's/^INSPECT=on/INSPECT=off/' /etc/pi-fortress/segments.d/desk.env && sudo pf apply --local

Know these points:

• With ADMIN=yes on the desk, apply warns. The SSH key of the desk for the Pi can read all real keys on the Pi. Protect that key with a hardware key (ssh-keygen -t ed25519-sk) or a passphrase.
• pf-desk-restore restores the route of the desktop. It does not restore its keys. When the Pi is down, the placeholders do not work. Use a different device for an urgent login.
• The fence logs of the desk include the host, the method, the path, and the header names of unknown servers. They never include bodies or header values.
• The paranoid mode and the fake-IP of the agent network do not apply to the desk. The desk uses its own PARANOID key.
• For what breaks, refer to the FAQ.

9. Check it works¶

10. Daily loop¶

Policy changes and list changes need only a new apply, not a software update:

Pi:

sudo pf apply --local
sudo pf observe once
sudo pf monitor show -n 5

A new version of pf itself comes as an update from us.

sudo pf tui does the same things with menus:

• Select a network.
• Use Left and Right to move between its sections.
• Use Tab to move between its lists or logs.

The TUI highlights the current section and tab. Right from the last section goes to the first section. Left from the first section goes back to the menu.

The TUI saves an edit immediately. The edit takes effect at the next apply. The footer shows this until you push A. A runs the apply that the edit needs. It shows the output on System → Actions.

11. Seat¶

You can use the Pi with a keyboard and screen instead of SSH. To do this, add consoleblank=600 to the single line in /boot/firmware/cmdline.txt. Then the screen does not go blank during use. Log in and run:

Pi:

sudo pf tui

12. Do not¶

13. Troubleshooting¶