Difference between revisions of "Serial Terminal"

From Proxmox VE
Jump to navigation Jump to search
 
(18 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
[[Category:HOWTO]]
 
[[Category:HOWTO]]
==Why would I need a serial terminal / serial console ? ==
+
== Why would I need a serial terminal / serial console? ==
 
Note: This apply to qemu/kvm virtualization.  
 
Note: This apply to qemu/kvm virtualization.  
  
Line 15: Line 15:
  
 
Other use cases:  
 
Other use cases:  
* you lost network access to the guest and VNC is either too slow for you or don't have the features you need (i.e. easy copy/paste between other terminals)
+
* you lost network access to the guest and VNC is either too slow for you or does not have the features you need (i.e. easy copy/paste between other terminals)
* your guest freezes or kernel panics, you want to debug it, but it's impossible to capture all messages on VNC screen
+
* your guest freezes or kernel panics, you want to debug it, but it is impossible to capture all messages on VNC screen
 
* your keyboard layout is borked on the guest
 
* your keyboard layout is borked on the guest
 
* you are familiar with <code>xm console <guest></code> from Xen and you want to use a similar feature here
 
* you are familiar with <code>xm console <guest></code> from Xen and you want to use a similar feature here
Line 22: Line 22:
 
== Some background so you get the idea ==
 
== 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. This is called in Unix-speak the Default Console.
+
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. This is called in Unix-speak the '''default console''', or '''system console'''.
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 ... )  
+
During boot, the kernel sends its boot messages, like device detection, to this default console, and at the end of the boot processes, fires a "login: " prompt on this console. (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 PC.
+
Now it is 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 PC. We get then what is called a '''serial console'''
 
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 PC locally in text mode. The requirements of the terminal emulation are quite low, so you could use HyperTerminal on a Windows PC, Minicom on Linux or even an [http://www.tldp.org/LDP/LG/issue70/arndt.html old Atari ST] with the appropriate program.
 
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 PC locally in text mode. The requirements of the terminal emulation are quite low, so you could use HyperTerminal on a Windows PC, Minicom on Linux or even an [http://www.tldp.org/LDP/LG/issue70/arndt.html old Atari ST] with the appropriate program.
  
 
=== How do this apply to Proxmox PVE ? ===
 
=== How do this apply to Proxmox PVE ? ===
  
In proxmox things work exactly same, but with emulated devices. NoVNC/ VNC Applet connects to your VM keyboard and VM VGA display and displays the stuff you would expect from a real PC on a vga display with a locally attached keyboard.
+
In proxmox things work exactly the same, but with emulated devices. NoVNC/ VNC Applet connects to your VM keyboard and VM 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 VM to have an emulated serial port, and instruct the OS, to send a copy of the boot messages /start a login prompt on the emulated serial port.
+
Now we can also configure our VM to have an emulated serial port, and instruct the OS, to send a copy of the boot messages / 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''' program, which is handily builtin in the Proxmox Qemu Manager.
 
Once this is configured it will be possible to connect from the host (ie the server running pve)  using a '''terminal emulation''' program, which is handily builtin in the Proxmox Qemu Manager.
  
Line 37: Line 37:
  
 
===== Add a virtual serial port to the VM =====
 
===== Add a virtual serial port to the VM =====
 
+
Provided your VM IS is 101
 
  # open  /etc/pve/qemu-server/101.conf and add the following parameter at the end of file
 
  # open  /etc/pve/qemu-server/101.conf and add the following parameter at the end of file
 
  serial0: socket
 
  serial0: socket
 +
 +
or use
 +
qm set 101 -serial0 socket
  
 
== Configuration on the guest ==
 
== Configuration on the guest ==
 +
 +
==== Configure the terminal if not present ====
 +
As detailed in https://help.ubuntu.com/community/SerialConsoleHowto#Server_Setup , check if you have the file '''/etc/init/ttyS0.conf'''. If not, create it:
 +
    '''# ttyS0 - getty
 +
    '''#
 +
    '''# This service maintains a getty on ttyS0 from the point the system is
 +
    '''# started until it is shut down again.
 +
 +
    '''start on stopped rc RUNLEVEL=[12345]
 +
    '''stop on runlevel [!12345]
 +
 +
    '''respawn'''
 +
    '''exec /sbin/getty -L 115200 ttyS0 vt102'''
 +
then ask upstart to start terminal
 +
    '''sudo start ttyS0'''
 +
You might consider creating the ttyS1.conf file as well, just as a backup in case you have a crash with ttyS0
  
 
===== Reboot the VM, verify that the emulated serial port is there =====
 
===== Reboot the VM, verify that the emulated serial port is there =====
Line 47: Line 66:
 
  dmesg | grep ttyS
 
  dmesg | grep ttyS
 
  [    0.457814] 00:0a: ttyS0 at I/O 0x3f8 (irq = 4) is a 16550A
 
  [    0.457814] 00:0a: ttyS0 at I/O 0x3f8 (irq = 4) is a 16550A
 +
 +
If ttyS0 is not there, type
 +
 +
'''sudo start ttyS0'''
 +
from the VM shell
  
 
===== Instruct grub2 to send the boot messages on the VGA display and on the serial port =====
 
===== 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
+
  # in /etc/default/grub change the GRUB_CMDLINE_LINUX parameter to
  GRUB_CMDLINE_LINUX_DEFAULT="quiet console=tty0 console=ttyS0,38400n8"  
+
  GRUB_CMDLINE_LINUX="quiet console=tty0 console=ttyS0,115200"  
  
and run
+
run
 +
# debian based
 
  update-grub
 
  update-grub
 +
# redhat based
 +
grub2-mkconfig --output=/boot/grub2/grub.cfg
  
===== Instruct the init system (here systemd) to start a login promt on the serial port =====
+
and do a final reboot
 
 
systemctl start serial-getty@ttyS0.service
 
systemctl enable serial-getty@ttyS0.service
 
  
 
== Connecting to the Serial Terminal ==
 
== Connecting to the Serial Terminal ==
  
 
On the Host, just enter
 
On the Host, just enter
   qm terminal <VMiD>  
+
   '''qm terminal <VMiD>'''
and enter enter a second time you should get a login prompt
+
and enter '''enter''' a second time you should get a login prompt
 +
 
 +
'''Note:''' if it seems this is not working, and if you have defined ttyS1, you can connect to itwith the command
 +
  '''qm terminal <VMiD> -iface serial1'''
 +
 
 +
Now if you reboot your system you should see that the kernel startup messages are send to both your serial terminal and NoVNC display.
 +
 
  
Now if you reboot your system you should see that the kernel startup messages are send to both your serial terminal and NoVNC display:
+
 
 +
Additionally (quoting from a private email, edited for clarity):
 +
Qemu also supports binding the emulated serial port to a telnet server.  Look for the -chardev parameter in the qemu-kvm manual page.  (With proxmox you would then use the "args:" parameter in vm.conf to specify extra args.)  This would allow you to telnet to your host on a specific port to get a serial console.  As with every telnet traffic remember that nothing is encrypted, so I wouldn't do this in a production setup.
  
 
== Trouble shooting ==
 
== Trouble shooting ==
Line 78: Line 110:
 
  serial0: filename=disconnected:unix:/var/run/qemu-server/101.serial0,server
 
  serial0: filename=disconnected:unix:/var/run/qemu-server/101.serial0,server
  
Remember the <code>qm terminal</code> uses Ctrol-O as shortcut, so saving a file from <code>nano</code> with Ctrl-O will log you out instead
+
Remember the <code>qm terminal</code> uses Ctrl-O as shortcut, so saving a file from <code>nano</code> with Ctrl-O will log you out instead
 +
 
 +
== References ==
 +
* Systemd documentation: http://0pointer.de/blog/projects/serial-console.html
  
== Going Further with a Serial Console ==
+
== Going Further ==
It is also possible to have the grub2 menu, and the whole boot process send to the serial port. See https://help.ubuntu.com/community/Grub2#Booting_from_a_serial_console for how to do this with Grub2.
+
It is also possible to have the grub2 and grub accessible from the serial port. See https://help.ubuntu.com/community/Grub2#Booting_from_a_serial_console for how to do this with Grub2.

Latest revision as of 11:00, 27 August 2018

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)
Debian GNU/Linux 8 debian8 ttyS0
debian8 login: 

Other use cases:

  • you lost network access to the guest and VNC is either too slow for you or does not have the features you need (i.e. easy copy/paste between other terminals)
  • your guest freezes or kernel panics, you want to debug it, but it is impossible to capture all messages on VNC screen
  • your keyboard layout is borked on the guest
  • you are familiar with xm console <guest> from Xen and you want to use a similar feature here

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. This is called in Unix-speak the default console, or system console. During boot, the kernel sends its boot messages, like device detection, to this default console, and at the end of the boot processes, fires a "login: " prompt on this console. (Actually it spawns multiple login prompts, you can switch between them with Ctrl-alt-F1, Ctrl-alt-F2, etc ... )

Now it is 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 PC. We get then what is called a serial console 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 PC locally in text mode. The requirements of the 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 program.

How do this apply to Proxmox PVE ?

In proxmox things work exactly the same, but with emulated devices. NoVNC/ VNC Applet connects to your VM keyboard and VM 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 VM to have an emulated serial port, and instruct the OS, to send a copy of the boot messages / 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 program, which is handily builtin in the Proxmox Qemu Manager.

Configuration on the host

Add a virtual serial port to the VM

Provided your VM IS is 101

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

or use

qm set 101 -serial0 socket

Configuration on the guest

Configure the terminal if not present

As detailed in https://help.ubuntu.com/community/SerialConsoleHowto#Server_Setup , check if you have the file /etc/init/ttyS0.conf. If not, create it:

   # ttyS0 - getty
   #
   # This service maintains a getty on ttyS0 from the point the system is
   # started until it is shut down again.
   start on stopped rc RUNLEVEL=[12345]
   stop on runlevel [!12345]
   respawn
   exec /sbin/getty -L 115200 ttyS0 vt102

then ask upstart to start terminal

   sudo start ttyS0

You might consider creating the ttyS1.conf file as well, just as a backup in case you have a crash with ttyS0

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

If ttyS0 is not there, type

sudo start ttyS0

from the VM shell

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 parameter to
GRUB_CMDLINE_LINUX="quiet console=tty0 console=ttyS0,115200" 

run

# debian based
update-grub
# redhat based
grub2-mkconfig --output=/boot/grub2/grub.cfg

and do a final reboot

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

Note: if it seems this is not working, and if you have defined ttyS1, you can connect to itwith the command

 qm terminal <VMiD> -iface serial1 

Now if you reboot your system you should see that the kernel startup messages are send to both your serial terminal and NoVNC display.


Additionally (quoting from a private email, edited for clarity):

Qemu also supports binding the emulated serial port to a telnet server.  Look for the -chardev parameter in the qemu-kvm manual page.  (With proxmox you would then use the "args:" parameter in vm.conf to specify extra args.)  This would allow you to telnet to your host on a specific port to get a serial console.  As with every telnet traffic remember that nothing is encrypted, so I wouldn't do this in a production setup.

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

Remember the qm terminal uses Ctrl-O as shortcut, so saving a file from nano with Ctrl-O will log you out instead

References

Going Further

It is also possible to have the grub2 and grub accessible from the serial port. See https://help.ubuntu.com/community/Grub2#Booting_from_a_serial_console for how to do this with Grub2.