Gateway (create a zone)

A zone is a subnet, which has a gateway, behind which you can connect as many machines as you want.

Hardware

The gateway is ideally installed on a mini-computer that is always on, with at least two network interfaces: one to the ISP box (WAN), the others to the local network (LAN, ethernet or wifi).

What hardware?

For example, a Protectli 🡕 box or equivalent:

• NVMe disk ≥ 256 GB
• coreboot BIOS preferably
• Optional wifi card

Declare the zone

The zone and its gateway are described in etc/config.yaml:

etc/config.yaml

zones:
  maison:
    description: "Home network"
    ipPrefix: "10.0"             # zone in 10.0.0.0/16
    gateway:
      wan:
        interface: "enp1s0"      # to the ISP box
      lan:
        interfaces: ["enp2s0"]   # to the local network

hosts:
  - hostname: "gw"
    name: "Gateway"
    zone: "maison:1.1"           # fixed IP 10.0.1.1
    profile: "gateway"
    services:
      adguardhome:               # DNS + ad blocking
      homepage:                  # service portal
    disko:
      profile: "server-1-disk"
      devices:
        main: "/dev/sda"

Automatic services

The gateway profile wires the router, firewall, DNS/DHCP (dnsmasq) and the VPN client. Declared services (homepage, adguardhome…) are configured automatically. See Network.

Install the gateway

Installation is often done remotely: someone on site prepares the machine, the administrator installs over SSH.

1. Prepare the gateway (on site)

   1. Plug the gateway into the box.
   2. Boot from the USB stick (image just build-iso).
   3. Note the gateway’s IP address.
   4. Forward port 22 of the box to the gateway.

   Why forward port 22?

   It provides SSH access during the installation. The USB stick only accepts authentication keys (no password). The forwarding can be removed afterwards.

2. Install (administrator)

   A single command chains disk formatting, hardware configuration, deployment, and cleanup :

   just full-install gw nixos <ip>

   • gw: host name declared in etc/config.yaml.
   • nixos: user of the live USB stick (DNF image).
   • <ip>: address noted at the previous step.

   Do without the address

   If the gateway’s mac key is listed in etc/config.yaml, its address is reserved in advance and does not change between the USB stick and the installed system. just full-install gw is then enough, without reading or entering anything.

Install from another zone

A gateway is often prepared somewhere other than its destination. Plug its WAN interface into the local network of the hosting zone : it receives the roaming address that this zone reserves for it based on its MAC.

Three conditions :

• the gateway’s mac key is declared in etc/config.yaml ;
• the gateway of the hosting zone has been redeployed since that declaration;
• the administration machine too, so that SSH reads the forwarding set up during the installation.

Then, just full-install gw does without an address : the tooling computes the target and tracks it from start to finish. The principle is described in Machines outside their zone.

Once the gateway is delivered

On site, it takes back the fixed address of its zone (.1.1). The SSH forwarding set up for the installation is no longer needed : just roaming-clear gw.

Register the gateway on the VPN

A gateway is a Tailscale client: it advertises its zone’s subnet in the Headscale mesh. Until it is registered on the tailnet, other zones cannot see it.

Follow the dedicated procedure: Register a gateway.

Connecting other machines

• Linux workstations : same procedure as the first workstation, see Initial installation.
• Smartphones, tablets, third-party PCs : connect automatically to the gateway’s network.

Replacing the hardware

Replacing the computer of a gateway in service is a distinct procedure : the machine is new, but its state is not. See Migrating a gateway’s hardware.