Setting up a serial console

This tutorial will show you how to set up a serial console on a Linux system, and connect to it via a null modem cable. This is quite useful if your Linux server is in a headless configuration (no keyboard or monitor), as it allows you to easily get a console on the system if there are any problems with it (especially network problems, when SSH is not available). In the end, the GRUB menu will appear over the serial link, as will the bootup messages (output when booting the system). I'm using Debian Etch on the server and Ubuntu Edgy on my client, although this should work on any Linux distribution.

First steps

One of the most important things we need to check that you do actually have a serial port on the server :). Take a look at the back of your server, and see if it has a 9-pin serial port. Most motherboards have either one or two serial ports. On the system, check to see that Linux is recognising the serial ports:

[email protected]:~# dmesg | grep tty
serial8250: ttyS0 at I/O 0x3f8 (irq = 4) is a 16550A
00:08: ttyS0 at I/O 0x3f8 (irq = 4) is a 16550A

This shows that my system has one serial port, ttyS0 (remember this for later).

GRUB configuration

The next step is to edit the GRUB configuration, so it sends its messages to the serial console. One of the most important things is to set a password, otherwise anyone can connect a serial cable, edit the GRUB configuration line while the system is booting (via the "e" key), and get root access. When a password is set, interactive menu editing will be disabled, unless the correct password is entered. To set the password, we first need to get the encrypted version of it.

Run grub, and use the "md5crypt" command to encrypt the password:

grub> md5crypt

Password: ********
Encrypted: $1$AlfMq1$FxRolxW5XvSLAOksiC7MD1

Copy the encrypted version of the password (we need it for the next step), and then type quit to exit.

Now, we need to edit the GRUB configuration. Edit the /boot/grub/menu.lst file (by typing nano /boot/grub/menu.lst), and find this section:

## password ['--md5'] passwd
   # If used in the first section of a menu file, disable all interactive editing
   # control (menu entry editor and command-line)  and entries protected by the
   # command 'lock'
   # e.g. password topsecret
   #      password --md5 $1$gLhU0/$aW78kHK1QfV3P2b2znUoe/
   # password topsecret

Below that, add:

password --md5 $1$AlfMq1$FxRolxW5XvSLAOksiC7MD1
serial --unit=0 --speed=38400 --word=8 --parity=no --stop=1   
terminal --timeout=10 serial console

Replace $1$AlfMq1$FxRolxW5XvSLAOksiC7MD1 with the encrypted form of your password. The second line tells GRUB to initialise the serial port at 38,400 bps (same speed as the standard console), 8 data bits, no parity, and 1 stop bit (basically, the standard settings). Note that the --unit=0 means that it will use the first serial port (ttyS0). If you're using the second serial port (ttyS1), change it to --unit=1. The last line tells GRUB to show its menu on both the serial line and the console (monitor).

Now, we also need to edit the kernel sections, so that they output messages to the serial console. At the end of every kernel line, add console=tty0 console=ttyS0,38400n8 (replace ttyS0 with the correct serial port). In my case, it ended up looking like:

title           Debian GNU/Linux, kernel 2.6.18-4-vserver-686
   root            (hd0,1)
   kernel          /vmlinuz-2.6.18-4-vserver-686 root=/dev/hda3 ro console=tty0 console=ttyS0,38400n8
   initrd          /initrd.img-2.6.18-4-vserver-686
   savedefault
title           Debian GNU/Linux, kernel 2.6.18-4-vserver-686 (single-user mode)
   root            (hd0,1)
   kernel          /vmlinuz-2.6.18-4-vserver-686 root=/dev/hda3 ro single console=tty0 console=ttyS0,38400n8
   initrd          /initrd.img-2.6.18-4-vserver-686
   savedefault
title           Debian GNU/Linux, kernel 2.6.18-3-686
   root            (hd0,1)
   kernel          /vmlinuz-2.6.18-3-686 root=/dev/hda3 ro console=tty0 console=ttyS0,38400n8
   initrd          /initrd.img-2.6.18-3-686
   savedefault
title           Debian GNU/Linux, kernel 2.6.18-3-686 (single-user mode)
   root            (hd0,1)
   kernel          /vmlinuz-2.6.18-3-686 root=/dev/hda3 ro single console=tty0 console=ttyS0,38400n8
   initrd          /initrd.img-2.6.18-3-686
   savedefault

Save and exit, by pressing CTRL+O (to "output", or save the file), Enter (to accept the file name) and CTRL+X (to actually exit).

Allow logins over Serial Console

Now, the GRUB menu will appear over the serial connection, but we still aren't listening for logins over it (there's no "getty" running on it yet). Edit the /etc/inittab file, and find this section:

# Example how to put a getty on a serial line (for a terminal)
#
#T0:23:respawn:/sbin/getty -L ttyS0 9600 vt100
#T1:23:respawn:/sbin/getty -L ttyS1 9600 vt100

Below that (I don't like editing the default lines :P), add:

T0:2345:respawn:/sbin/getty -L ttyS0 38400 vt100

And that's all there is to it. Your server will now show the GRUB menu over the serial console, and also allow logons (once it has finished booting).

Let's test it!

Now that that's all done, we need to configure our client. I'm using GtkTerm on my laptop, although any terminal program should work (as long as it can use a serial port. On Windows, HyperTerminal should work). My laptop doesn't have a serial port, so I'm using a USB to Serial adapter I bought off eBay (it creates a ttyUSB0 device). Set your terminal program to these settings:

Port (Linux): ttyS0 or ttyS1 (if your system has a serial port), or ttyUSB0 (if you're using a USB to Serial converter).
Port (Windows): COM1 or COM2
Bits per second: 38400
Data bits: 8
Parity: None
Stop bits: 1
Flow control: None, although hardware (RTS/CTS) should work properly

Restart the server (probably from a SSH connection, or however you edited the GRUB config above), and then connect the null modem cable as it's starting (ie. at the BIOS screen). Press any key when prompted, and you'll get something like:

This means that GRUB is working fine :). Press enter, and it should boot, showing all messages in the terminal window. Once it boots, it will look something like:

Finally, log in, and check that it works fine:

Congratulations, everything is set up and working fine.

Hope you enjoyed this tutorial! :)

Daniel15 (Daniel Lo Nigro)
http://www.daniel15.com/
http://www.dansoftaustralia.net/

view as pdf | print

Share this page:

7 Comment(s)

Add comment

Comments

By:

1. You can easily use faster baud rates like 57600.

2. vt102 is the best terminal emulation offered by the kernel. For more information - "man console_codes". For a comparison of various terminals see the Kermit 95 Terminal Types list.

3. On Ubuntu Edgy Eft (6.10) or later, Upstart is used instead of init. To configure ttyS0, create a new entry in /etc/event.d by copying one of the existing tty# entries and modifying it. Example ttyS0:

------------------------------------------------------
# ttyS0 - getty
#
# This service maintains a getty on ttyS0 from the point the system is
# started

start on runlevel-2
start on runlevel-3
start on runlevel-4
start on runlevel-5

stop on shutdown

respawn /sbin/getty -L 38400 ttyS0 vt102
------------------------------------------------------

4. On Ubuntu, for a non-root user to access ttyS0 they must be a member of the dialout group.

5. Some versions of Grub (0.95, 0.97) on Edgy Eft have broken serial support. See bug #32904. This appears to be fixed in Feisty Fawn (7.04) Herd 5.

6. Other options for serial terminals are minicom, cu, and c-kermit:

apt-get install minicom
man minicom
minicom -s # Initial setup. Set port as required and erase modem init and reset strings.
minicom # Normal startup. You are connected immediately. Enter Ctrl-A followed by "Z" for help.

apt-get install cu
man cu
cu -lttyS0
Enter "~.~." to disconnect.

apt-get install ckermit
man kermit
kermit -l /dev/ttyS0 -b 38400 -8
Enter "?" for a list of commands. Enter "connect" to connect to port. Enter a Ctrl-\ and then a "C" to return to local.

7. You can run Midnight Commander through a terminal. Minicom doesn't support graphic characters well so using cu or kermit is recommended.

apt-get install mc
mc
mc -c # if you want color (overrides MC's default behavior which is based on target system's TERM variable)

One of the limitations of the vt100/vt102 terminals is the lack of support for function keys other than F1-F4 and some navigation keys. In MC you can use Esc # where # is 1-9,0 representing the F1-F10 menu keys.

Other references:

http://www.linuxselfhelp.com/HOWTO/Text-Terminal-HOWTO-9.html
http://tldp.org/HOWTO/html_single/Text-Terminal-HOWTO/
http://www.gnu.org/software/grub/manual/grub.html#Serial-terminal

Also see serial-console.txt in the kernel documentation.

By: David

First, thanks for posting this really helpful information. I have what I hope is a simple question. This post sets up the console to emulate a VT102 or VT100 terminal. If I'm using a printing console (a traditional printing tty) then what emulation would I use? I found a reference in "man getty" that seems to suggest that the line /sbin/getty 9600 ttys1 would do the trick. (serial port 1 at 9600 baud and no terminal emulation.) Before I head down that road I wondered if I was on the right path.

By: Anonymous

Super tutorial!

By: Anonymous

In case you do not have either minicom, or a full-blown X with GTkTerm, you can use the terminal based 'screen' application.

Screen can use a serial port as well, you simply hook up you laptop with either a RS-232 or an USB-to-RS-232 and start your session with:

screen /dev/ttyS0 38400 , or in the USB dongle case : screen /dev/ttyUSB0 38400

By: Tom

Thankyou - just what I was looking for.

By: David Reid

Thanks so much for the tutorial. I hope you don't mind revisiting this. I'd like to create a small system that uses a printing terminal instead of a VT type terminal or emulator. I'd also like to use Ubuntu 14.04.

Are there any changes that I should be aware of in your tuturial?

What terminal type should I use for the printing terminal using 9600 baud Even parity and 1 stop bit?

Thanks for your help. This is a demonstration project for a history class that I'm teaching. I'd like to make sure that it goes according to plan.

David

By: sarah

Hi, thank ypu for your great post.

i've a Q. I have a xen with ubuntu host, which i want use it's serial console with three times hitting CTRL-a in it. (as xl dmesg output shows), but after installing screen, entering it by 'screen /dev/ttyS0/ 57600', when pressing three times of CTRL-a, i can not see Xen serial output.

would you please tell me what can i do? Does it need any change in grub2 file of xen host? if so, How?

Thanks a lot.