Serial Terminal

Why would I need a serial terminal / serial console ?

Note: This apply to qemu/kvm virtualization.

If you do a lot of work over ssh on your pve server you would maybe appreciate to connect to your running VMs like:

qm status 101
status: running

qm terminal 101
starting serial terminal on interface serial0 (press control-O to exit)
------------------------------------------------------------------------------

Welcome to the Proxmox Virtual Environment. Please use your web browser to 
.....
------------------------------------------------------------------------------
pve4 login:

This is especially useful if the keyboard layout or network is broken on the guest, as the text terminal don't use them. As the displaying of the text is done client side, it also uses much less ressources than the javascript console, which can be important if you get a lot of text output.

Some background so you get the idea

When you start Unix/ Linux on a PC, the default input device is the attached keyboard (PS/2 or USB), and the default output device is the available VGA /HDMI / Display port of the PC. During the system boot, the kernel send its boot messages, like device detection, to the default output device , and at the end of the boot processes, fires a "login: " prompt on this default output device ( ie your pc display). ( Actually it spawns multiple login prompts, you can switch between them with Ctrl-alt-F1, Ctrl-alt-F2, etc ... )

Now it's perfectly fine to send the boot messages and start a login prompt on something else. For instance the Linux Kernel has a netconsole feature, to send the boot messages over the network to another Linux computer. It is also possible to send a copy of the boot messages, and start a login prompt on the serial port of the Linux PC. If you connect to this serial port any computing device with a terminal emulation program, it will be possible to work on the Linux PC as if you were using the Linux PC locally in text mode. This requirements of this computing device with terminal emulation are quite low, so you could use HyperTerminal on a Windows PC, Minicom on Linux or even an old Atari ST with the appropriate programm.

How do this apply to Proxmox PVE ?

In proxmox things work exactly same, but with emulated devices. NoVNC/ VNC Applet connects to your emulated PC keyboard and emulated PC VGA display and displays the stuff you would expect from a real PC on a vga display with a locally attached keyboard. Now we can also configure our emulated PC to have an emulated serial port, and instruct the OS running inside, to send a copy of the boot messages, and start a login prompt on the emulated serial port. Once this is configured it will be possible to connect from the host (ie the server running pve) using a terminal emulation programm, which is handily builtin in the Proxmox Qemu Manager.

Configuration on the host

Add a virtual serial port to the VM

# open  /etc/pve/qemu-server/101.conf and add the following parameter at the end of file
serial0: socket

Configuration on the guest

Reboot the VM, verify that the emulated serial port is there

dmesg | grep ttyS
[    0.457814] 00:0a: ttyS0 at I/O 0x3f8 (irq = 4) is a 16550A

Instruct grub2 to send the boot messages on the VGA display and on the serial port

# in /etc/default/grub change the GRUB_CMDLINE_LINUX_DEFAULT parameter to
GRUB_CMDLINE_LINUX_DEFAULT="quiet console=tty0 console=ttyS0,38400n8" 

and run

update-grub

Instruct the init system (here systemd) to start a login promt on the serial port

systemctl start serial-getty@ttyS0.service
systemctl enable serial-getty@ttyS0.service

Connecting to the Serial Terminal

On the Host, just enter

 qm terminal <VMiD> 

and enter enter a second time you should get a login prompt

Trouble shooting

You can check that the virtual serial port is present, and properly bound to the unix socket that qm terminal uses with:

qm monitor <VMiD>
info chardev 

which should contains a line starting with serial0 like:

serial0: filename=disconnected:unix:/var/run/qemu-server/101.serial0,server