Docs · 1.0

Console and remote desktop

This chapter explains how to see a virtual machine's screen and type into it: the graphical console (VNC) and the serial console in the web page, connecting with an RDP client, the monitor attached to the host itself (Ctrl-Alt-F1 … F12 and the info screen), USB redirection, and screen recording. For starting, stopping and changing settings of virtual machines see Virtual machines.

1. Consoles in the web page

While a virtual machine is running, each list row and the top of the detail page have console buttons: Serial console, and for machines with VNC turned on also Screen (VNC) (icons in the list, with tooltips). A machine without VNC has no graphical console; see Virtual machines §2.5. The left of the detail page also has a small picture called the guest's screen, refreshed every 5 seconds; click it to open the VNC console. If the virtual machine has no picture it says no screen.

Each console can be opened in three ways:

• opens in its own window: click the button itself (on the detail page the button has a ↗).
• in this page: the button next to it on the detail page.
• floating: always on top and can be dragged outside the browser (one per browser tab; needs browser support); the icon buttons in the list open it this way.

If the browser blocks the pop-up window you are told, and it automatically opens in this page; allow pop-ups for this site to use a new window.

1.1 Screen (VNC)

The web page shows the virtual machine's screen directly, with keyboard and mouse, from the boot screen and BIOS to the installer. There are a few buttons at the top:

• Ctrl-Alt-Del: sends this key combination to the virtual machine (the browser itself intercepts the real keys).
• Full screen, Fit to window.
• After a disconnect click Connect again; the status shows connecting…, connected or disconnected.

Only one person can watch at a time. When someone else is using it, the page says "so-and-so has been using this screen since such-and-such address"; click Take over (disconnects them) to take it. The person who was taken from sees "so-and-so took this screen over".

Note: for a virtual machine with a graphics card passed through, once the driver is up the picture is on the monitor attached to that card, and the web console may stay stuck at the boot screen; that does not mean it has crashed. For a virtual machine with the Intel integrated GPU passed through, the web console shows the integrated GPU's picture at about 10 frames per second; use RDP if you want smoothness.

1.2 Serial console

The virtual machine's serial port (text), useful for Linux, BSD and routers when the kernel and login terminal are on the serial port. Several people can watch at once, but only one can type at a time:

• The status bar says you type here, or watching · so-and-so types / watching · nobody types, and N connected.
• On a watch-only page click Take over to start typing and Stop typing to let go. When someone else takes over you are notified.
• When the virtual machine is not running it says "not running, will connect automatically after it starts" and connects by itself once it is up; after a disconnect it reconnects automatically.

What appears on the serial port is also kept in the Serial tab of the Log (top of the detail page); see Virtual machines §10.

2. Connecting to a virtual machine's screen with RDP

keelOS runs an RDP service on the host (keel-rdp), and all virtual machines share the host's port 3389; you choose the virtual machine with the user name. What it connects to is the screen itself of the virtual machine, not a remote desktop inside the guest: nothing needs installing in the guest, and you can see and operate the boot screen, BIOS, installer, and virtual machines with no network.

The RDP row of the virtual machine's detail page gives address:port, user name <virtual machine name>, and the line below says which password applies: this guest's own RDP password (set under Remote console on the edit page), the admin password (when none is set; the user name is still the virtual machine's name), or the host's RDP password.

• Windows: click Download .rdp file and double-click it; Remote Desktop (mstsc) connects, and asks for the password by itself.
• Other systems: any RDP client (FreeRDP, Remmina, Microsoft's "Windows App" on other platforms) with the same address, port, user name and password.
• kRDPclient: keel's own client; on top of mstsc it has a video-encoded picture, USB redirection and sound. See Companion software.

The RDP service, like mDNS, can be turned off altogether under System; see System: maintenance, time and host console.

2.1 Console video (for kRDPclient)

Console video in the Remote console section of the edit page adjusts the video picture kRDPclient receives (mstsc is not affected), and takes effect at the next RDP connection:

• frame rate: 60 by default.
• quality: balanced (default), speed (less CPU), quality (more CPU and bandwidth).
• encoder threads: auto (default) or at most N.

2.2 Sound

Sound card (HD Audio) under Devices on the edit page: Automatic (keel decides), On, Off. Sound is sent by keel-rdp to the RDP client, and the guest uses the driver built into the system. With automatic, Windows Vista and later and Linux desktops get a sound card; Windows XP, Server 2003, routers, NAS and virtual machines without a display do not. It takes effect at the next cold start. The Sound card row of the detail page says whether there is one now and, if not, why (for example "PCI slots 3–27 are all used").

2.3 USB redirection

USB sticks, USB-to-serial adapters and dongles on the user's computer can be plugged into the virtual machine through the RDP client. Tick USB redirection (Devices on the RDP client's side) under Devices on the edit page: keel adds two empty USB ports (USB 2 and USB 3) to the virtual machine, and the client attaches devices to them after it connects.

• mstsc: Local Resources → More… → Other supported RemoteFX USB devices. In kRDPclient you choose in its interface.
• Virtual machines with UHCI USB (Windows 7 and older) do not work for now. If the host's bhyve is too old, the checkbox shows USB redirection needs a newer bhyve.
• The detail page gets a USB devices card listing the device on each port, Plugged in by (account and source address) and Since; it is in the audit log as well. The Detach button currently only records the request and does not force the device out: ask the user to untick it in the client.
• Boot from USB once: plug a boot stick in through RDP, click this button, and the next start (a running machine is reset first) boots from the stick, this once only; available for UEFI virtual machines and needs USB and power permission. Without a stick it boots from the hard disk as usual.

3. Screen recording

The Screen recording card on the detail page works like a dashcam: once turned on, every run of the virtual machine has its screen recorded at a very low frame rate, in segments of about a minute, and the oldest are deleted when space runs out. The latest few segments are put into the diagnostics bundle, so when something goes wrong you can see what happened before.

• Turn on / Turn off: the switch. Under Settings you can change Space for recordings (MiB) (16 to 65536) and Frames per second (1 to 10).
• Watch: opens a player window listing each segment by time (start, duration, size; the one being recorded is marked recording now); click a row to play it. Times are shown in the host's time zone. Delete all removes all recordings of this virtual machine.
• Changing settings needs write permission on the virtual machine; watching needs console permission.

4. The host's own monitor (screens F1 to F12)

When a monitor and keyboard are attached to the host, the Virtual machines → Screens (F1–F12) sub-page appears (it does not when the local screen feature is off or the host has no monitor).

• Ctrl-Alt-F1 is the host's own console, and Ctrl-Alt-F2, F3 … switch to the screens of the virtual machines; one set of keys works everywhere. Only virtual machines with VNC on take a key, by default sorted by name.
• At the top of the page is a strip of keys F1 … F12; each shows its current picture (refreshed every 5 seconds), on the screen marks which key the monitor is on now, and the Switch button is the same as pressing that key. A virtual machine with a graphics card passed through says "Passthrough VGA, not available here". Drag a virtual machine's name onto a key, or pick it in the key, to change which key it uses; back to automatic returns to sorting by name. After arranging by hand, a newly created virtual machine goes into the first empty key.
• A virtual machine that is not running shows a notice on screen; press Enter to start it right there.
• To send Ctrl-Alt-Fn itself into the virtual machine (for example to switch a Linux desktop back to a text terminal), press Ctrl-Alt-Shift-Fn.
• In a virtual machine's picture, every key except Ctrl-Alt-Fn is handed to the virtual machine unchanged.
• A virtual machine using an integrated-GPU SR-IOV VF cannot normally be seen by the host. Drag it onto a screen key, and when you press that key the display virtual machine shows its keelagent picture (keelagent must be running in the guest and the desktop logged in). This is an experimental feature, off by default in the info screen card (VF guests on their screen keys (experimental)): on machines such as the 13420H it hangs the GPU's video engine and the virtual machine blue-screens, so please leave it off.

Note: after keelOS's lower layer restarts (a reload), each key returns to the same virtual machine picture as before.

4.1 Info screen

F2 is the Info screen by default (the page says Info screen): before the admin password is set it shows the keelOS logo and the login address; afterwards it shows a clock, host information, CPU, memory and the virtual machine list. In the "Info screen" card below the key strip you can turn it On, choose which key it occupies with Shown on (no key = takes none), and six templates (host overview, System, photo frame, Video, Weather, Clock) are laid out as live previews; click one to switch to it. At the top of the card you can set the info screen's Language (when following the system, decided by the time zone).

On the host's monitor, press ← → or the digits 1–6 to change template (1 host overview, 2 system, 3 photo frame, 4 video, 5 weather, 6 clock), and ↑ ↓ or space to change photo (change video on the video page); these keys are shown at the bottom when you switch to the info screen.

Each template has its own options below it:

• Clock: digital or analogue; when digital you can choose the font (default, monospace, seven-segment).
• Photo frame: Next after (slider, 5 seconds to 1 hour), Change (fade, slide, tiles, none), and Picture filled or shown whole. The card shows how the picture is output: with Output: display VM, page flips sliding does not tear; with without page flips or the host itself moving pictures may tear, and then tiles and fade look better.
• Weather: renders the whole screen as the current sky with animation (rain, snow, clouds, stars); Motion can be turned off.
• Video: plays the videos in the Video folders… in order by name, in a loop (MP4, MKV, WebM, MOV; H.264, HEVC including 10-bit, VP9, AV1). The display virtual machine decodes them in hardware on the integrated GPU, using almost no CPU. In the options you can choose whole-picture (with black bars) or filled, and whether to show a clock; there is no sound for now. Player… under the video card opens a small player: choose a video, drag the position, play/pause, previous/next. Playing, dragging or choosing a video switches the info screen to the video page; the video pauses automatically when the screen is switched to another page and continues when it comes back. Videos that cannot be played are skipped, with the reason shown on screen.

Weather…: search for and choose your area (until then it says no place chosen: the weather widget is empty); after that the host overview and the photo frame show the weather and the forecast for the next few days. The forecast comes by default from the models of the local national weather service (the China Meteorological Administration for China, via Open-Meteo), and Forecast lets you pick another one to compare. Open-Meteo's free API is for non-commercial use only; a business should enter its own key in Open-Meteo API key.

Photo folders… and Video folders…: the photo frame's photos by default come from the photo library of the photo inbox, and you can also name a dataset or directory (photos can be JPEG, PNG, WebP; HEIC is not supported yet). The "open" next to each folder uses the file browser to look, upload and delete; when there is no folder yet, click "Make /photos" (/videos for videos) and keel creates one. Once a video folder is set, the display virtual machine uses 512 MB more memory (and the display virtual machine is restarted once automatically). Videos can be played only when the display virtual machine has taken over the monitor (the integrated GPU is passed through to it).

In the same dialog, tick "Also landscape photos from Wikimedia Commons" and keel downloads about 100 freely licensed selected landscape photos once (about 70 MB) and rotates them together with your local photos, with the author and licence shown below the photo; if you do not tick it, nothing goes online.

5. What 1.0 does not support yet

• Only one person at a time can use VNC in the web page; for several people watching at once use RDP or the serial console.
• Detach for USB redirection only records the request and does not force the device out (§2.3); old UHCI systems cannot use redirection.
• The info screen's video has no sound for now.