Install a gateway

Each customer needs a gateway on their network, in the customer’s region; see How Witina works for an MSP. A gateway can’t be moved to another region later, so choose the region carefully.

Before you start

• A host on the customer’s network. One of: Hyper-V; VMware or VirtualBox; a bare-metal x86 machine; or a Docker or Kubernetes host (x86 only).
• Room for the VM. The images are set up with 2 virtual CPUs, 2 GB of memory, and a 20 GB disk.
• Outbound HTTPS (port 443) from the gateway to the internet. Nothing needs to connect in to it. See Gateway network requirements.
• An address from DHCP. The gateway takes its address from DHCP. If you want it to keep the same address, give it a DHCP reservation, for example in the customer’s UniFi console.

Installing a gateway has two parts: getting it running on the customer’s network, then claiming it, which connects it to your organization and places it in a region. The Hyper-V command and the container commands claim the gateway for you. For a VM or a bare-metal machine, claiming on the network is the easiest way.

Hyper-V

The quickest way on Windows. One command creates the VM and claims it.

1. Go to Gateways → Add gateway and choose Install from an image.
2. Choose the customer’s Region, and optionally a Division, Name, and Description. Then choose Continue.
3. Under Hyper-V (Windows), copy the command.
4. On the Hyper-V host, open PowerShell with Run as administrator and paste the command.

The command:

• checks that Hyper-V is installed and running
• connects the VM to the host’s external virtual switch. If there are several, it asks which; if there are none, it asks before creating one called “Witina External”.
• downloads the gateway’s disk and checks it hasn’t been altered
• creates a VM called “Witina Gateway” that starts with the host
• waits for the VM to get an address, and claims it

The command works for 3 days. Leave the Add gateway window open: it shows “Gateway checked in” when the gateway has connected.

VMware or VirtualBox

1. Go to Gateways → Downloads and, under Virtual appliance (OVA), choose Download OVA.
2. Import the OVA into your hypervisor, connect its network adapter to the customer’s network, and start it. On its first boot it restarts once by itself.
3. Claim it on the network, or with a provisioning token.

Bare metal

Use the ISO for a dedicated x86 machine.

1. Go to Gateways → Downloads and, under ISO image, download the ISO. Write it to a USB drive.
2. Boot the machine from it.

Caution

The ISO installs itself without asking. It erases the machine’s first internal disk.

3. The machine restarts into the installed gateway. Claim it on the network, or with a provisioning token.

Container

1. Go to Gateways → Add gateway and choose Run it as a container.
2. Choose the customer’s Region, and optionally a Division, Name, and Description. Then choose Continue.
3. Pick Docker, Docker Compose, or Kubernetes, and run the commands shown. They include a provisioning token, so the gateway claims itself.

The container needs the host’s network, not a bridged one, and three Linux capabilities: NET_ADMIN and NET_RAW to listen for LLDP, CDP, and DHCP traffic, and NET_BIND_SERVICE to serve files to devices during a configuration restore. Without them the gateway still runs, but those features stop working. The VPN needs the host’s network and NET_ADMIN too, and WireGuard in the host’s kernel; see Run the VPN on a Docker gateway.

Claim a gateway on the network

From a computer on the same network as a gateway that’s running but not yet claimed:

1. Go to Gateways → Add gateway and choose Find it on this network.
2. Witina looks for unclaimed gateways for up to two minutes. Your browser may ask for permission to access devices on your local network.
3. Choose Claim next to the gateway, enter a Gateway name, and choose its Region and, optionally, a Division. Then choose Claim gateway.

This works within one network segment, not across VLANs or a VPN. The gateway also needs internet access already.

Claim a gateway with a token

If you can’t be on the gateway’s network segment, claim it with a provisioning token:

1. Get a token:
   • Gateways → Add gateway → Install from an image, choose the region, and choose Continue. The token works for 3 days.
   • Or use the token shown when you onboarded the customer, or Issue provisioning token on the customer’s page. These work for 30 days.
2. The gateway’s console shows its address and its page, http://<address>:8080. From a computer that can reach the gateway, open that page.
3. Choose Claim this gateway, enter the token, and choose Claim.

After installing

The gateway appears under Gateways with its state, address, version, and region. Once it’s online, it starts discovering the network; see Bring devices under management.

Console login and SSH

A gateway installed from an image has no console login until it’s claimed. After that, its row under Gateways has:

• Change console password: Witina asks you to confirm it’s you, then shows a new password once. Witina doesn’t keep it.
• Turn on SSH and Turn off SSH.

Container gateways have no console login.

Updates

Choose Software version from a gateway’s menu to pick what it runs:

• Automatic keeps it on the latest version.
• A specific version pins it there.
• Hold leaves it as it is.

Gateways installed from an image start on Hold, and container gateways on Automatic. A gateway installed from an image restarts into the new version, and goes back to the previous one by itself if the new version doesn’t come up healthy.