Docs · 1.0

System: The keelRM Management Port

keelRM is like the web management port of a server BMC, but provided by keelOS itself: a very small management VM runs on the host, takes one network port for itself, and serves a web page on its own address. When the host's keelOS is reloading, hung or even down, this page still opens, so you can look at the screen, read logs and restart without going to the machine room. This chapter covers the System → Remote management tab: when it can be used, how to enable and disable it, and what it can do.

1. What it can do

The keelRM page (HTTPS) offers:

• The host's screen and serial console;
• The hypervisor (hyp) log;
• Reloading root (reload), reset, power off, and "boot once from slot A / B next time".

Log in as root with the admin password (see Accounts, Tokens and Permissions). After many failed logins from the same address you have to wait a while.

The host's own network ports and addresses are left completely alone. keelRM does not cut the host off: it takes an additional, cabled network port.

2. When it can be used

keelRM needs:

• A network port of its own: besides the host's management port, another network port that is plugged in and carries no VM network (it is not part of a keel switch, network or bridge). A host with only one cabled port cannot enable keelRM, because then the host and the VMs would all depend on the management VM for network access, which keelOS does not allow. Plug in a cable at a second port and then enable it.
• An Intel CPU with VT-x including EPT, and VT-d (IOMMU) turned on in the BIOS. AMD CPUs are not supported in 1.0.
• The host runs on keelOS's hypervisor (not native mode, see System: Upgrade and Restart).
• A CPU with hyper-threading and at least 4 logical CPUs: keelRM takes one hyper-thread (the other thread of the same core is left to the host) and 64 MiB of memory. A CPU without hyper-threading (for example 4 cores, 4 threads) gets no keelRM, because that would take a whole core.
• The running keelOS includes the management VM image.

When something is not met, the Enable keelRM dialog explains point by point which one.

Note: The older modes from before 1.0 (the management VM sharing a port with the host) have been removed. On a host that has an old mode installed, a yellow card keelRM's old mode is not supported any more appears on the page with a Disable keelRM button: it restarts once through the firmware and the port goes back to the host; if the host has a second cabled port, enable keelRM again on that port.

3. Enabling

1. Open System → Remote management and click Enable keelRM. keel works out all the details first and lists them in the dialog: - keelRM's own port: if there is only one candidate port it is used directly; with several, choose one. It is shown by a name such as igb1 (00:19.0). Ports that cannot go to keelRM (the host's management port, ports with VM networks, ports without a cable) are listed as well, with the reason. - A yellow reminder that keelRM takes one hyper-thread and 64 MiB of memory. - keelRM's address: DHCP (automatic), or Fixed address (enter Address/prefix such as 192.168.1.250/24, and Gateway (optional)). keelRM is a separate device with its own address; if you use DHCP, reserve an address for it on the router. - If this port has an address now, it goes away together with the port (the dialog reminds you). - The host must restart once through the firmware (a few minutes); running VMs are shut down and started again afterwards, and the dialog lists which ones.
2. Tick Restart now (otherwise at the next restart) and click Enable keelRM. If you do not tick it, a card on the page says keelRM will be enabled at the next restart, and you can click Restart now at any time.
3. After the host restarts, keel checks by itself whether the management VM is running with this port. On success the page shows its address and the Page link. On failure keel reverts the change and the reason is shown on a card on the page (Enabling keelRM failed); the host's network is not affected.

4. What the page shows

Once enabled, System → Remote management shows:

keelRM uses its own self-signed certificate (the name is <host name>-keelrm plus its address); the first time, the browser asks you to confirm once.

Click Change to set keelRM access: switch remote management on or off, and the Networks allowed (CIDR, one per line; empty means from anywhere). With Only the management network (automatic) ticked, only the host's management network is allowed.

5. Disabling

Click Disable keelRM. The dialog lists that the port goes back to the host, that the management VM lines are removed from the boot partition's configuration, and that one restart through the firmware is needed (a few minutes; running VMs are shut down and started again). Click Disable keelRM to confirm; tick Restart now to restart at once.

6. Safe mode

If the host's root keeps failing and cannot start, you can use the keelRM page to make it start in safe mode next time: VMs do not autostart and passthrough devices stay with the host, so you can rescue the host first. While in safe mode there is a card at the top of System → Remote management: this start is in safe mode. When it is fixed, click Leave safe mode: autostart VMs start, and those with passthrough devices wait until the next start.

7. The screen while the host restarts

When an upgrade switches or the host restarts, the web page is covered by a "the host is restarting" notice. On a host with keelRM enabled, the notice also shows root's state and boot stage live, the last lines of the serial console (or the screen), and a link to open keelRM, until the host is back. If the host crashes or hangs it says so at once and stays on screen for you to act. If keelRM's certificate has not been accepted yet, the notice has a link to accept it.

8. Limits in 1.0

• Only the "own port" mode is supported; a host with only one network port cannot use it.
• Intel CPUs only.