Remote Serial Console HOWTO Glen Turner Australian Academic and Research Network glen.turner+howto@aarnet.edu.au Mark F. Komarinski mkomarinski@valinux.com v2.0 2002/02/02 Revision History 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 in remote sites or are deployed in high-density racks. This HOWTO describes how to configure Linux to attach a serial console. ----------------------------------------------------------------------------- Table of Contents 1. Preliminaries 1.1. Copyright 1.2. Disclaimer 1.3. Acknowledgments 1.4. Comments and corrections 2. Introduction 2.1. What is a console? 2.2. Why use a serial console? 2.3. Alternative meanings of ??console?? 2.4. Configuration overview 3. Preparation 3.1. Create fallback position 3.2. Select a serial port 3.3. Select a serial speed and parameters 3.4. Configure the modem or the null-modem cable 3.5. Configure the terminal or the terminal emulator 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 10. Configuring a kernel to support serial console 10.1. Linux kernel version 2.4 10.2. 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. 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. Red Hat Linux 7.1 and SysVinit A.2. BIOSs, keyboards and video cards A.3. Modem hangs up upon reboot A.4. init and syslog output does not display on secondary consoles A.5. The console is unresponsive after connecting A.6. Modem hangs up during initialization A.7. Boot loader has no flow control A.8. Boot loaders are vulnerable to line noise A.9. Advanced Power Management A.10. Modems and overseas telecommunications requirements B. Uploading files from a serial console B.1. ASCII upload and cat B.2. Disable logging to console 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. Terminal server configuration D.1. Cisco 2511 E. Gratuitous advice for developers E.1. Advice for boot loader authors E.2. Advice for BIOS authors Colophon List of Tables 2-1. Different ways of referring to the ??console?? 3-1. Many names for the same serial port 4-1. SYSLINUX flow control bitmap 10-1. IBM-PC/AT serial port bit rates and their bit-clock divisors List of Figures 3-1. Serial parameter syntax, 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 configuration for command line interface for terminals other than VT100 4-9. Adding a single user mode option to the GRUB menu 4-10. Syntax of SYSLINUX serial command, in EBNF 4-11. 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. getty is started by init, based upon an entry in /etc/inittab 6-3. Define CON9600 in gettydefs 6-4. Syntax of entries in /etc/gettydefs, in EBNF 6-5. /etc/inittab entry for agetty 6-6. /etc/inittab entry for mgetty 6-7. mgetty configuration file mgetty.config 6-8. Fewer virtual terminals. Removing mingetty entries from /etc/inittab 6-9. Fewer virtual terminals. Deallocating unused virtual terminals and removing their device files. 6-10. 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. Removal of ioctl.save containing the saved console parameters 7-3. Remove /dev/modem if it points to the serial console's port 7-4. Default value of /dev/systty in /etc/makedev.d/linux-2.4.x 7-5. Alter value of /dev/systty in MAKEDEV configuration file 7-6. Installing new value of /dev/systty 7-7. Default in console.perms refers to attached keyboard and screen 7-8. Default device listing in console.perms 7-9. Devices in console.perms required for attached keyboard and screen 7-10. Add in console.perms to refer to serial console 7-11. Remaining devices in console.perms altered to refer to serial console 7-12. Alterations to /etc/sysconfig/init for Red Hat Linux 7-13. Alterations to /etc/sysconfig/kudzu for Red Hat Linux 9-1. Restrict sending of messages to console user 9-2. Restrict sending of messages to console user, /etc/profile.d/mesg.sh 9-3. Restrict sending of messages to console user, /etc/profile.d/mesg.csh 9-4. Install files into /etc/profile.d 9-5. Using sysctl to defeat the magic SysRq key 9-6. Configuring /etc/sysctl.conf to defeat the magic SysRq key 9-7. Kernel make menuconfig showing disabled SysRq key 9-8. Kernel .config showing disabled SysRq key 9-9. Default handling of Ctrl-Alt-Delete in /etc/inittab 9-10. Ignoring Ctrl-Alt-Delete in /etc/inittab 9-11. 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 11-1. Null modem cable with full status and handshaking 11-2. Null modem cable with falsified status and handshaking 11-3. 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. 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 D-1. Basic configuration for Cisco 2511 terminal server to Linux PC E-1. Configuring /dev/nvram to access the CMOS configuration E-2. Getting the CMOS configuration E-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. Preliminaries 1.1. Copyright The first edition of this document is copyright © 2001 Mark F. Komarinski and is distributed under the terms of the Linux Documentation Project (LDP) License, see Section 1.1.1. The revisions to this document for the second edition are copyright © AARNet Pty Ltd (Australian Company Number 084 540 518), 2001-2002. These parts were written by Glen Turner. He asserts his moral rights to be identified as one of the authors of this work under the Copyright Act 1968 (Commonwealth of Australia). The Australian Academic and Research Network and Glen Turner distribute these parts under the terms of the Linux Documentation Project (LDP) License, see Section 1.1.1. ----------------------------------------------------------------------------- 1.1.1. Linux Documentation Project License Unless otherwise stated, Linux HOWTO documents are copyrighted by their respective authors. Linux HOWTO documents may be reproduced and distributed in whole or in part, in any medium physical or electronic, as long as this copyright notice is retained on all copies. Commercial redistribution is allowed and encouraged; however, the author would like to be notified of any such distributions. All translations, derivative works, or aggregate works incorporating any Linux HOWTO documents must be covered under this copyright notice. That is, you may not produce a derivative work from a HOWTO and impose additional restrictions on its distribution. Exceptions to these rules may be granted under certain conditions; please contact the Linux HOWTO coordinator at the address given below. In short, we wish to promote dissemination of this information through as many channels as possible. However, we do wish to retain copyright on the HOWTO documents, and would like to be notified of any plans to redistribute the HOWTOs. If you have any questions, please contact . ----------------------------------------------------------------------------- 1.2. Disclaimer No liability for the contents of this documents can be accepted. Use the concepts, examples and other content at your own risk. As this is a new edition of this document, there may be errors and inaccuracies, that may of course be damaging to your system. Proceed with caution, and although this is highly unlikely, the author(s) do not take any responsibility for that. All copyrights are held by their by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. Naming of particular products or brands should not be seen as endorsements. You are strongly recommended to take a backup of your system before major installation and backups at regular intervals. ----------------------------------------------------------------------------- 1.3. Acknowledgments The first edition of this HOWTO was written by Mark Komarinski. It was based upon /usr/src/linux/Documentation/serial-console.txt, which was written by Miquel van Smoorenburg. The second edition of this HOWTO was written by the staff of the Australian Academic and Research Network, mainly Glen Turner and David Vu. The revised text was proof read by the members of the LinuxSA mailing list. [http:// www.linuxsa.org.au/] LinuxSA is a Linux user group based in South Australia. David Lawyer, author of the Text-Terminal-HOWTO, reviewed the second edition. Many thanks to David for his useful feedback. 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. Thanks Karen, Kayla and Ella. ----------------------------------------------------------------------------- 1.4. Comments and corrections Without your submissions this document would not exist. Linux is continually improving and your author is not a professional editor. Please send corrections, additions, comments and criticisms to the maintainer, currently . ----------------------------------------------------------------------------- Chapter 2. 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. ----------------------------------------------------------------------------- 2.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. ----------------------------------------------------------------------------- 2.2. Why use a serial console? For the average user a serial console has no advantage over using 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 an good operating system for deployment at unstaffed sites. Linux is also good at hosting critical network infrastructure such as DNS and DHCP servers. These servers are generally installed at every site of an organisation including sites which may be too small or too remote to have IT 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 be 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. A 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 as the operating system in 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. 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 reconfigure the BIOS and seeing makes it 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 as the console. 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. ----------------------------------------------------------------------------- 2.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 2-1. Different ways of referring to the ??console?? +------------------------+---------------+-----------------------------+ |This HOWTO |console |Attached monitor and keyboard| +------------------------+---------------+-----------------------------+ |Some Linux documentation|Logical console|Physical console | +------------------------+---------------+-----------------------------+ |Device names |/dev/console |/dev/systty | +------------------------+---------------+-----------------------------+ ----------------------------------------------------------------------------- 2.4. Configuration overview There are four major steps to configuring a serial console. 1. The boot loader must be configured to use the serial port. 2. 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. 3. The init system should keep a process running to monitor the serial console for logins. The monitoring process is traditionally called getty. 4. 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 and 7.2, which were released in 2001. The maintainer would appreciate updates for later versions of Red Hat Linux. The maintainer would very much appreciate examples for Linux distributions that are dissimilar to Red Hat Linux; particularly Debian GNU/Linux and Slackware Linux. ----------------------------------------------------------------------------- Chapter 3. 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. ----------------------------------------------------------------------------- 3.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 | +---------------------------------------------------------------------------+ 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. ----------------------------------------------------------------------------- 3.2. Select a serial port 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. 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; and is known as port 0 to the boot loader. The examples in this HOWTO use this first serial port, as that is the serial port which most readers will wish to use. Table 3-1. Many names for the same serial port +------+------------+------------------+ |IBM PC|Linux kernel|Most boot loaders | +------+------------+------------------+ |COM1: | /dev/ttyS0 | 0 | +------+------------+------------------+ |COM2: | /dev/ttyS1 | 1 | +------+------------+------------------+ |COM3: | /dev/ttyS2 | 2 | +------+------------+------------------+ |COM4: | /dev/ttyS3 | 3 | +------+------------+------------------+ ----------------------------------------------------------------------------- 3.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?? and ??stop bits?? refer to the Serial-HOWTO and the Modem-HOWTO. The Linux kernel uses the syntax in Figure 3-1 to describe the serial parameters. Many boot loaders use a variation of the syntax used by the Linux kernel. Figure 3-1. Serial parameter syntax, in extended Backus-Naur form  ::=   ::=    ::= n | e | o  ::= 7 | 8  ::= 1 | 2  ::=  |   ::= 0 | 1 | ?? | 9 The variables and their values are: The speed of the serial link in bits per second. The Linux kernel on a modern PC supports 50, 75, 110, 134.5, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600 and 115200 bits per second. Higher bit rates may be possible depending upon the model of the serial port's semiconductor. Most boot loaders only support a subset of this range. 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 semiconductor. Early model UARTs such as the 8250 series and the 16450 could only reliably recieve at up to 14400bps. The 16550 series and later models will work at all bit rates. 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. 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. 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. The number of stop bit-times.[2] 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. Most boot loaders default to 9600n81. A common default found on older terminals is 9600e71. Use 9600n81 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 9600n81 will know what to alter. ----------------------------------------------------------------------------- 3.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 3.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. ----------------------------------------------------------------------------- 3.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. If you are using a terminal emulator then it is best to choose to emulate the popular DEC VT100 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, IBM PC colors and a selection of X3.64-1979 control sequences. See the Text-Terminal-HOWTO for much more information on configuring terminals. ----------------------------------------------------------------------------- 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. In turn, the boot loader reads the operating system into memory and then runs it. 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. 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 loaded interactively. This is useful when deploying a new kernel, as it provides a simple fallback to an older 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, except that one stop bit is assumed. 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 3-1) 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, although 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 [configure-boot-loader-grub-md5] configure-boot-loader-grub-md5. 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. 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. | +-------------------------------------------------------------------------------+ Note 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-8. 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-9. 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-9. 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-10. Syntax of SYSLINUX serial command, in EBNF serial   [   [   ] ] The variables are the same as used by syntax descriptions in Figure 3-1 and Figure 4-2 plus those in Figure 4-11. Figure 4-11. 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 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 use a serial console by passing it the console parameter. The console parameter can be given repeatedly; in that case 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 is the number of the serial port. This is defined in Figure 4-2 and discussed in Section 3.2. The examples in this HOWTO use the first serial port, giving the value ttyS0. 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. is defined in Figure 3-1 and is discussed in Section 3.3. The examples in this HOWTO use 9600 bits per second, eight data bits, no parity and one stop bit, giving the value of 9600n81. 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 PCs with 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,9600n81 For PCs without a video card, this HOWTO suggests the kernel parameters: Figure 5-3. Recommended kernel parameters, PCs without video card console=ttyS0,9600n81 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 timeout=200 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,9600n81" 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,9600n81 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,9600n81 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,9600n81 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,9600n81 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 | +---------------------------------------------------------------------------+ 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-2. getty is started by init, based upon an entry in /etc/inittab +---------------------------------------------------------------------------+ |s0:2345:respawn:/sbin/getty ttyS0 CON9600 | +---------------------------------------------------------------------------+ Each field in inittab is separated by a colon and contains: s0 Arbitrary entry for inittab. As long as this entry doesn't appear anywhere else in inittab, you're okay. We named this entry s0 because it's for /dev/ttyS0. 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. ----------------------------------------------------------------------------- 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-2 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-3. Define CON9600 in gettydefs # Serial console 9600n81, 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-4. Syntax of entries in /etc/gettydefs, in EBNF