1.1. What is a console?

The console is the text output device for system administration messages. These messages come from the kernel, from the init system and from the system logger.

On modern small computers the console is usually the computer's attached monitor and keyboard.

On many older computers the console is an RS-232 link to a terminal such as a DEC VT100. This terminal is in a locked room and is continually observed by the minicomputer's operators. Large systems from Sun, Hewlett-Packard and IBM still use serial consoles.

It is usually possible to login from the console. A login session from the console is treated by many parts of the operating system as being more trustworthy than a login session from other sources. Logging in as the root super-user from the console is the Command Line of Last Resort when faced with a misbehaving system.

1.2. Why use a serial console?

For the average user a serial console has no advantage over a console offered by a directly attached keyboard and screen. Serial consoles are much slower, taking up to a second to fill a 80 column by 24 line screen. Serial consoles generally only support non-proportional ASCII text, with limited support for languages other than English. A new terminal can be more expensive than an old PC.

There are some scenarios where serial consoles are useful. These are:

Unlike minicomputer systems, the IBM PC was not designed to use a serial console. This has two consequences.

Firstly, Power On Self-Test messages and Basic Input/Output System (BIOS) messages are sent to the screen and received from the keyboard. This makes it difficult to use the serial port to reconfigure the BIOS and impossible to see Power On Self-Test errors.

An increasing number of manufacturers of rackable server equipment are altering their BIOSs to optionally use the RS-232 port for BIOS configuration and test messages. If you are buying a machine specifically for use with serial console you should seek this feature. If you have an existing machine that definitely requires access to the BIOS from the serial port then there are hardware solutions such as PC Weasel 2000.

Secondly, the RS-232 port on the IBM PC is designed for connecting to a modem. Thus a null modem cable is needed when connecting the PC's serial port to a terminal.

1.3. Alternative meanings of "console"

Some authors use the word "console" to refer to the keyboard and monitor that are attached to the system unit. This is described as a "physical console" by some Linux documentation. The console where system messages appear is described as the "logical console" by that documentation.

As an illustration of the difference, X Windows should start on the physical console but system messages issued by failures when starting X Windows should be written to the logical console.

To avoid confusion this HOWTO uses the word "console" to describe the place where system messages are printed. This HOWTO uses the phrase "attached monitor and keyboard" rather than the confusing words "physical console".

These distinctions are also made in the naming of devices. The device /dev/console is used to send messages to the console. The symbolic link /dev/systty points to the device which is used by the attached monitor and keyboard, often /dev/tty0.

1.4. Configuration overview

There are five major steps to configuring a serial console.

Examples in this HOWTO are from Red Hat Linux versions 7.1 through to 7.3 (released 2001 through to 2002). The maintainer would appreciate updates when new versions of Red Hat Linux appear. The maintainer would very much appreciate examples for Linux distributions that are dissimilar to Red Hat Linux; particularly Debian GNU/Linux and Slackware Linux. All contributors are acknowledged in Section G.3.

2.1. Create fallback position

Good system administrators always have a viable fallback plan to cope with failures. A mistake configuring the serial console can make both the serial console and the attached monitor and keyboard unusable. A fallback plan is needed to retrieve console access.

Many Linux distributions allow boot diskettes to be created. Writing a boot diskette before altering the console configuration results in a boot diskette that passes good parameters to the kernel rather than parameters that may contain an error.

Under Red Hat Linux a boot diskette is created by determining the running kernel version

bash$ uname -r
2.4.2-2

and then using that version to create the boot diskette

bash# mkbootdisk --device /dev/fd0 2.4.2-2

Under Debian GNU/Linux the boot diskette is created by determining the version of the running kernel and then using that version to write the boot diskette

bash# mkboot /boot/vmlinuz-2.4.2-2

An alternative fallback position is have a rescue diskette with the machine. A common choice is Tom's root boot.

2.2. Select a serial port

# Disable /dev/ttyS2 so interrupt 4 is not shared,
# then /dev/ttyS0 can be used as a serial console.
setserial /dev/ttyS2 uart none port 0x0 irq 0

2.3. Select a serial speed and parameters

This HOWTO does not discuss the RS-232 standard, which is formally known as ANSI/TIA/EIA-232-F-1997 Interface Between Data Terminal Equipment and Data Circuit-Terminating Equipment Employing Serial Data Interchange. For an explanation of "bits per second", "start bits", "data bits", "parity", "stop bits" and "flow control" refer to the Serial-HOWTO and the Modem-HOWTO.

The description of the command syntax for setting the serial parameters in the kernel, boot loaders and login applications uses the following variables which describe RS-232 parameters.

At present the RS-232 status lines are ignored by the kernel. A kernel message will be printed even if Data Carrier Detect and Data Set Ready are not asserted. This leads to the kernel messages being sent to a modem which is idle and in command mode.

The console's slack interpretation of CTS, DSR and DCD makes it impossible to connect a serial console to an RS-232 multi-drop circuit. Multi-drop circuits have more than two computers on the circuit; they are traditionally four-wire, satelite or wireless services.

The Linux kernel uses the syntax in Figure 2-7 to describe the serial parameters. Many boot loaders use a variation of the syntax used by the Linux kernel.

Note that <mode> does not include <stop>. The kernel assumes the number of stop bits to be one. This shortcoming needs to be considered when deploying long RS-232 cables.

Most boot loaders default to 9600n8. A common default found on older terminals is 9600e7.

Use 9600n8 if possible, as this is the default for most Linux software and modern devices.

This HOWTO always configures the serial speed and parameters, even where not strictly necessary. This is so that people configuring parameters other than the recommended and common default value 9600n8 will know what to alter.

2.4. Configure the modem or the null-modem cable

If a modem is used, configure it to be a dumb modem at the port speed selected in Section 2.3. If the modem accepts Hayes AT commands see Chapter 12 to dumb-down the modem.

Alternatively if a terminal and a null-modem cable are used see Section 11.3, which discusses the pinout of the null modem cable.

2.5. Configure the terminal or the terminal emulator

Configure the terminal to match the serial parameters. The data bits, parity bits and stop bits must match. If a modern "smart" modem is used then the bit speeds need not match. If a dumb modem or a null modem cable is used then the bit speeds must match.

Set CTS/RTS handshaking on, DTR/DSR handshaking off and XON/XOFF handshaking off. Your equipment may call CTS/RTS handshaking or DTR/DSR handshaking "hardware handshaking" and may call XON/XOFF handshaking "software handshaking".

Set automatic line wrapping on. This allows all of a long console message to be read.

Set the received end of line characters to CR LF (carriage return then line feed). Set the transmitted end of line characters to just CR (carriage return).

If you are using a terminal emulator then it is best to choose to emulate the popular DEC VT100 or VT102 terminal. Later terminals in the DEC VT range are compatible with the VT100. If this terminal is not available then try to emulate another terminal that implements ANSI X3.64-1979 Additional Controls for Use with American National Standard Code for Information Interchange (or its successor ISO/IEC 6429:1992 ISO Information technology — Control functions for coded character sets). For example, many emulators have a terminal called ANSI BBS which uses the IBM PC character set, the 16 IBM PC colors, a 80 column by 25 line screen and a selection of X3.64-1979 control sequences.

See the Text-Terminal-HOWTO for much more information on configuring terminals.

4.1. Configure the LILO boot loader

LILO is the Linux Boot Loader used on Intel machines. Other boot loaders for Intel machines exist, common alternatives are GRUB and SYSLINUX. Equivalents to LILO exist for other processor architectures, their names are usually some play upon "LILO".

LILO is documented in the lilo(8) and lilo.conf(5) manual pages; the LILO Generic boot loader for Linux … User's Guide found in the file /usr/share/doc/lilo…/doc/User_Guide.ps; and the LILO mini-HOWTO.

The LILO configuration is kept in the file /etc/lilo.conf. The first part of the file applies to all images. The following parts are image descriptions for each kernel.

Set LILO to use the serial port. The syntax of the serial line parameters follows that used by the kernel.

Where the variables are the same as used by the kernel (shown in Figure 2-7) and:

Our examples use /dev/ttyS0, which LILO knows as port 0.

serial=0,9600n8
timeout=100
restricted
password=PASSWORD

The parameters restricted and password are used to avoid someone dialing in, booting the machine, and stepping around the Linux access permissions by typing:

LILO: linux init=/sbin/sash

The password should be good, as it can be used to gain root access. The LILO password is stored in plain text in the configuration file, so it should never be the same as any other password. The permissions on the configuration file should be set so that only root can read /etc/lilo.conf.

bash# chmod u=rw,go= /etc/lilo.conf

LILO has an option to display a boot message. This does not work with serial consoles. Remove any lines like:

message=/boot/message

LILO is now configured to use the serial console. The kernels booted from LILO are yet to be configured to use the serial console.

4.2. Configure the GRUB boot loader

GRUB is a boot loader designed to boot a wide range of operating systems from a wide range of filesystems. GRUB is becoming popular due to the increasing number of possible root filesystems that can Linux can reside upon.

GRUB is documented in a GNU info file. Type info grub to view the documentation.

The GRUB configuration file is /boot/grub/menu.lst. Some distributions use another configuration file; for example, Red Hat Linux uses the file /boot/grub/grub.conf.

GRUB configuration files are interpreted. Syntax errors will not be detected until the machine is rebooted, so take care not to make typing errors.

Edit the GRUB configuration file and remove any splashimage entries. If these entries are not removed GRUB 0.90 behaves very oddly, transferring control between the serial console and the attached monitor and keyboard.

If there is not already a password command in the GRUB configuration file then create a hashed password, see Figure 4-4. The password should be good, as it can be used to gain root access.

grub> md5crypt
Password: **********
Encrypted: $1$U$JK7xFegdxWH6VuppCUSIb.

Use that hashed password in the GRUB configuration file, this is shown in Figure 4-5.

password --md5 $1$U$JK7xFegdxWH6VuppCUSIb.

Define the serial port and configure GRUB to use the serial port, as shown in Figure 4-6.

serial --unit=0 --speed=9600 --word=8 --parity=no --stop=1
terminal serial

--unit is the number of the serial port, counting from zero, unit 0 being COM1.

Note that the values of --parity are spelt out in full: no, even and odd. The common abbreviations n, e and o are not accepted.

If there is mysteriously no output on the serial port then suspect a syntax error in the serial or terminal commands.

If you also want to use and attached monitor and keyboard as well as the serial port to control the GRUB boot loader then use the alternative configuration in Figure 4-7.

password --md5 $1$U$JK7xFegdxWH6VuppCUSIb.
serial --unit=0 --speed=9600 --word=8 --parity=no --stop=1
terminal --timeout=10 serial console

When both the serial port and the attached monitor and keyboard are configured they will both ask for a key to be pressed until the timeout expires. If a key is pressed then the boot menu is displayed to that device. Disconcertingly, the other device sees nothing.

If no key is pressed then the boot menu is displayed on the whichever of serial or console is listed first in the terminal command. After the timeout set by the timeout the default option set by default is booted.

Press any key to continue.
Press any key to continue.
Press any key to continue.
Press any key to continue.
Press any key to continue.
Press any key to continue.
Press any key to continue.
Press any key to continue.
Press any key to continue.
Press any key to continue.

    GRUB  version 0.90  (639K lower / 162752K upper memory)

 +-------------------------------------------------------------------------+
 | [ Red Hat Linux (2.4.9-21)   ]                                          |  
 |                                                                         |
 |                                                                         |
 +-------------------------------------------------------------------------+
      Use the ^ and v keys to select which entry is highlighted.
      Press enter to boot the selected OS or 'p' to enter a
      password to unlock the next set of features.

   The highlighted entry will be booted automatically in 10 seconds.

If you are not using a VT100 terminal then the cursor keys may not work to select a GRUB menu item. The instructions shown in Figure 4-8 are literally correct: Use the ^ and v keys means that the caret key (Shift-6) moves the cursor up and letter vee key (V) moves the cursor down.

Note when configuring GRUB that there are two timeouts involved. Press any key to continue is printed for terminal --timeout=10 seconds, waiting for someone on the keyboard or terminal to press a key to get the input focus. Then the menu is displayed for timeout 10 seconds before the default boot option is taken.

If the terminal attached to the serial port is not a real or emulated VT100, then force GRUB to use it's command line interface. This interface is much more difficult to use than GRUB's menu interface; however, the command line interface does not assume the VT100's terminal language.

terminal --timeout=10 --dumb serial console

This HOWTO does not discuss the use of GRUB's command line. It is far too complex and error-prone to recommend for use on production machines. Wizards will know to consult GRUB's info manual for the commands required to boot the kernel.

GRUB's menu's can be edited interactively after P is pressed and the password supplied. A better approach is to add menu items to boot the machine into alternative run levels. A sample configuration showing a menu entry for the default run level and an alternative menu entry for single user mode (run level s) is shown in Figure 4-10. Remember to use the lock command to require a password for single user mode, as single user mode does not ask for a Linux password.

password --md5 $1$U$JK7xFegdxWH6VuppCUSIb.
default 0
title Red Hat Linux (2.4.9-21)
        root (hd0,0)
        kernel /vmlinuz-2.4.9-21 ro root=/dev/hda6
        initrd /initrd-2.4.9-21.img
title Red Hat Linux (2.4.9-21) single user mode
        lock
        root (hd0,0)
        kernel /vmlinuz-2.4.9-21 ro root=/dev/hda6 s
        initrd /initrd-2.4.9-21.img

File names in the kernel and initrd commands are relative to the GRUB installation directory, which is usually /boot/grub. So /vmlinuz-2.4.9-21 is actually the file /boot/grub/vmlinuz-2.4.9-21.

GRUB is now configured to use the serial console. The kernels booted from GRUB are yet to be configured to use the serial console.

4.3. Configure the SYSLINUX boot loader

SYSLINUX is a boot loader that is installed on a MS-DOS floppy disk. As directed by it's configuration file \SYSLINUX.CFG it will load one of the files from the floppy disk as a Linux kernel.

SYSLINUX presents a simple text interface that can be used to select between canned configurations defined in the configuration file and can be used to add parameters to the kernel.

ISOLINUX and PXELINUX are variants of SYSLINUX for CD-ROMs and Intel's Preboot Execution Environment.

SYSLINUX supports a variety of serial port speeds, but it only supports eight data bits, no parity and one stop bit. SYSLINUX supports the serial ports COM1: through to COM4:, as with most boot loaders these are written as port 0 through to port 3.

For SYSLINUX to support a serial console add a new first line to \SYSLINUX.CFG:

The variables are the same as used by syntax descriptions in Figure 2-7 and Figure 4-2 plus those in Figure 4-12.

The <syslinux_flow_control> variable controlling the RS-232 status and flow control signals is optional. If your null-modem cable does not present any status or handshaking signals then do not use it. The value of <syslinux_flow_control> is calculated by adding the hexadecimal values for the desired flow control behaviours listed in Table 4-1.

The behaviours for a correctly-wired null-modem cable or a correctly configured modem are marked "Required for full RS-232 compliance" in the table. The sum of these values is 0xab3.

Our preferred configuration of 9600bps, port 0, full RS-232 status signals and CTS/RTS flow control is written as:

serial 0 9600 0xab3

When using this configuration SYSLINUX will not display anything and will not accept any typed character until the RS-232 status signals show a connected modem call (or a connected terminal if you are using a null-modem cable).

If you have a null modem cable with no RS-232 status signals and no flow control then use:

serial 0 9600

Remember that the serial command must be the first line in \SYSLINUX.CFG.

5.1. Configure Linux kernel using LILO

For each image entry in /etc/lilo.conf add the line:

append="console=tty0 console=ttyS0,9600n8"

Sometimes the append line will already exist. For example

append="mem=1024M"

In this case, the existing append line is modified to pass all the parameters. The result is:

append="mem=1024M console=tty0 console=ttyS0,9600n8"

As a complete example, a typical /etc/lilo.conf configuration from Red Hat Linux 7.1 is:

boot=/dev/hda
map=/boot/map
install=/boot/boot.b
prompt
timeout=50
message=/boot/message
default=linux

image=/boot/vmlinuz-2.4.2-2
  label=linux
  read-only
  root=/dev/hda6
  initrd=/boot/initrd-2.4.2-2.img

This is modified to

boot=/dev/hda
map=/boot/map
install=/boot/boot.b
prompt
default=linux
# Changes for serial console on COM1: in global section
#   Deleted: message=/boot/message
serial=0,9600n8
timeout=100
restricted
password=de7mGPe3i8

image=/boot/vmlinuz-2.4.2-2
  label=linux
  read-only
  root=/dev/hda6
  initrd=/boot/initrd-2.4.2-2.img
  # Changes for serial console on COM1: in each image section
  append="console=tty0 console=ttyS0,9600n8"

Now that we have finished configuring LILO, use the lilo command to install the new boot record onto the disk:

bash# chown root:root /etc/lilo.conf
bash# chmod u=rw,g=,o= /etc/lilo.conf
bash# lilo
Added linux *

5.2. Configure Linux kernel using GRUB

Find each title entry in the GRUB configuration file. It will be followed by a kernel line. For example

title Red Hat Linux (2.4.9-21)
  root (hd0,0)
  kernel /vmlinuz-2.4.9-21 ro root=/dev/hda6
  initrd /initrd-2.4.9-21.img

Modify each of the kernel lines to append the parameters that inform the kernel to use a serial console.

title Red Hat Linux (2.4.9-21)
  root (hd0,0)
  kernel /vmlinuz-2.4.9-21 ro root=/dev/hda6 console=tty0 console=ttyS0,9600n8
  initrd /initrd-2.4.9-21.img

As a complete example, Example 5-3 is a typical GRUB configuration from Red Hat Linux 7.2.

default=0
timeout=10
splashimage=(hd0,0)/grub/splash.xpm.gz
password --md5 $1$wwmIq64O$2vofKBDL9vZKeJyaKwIeT.
title Red Hat Linux (2.4.9-21)
root (hd0,0)
  kernel /vmlinuz-2.4.9-21 ro root=/dev/hda6
  initrd /initrd-2.4.9-21.img

The modified configuration file is shown in Example 5-4.

default=0
timeout=10
password --md5 $1$wwmIq64O$2vofKBDL9vZKeJyaKwIeT.
serial --unit=0 --speed=9600 --word=8 --parity=no --stop=1
terminal --timeout=10 serial console
title Red Hat Linux (2.4.9-21)
  root (hd0,0)
  kernel /vmlinuz-2.4.9-21 ro root=/dev/hda6 console=tty0 console=ttyS0,9600n8
  initrd /initrd-2.4.9-21.img
title Red Hat Linux (2.4.9-21) single user mode
  lock
  root (hd0,0)
  kernel /vmlinuz-2.4.9-21 ro root=/dev/hda6 console=tty0 console=ttyS0,9600n8 s
  initrd /initrd-2.4.9-21.img

5.3. Configure Linux kernel using SYSLINUX

Edit each LABEL entry to add an APPEND line containing the serial console parameter to pass to the Linux kernel. Like LILO, if a kernel already has parameters, then add our parameters to the list after APPEND.

For example:

APPEND console=tty0 console=ttyS0,9600n8

There are some traps for beginners in the differences between LILO and SYSLINUX. LILO uses append=, whereas SYSLINUX uses just append. lilo needs to be run after each change to /etc/lilo.conf, whereas syslinux does not need to be run after changing \SYSLINUX.CFG.

6.1. init system

The file /etc/inittab contains the background programs that used to keep the system running. One of these programs is one getty process per serial port.

co:2345:respawn:/sbin/getty ttyS0 CON9600 vt102

Each field in inittab is separated by a colon and contains: