You are here: Home Cheat Sheets Unix Serial Howto

Unix Serial Howto

A quick Linux and FreeBSD serial howto that includes some VMware tips.

This text is merely a compilation of things i found on the web and a little bit of trial and error. I'm going to try to quickly describe how to setup a serial console on Linux and FreeBSD with VMware, pointing out some of the pitfalls i ran into in the process. As a general note, all these configurations assume the following serial setting on this first serial port of the system:

115200 baud
no parity
8 data bits
one stop bit

They also assume you're using a Null-Modem cable, except for the connections made using socat. I'll start with the Linux installation.


For Linux i have played around with installers as well as post modifications to running systems to add serial access. There are a few things to consider here. The first one is SysLinux and pertains to the isolinux.cfg. I have tried this on Red Hat based systems mainly CentOS 5. There maybe/probably are differences between this and other distros. Here's a listing of isolinux.cfg with the relevant parts highlighted. This file BTW describes the installation boot menu. See documentation about this here.

serial 0 115200
default text
prompt 1
display boot.msg
F1 boot.msg
F2 options.msg
F3 general.msg
F4 param.msg
F5 rescue.msg

label text
  kernel vmlinuz
  append initrd=initrd.img text ramdisk_size=8192
label serial
  kernel vmlinuz
  append ks=file:ks-serial.cfg text initrd=initrd.img ramdisk_size=8192 console=tty0 console=ttyS0,115200n8
label expert
  kernel vmlinuz
  append expert initrd=initrd.img ramdisk_size=8192

The first line is responsible for the installer boot menu to show up on the screen. It is important that serial is the first entry and if you're using a null modem cable that 115200 is specified. I got this from the last line of the faqs serial howto. The lower entries under the serial section basically say use a regular console in addition to the serial console. This section takes over once you type serial and hit enter. If you just hit enter the text section will take over and the serial connection will be disconnected.

The next thing would be the kickstart file. I do not know how to set this up running the manual install as i haven't tried this. The relevant kickstart entry is

bootloader --location=mbr  --append="console=tty0 console=ttyS0,115200n8"

Again the highlighted part is added to the existing bootloader option. It essentially adds the contents of append to every kernel line in /boot/grub/grub.conf. This enables post installation serial or local startups. This does not handle login into the system after boot up though. To allow this i added the following to the %post section of the serial kickstart script (ks-serial.cfg in this example).

# add serial access
echo "se:2345:respawn:/sbin/agetty 115200 ttyS0 vt102" >> /etc/inittab
echo "ttyS0" >> /etc/securetty

This basically adds a listener for serial connections on ttyS0 serial port 1. The second entry adds ttyS0 as a login terminal. On already running systems one can just add the entries to the /boot/grub/grub.conf, /etc/inittab and /etc/securetty files. The a reboot will pick up the changes, or simply running

telinit -q

Will tell init to reread inittab and spawn agetty to instantly allow serial connections.


I run FreeBSD at home, so i wanted to figure out how this works there, too. Here the FreeBSD Handbook came to the rescue. For me the instructions here were create /boot.config with the following contents


This basically provides output to the serial port as well as the video console. This setting is picked up at first. Then i added this to /boot/loader.conf


This also redirects output to both serial and video consoles. Like the SysLinux entry above this setting needs to be the first entry in /boot/loader.conf.

To add a listener to the system i looked for this in /etc/ttys

ttyu0   "/usr/libexec/getty std.9600"   dialup onifconsole secure

I changed that to

ttyu0   "/usr/libexec/getty std.115200" vt102   on  secure

Note: This has been tested on On FreeBSD 10.



I use VMware for testing as well as dealing with peski M$ app requirements. VMware allows you map the guest's serial port to either a physical port on the vm host or to a unix socket on the vm host. The first is obvious so i'll concentrate on the latter. A way to use the unix socket on a system without any or not enough physical serial ports, is to use socat. Socat as the name suggests, is sort of a swiss army knife of socket connecting or concatenating. On some systems it's available via package management, on others it can simply be built from source, provided you have the necessary build tools installed. In VMware simply add a Serial port, then choose "Output to socket" pick a socket name, let's call it /tmp/serialport and leave the default "From: Server To: Virtual Machine" settings. Obviously leave "Connect at power on" checked. With the VM image powered up you can run the following on the vm host:

socat -d -d /tmp/serialport PTY:

This  basically tells socat to map the socket at /tmp/serialport to a pseudo terminal. The 2 -d settings increase verbosity levels to a point where socat will print the pseudo terminal it mapped to the socket to. You should be getting something along the lines of:

2010/02/14 16:25:55 socat[16313] N successfully connected via
2010/02/14 16:25:55 socat[16313] N PTY is /dev/pts/4
2010/02/14 16:25:55 socat[16313] N starting data transfer loop with FDs [3,3] and [4,4]

Note: I initially started out with socat version 2.0.0-b3. It failed opening the PTY for some reason. After spending some time head scratching, i decided to try an older GA version with better results.

After that you can point whatever console program you use at /dev/pts/4 or whatever PTY socat chose. In my case i used minicom.


I use picocom because it handles UTF-8 consoles well. This avoids problems with line drawing interfaces looking like garbage.
picocom -b115200 /dev/pts/4




Document Actions

Copyright © 2007-2015 Mario Theodoridis. All rights reserved. Content licensed under AFL.   Impressum   Datenschutz
Content from the underlying Plone CMS is © 2000-2009 by the Plone Foundation