Docs · 1.0

Network

This chapter covers the host's network: how to set and change the host's own management address, the networks and physical ports on the Network page, bridges and VALE virtual switches, connecting VMs to networks, the per-NIC firewall, SR-IOV and whole-port passthrough, the ports you need to open, and what to check first when a VM has no network. For getting the first address see Installation; for choosing a network when creating a VM see Managing virtual machines.

1. A few concepts

• Physical port: a network port on the host (igb0, ixl1...). They are listed under Physical ports on the Network page.
• Management port: the port that carries the host's own address (the address you use to open this web page). It is set at install time on the first port that gets a DHCP lease, and you can change it later.
• Network: a named layer-2 segment in keel, meaning "which physical port, with or without a VLAN tag". A VM's NIC connects to a network and does not care which port or bridge is underneath. The same network can be placed on several ports.
• The guest networks on a port have two back ends. The default is a bridge (if_bridge plus tap virtual NICs; keel sets it up behind the scenes and you never touch it on the web page). You can also switch a port to a VALE virtual switch, see §3.4. If you change nothing, it is a bridge.
• A VM's NIC can be connected in four ways: Automatic, virtual NIC, SR-IOV VF, whole port, see §5 and §6.

2. The host's management address

Open Configuration → Network → Management network.

Now lists every interface on the host (Interface, Type, Address). The type is Port, VLAN, Bridge or Other, and a port used by guests also says "N guest NICs". A port with no cable says no link. NICs that keelOS has no driver for are listed separately; you can pass them through to a VM, see Device passthrough.

To change the management address:

1. If you need to, change the Host name and Domain (optional) (host name plus domain is the host's full name, used in the certificate and the browser address). Under Interface choose the interface that carries the address. To use a VLAN, tick a VLAN on a port, choose the port and enter the VLAN number (1-4094); keel creates port.VLAN.
2. Choose DHCP or static. Static needs IPv4 address (CIDR) (for example 192.168.1.10/24), Gateway, DNS servers and Search domain; with DHCP the gateway and DNS come from DHCP. IPv6 can be Off, SLAAC (router advertisements) or static (IPv6 address (CIDR), IPv6 gateway).
3. Click Test and apply. The change takes effect at once and the old address is kept for now; the page asks you to confirm from the new address within a time limit it shows: - If the new address opens: the browser warns that the certificate is not trusted (the new address has not been accepted before); click "Advanced" then "Continue". Opening the new address is the confirmation. Only then is the change written to the boot partition, and you are logged in automatically. - If the new address does not open: when the time is up keel restores the old settings by itself and the page goes back to the old address. To undo immediately, click Undo now.
4. After the address changes, keel's certificate includes the new address from the next start of keel serve.

Note: A port already used by guests is a bridge member, so the address sits on the bridge and the bridge is left alone; the page tells you so ("... is a member of bridge ...").

Note: If you got it wrong and cannot reach the page either, use keel host net on the host's screen (console) to look and change. If there was no DHCP on first boot, the questions on the screen can be redone with keel host net setup.

Host addresses on other networks

Under Host addresses on other networks: besides the management address, the host can have one more static IPv4 address on a network, for example on a 10GbE switch to use for VM migration. In Add an address choose a Switch or network and an Address (CIDR). After saving, the list shows the Interface, Link (speed) and State (in use or not applied). The address sits on that network's bridge, and VMs keep using the network as before.

With a manager (keelMGR), Address for migrations to this host defaults to Automatic: the manager picks a network on which both hosts have an address (the faster link first), and falls back to the management address if there is none.

HTTPS certificate

Configuration → Network → Certificate lets you import your own certificate so the browser stops warning that it is not trusted. Without one, keel's own self-signed certificate is used. Remote desktop (keel-rdp) always uses keel's own certificate, so importing or deleting a certificate does not cut RDP.

3. The Network page

Configuration → Network has seven sub-pages, in this order: Network, Physical ports, Switches, Found on the ports, Topology, Management network, Certificate. At the top of the page, configuration problems related to these networks, ports and switches (for example a NIC connected to a network that does not exist) are listed as hints with Fix…, see Configuration: Problems and Advanced.

3.1 Physical ports and probing

Physical ports has one row per port: Link, Switching (Bridge, or VALE …), Mode (access or trunk), Native VLAN, VLAN, Seen on it, SR-IOV, Switch (the switch and port at the other end), Use (who uses it). Click a row to expand it: MAC, MTU, details of the last probe, guests on VALE, and the VFs in use on an SR-IOV port. Mode, VLAN and so on carry ◉ (detected automatically) or ✎ (set by hand).

Click Probe and keel listens on that port for a few seconds. It reads the neighbouring switch and native VLAN from the switch's LLDP/CDP, and works out subnets, routers and DHCP servers from the traffic on each VLAN. Tick "send a DHCP DISCOVER (does not take an address)" for a more accurate result. Probing only listens and never changes any configuration.

• If the switch sends no LLDP/CDP the page says no LLDP/CDP from the switch: set the switch and the native VLAN by hand. Click Edit and fill in Mode, Tagged VLANs (10,20; empty = as probed; none = none), Native VLAN number, Switch and port. Values set by hand carry ✎, detected ones ◉.
• To VALE / To bridge: switch the back end of the guest networks on this port, see §3.4.
• Clear forgets the probe result (the port and guests are unchanged; just probe again). It can also clear the hand-set values.

3.2 Found on the ports

Found on the ports merges probe results into candidate networks: the same DHCP server, router, subnet or group of hosts counts as one network. Each entry shows Why; click Create to make the network. Existing ones show "exists: name". If you have not probed yet, the page says to probe the physical ports first.

3.3 Making a network

1. Click Make a network on the Network sub-page (needs host write permission).
2. Name: lowercase letters, digits and _, starting with a letter, at most 12 characters (for example lan, office_2). A network cannot be renamed once made.
3. On: choose a port and enter a VLAN number (0 = untagged). + port adds another.
4. Optionally fill in Subnet and Note, then Save.

The network's card lists the ports it is on and every VM NIC connected to it: which VM, which NIC, how it is connected, and for running VMs which port it actually landed on (virtual NIC · igb0:100) and why; VMs that are off say not running. A network used by a VM cannot be Deleted.

Note: The first time you put a network on a port untagged, keel has to turn off offloads (TSO, checksum) on that port, which resets the port for a few seconds. If the host's management address is on that port, the page may drop for a moment. The dialog warns you first.

A network that is not on any port (the page says no port: internal, its guests reach each other only) is an internal network: it connects only the VMs attached to it and does not reach the outside.

The Topology sub-page draws a diagram: physical ports on the left, networks in the middle, VM NICs on the right.

3.4 Switches: VALE virtual switch

By default the guest network on each port is a bridge. Click To VALE under Physical ports and the guest network on that port is forwarded by a VALE virtual switch instead (faster between guests, per-port VLAN and isolation, counters and a MAC table). The network pages and a VM's NIC settings work the same with either back end.

• The port's link drops for a few seconds when you switch (up to a minute if the switch runs STP), and so does the host's address on that port; the confirmation dialog warns you. Running VMs switch over only after they restart.
• Before To bridge you must stop the VMs on that VALE switch.
• Only physical ports of the host have this button, not ports derived from them such as VLAN sub-ports.

A port that uses VALE appears on the Switches sub-page as a virtual switch (vs0...). If there is none, the sub-page says there are no virtual switches.

The Switches sub-page has three views:

• Ports: one table per switch with Port, Description, State (connected, not connected, shut down), Guest and Mode. By default only ports that are on, have a description or have a guest plugged in are listed; tick Show the empty ports to see all. Uplink ports (to a physical port) and the host port are in the table too. Click a port's edit button to set, in the dialog: Port on (no shutdown), the description, the Mode (access or trunk), Access VLAN (0 is untagged traffic of an uplink port), for trunks the Allowed VLANs (trunk) and Native VLAN, and Port isolation (an isolated port talks only to ports that are not isolated). After Into the candidate, nothing has changed yet.
• running-config: the same configuration as text, in Arista EOS syntax. You can edit the whole text and then Into the candidate.
• Counters and MAC table: packets, bytes and drops (split by reason) for each port, and the MAC table learned in the last 5 minutes, which you can filter by VLAN, MAC or port.

A change takes two steps: first put it into the candidate (the page then shows "there is a candidate configuration" and the differences); click Commit to make it take effect, or Discard to drop the candidate. After a commit there is a confirmation window (the page says that if the last commit is not confirmed it rolls back automatically): click Confirm the commit within it, or keel rolls back to the state before the commit, so a wrong change cannot lock you out. Undo my edits drops edits in the dialog that have not yet gone into the candidate. VLAN, mode and isolation of a port act on running guests at commit; shutting a port down waits until that VM restarts.

Note: In 1.0 the web page cannot yet pick a specific port of vs0 when creating a VM; a NIC connected to the network on this switch automatically gets a free port. If you need a specific port, set it in the VM's configuration (see The keel command line).

4. Example: add an isolated VLAN to the office network

On the switch, igb0 is a trunk port, the native VLAN is the office network and VLAN 20 is for guests:

1. Under Physical ports click Probe on igb0 and check that it sees the office network (untagged) and VLAN 20.
2. Under Found on the ports click Create for the office network and name it lan; then make another network named guest on port igb0, VLAN 20.
3. When creating a VM, choose lan or guest for its NIC.

5. Connecting a VM to a network

In the Network step of the new-VM wizard, or in the detail page's Edit → Network, each NIC has three drop-downs:

1. Network: which network to connect to. The list may also contain Switch name and Bridge name entries; those were created earlier with the command line or the API, while the Network page makes networks. If the host has no network at all, this step tells you to make one on the Network page, and what you already filled in is kept.
2. Connection: Automatic (a virtual NIC; a VF is used if the VM is shut down during a host reload and the network has a free VF), virtual NIC, SR-IOV VF, whole port.
3. Model: virtio-net (fast; Linux has the driver built in, Windows needs the virtio-win driver), e1000, pcnet. The model needs no choice for a VF or passthrough.

+ NIC adds one and ✕ removes one. The MAC is generated by keel and regenerated when you clone; expand the detail page to see each NIC's MAC and the IP the host sees.

A change of network applies at once and the guest's link does not drop (after changing to another subnet, renew DHCP inside the guest). Changing the model or connection type, or adding or removing NICs, waits for the next restart. If the network, switch or bridge a NIC is connected to no longer exists, the VM cannot start; the detail page marks it, and you just switch to an existing one (it also shows under Configuration → Problems).

Per-NIC firewall

On a VM's detail page each NIC has a Firewall row, off (everything passes) by default; NICs with it off have no overhead at all. Click Change (Show for a read-only account) to open the dialog:

1. Tick Filter this NIC (inbound denied unless allowed below).
2. Allowed inbound, one per line: protocol[/port][@source], for example tcp/22@lan, tcp/8000-8100@any, [email protected]/24, udp/53. The protocol is tcp, udp, icmp (ping only) or any; the source is any, lan (the default; excludes other guests), guests or an address/CIDR.
3. Pick one level for Outbound: internet only, internet and LAN, replies only (only replies to inbound connections pass).
4. Also allowed outbound, one per line: allowed in addition to the level above, written as [protocol[/port]@]destination. The destination can be keelauth, frontdoor, app:appname, guests, lan or an address/CIDR, for example tcp/[email protected]. Names are resolved to addresses when the VM starts.

Replies to allowed connections pass in both directions; ARP, DHCP and IPv6 neighbour discovery are always allowed. The dialog and the NIC row show the inbound and outbound packets blocked since this boot and the current connection count. A change takes effect at the VM's next start; until then the dialog says the guest still runs with the old rules.

Note: When the NIC uses an SR-IOV VF or whole-port passthrough, traffic does not go through the host and the firewall cannot be used; with Automatic, a NIC with the firewall on does not use a VF. The inbound ports of a kcell application are defined by the application template and shown on the application's card, see kcell applications.

The front door is a kcell application that gives other applications an https address; the applications' own firewalls accept connections only from the front door. How to install and use it is in kcell applications.

Routers and firewall VMs

For VMs such as OpenWrt, OPNsense and RouterOS:

• At most one port may connect to the office network (either one network or one VF, not both); connect the other ports to isolated networks that exist only on this host. Router images often bridge every port except WAN together by default, and connecting two ports that lead to the office network makes a loop that takes the whole office network down. For router templates the wizard does not allow several ports on the same network.
• By default each virtual NIC can only send packets with its own MAC (loop protection). If the VM runs its own bridge, VRRP or container macvlan, those packets are dropped. The web page has no switch to turn this filter off yet; when you need it, set allow_mac_spoofing in the VM's configuration (see The keel command line).

6. SR-IOV and whole-port passthrough

• SR-IOV VF: a supported NIC (Intel X710, X550, I350 and so on) can split one physical port into several virtual ports (VFs). Each VF is passed to one VM, which sees a real NIC driver and gets the best performance. Under Configuration → SR-IOV each port shows "VFs: created N / at most M" and you set them with VFs; each VF has a fixed MAC, VLAN and the guest that uses it.
• To use a VF on a network: choose SR-IOV VF as the NIC's connection type. The port the VF belongs to must be in that network.
• Whole port: the whole NIC goes to one VM; first Keep it for passthrough under Configuration → PCI passthrough.

Note: A VM with a VF is shut down and started again at a host reload, not suspended; only VMs with whole-device passthrough are paused. Changing the VF count usually makes the port renegotiate its link, and STP on the switch may block for about 30 seconds; if the host is using the port, you are warned that it will lose the network for about 30 seconds.

Details are in Device passthrough.

7. Ports and firewalls

The keelOS host does not allow "any port" by itself. Here is what you need to allow on your firewall or router:

keelRM is a separate management port, like a server's BMC: it uses another plugged-in network port of the host and has its own address; the page is https://<its address>/, and port 80 redirects there. Choose DHCP or a fixed address (Address/prefix, Gateway) in the keelRM settings; the address is shown on the page, and the host's ports and addresses stay as they are. See The keelRM management port.

8. 10GbE networks

• 10GbE ports are used the same way as gigabit ones; no special setup of the management address or networks is needed.
• For a 10GbE switch used for migration, put an address on it under Host addresses on other networks in §2.
• On ix ports such as the X550 the VF count has a default limit; "Make the setting (after a restart)" on the SR-IOV page raises it, and needs a host reboot.
• The web page has no tuning options specific to 10GbE.

9. A VM has no network

Check in this order:

1. Does the network the NIC is connected to still exist? See whether the NIC row on the VM's detail page is marked red "does not exist". You can fix it under Configuration → Problems.
2. Is the network on the right port? On the Network page look at the network's port and VLAN. The VLAN number must match the switch; if unsure, Probe the port under Physical ports.
3. The switch port: is it trunk or access? A trunk must allow this VLAN. Does the port have a Link?
4. Inside the guest: a Windows virtio-net NIC needs the virtio-win driver, otherwise there is no NIC. If DHCP gives no address, look at the network card on the Network page for the port the NIC actually landed on, then check Seen on it under Physical ports to see whether that VLAN has a DHCP server.
5. A VM on a VF: the VLAN of the VF's port must match the network's VLAN; the guest needs the VF driver (the default OpenWrt image has no iavf; install kmod-iavf).
6. The whole office network is slow or down: check whether a router VM has two ports connected to the office network, see §5.
7. The host's own web page is unreachable: see the recovery steps in §2; if you cannot wait, use keel host net on the host's screen.

More troubleshooting is in Troubleshooting and Logs.

10. What 1.0 does not do

• VALE is not the default back end yet: a port is a bridge by default, and you must switch it to VALE per port by hand (§3.4). A VALE switch has only one uplink and no mirror port.
• The host has no NAT and no DHCP service, and no per-host or per-network firewall (only the per-NIC firewall). If you need those, run a router VM, see §5.
• The web page has no link aggregation (LAG/LACP); STP is off, and loop protection relies on the virtual NIC's source MAC filter.