Remote Serial Console HOWTO Glen Turner Australian Academic and Research Network Mark F. Komarinski v2.6 2003-03-31 Revision History Revision 2.6 2003-03-31 Revised by: gdt Correct opposing CTS/RTS explanations. Use in markup. TLDP PDF is now good, so remove instructions for rendering PostScript to PDF. Typo in GRUB configuration. Revision 2.5 2003-01-20 Revised by: gdt Only one console per technology type. Setting timezone. Use off parameter rather than comments in inittab. Cable lengths. Revision 2.4 2002-10-03 Revised by: gdt Kernel flow control bug, more cabling, Debian, Livingston Portmaster, typos (especially those found during translation to Japanese). Revision 2.3 2002-07-11 Revised by: gdt Updates for Red Hat Linux 7.3, corrections to serial port speeds and UARTs, ioctlsave. Revision 2.2 2002-05-22 Revised by: gdt Minor changes Revision 2.1 2002-05-16 Revised by: gdt Corrections to kernel console syntax. Addition of USB and devfs. Revision 2.0 2002-02-02 Revised by: gdt Second edition. Revision ??1.0 2001-03-20 Revised by: mfk First edition. An RS-232 serial console allows Linux to be controlled from a terminal or modem attached to an asynchronous serial port. The monitor, mouse and keyboard are no longer required for system administration. Serial consoles are useful where Linux systems are deployed at remote sites or are deployed in high-density racks. This HOWTO describes how to configure Linux to attach a serial console. ----------------------------------------------------------------------------- ----------------------------------------------------------------------------- Dedication Glen Turner would like to thank his family for allowing him to work on this project for the surprisingly large number of evenings which it took to write this HOWTO. Thank you Karen, Kayla and Ella. Table of Contents 1. Introduction 1.1. What is a console? 1.2. Why use a serial console? 1.3. Alternative meanings of "console" 1.4. Configuration overview 2. Preparation 2.1. Create fallback position 2.2. Select a serial port 2.3. Select a serial speed and parameters 2.4. Configure the modem or the null-modem cable 2.5. Configure the terminal or the terminal emulator 3. Optionally configure the BIOS 4. Configure the boot loader 4.1. Configure the LILO boot loader 4.2. Configure the GRUB boot loader 4.3. Configure the SYSLINUX boot loader 5. Configure Linux kernel 5.1. Configure Linux kernel using LILO 5.2. Configure Linux kernel using GRUB 5.3. Configure Linux kernel using SYSLINUX 6. Configure getty 6.1. init system 6.2. Traditional getty 6.3. agetty 6.4. mgetty 6.5. mingetty 6.6. No getty 7. Configure incidentals 7.1. Allow root to login from serial console 7.2. Change init level to textual 7.3. Remove saved console settings 7.4. Serial console is not /dev/modem 7.5. Alter target of /dev/systty 7.6. Configure Pluggable Authentication Modules 7.7. Configure Red Hat Linux 8. Reboot and test 8.1. Verify console operation 8.2. Re-create saved console settings 8.3. Test the console 8.4. Where to next from here? 9. Security 9.1. Use good passwords 9.2. Obey Data Terminal Ready and Data Carrier Detect 9.3. Use or configure a dumb modem 9.4. Restrict console messages 9.5. Modem features to restrict usage 9.6. BIOS features 9.7. Use a boot loader password 9.8. Non-interactive boot sequence 9.9. Magic SysRq key 9.10. Adjust behaviour of Ctrl-Alt-Delete 9.11. Log attempted access 9.12. Countering interception of telephony links 10. Configuring a kernel to support serial console 10.1. Linux kernel version 2.5 10.2. Linux kernel version 2.4 10.3. Linux kernel version 2.2 11. Serial cabling 11.1. Jargon 11.2. Cable from console port to modem 11.3. Cable from console port to terminal (or another PC) 11.4. Lengths of serial cables 11.5. Making serial cables 12. Modem configuration 12.1. Using Minicom to give commands to a modem 12.2. Configure dumb modem 12.3. Configure modem with AT commands 12.4. Internal modems 12.5. WinModems A. Bugs and annoyances A.1. Flow control in Linux kernel A.2. Red Hat Linux 7.1 and SysVinit A.3. BIOSs, keyboards and video cards A.4. Modem hangs up upon reboot A.5. init and syslog output does not display on secondary consoles A.6. The console is unresponsive after connecting A.7. Modem hangs up during initialization A.8. Boot loader has no flow control A.9. Boot loaders are vulnerable to line noise A.10. Advanced Power Management A.11. Modems and overseas telecommunications requirements B. Uploading files from a serial console B.1. Disable logging to console B.2. ASCII upload and cat B.3. Xmodem, Ymodem and Zmodem B.4. Kermit C. Upgrading Red Hat Linux from a serial console C.1. Select boot disk C.2. Configure the BIOS to use the serial port C.3. Configure modem to ignore DTR and assert DCD C.4. Prepare a network install floppy diskette C.5. Prepare HTTP server C.6. Record network configuration C.7. Record LILO configuration C.8. Upgrade Red Hat distribution C.9. Create boot disk for serial console C.10. Further references D. Upgrading Debian GNU/Linux from a serial console E. Terminal server configuration E.1. Considerations when buying second-hand terminal servers E.2. Cisco 2511 E.3. Xyplex/iTouch MAXserver 1600 E.4. Xylogics/Bay/Nortel Annex E.5. Livingston/Lucent Portmaster F. Gratuitous advice for developers F.1. Advice for boot loader authors F.2. Advice for BIOS authors G. About this HOWTO G.1. Copyright G.2. Disclaimer G.3. Acknowledgments G.4. Comments and corrections Colophon List of Tables 1-1. Different ways of referring to the "console" 2-1. Many names for the same serial port 2-2. Interrupts used for IBM PC/AT RS-232 ports 4-1. SYSLINUX flow control bitmap 10-1. IBM-PC/AT serial port bit rates and their bit-clock divisors 11-1. Data rates and the maximum distances recommended in RS-232 List of Figures 2-1. Using the setserial command in /etc/rc.serialto disable the serial port /dev/ttyS2 2-2. Syntax for serial bits per second rate, in extended Backus-Naur form 2-3. Syntax for serial parity, in extended Backus-Naur form 2-4. Syntax for serial data bits, in extended Backus-Naur form 2-5. Syntax for serial stop bits, in extended Backus-Naur form 2-6. Syntax for serial flow control, in extended Backus-Naur form 2-7. Syntax for kernel serial parameters, in extended Backus-Naur form 4-1. Syntax of LILO serial command, in EBNF 4-2. LILO serial EBNF variables 4-3. LILO boot loader sample configuration 4-4. Using md5crypt to create a hashed password for GRUB 4-5. GRUB configuration to require a password 4-6. GRUB configuration for serial console 4-7. GRUB configuration for serial console and attached monitor and keybaord console 4-8. GRUB output to default device when configured for serial and attached monior output 4-9. GRUB configuration for command line interface for terminals other than VT100 4-10. Adding a single user mode option to the GRUB menu 4-11. Syntax of SYSLINUX serial command, in EBNF 4-12. SYSLINUX serial EBNF variables 5-1. Kernel console syntax, in EBNF 5-2. Recommended kernel parameters, PCs with video card 5-3. Recommended kernel parameters, PCs without video card 5-4. Recommended kernel parameters, LILO configuration 5-5. Recommened kernel parameters, GRUB configuration 5-6. Recommended kernel parameters, SYSLINUX configuration 6-1. Interactively altering the connecting terminal's make and model 6-2. Interactively altering the connecting terminal's time zone 6-3. getty is started by init, based upon an entry in /etc/inittab 6-4. Define CON9600 in gettydefs 6-5. Syntax of entries in /etc/gettydefs, in EBNF 6-6. /etc/inittab entry for agetty 6-7. /etc/inittab entry for mgetty 6-8. mgetty configuration file mgetty.config 6-9. Fewer virtual terminals. Removing mingetty entries from /etc/inittab 6-10. Fewer virtual terminals. Deallocating unused virtual terminals and removing their device files. 6-11. Contents of /etc/rc.serial to lock console serial port when no getty used 7-1. Alter securetty to allow root to log in from the serial console 7-2. Xservers from Red Hat Linux 7.2 7-3. [servers] section of gdm.conf from Red Hat Linux 7.2 7-4. Removal of ioctl.save containing the saved console parameters 7-5. Remove /dev/modem if it points to the serial console's port 7-6. Default value of /dev/systty in /etc/makedev.d/linux-2.4.x 7-7. Alter value of /dev/systty in MAKEDEV configuration file 7-8. Installing new value of /dev/systty 7-9. Default in console.perms refers to attached keyboard and screen 7-10. Default device listing in console.perms 7-11. Devices in console.perms required for attached keyboard and screen 7-12. Add in console.perms to refer to serial console 7-13. Remaining devices in console.perms altered to refer to serial console 7-14. Alterations to /etc/sysconfig/init for Red Hat Linux 7-15. Alterations to /etc/sysconfig/kudzu for Red Hat Linux 8-1. Using ioctlsave to create /etc/ioctl.save without entering single user mode 9-1. Extract from Crackers favour war dialling and weak passwords 9-2. /etc/syslog.conf modified to copy log messages to a log server 9-3. Allowing remote log messages by setting options in /etc/sysconfig/syslog 9-4. Restrict syslog messages to remote.example.edu.au 9-5. Using nscd to cache reverse DNS lookups 9-6. Restrict sending of messages to console user 9-7. Restrict sending of messages to console user, /etc/profile.d/mesg.sh 9-8. Restrict sending of messages to console user, /etc/profile.d/mesg.csh 9-9. Install files into /etc/profile.d 9-10. Using sysctl to defeat the magic SysRq key 9-11. Configuring /etc/sysctl.conf to defeat the magic SysRq key 9-12. Kernel make menuconfig showing disabled SysRq key 9-13. Kernel .config showing disabled SysRq key 9-14. Default handling of Ctrl-Alt-Delete in /etc/inittab 9-15. Ignoring Ctrl-Alt-Delete in /etc/inittab 9-16. Shut down cleanly upon Ctrl-Alt-Delete in /etc/inittab 10-1. Kernel configuration for serial console using make menuconfig 10-2. Kernel configuration for serial console using .config 10-3. Kernel configuration for USB dongle serial console using make menuconfig 10-4. Kernel configuration for USB dongle serial console using .config 10-5. Kernel configuration for serial console using make menuconfig 10-6. Kernel configuration for serial console using .config 11-1. Null modem cable with full status and handshaking 11-2. Variation on null modem cable with full status and handshaking 11-3. Null modem cable with falsified status and handshaking 11-4. Null modem cable with no status or handshaking 11-5. One-way null modem cable with no status or handshaking 12-1. Front panel of a dumb modem 12-2. Testing the modem's port speed 12-3. Configure modem using AT commands 12-4. Resetting a Hayes AT-style modem A-1. A kernel console parameter with CTS/RTS flow control A-2. Kernel source code for console CTS/RTS flow control A-3. setserial causes a modem to hang up as the machine initializes B-1. Supressing kernel messages to the console in Red Hat Linux C-1. Configuring BIOS to use serial link C-2. Configuring BIOS to boot from hard disk C-3. Extract from Red Hat Linux 7.2 mkbootdisk which creates SYSLINUX.CFG C-4. Altered extract from mkbootdisk, which creates a SYSLINUX.CFG that uses a serial console E-1. Basic configuration for Cisco 2511 terminal server to Linux PC E-2. Portmaster unit configuration E-3. Portmaster port configuration F-1. Configuring /dev/nvram to access the CMOS configuration F-2. Getting the CMOS configuration F-3. Setting the CMOS configuration List of Examples 4-1. Using kernel parameters to avoid access permissions 5-1. Complete LILO configuration, as installed by vendor 5-2. Complete LILO configuration, modified for serial console 5-3. Complete GRUB configuration, as installed by vendor 5-4. Complete GRUB configuration, modified for serial console 8-1. Dialing into a serial console C-1. Displaying the Internet Protocol configuration C-2. Displaying the LILO configuration ----------------------------------------------------------------------------- Chapter 1. Introduction   console n. [From latin consolatio(n) "comfort, spiritual solace."] A device for displaying or printing condolances or obituaries for the operator. Stan Kelly-Bootle, The Computer Contradictionary. ----------------------------------------------------------------------------- 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: Systems administration of remote computers Linux is a good operating system for deployment at unstaffed sites. Linux is also good for hosting critical network infrastructure such as DNS and DHCP services. These services are generally installed at every site of an organisation including sites which may be too small or too remote to have information technology staff. System administration of these remote computers is usually done using SSH , but there are times when access to the console is the only way to diagnose and correct software failures. Major upgrades to the installed distribution may also require console access. In these cases the serial console is attached to a modem. Access to the console is gained from a remote computer by dialing into the modem. This allows the console to be reached from any telephone socket. High density racks of computers Clusters of personal computers can outperform mainframe computers and form competitive supercomputers for some applications. See the Cluster-HOWTO for more information on clustering. These clusters are typically assembled into 19 inch telecommunications equipment racks and the system unit of each computer is typically one rack unit (or 1.75 inches) tall. It is not desirable to put a keyboard and monitor on each computer, as a small cathode ray tube monitor would consume the space used by sixteen rack units. A first glance it seems that a monitor and keyboard switch is the best solution. However the VGA signal to the monitor is small, so even with the switch the monitor cannot be placed very far away from the rack of computers. It is desirable to allow the consoles to be monitored in the operators' room of the computer center, rather than in the very expensive space of the machine room. Although monitor switches with remote control and fiber optical extensions are available, this solution can be expensive. A standard RS-232 cable can be 15 meters in length. Longer distances are easily possible. The cabling is cheap. Terminal servers can be used to allow one terminal to access up to 90 serial consoles. Recording console messages This is useful in two very different cases. Kernel programmers are often faced with a kernel error message that is displayed a split second before the computer reboots. A serial console can be used to record that message. Another Linux machine can be used as the serial terminal. Some secure installations require all security events to be unalterably logged. One way to meet this requirement is to print all console messages. Connecting the serial console to a serial printer can achieve this.[1] Embedded software development Linux is increasingly being used as an operating system for embedded applications. These computers do not have keyboards or screens. A serial port is a cheap way to allow software developers to directly access the embedded computer. This is invaluable for debugging. Most chip sets designed for embedded computers have a serial port precisely for this purpose. The shipping product need not present the RS-232 port on an external connector. Alternatively the RS-232 port is often used for downloading software updates. Craft terminal for telecommunications equipment Linux is increasingly being used as the operating system inside telecommunications equipment. The Carrier Grade Linux consortia hopes to accelerate and coordinate this trend. Most telecommunications equipment is remotely managed from a distant computer. However, site technicans (called craft personnel in telco-speak) need to access the equipment to test installation changes, check the status of reported faults, and so on. The terminal used by the craft personnel is called the craft terminal. The craft terminal plugs into the craft interface on the equipment. The serial console makes an ideal craft interface. 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. Table 1-1. Different ways of referring to the "console" +------------------------+-----------------+--------------------------------+ |Document |  |  | +------------------------+-----------------+--------------------------------+ |This HOWTO |"Console" |"Attached monitor and keyboard" | +------------------------+-----------------+--------------------------------+ |Some Linux documentation|"Logical console"|"Physical console" | +------------------------+-----------------+--------------------------------+ |Device names |/dev/console |/dev/systty | +------------------------+-----------------+--------------------------------+ ----------------------------------------------------------------------------- 1.4. Configuration overview There are five major steps to configuring a serial console. 1. Optionally, the BIOS may be configured to use the serial port. 2. If needed, the boot loader may be configured to use the serial port. 3. The Linux kernel must be configured to use the serial port as its console. This is done by passing the kernel the console parameter when the kernel is started by the boot loader. 4. The init system should keep a process running to monitor the serial console for logins. The monitoring process is traditionally called getty. 5. A number of system utilities need to be configured to make them aware of the console, or configured to prevent them from disrupting the 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. ----------------------------------------------------------------------------- Chapter 2. Preparation This chapter ensures that access the existing console can be restored should the serial console fail to start. This chapter then discusses the selection of the RS-232 port and its parameters. ----------------------------------------------------------------------------- 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 [http://www.toms.net/rb/] Tom's root boot. ----------------------------------------------------------------------------- 2.2. Select a serial port 2.2.1. Serial port names Linux names its serial ports in the UNIX tradition. The first serial port has the file name /dev/ttyS0, the second serial port has the file name /dev/ ttyS1, and so on. This differs from the IBM PC tradition. The first serial port is named COM1:, the second serial port is named COM2:, and so on. Up to four serial ports can be present on a IBM PC/AT computer and its successors. Most boot loaders have yet another naming scheme. The first serial port is numbered 0, the second serial port is numbered 1, and so on. If your distribution of Linux uses the devfs device manager then the serial ports have yet another name. The first serial port is /dev/tts/0, the second serial port is /dev/tts/1, and so on. The result is that the first serial port is labeled COM1: on the chassis of the IBM PC; is known as /dev/ttyS0 to Linux; is known as /dev/tts/0 to Linux when configured with devfs; and is known as port 0 to many boot loaders. The examples in this HOWTO use this first serial port, as that is the serial port which most readers will wish to use. Table 2-1. Many names for the same serial port +------+-------------+------------------------+------------------+ |IBM PC|Linux kernel |Linux kernel with devfs |Most boot loaders | +------+-------------+------------------------+------------------+ |COM1: | /dev/ttyS0 | /dev/tts/0 | 0 | +------+-------------+------------------------+------------------+ |COM2: | /dev/ttyS1 | /dev/tts/1 | 1 | +------+-------------+------------------------+------------------+ |COM3: | /dev/ttyS2 | /dev/tts/2 | 2 | +------+-------------+------------------------+------------------+ |COM4: | /dev/ttyS3 | /dev/tts/3 | 3 | +------+-------------+------------------------+------------------+ ----------------------------------------------------------------------------- 2.2.2. Cannot share interrupt used for console's serial port When used for a console the serial port cannot share an interrupt with another device. The IBM PC devices are usually installed as shown in Table 2-2. If you use the serial port /dev/ttyS0 for the console then you should avoid sharing interrupt 4 by not installing a serial port /dev/ttyS2 in your PC. If /dev/ttyS2 cannot be physically removed then disable it using the setserial command, as shown in Figure 2-1. Table 2-2. Interrupts used for IBM PC/AT RS-232 ports +-----------+----------+-----+ | Device |Interrupt |Port | +-----------+----------+-----+ |/dev/ttyS0 | 4 |0x3f8| +-----------+----------+-----+ |/dev/ttyS1 | 3 |0x2f8| +-----------+----------+-----+ |/dev/ttyS2 | 4 |0x3e8| +-----------+----------+-----+ |/dev/ttyS3 | 3 |0x2e8| +-----------+----------+-----+ Figure 2-1. Using the setserial command in /etc/rc.serialto disable the serial port /dev/ttyS2 # 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 Reading the source code suggests that the interrupt-sharing constraint applies to all computer architectures, not just Intel Architecture-32. ----------------------------------------------------------------------------- 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. The speed of the serial link in bits per second. The Linux kernel on a modern PC supports a serial console speeds of 1200, 2400, 4800, 9600, 19200, 38400, 57600 and 115200 bits per second. The kernel supports a much wider range of serial bit rates when the serial interface is not being used as a serial console.[2] Very recent Linux kernels can also offer a serial console using a USB serial dongle at speeds of 1200, 2400, 4800, 9600, 19200, 38400, 57600 and 115200 bits per second. Most boot loaders only support a different range of speeds than are supported by the kernel. LILO 21.7.5 supports 110, 150, 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 56000, 57600 and 115200 bits per second. SYSLINUX 1.67 supports 75 to 56000 bits per second. GRUB 0.90 supports 2400, 4800, 9600, 19200, 38400, 57600 and 115200 bits per second. You must chose the same speed for both the boot loader and for the Linux kernel. An operating system may use more than one boot loader. For example, Red Hat Linux uses SYSLINUX to install or upgrade the operating system; LILO as the boot loader for Red Hat Linux 7.1 and earlier; and GRUB as the boot loader for Red Hat Linux 7.2 and later. If you are using a serial terminal or if you are using a dumb modem then the bit rate of the terminal or dumb modem must also match the bit rate selected in the boot loader and kernel. If the serial console is connected to a Hayes-style modem slower than 9600bps then configure the serial console with the same speed as the modem. Modems faster than 9600bps will generally automatically synchronize to the speed of the serial port. The selected bit rate must also be supported by the serial port's UART semiconductor chip. Early UARTs without on-chip receive buffers could only reliably receive at up to 14400bps, this includes models 8250A, 82510, 16450 and 16550 (with no A). Recent UARTs with receive buffers will work at all serial console bit rates, this includes models 16550A, 16552, 16650, 16654, 16750, 16850 and 16950. Unless you have good reason, use the popular bit rate of 9600 bits per second. This is the default bit rate of a great many devices. The speeds that are supported by the kernel, the three common boot loaders, and all IBM PCs capable of running Linux are: 2400, 4800, 9600 and 19200 bits per second. This is a depressingly small selection: not slow enough to support a call over an international phone circuit and not fast enough to upload large files. You may need to choose a speed that will result in a less robust software configuration. Figure 2-2. Syntax for serial bits per second rate, in extended Backus-Naur form  ::=    ::=  |   ::= 0 | 1 | ?? | 9 Number of parity bits and the interpretation of a parity bit if one is present. Allowed values are n for no parity bit, e for one bit of even parity and o for one bit of odd parity. Using no parity bit and eight data bits is recommended. If parity is used then even parity is the common choice. Parity is a simple form of error detection. Modern modems have much better error detection and correction. As a result the parity bit guards only the data on the cable between the modem and the serial port. If this cable has a low error rate, and it should, then the parity bit is not required. Figure 2-3. Syntax for serial parity, in extended Backus-Naur form  ::= n | e | o The number of data bits per character. Allowed values are 7 bits or 8 bits, as Linux uses the ASCII character set which requires at least seven bits. Eight data bits are recommended. This allows the link to easily be used for file transfers and allows non-English text to be presented. Figure 2-4. Syntax for serial data bits, in extended Backus-Naur form  ::= 7 | 8 The number of stop bit-times.[3] Allowed values are 1 or 2. One stop bit-time is recommended. If the RS-232 cable is very long then two stop bit-times may be needed. You may occassionally see 1.5 stop bit-times. The intent is to gain 4% more data throughput when a link is too long for one stop bit-time but is too short to require two stop bit-times. 1.5 stop bit-times is now rare enough to be a hazard to use. Figure 2-5. Syntax for serial stop bits, in extended Backus-Naur form  ::= 1 | 2 The type of flow control to use. The Linux kernel allows no flow control and CTS/RTS flow control. No flow control is the default, this is indicated by omitting < flow_control>. CTS/RTS flow control is recommended, especially if login access is also provided to the serial port. This is indicated by a of r. CTS/RTS flow control regulates the flow of chatacters. The computer does not send characters until Clear To Send is asserted by the modem. If the computer is has enough buffering to recieve characters from the modem the computer asserts Ready to Send. Thus neither the computer nor the modem's buffers are filled to overflowing. Caution The kernel's CTS/RTS flow control is currently buggy. Machines can take a significant time to write console messages if flow control is enabled but CTS will never be asserted (as occurs when there is no call present on a modem or no session on a null modem cable or cable to a terminal server). As a result of the large number of kernel messages when the kernel is started a machine configured with the kernel's CTS/RTS flow control can take many minutes to reboot. The kernel's CTS/RTS flow control cannot be recommended at this time. The HOWTO's author has a kernel patch available which he is seeking to have included in the mainstream kernel source code. The CTS/RTS flow control in user-space applications does not share the kernel's bugs and CTS/RTS flow control is still recommended for getty. Figure 2-6. Syntax for serial flow control, in extended Backus-Naur form  ::=  | r 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. Figure 2-7. Syntax for kernel serial parameters, in extended Backus-Naur form  ::=  Note that does not include . 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. ----------------------------------------------------------------------------- Chapter 3. Optionally configure the BIOS Some BIOSs provide support for serial consoles. If your computer's BIOS is one of these you should investigate the extent of the support provided. Depending upon the extent of serial console support you may not need to explicitly configure the boot loader to use the serial port. The contributors to this HOWTO have encountered the following styles of BIOS support for serial consoles. Redirection of textual VGA output to the serial port The BIOS takes the interrupt 0x10 "video" requests used to write to the screen and sends the characters that would have appeared on the screen to the serial port. Characters recieved from the serial port are used to supply characters to BIOS interrupt 0x16 "read key" requests. Any 16-bit application which uses the BIOS functions for outputing text to the screen and reading from the keyboard is redirected to the serial port. This includes the BIOS itself, the boot loader, and 16-bit operating systems (such as MS-DOS). When a 32-bit operating system (such as Linux, BSD or Windows NT/2000/XP) loads the 16-bit BIOS is no longer accessible and the BIOS can no longer be used for input and output. The 32-bit operating system loads its own device drivers for this purpose. These device drivers then need to provide the redirection of console I/O to the serial port. If your BIOS uses this technique then you should: 1. Configure the BIOS to redirect keyboard input and video output to the serial port. 2. Do not configure the boot loader, as the BIOS will redirect this 16-bit application's input and output to the serial port. 3. Configure Linux to use the serial port as a console, as Linux is a 32-bit operating system. BIOS configuration and power on self-test uses the serial port These BIOSs use the serial port for configuration and the power-on self-test, but do not redirect the interrupt 0x10 "video" requests interrupt 0x16 "read key" requests to the serial port. Some BIOSs which usually redirect all keyboard and video output to the serial port can be configured in only to redirect BIOS input and output. Look for a BIOS configuration option similar to Cease redirection after boot. If your BIOS uses this technique or you choose to set Cease redirection after boot then you should: 1. Configure the BIOS to send its output to the serial port. 2. Configure the boot loader to use the serial port. 3. Configure Linux to use the serila port as the console, as Linux is a 32-bit operating system. Redirection of graphical VGA output to the serial port Some graphical 32-bit operating systems do not provide their own facilities to send console output to the serial port. Some BIOSs attempt to overcome this shortcoming, using a propietary serial protocol to send graphical output to a remote serial client. As these machines cannot be connected to from a standard terminal emulator this facility is best left unconfigured when using the Linux operating system. 1. Configure the BIOS not to send output to the serial port. 2. Configure the boot loader to use the serial port. 3. Configure Linux to use the serial port as the console. No serial port facilities The BIOS cannot be accessed from the serial port, so power-on self-test messages cannot be seen. Note that BIOS may still be able to be configured remotely using the /dev /nvram device. This takes some care. 1. Configure the boot loader to use the serial port. 2. Configure Linux to use the serial port as the console. If you need to configure the boot loader to use the serial port then continue to Chapter 4. Otherwise go directly to Chapter 5 to configure the kernel; this is done by configuring the boot loader to pass boot parameters to the Linux kernel. ----------------------------------------------------------------------------- Chapter 4. Configure the boot loader When a PC boots the CPU it runs code from Read-Only Memory. This code is the Basic Input/Output System, or BIOS. The BIOS then loads a boot loader from the Master Boot Record of the first hard disk.[4] In turn, the boot loader reads the operating system into memory and then runs it.[5] Neither the BIOS nor the boot loader are strictly necessary. For example, there are [http://www.acl.lanl.gov/linuxbios/] versions of Linux that run directly from the flash memory which usually contains the BIOS. Linux was originally designed to run without an interactive boot loader, by placing the kernel at particular sectors of the disk. The benefits of using a boot loader are:   * Multiple operating systems can be booted. See the Linux + Windows HOWTO for more information.   * Parameters can be passed to the kernel interactively. This is useful for solving hardware problems; for example, some interrupt lines can be disabled, direct memory access to some drives can be disabled, and so on. See the Linux BootPrompt-HOWTO for a list of kernel parameters.   * Differing kernels can be interactively loaded. This is useful when deploying a new kernel, as it provides simple fallback to a proven kernel. For these reasons systems administrators want to be able to interactively control the boot loader from the serial console. LILO, GRUB and SYSLINUX are popular boot loaders for IBM PCs. Find which of these boot loaders your Linux installation uses and then follow the instructions for your boot loader in the following section. ----------------------------------------------------------------------------- 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. Figure 4-1. Syntax of LILO serial command, in EBNF serial=[,[[]]] Where the variables are the same as used by the kernel (shown in Figure 2-7) and: Figure 4-2. LILO serial EBNF variables  ::= 0 | 1| ?? | 3 Our examples use /dev/ttyS0, which LILO knows as port 0. Figure 4-3. LILO boot loader sample configuration 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: Example 4-1. Using kernel parameters to avoid access permissions +---------------------------------------------------------------------------+ |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. Figure 4-4. Using md5crypt to create a hashed password for GRUB +---------------------------------------------------------------------------+ |grub> md5crypt | |Password: ********** | |Encrypted: $1$U$JK7xFegdxWH6VuppCUSIb. | +---------------------------------------------------------------------------+ Use that hashed password in the GRUB configuration file, this is shown in Figure 4-5. Figure 4-5. GRUB configuration to require a password password --md5 $1$U$JK7xFegdxWH6VuppCUSIb. Define the serial port and configure GRUB to use the serial port, as shown in Figure 4-6. Figure 4-6. GRUB configuration for serial console 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. Figure 4-7. GRUB configuration for serial console and attached monitor and keybaord console 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. Figure 4-8. GRUB output to default device when configured for serial and attached monior output +-------------------------------------------------------------------------------+ |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. Figure 4-9. GRUB configuration for command line interface for terminals other than VT100 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. Figure 4-10. Adding a single user mode option to the GRUB menu 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: Figure 4-11. Syntax of SYSLINUX serial command, in EBNF serial   [   [  < syslinux_flow_control> ] ] The variables are the same as used by syntax descriptions in Figure 2-7 and Figure 4-2 plus those in Figure 4-12. Figure 4-12. SYSLINUX serial EBNF variables  ::= ?? ??  ::=   ::= 0x  ::= 0 | 1 | ?? | 9 | a | b | ?? | f The 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. Table 4-1. SYSLINUX flow control bitmap +------------------------------+---------+----------------------------------+ | Flow control behaviour |Hex value| Required for full RS-232 | | | | compliance? | +------------------------------+---------+----------------------------------+ |Assert DTR | 0x001 | Yes | +------------------------------+---------+----------------------------------+ |Assert RTS | 0x002 | Yes | +------------------------------+---------+----------------------------------+ |Wait for CTS assertion | 0x010 | Yes | +------------------------------+---------+----------------------------------+ |Wait for DSR assertion | 0x020 | Yes | +------------------------------+---------+----------------------------------+ |Wait for RI assertion | 0x040 | No | +------------------------------+---------+----------------------------------+ |Wait for DCD assertion | 0x080 | Yes | +------------------------------+---------+----------------------------------+ |Ignore input unless CTS | 0x100 | No | |asserted | | | +------------------------------+---------+----------------------------------+ |Ignore input unless DSR | 0x200 | Yes | |asserted | | | +------------------------------+---------+----------------------------------+ |Ignore input unless RI | 0x400 | No | |asserted | | | +------------------------------+---------+----------------------------------+ |Ignore input unless DCD | 0x800 | Yes | |asserted | | | +------------------------------+---------+----------------------------------+ Our preferred configuration of 9600bps, port 0, full RS-232 status signals and CTS/RTS flow control is written as: serial 0 9600 0xab3 Tip 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. ----------------------------------------------------------------------------- Chapter 5. Configure Linux kernel The Linux kernel is configured to select the console by passing it the console parameter. The console parameter can be given repeatedly, but the parameter can only be given once for each console technology. So console=tty0 console=lp0 console=ttyS0 is acceptable but console=ttyS0 console=ttyS1 will not work. When multiple consoles are listed output is sent to all consoles and input is taken from the last listed console. The last console is the one Linux uses as the /dev/console device. The syntax of the console parameter is given in Figure 5-1. Figure 5-1. Kernel console syntax, in EBNF console=ttyS[,] console=tty console=lp console=ttyUSB[[,] is the number of the serial port. This is defined in Figure 4-2 and discussed in Section 2.2. The examples in this HOWTO use the first serial port, giving the value 0, which in turn gives kernel parameter console=ttyS0. If you are using the devfs device filesystem with your Linux installation the kernel parameter for the first serial port is still ttyS0, even though the first serial device is no longer known as /dev/ttyS0 but as /dev/ttys/0. is defined in Figure 2-7 and is discussed in Section 2.3. The examples in this HOWTO use 9600 bits per second, one start bit, eight data bits, no parity, one stop bit, and no CTS/RTS flow control giving the value of 9600n8. When the current kernel flow control bugs are corrected this HOWTO will once again recommend the value 9600n8r. can specify the address of a USB dongle containing a serial port to be used as a serial console.[6] For example, the serial port console= ttyS0,9600n8 when moved to a USB serial dongle would be written as console= ttyUSB0,9600n8. The USB subsystem is started rather late in the boot process, console messages printed during boot before the USB subsystem is loaded will be lost. With no console parameter the kernel will use the first virtual terminal, which is /dev/tty0. A user at the keyboard uses this virtual terminal by pressing Ctrl-Alt-F1. If your computer contains a video card then we suggest that you also configure it as a console. This is done with the kernel parameter console= tty0. For computers with both a video card and a serial console in the port marked "COM1:" this HOWTO suggests the kernel parameters: Figure 5-2. Recommended kernel parameters, PCs with video card console=tty0 console=ttyS0,9600n8 Kernel messages will appear on both the first virtual terminal and the serial port. Messages from the init system and the system logger will appear only on the first serial port. This can be slightly confusing when looking at the attached monitor: the machine will appear to boot and then hang. Don't panic, the init system has started but is now printing messages to the serial port but is printing nothing to the screen. If a getty has been configured then a login: prompt will eventually appear on the attached monitor. For PCs without a video card, this HOWTO suggests the kernel parameters: Figure 5-3. Recommended kernel parameters, PCs without video card console=ttyS0,9600n8 These parameters are passed to the booting kernel by the boot loader. Next we will configure the boot loader used by your Linux installation to pass the console parameters to the kernel. ----------------------------------------------------------------------------- 5.1. Configure Linux kernel using LILO For each image entry in /etc/lilo.conf add the line: Figure 5-4. Recommended kernel parameters, LILO configuration 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: Example 5-1. Complete LILO configuration, as installed by vendor 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 Example 5-2. Complete LILO configuration, modified for serial console 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. Figure 5-5. Recommened kernel parameters, GRUB configuration 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. Example 5-3. Complete GRUB configuration, as installed by vendor 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. Example 5-4. Complete GRUB configuration, modified for serial console 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: Figure 5-6. Recommended kernel parameters, SYSLINUX configuration 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. ----------------------------------------------------------------------------- Chapter 6. Configure getty getty monitors serial lines, waiting for a connection. It then configures the serial link, sends the contents of /etc/issue, and asks the person connecting for their login name. getty then starts login and login asks the person for their password. If the user does nothing, getty or login hang up and getty goes back to waiting. The getty command has been re-implemented numerous times. There is a wide selection of getty clones, each with slight differences in behavior and syntax. We will describe the traditional getty, and then some popular alternatives. One of the jobs of a getty is to set the TERM environment variable to indicate the make and model of the terminal which is connecting. In this HOWTO we set the terminal to the commonly emulated DEC VT100. If you occassionally connect using a different terminal emulation then you can interactively change your choice of terminal by setting TERM to the appropiate terminal listed in /etc/termcap. Figure 6-1. Interactively altering the connecting terminal's make and model +---------------------------------------------------------------------------+ |bash$ TERM=kermit | |bash$ tset -r | +---------------------------------------------------------------------------+ A getty is also responsible for setting the time zone when a permanently-connected remote terminal is located beyond the machine's default time zone. The getty overrides the default timezone by setting the TZ environment variable. As with the TERM environment variable, a user connecting from a modem can interactively override the default time zone. Figure 6-2. Interactively altering the connecting terminal's time zone +---------------------------------------------------------------------------+ |bash$ TZ=Australia/Adelaide | |bash$ export TZ | +---------------------------------------------------------------------------+ If you do not know your time zone name, run the tzselect utility to generate the appropiate contents for TZ. But first, let's see how getty gets started in the first place. ----------------------------------------------------------------------------- 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. Figure 6-3. getty is started by init, based upon an entry in /etc/inittab +---------------------------------------------------------------------------+ |co:2345:respawn:/sbin/getty ttyS0 CON9600 vt102 | +---------------------------------------------------------------------------+ Each field in inittab is separated by a colon and contains: co Arbitrary entry for inittab. As long as this entry doesn't appear anywhere else in inittab, you're okay. We named this entry co because it's for the console. Red Hat Linux 7.3 has a program called kudzu which configures the system when it is booted. kudzu treats an inittab entry of co specially, setting it for the attached monitor and keyboard or the serial console. Hardcoding the value of co prevents this behaviour. 2345 Run levels where this entry gets started. Run levels 2, 3, 4 and 5 can be used for an operational system, getty should not be used in other run levels. The serial console still works in run level 1 (or single user mode) even without a getty. respawn Re-run the program if it dies. We want this to happen so that a new login prompt will appear when you log out of the console. /sbin/getty ttyS0 CON9600 vt102 The command to run. In this case, we're telling getty to connect to /dev/ ttyS0 using the settings for CON9600 which exists in /etc/gettydefs. This entry represents a terminal running at 9600bps. Initially assume that the terminal is a later-model VT100. After changing /etc/inittab restart init with +---------------------------------------------------------------------------+ |telinit q | +---------------------------------------------------------------------------+ An alternative is to send the hangup signal to init with the command kill -HUP 1. This is not recommended: if you make a typing mistake and actually kill init then your system will suddenly halt. Note Comments in inittab and Red Hat's kudzu   kudzu uses the # line comment to activate and deactivate the gettys for the attached monitor and keyboard and for the serial port. To prevent a genuine comment from becoming confused with a line saved by kudzu use ## at the start of a line of genuine comments. ----------------------------------------------------------------------------- 6.2. Traditional getty Traditional getty implementations include uugetty and getty_ps. The traditional getty is listed in /etc/inittab with the name of a section in /etc/gettydefs to use for its configuration. Our example in Figure 6-3 used the section CON9600. There is no CON9600 in the standard gettydefs. This is deliberate, as serial consoles sometimes require slight tweaking. Copy the DT9600 entry and use it as your model. Figure 6-4. Define CON9600 in gettydefs # Serial console 9600, 8, N, 1, CTS/RTS flow control CON9600# B9600 CS8 -PARENB -ISTRIP CRTSCTS HUPCL # B9600 SANE CS8 -PARENB -ISTRIP CRTSCTS HUPCL #@S @L login: #CON9600 Separate each line with a blank line. Each configuration line has the syntax: Figure 6-5. Syntax of entries in /etc/gettydefs, in EBNF