Skip to main content

Serial Console

The serial console provides out-of-band, text-based access to a virtual machine, independent of its normal network connectivity. The platform attaches an emulated serial port on the VM and presents it inside the guest as a serial device; /dev/ttyS0 on Linux. Its input and output are tunnelled to your browser through the Gallium Console, so you can watch boot messages and log in even when the VM's networking is unavailable.

info

The serial console is only available on virtual machines that use a Linux hardware profile. Windows does not provide an interactive serial terminal by default.

Opening the Serial Console​

To open the serial console:

  1. Navigate to the VM's detail page and select the Dashboard tab.
  2. Click Serial Console.
  3. The console opens in your browser. Press Enter to prompt the guest to redraw the current screen or display a login prompt.

Guest Configuration Requirements​

For the console to be usable the guest operating system must direct a login and console output to the serial port. On Linux this requires a console=ttyS0 kernel argument and a serial getty listening on the port. This is standard in cloud images but is usually absent from VMs installed from an ISO.

tip

VMs created from Gallium's Linux templates use cloud images, which are already configured for serial console output. In most cases the serial console works with no extra setup.

Troubleshooting​

The console connects but shows a blank screen​

If the serial console opens but stays blank, the connection has succeeded; the serial port exists, but nothing inside the guest is writing to it. This is expected when the guest has not been configured to use the serial port, which is common for systems installed from an ISO rather than a cloud image.

First, press Enter. A configured guest will respond by redrawing its output or showing a login prompt. If the screen remains blank, configure the guest to use the serial port as follows.

1. Add the kernel console argument.

Edit /etc/default/grub and add console=ttyS0,115200 to the GRUB_CMDLINE_LINUX line. Keeping console=tty0 as well preserves output on the graphical console:

GRUB_CMDLINE_LINUX="console=tty0 console=ttyS0,115200"

Apply the change and reboot:

# Debian/Ubuntu
sudo update-grub

# RHEL/CentOS/Fedora
sudo grub2-mkconfig -o /boot/grub2/grub.cfg

2. Enable a login prompt on the serial port.

Start a getty on ttyS0 so you can log in:

sudo systemctl enable --now serial-getty@ttyS0.service

After rebooting, boot messages will appear in the serial console and pressing Enter will present a login prompt.

note

These steps apply to most systemd-based Linux distributions. The exact bootloader configuration may differ on other systems.