Index: head/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml (revision 44389) +++ head/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml (revision 44390) @@ -1,2761 +1,2761 @@ Serial Communications Synopsis serial communications &unix; has always had support for serial communications as the very first &unix; machines relied on serial lines for user input and output. Things have changed a lot from the days when the average terminal consisted of a 10-character-per-second serial printer and a keyboard. This chapter covers some of the ways serial communications can be used on &os;. After reading this chapter, you will know: How to connect terminals to a &os; system. How to use a modem to dial out to remote hosts. How to allow remote users to login to a &os; system with a modem. How to boot a &os; system from a serial console. Before reading this chapter, you should: Know how to configure and install a custom kernel. Understand &os; permissions and processes. Have access to the technical manual for the serial hardware to be used with &os;. Serial Terminology and Hardware The following terms are often used in serial communications: bps Bits per Secondbits-per-second (bps) is the rate at which data is transmitted. DTE Data Terminal EquipmentDTE (DTE) is one of two endpoints in a serial communication. An example would be a computer. DCE Data Communications EquipmentDCE (DTE) is the other endpoint in a serial communication. Typically, it is a modem. RS-232 The original standard which defined hardware serial communications. It has since been renamed to TIA-232RS-232C cables. When talking about communications data rates, this section does not use the term baud. Baud refers to the number of electrical state transitions that may be made in a period of time, while bps is the correct term to use. To connect a modem or serial terminal to a &os; system, a serial port on the computer and the proper cable to connect to the serial device are needed. Users who are already familiar with serial hardware and cabling can safely skip this section. Serial Cables and Ports There are several different kinds of serial cables. The two most common types are null-modem cables and standard RS-232 cables. The documentation for the hardware should describe the type of cable required. null-modem cable A null-modem cable passes some signals, such as Signal Ground, straight through, but switches other signals. For example, the Transmitted Data pin on one end goes to the Received Data pin on the other end. A null-modem cable can be constructed for use with terminals. The following table shows the RS-232C signal names and the pin numbers on a DB-25 connector. While the standard calls for a straight-through pin 1 to pin 1 Protective Ground line, it is often omitted. Some terminals work using only pins 2, 3, and 7, while others require different configurations than the examples shown below. DB-25 to DB-25 Null-Modem Cable Signal Pin # Pin # Signal SG 7 connects to 7 SG TD 2 connects to 3 RD RD 3 connects to 2 TD RTS 4 connects to 5 CTS CTS 5 connects to 4 RTS DTR 20 connects to 6 DSR DTR 20 connects to 8 DCD DSR 6 connects to 20 DTR DCD 8 connects to 20 DTR
The next two tables show two other common schemes. DB-9 to DB-9 Null-Modem Cable Signal Pin # Pin # Signal RD 2 connects to 3 TD TD 3 connects to 2 RD DTR 4 connects to 6 DSR DTR 4 connects to 1 DCD SG 5 connects to 5 SG DSR 6 connects to 4 DTR DCD 1 connects to 4 DTR RTS 7 connects to 8 CTS CTS 8 connects to 7 RTS
DB-9 to DB-25 Null-Modem Cable Signal Pin # Pin # Signal RD 2 connects to 2 TD TD 3 connects to 3 RD DTR 4 connects to 6 DSR DTR 4 connects to 8 DCD SG 5 connects to 7 SG DSR 6 connects to 20 DTR DCD 1 connects to 20 DTR RTS 7 connects to 5 CTS CTS 8 connects to 4 RTS
When one pin at one end connects to a pair of pins at the other end, it is usually implemented with one short wire between the pair of pins in their connector and a long wire to the other single pin. The above designs seem to be the most popular. In another variation, SG connects to SG, TD connects to RD, RTS and CTS connect to DCD, DTR connects to DSR, and vice-versa. RS-232C cables A standard serial cable passes all of the RS-232C signals straight through. The Transmitted Data pin on one end of the cable goes to the Transmitted Data pin on the other end. This is the type of cable used to connect a modem to the &os; system, and is also appropriate for some terminals. Serial ports are the devices through which data is transferred between the &os; host computer and the terminal. This section describes the kinds of ports that exist and how they are addressed in &os;. Several kinds of serial ports exist. Before purchasing or constructing a cable, make sure it will fit the ports on the terminal and on the &os; system. Most terminals have DB-25 ports. Personal computers may have DB-25 or DB-9 ports. A multiport serial card may have RJ-12 or RJ-45 ports. See the documentation that accompanied the hardware for specifications on the kind of port or visually verify the type of port. In &os;, each serial port is accessed through an entry in /dev. There are two different kinds of entries: Call-in ports are named - /dev/ttyuN + /dev/ttyuN where N is the port number, starting from zero. Generally, the call-in port is used for terminals. Call-in ports require that the serial line assert the Data Carrier Detect (DCD) signal to work correctly. Call-out ports are named - /dev/cuauN. + /dev/cuauN. Call-out ports are usually not used for terminals, but are used for modems. The call-out port can be used if the serial cable or the terminal does not support the carrier detect signal. If a terminal is connected to the first serial port(COM1), use /dev/ttyu0 to refer to the terminal. If the terminal is on the second serial port (COM2), use /dev/ttyu1, and so forth. Kernel Configuration &os; supports four serial ports by default. In the &ms-dos; world, these are known as COM1, COM2, COM3, and COM4. &os; currently supports dumb multiport serial interface cards, such as the BocaBoard 1008 and 2016, as well as more intelligent multi-port cards such as those made by Digiboard and Stallion Technologies. However, the default kernel only looks for the standard COM ports. To see if the kernel recognizes the serial ports, watch for messages while the kernel is booting, or use /sbin/dmesg to replay the kernel's boot messages. Look for messages that start with the characters uart: &prompt.root; /sbin/dmesg | grep 'uart' If the kernel does not recognize all of the serial ports, configure /boot/device.hints. When editing this file, one can comment out or completely remove lines for devices that do not exist on the system. port IO_COM1 is a substitution for port 0x3f8, IO_COM2 is 0x2f8, IO_COM3 is 0x3e8, and IO_COM4 is 0x2e8. These are fairly common port addresses for their respective serial ports and interrupts 4, 3, 5, and 9 are fairly common interrupt request lines. Regular serial ports cannot share interrupts on ISA-bus PCs. Multiport boards have on-board electronics that allow all the 16550A's on the board to share one or two interrupt request lines. Device Special Files Most devices in the kernel are accessed through device special files which are located in - /dev. The + /dev. The sio devices are accessed through the - /dev/ttyuN + /dev/ttyuN (dial-in) and - /dev/cuauN + /dev/cuauN (call-out) devices. &os; also provides initialization devices - (/dev/ttyuN.init + (/dev/ttyuN.init and - /dev/cuauN.init) + /dev/cuauN.init) and locking devices - (/dev/ttyuN.lock + (/dev/ttyuN.lock and - /dev/cuauN.lock). + /dev/cuauN.lock). The initialization devices are used to initialize communications port parameters each time a port is opened, such as crtscts for modems which use RTS/CTS signaling for flow control. The locking devices are used to lock flags on ports to prevent users or programs changing certain parameters. Refer to &man.termios.4;, &man.sio.4;, and &man.stty.1; for information on terminal settings, locking and initializing devices, and setting terminal options, respectively. Serial Port Configuration ttyu cuau The - ttyuN (or - cuauN) + ttyuN (or + cuauN) is the regular device to open for applications. When a process opens the device, it will have a default set of terminal I/O settings. These settings can be viewed with the command: &prompt.root; stty -a -f /dev/ttyu1 When the settings are changed for a device, the settings are in effect until the device is closed. When the device is reopened, it goes back to the default set. To permanently change the default set, open and adjust the settings of the initial state device. For example, to turn on mode, 8 bit communication, and flow control for ttyu5, type: &prompt.root; stty -f /dev/ttyu5.init clocal cs8 ixon ixoff rc files rc.serial System-wide initialization of serial devices is controlled by /etc/rc.d/serial. This file affects the default settings of serial devices. To prevent certain settings from being changed by an application, make adjustments to the lock state device. For example, to lock the speed of ttyu5 to 57600 bps, type: &prompt.root; stty -f /dev/ttyu5.lock 57600 Now, an application that opens ttyu5 and tries to change the speed of the port will be stuck with 57600 bps. The initial state and lock state devices should only be writable by root. Terminals terminals Terminals provide a convenient and low-cost way to access a &os; system when not at the computer's console or on a connected network. This section describes how to use terminals with &os;. The original &unix; systems did not have consoles. Instead, users logged in and ran programs through terminals that were connected to the computer's serial ports. The ability to establish a login session on a serial port still exists in nearly every &unix;-like operating system today, including &os;. By using a terminal attached to an unused serial port, a user can log in and run any text program that can normally be run on the console or in an xterm window. Many terminals can be attached to a &os; system. An older spare computer can be used as a terminal wired into a more powerful computer running &os;. This can turn what might otherwise be a single-user computer into a powerful multiple user system. &os; supports three types of terminals: Dumb terminals Dumb terminals are specialized hardware that connect to computers over serial lines. They are called dumb because they have only enough computational power to display, send, and receive text. No programs can be run on these devices. Dumb terminals connect to a computer that has all the power to run text editors, compilers, email, games, and so forth. There are hundreds of kinds of dumb terminals made by many manufacturers, and just about any kind will work with &os;. Some high-end terminals can even display graphics, but only certain software packages can take advantage of these advanced features. Dumb terminals are popular in work environments where workers do not need access to graphical applications. Computers Acting as Terminals If a dumb terminal has just enough ability to display, send, and receive text, any spare computer can be a dumb terminal. All that is needed is the proper cable and some terminal emulation software to run on the computer. This configuration can be useful. For example, if one user is busy working at the &os; system's console, another user can do some text-only work at the same time from a less powerful personal computer hooked up as a terminal to the &os; system. There are at least two utilities in the base-system of &os; that can be used to work through a serial connection: &man.cu.1; and &man.tip.1;. To connect from a client system that runs &os; to the serial connection of another system, use: - &prompt.root; cu -l serial-port-device + &prompt.root; cu -l serial-port-device Where serial-port-device is the name of a special device file denoting a serial port on the system. These device files are called - /dev/cuauN. + /dev/cuauN. The N-part of a device name is the serial port number. Note that device numbers in &os; start from zero and not one. This means that COM1 is /dev/cuau0 in &os;. Some people prefer to use other programs available through the Ports Collection, such as comms/minicom. X Terminals X terminals are the most sophisticated kind of terminal available. Instead of connecting to a serial port, they usually connect to a network like Ethernet. Instead of being relegated to text-only applications, they can display any X application. This chapter does not cover the setup, configuration, or use of X terminals. Configuration This section describes how to configure a &os; system to enable a login session on a terminal. It assumes that the kernel is configured to support the serial port to which the terminal is connected and that the terminal is connected. The init process is responsible for all process control and initialization at system startup. One of the tasks performed by init is to read /etc/ttys and start a getty process on the available terminals. The getty process is responsible for reading a login name and starting the login program. To configure terminals for a &os; system, the following steps should be taken as root: Add a line to /etc/ttys for the entry in /dev for the serial port if it is not already there. Specify that /usr/libexec/getty be run on the port, and specify the appropriate getty type from /etc/gettytab. Specify the default terminal type. Set the port to on. Specify whether the port should be secure. Force init to reread /etc/ttys. As an optional step, create a custom getty type for use in step 2 by making an entry in /etc/gettytab. For more information, refer to &man.gettytab.5; and &man.getty.8;. Adding an Entry to <filename>/etc/ttys</filename> /etc/ttys lists all of the ports on the &os; system which allow logins. For example, the first virtual console, ttyv0, has an entry in this file, allowing logins on the console. This file also contains entries for the other virtual consoles, serial ports, and pseudo-ttys. For a hardwired terminal, list the serial port's /dev entry without the /dev part. For example, /dev/ttyv0 would be listed as ttyv0. A default &os; install includes an /etc/ttys with support for the first four serial ports: ttyu0 through ttyu3. When attaching a terminal to one of those ports, this file does not need to be edited. Adding Terminal Entries to <filename>/etc/ttys</filename> This example configures two terminals: a Wyse-50 and an old 286 IBM PC running Procomm terminal software emulating a VT-100 terminal. The Wyse is connected to the second serial port and the 286 to the sixth serial port on a multiport serial card. The corresponding entries in /etc/ttys would look like this: ttyu1 "/usr/libexec/getty std.38400" wy50 on insecure ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure The first field normally specifies the name of the terminal special file as it is found in /dev. The second field is the command to execute for this line, which is usually &man.getty.8;. getty initializes and opens the line, sets the speed, prompts for a user name, and then executes &man.login.1;. The getty program accepts one (optional) parameter on its command line, the getty type. A getty type configures characteristics on the terminal line, like bps rate and parity. getty reads these characteristics from /etc/gettytab. /etc/gettytab contains many entries for terminal lines, both old and new. In almost all cases, the entries that start with the text std will work for hardwired terminals as these entries ignore parity. There is a std entry for each bps rate from 110 to 115200. &man.gettytab.5; provides more information. When setting the getty type in /etc/ttys, make sure that the communications settings on the terminal match. For this example, the Wyse-50 uses no parity and connects at 38400 bps. The 286 PC uses no parity and connects at 19200 bps. The third field is the type of terminal usually connected to that terminal line. For dial-up ports, unknown or dialup is typically used since users may dial up with practically any type of terminal or software. Since the terminal type does not change for hardwired terminals, a real terminal type from &man.termcap.5; can be used in this field. For this example, the Wyse-50 uses the real terminal type while the 286 PC running Procomm will be set to emulate at VT-100. The fourth field specifies if the port should be enabled. If set to on, the init process will start the program in the second field, getty. If this field is set to off, there will be no getty, and hence no logins on the port. The final field is used to specify whether the port is secure. Marking a port as secure means that it is trusted enough to allow root, or any account with a UID of 0, to login from that port. Insecure ports do not allow root logins. On an insecure port, users must login from unprivileged accounts and then use &man.su.1; or a similar mechanism to gain superuser privileges. It is highly recommended to use insecure, even for terminals that are behind locked doors. It is quite easy to login and use su when superuser privileges are needed. Force <command>init</command> to Reread <filename>/etc/ttys</filename> After making any changes to /etc/ttys, send a SIGHUP (hangup) signal to the init process to force it to re-read its configuration file: &prompt.root; kill -HUP 1 init is always the first process run on a system, therefore it will always have a process ID of 1. If everything is set up correctly, all cables are in place, and the terminals are powered up, then a getty process should be running on each terminal and login prompts should be available on each terminal. Troubleshooting the Connection Even with the most meticulous attention to detail, something could still go wrong while setting up a terminal. Here is a list of common symptoms and some suggested fixes. If no login prompt appears, make sure the terminal is plugged in and powered up. If it is a personal computer acting as a terminal, make sure it is running terminal emulation software on the correct serial port. Make sure the cable is connected firmly to both the terminal and the &os; computer. Make sure it is the right kind of cable. Make sure the terminal and &os; agree on the bps rate and parity settings. For a video display terminal, make sure the contrast and brightness controls are turned up. If it is a printing terminal, make sure paper and ink are in good supply. Make sure that a getty process is running and serving the terminal. For example, to get a list of running getty processes with ps, type: &prompt.root; ps -axww|grep getty There should be an entry for the terminal. For example, the following display shows that a getty is running on the second serial port, ttyu1, and is using the std.38400 entry in /etc/gettytab: 22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyu1 If no getty process is running, make sure the port is enabled in /etc/ttys. Remember to run kill -HUP 1 after modifying /etc/ttys. If the getty process is running but the terminal still does not display a login prompt, or if it displays a prompt but will not accept typed input, the terminal or cable may not support hardware handshaking. Try changing the entry in /etc/ttys from std.38400 to 3wire.38400, then run kill -HUP 1 after modifying /etc/ttys. The 3wire entry is similar to std, but ignores hardware handshaking. The baud rate may need to be reduced or software flow control enabled when using 3wire to prevent buffer overflows. If garbage appears instead of a login prompt, make sure the terminal and &os; agree on the bps rate and parity settings. Check the getty processes to make sure the correct getty type is in use. If not, edit /etc/ttys and run kill -HUP 1. If characters appear doubled and the password appears when typed, switch the terminal, or the terminal emulation software, from half duplex or local echo to full duplex. Dial-in Service dial-in service Configuring a &os; system for dial-in service is similar to connecting terminals except that modems are used instead of terminal devices. &os; supports both external and internal modems. External modems are more convenient for dial-up because they often can be semi-permanently configured via parameters stored in non-volatile RAM and they usually provide lighted indicators that display the state of important RS-232 signals, indicating whether the modem is operating properly. Internal modems usually lack non-volatile RAM, so their configuration may be limited to setting DIP switches. If the internal modem has any signal indicator lights, they are difficult to view when the system's cover is in place. modem When using an external modem, a proper cable is needed. A standard RS-232C serial cable should suffice as long as all of the normal signals are wired: Signal Names Acronyms Names RD Received Data TD Transmitted Data DTR Data Terminal Ready DSR Data Set Ready DCD Data Carrier Detect (RS-232's Received Line Signal Detector) SG Signal Ground RTS Request to Send CTS Clear to Send
&os; needs the RTS and CTS signals for flow control at speeds above 2400 bps, the CD signal to detect when a call has been answered or the line has been hung up, and the DTR signal to reset the modem after a session is complete. Some cables are wired without all of the needed signals, so if a login session does not go away when the line hangs up, there may be a problem with the cable. Like other &unix;-like operating systems, &os; uses the hardware signals to find out when a call has been answered or a line has been hung up and to hangup and reset the modem after a call. &os; avoids sending commands to the modem or watching for status reports from the modem. Serial Interface Considerations &os; supports the NS8250-, NS16450-, NS16550-, and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and 16450 devices have single-character buffers. The 16550 device provides a 16-character buffer, which allows for better system performance. Bugs in plain 16550's prevent the use of the 16-character buffer, so use 16550A's if possible. Because single-character-buffer devices require more work by the operating system than the 16-character-buffer devices, 16550A-based serial interface cards are preferred. If the system has many active serial ports or will have a heavy load, 16550A-based cards are better for low-error-rate communications. Quick Overview getty As with terminals, init spawns a getty process for each configured serial port for dial-in connections. For example, if a modem is attached to /dev/ttyu0, ps ax might show this: 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyu0 When a user dials the modem's line and the modems connect, the Carrier Detect (CD) line is reported by the modem. The kernel notices that the carrier has been detected and instructs getty to open the port. getty sends a login: prompt at the specified initial line speed. getty watches to see if legitimate characters are received, and, in a typical configuration, if it finds junk (probably due to the modem's connection speed being different than getty's speed), getty tries adjusting the line speeds until it receives reasonable characters. /usr/bin/login After the user enters their login name, getty executes /usr/bin/login, which completes the login by asking for the user's password and then starting the user's shell. Configuration Files There are three system configuration files in /etc that probably need to be edited to allow dial-up access to the &os; system. /etc/gettytab contains configuration information for the /usr/libexec/getty daemon. /etc/ttys holds information that tells init which ttys should have getty processes running on them. Lastly, port initialization commands can be placed in /etc/rc.d/serial. There are two schools of thought regarding dial-up modems on &unix;. One group likes to configure their modems and systems so that no matter at what speed a remote user dials in, the local computer-to-modem RS-232 interface runs at a locked speed. The benefit of this configuration is that the remote user always sees a system login prompt immediately. The downside is that the system does not know what a user's true data rate is, so full-screen programs like Emacs will not adjust their screen-painting methods to make their response better for slower connections. The other group configures their modems' RS-232 interface to vary its speed based on the remote user's connection speed. For example, V.32bis (14.4 Kbps) connections to the modem might make the modem run its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the modem's RS-232 interface run at 2400 bps. Because getty does not understand any particular modem's connection speed reporting, getty gives a login: message at an initial speed and watches the characters that come back in response. If the user sees junk, it is assumed that they know they should press Enter until they see a recognizable prompt. If the data rates do not match, getty sees anything the user types as junk, tries going to the next speed and gives the login: prompt again. This procedure normally only takes a keystroke or two before the user sees a good prompt. This login sequence does not look as clean as the locked-speed method, but a user on a low-speed connection should receive better interactive response from full-screen programs. This section will try to give balanced configuration information, but is biased towards having the modem's data rate follow the connection rate. <filename>/etc/gettytab</filename> /etc/gettytab /etc/gettytab is a &man.termcap.5;-style file of configuration information for &man.getty.8;. Refer to &man.gettytab.5; for complete information on the format of the file and the list of capabilities. When locking a modem's data communications rate at a particular speed, no changes to /etc/gettytab should be needed. However, a change is needed to create a matching-speed configuration. Create an entry in /etc/gettytab to give getty information about the speeds to use for the modem. For a 2400 bps modem, use the existing D2400 entry. # # Fast dialup terminals, 2400/1200/300 rotary (can start either way) # D2400|d2400|Fast-Dial-2400:\ :nx=D1200:tc=2400-baud: 3|D1200|Fast-Dial-1200:\ :nx=D300:tc=1200-baud: 5|D300|Fast-Dial-300:\ :nx=D2400:tc=300-baud: For a higher speed modem, add an entry in /etc/gettytab. This entry is for a 14.4 Kbps modem with a top interface speed of 19.2 Kbps: # # Additions for a V.32bis Modem # um|V300|High Speed Modem at 300,8-bit:\ :nx=V19200:tc=std.300: un|V1200|High Speed Modem at 1200,8-bit:\ :nx=V300:tc=std.1200: uo|V2400|High Speed Modem at 2400,8-bit:\ :nx=V1200:tc=std.2400: up|V9600|High Speed Modem at 9600,8-bit:\ :nx=V2400:tc=std.9600: uq|V19200|High Speed Modem at 19200,8-bit:\ :nx=V9600:tc=std.19200: This will result in 8-bit, no parity connections. The example above starts the communications rate at 19.2 Kbps (for a V.32bis connection), then cycles through 9600 bps (for V.32), 2400 bps, 1200 bps, 300 bps, and back to 19.2 Kbps. Communications rate cycling is implemented with the nx= (next table) capability. Each of the lines uses a tc= (table continuation) entry to pick up the rest of the standard settings for a particular data rate. For a 28.8 Kbps modem or to take advantage of compression on a 14.4 Kbps modem, use a higher communications rate than 19.2 Kbps. Here is an example of a gettytab entry starting a 57.6 Kbps: # # Additions for a V.32bis or V.34 Modem # Starting at 57.6 Kbps # vm|VH300|Very High Speed Modem at 300,8-bit:\ :nx=VH57600:tc=std.300: vn|VH1200|Very High Speed Modem at 1200,8-bit:\ :nx=VH300:tc=std.1200: vo|VH2400|Very High Speed Modem at 2400,8-bit:\ :nx=VH1200:tc=std.2400: vp|VH9600|Very High Speed Modem at 9600,8-bit:\ :nx=VH2400:tc=std.9600: vq|VH57600|Very High Speed Modem at 57600,8-bit:\ :nx=VH9600:tc=std.57600: For a slow CPU or a heavily loaded system without 16550A-based serial ports, there may be sio silo errors at 57.6 Kbps. <filename>/etc/ttys</filename> /etc/ttys Configuration of /etc/ttys is covered in . Configuration for modems is similar, but a different argument is passed to getty and a different terminal type is specified. The general format for both locked-speed and matching-speed configurations is: ttyu0 "/usr/libexec/getty xxx" dialup on The first item in the above line is the device special file for this entry. ttyu0 indicates that getty is watching /dev/ttyu0. The xxx will replace the initial gettytab capability and is the process init will run on the device. The third item, dialup, is the default terminal type. The fourth parameter, on, indicates to init that the line is operational. There can be a fifth parameter, secure, but it should only be used for terminals which are physically secure, such as the system console. The default terminal type, dialup in this example, may depend on local preferences. dialup is the traditional default terminal type on dial-up lines so that users may customize their login scripts to notice when the terminal is dialup and automatically adjust their terminal type. Setting vt102 as the default terminal type allows users to use VT102 emulation on their remote systems. After editing /etc/ttys, send the init process a HUP signal to re-read the file: &prompt.root; kill -HUP 1 Wait until the modem is properly configured and connected before signaling init. For a locked-speed configuration, the ttys entry needs to have a fixed-speed entry provided to getty. For a modem whose port speed is locked at 19.2 Kbps, the ttys entry might look like this: ttyu0 "/usr/libexec/getty std.19200" dialup on If the modem is locked at a different data rate, substitute the appropriate value for - std.speed + std.speed instead of std.19200. Make sure to use a valid type listed in /etc/gettytab. In a matching-speed configuration, the ttys entry needs to reference the appropriate beginning auto-baud entry in /etc/gettytab. For example, for the above suggested entry for a matching-speed modem that starts at 19.2 Kbps, the /etc/ttys entry might look like this: ttyu0 "/usr/libexec/getty V19200" dialup on <filename>/etc/rc.d/serial</filename> rc files rc.serial High-speed modems, like V.32, V.32bis, and V.34 modems, need to use hardware (RTS/CTS) flow control. stty can be used to set the hardware flow control flag in the &os; kernel for the modem ports. For example, to set the termios flag crtscts on COM2's dial-in and dial-out initialization devices, the following lines could be added to /etc/rc.d/serial: # Serial port initial configuration stty -f /dev/ttyu1.init crtscts stty -f /dev/cuau1.init crtscts Modem Settings For a modem whose parameters may be permanently set in non-volatile RAM, a terminal program such as tip can be used to set the parameters. Connect to the modem using the same communications speed as the initial speed getty will use and configure the modem's non-volatile RAM to match these requirements: CD asserted when connected. DTR asserted for operation and dropping DTR hangs up the line and resets the modem. CTS transmitted data flow control. Disable XON/XOFF flow control. RTS received data flow control. Quiet mode (no result codes). No command echo. Read the documentation for the modem to find out which commands and/or DIP switch settings are needed. For example, to set the above parameters on a &usrobotics; &sportster; 14,400 external modem, give these commands to the modem: ATZ AT&C1&D2&H1&I0&R2&W Other settings can be adjusted in the modem, such as whether it will use V.42bis and/or MNP5 compression. The &usrobotics; &sportster; 14,400 external modem also has some DIP switches that need to be set. Other modems, may need these settings: Switch 1: UP — DTR Normal Switch 2: N/A (Verbal Result Codes/Numeric Result Codes) Switch 3: UP — Suppress Result Codes Switch 4: DOWN — No echo, offline commands Switch 5: UP — Auto Answer Switch 6: UP — Carrier Detect Normal Switch 7: UP — Load NVRAM Defaults Switch 8: N/A (Smart Mode/Dumb Mode) Result codes should be disabled/suppressed for dial-up modems to avoid problems that can occur if getty mistakenly gives a login: prompt to a modem that is in command mode and the modem echoes the command or returns a result code. This sequence can result in an extended, silly conversation between getty and the modem. For a locked-speed configuration, configure the modem to maintain a constant modem-to-computer data rate independent of the communications rate. On a &usrobotics; &sportster; 14,400 external modem, these commands will lock the modem-to-computer data rate at the speed used to issue the commands: ATZ AT&B1&W For a variable-speed configuration, configure the modem to adjust its serial port data rate to match the incoming call rate. On a &usrobotics; &sportster; 14,400 external modem, these commands will lock the modem's error-corrected data rate to the speed used to issue the commands, while allowing the serial port rate to vary for non-error-corrected connections: ATZ AT&B2&W Checking the Modem's Configuration Most high-speed modems provide commands to view the modem's current operating parameters in a somewhat human-readable fashion. On the &usrobotics; &sportster; 14,400 external modem, ATI5 displays the settings that are stored in the non-volatile RAM. To see the true operating parameters of the modem, as influenced by the modem's DIP switch settings, use ATZ and then ATI4. For a different brand of modem, check the modem's manual to see how to double-check the modem's configuration parameters. Troubleshooting Here are a few steps for troubleshooting a dial-up modem on a &os; system. Hook up the modem to the &os; system, boot the system, and, if the modem has status indication lights, watch to see whether the modem's DTR indicator lights when the login: prompt appears on the system's console. If it lights up, that should mean that &os; has started a getty process on the appropriate communications port and is waiting for the modem to accept a call. If the DTR indicator does not light, login to the &os; system through the console and type ps ax to see if &os; is trying to run a getty process on the correct port: 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyu0 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyu1 If something like this is displayed instead: 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyu0 and the modem has not accepted a call yet, this means that getty has completed its open on the communications port. This could indicate a problem with the cabling or a misconfigured modem, because getty should not be able to open the communications port until carrier detect has been asserted by the modem. If no getty processes are waiting to open the desired - ttyuN + ttyuN port, double-check the entries in /etc/ttys to see if there are any mistakes. Also, check /var/log/messages to see if there are any log messages from init or getty. If there are any messages, triple-check /etc/ttys and /etc/gettytab, as well as the appropriate device special files, /dev/ttyuN, for any mistakes, missing entries, or missing device special files. Next, try dialing into the system. Be sure to use 8 bits, no parity, and 1 stop bit on the remote system. If a prompt does not appear right away, or the prompt shows garbage, try pressing Enter about once per second. If there is still no login: prompt after a while, try sending a BREAK. When using a high-speed modem, try dialing again after locking the dialing modem's interface speed. If there is still no login: prompt, check /etc/gettytab again and double-check that: The initial capability name specified in the entry in /etc/ttys matches the name of a capability in /etc/gettytab. Each nx= entry matches another gettytab capability name. Each tc= entry matches another gettytab capability name. If the modem on the &os; system will not answer, make sure that the modem is configured to answer the phone when DTR is asserted. If the modem seems to be configured correctly, verify that the DTR line is asserted by checking the modem's indicator lights. If it still does not work, take a break and come back to it later. If it still does not work, try sending an email message to the &a.questions; describing the modem and the problem. Dial-out Service dial-out service The following are tips for getting the host to connect over the modem to another computer. This is appropriate for establishing a terminal session with a remote host. This kind of connection can be helpful to get a file on the Internet if there are problems using PPP. If PPP is not working, use the terminal session to FTP the needed file. Then use zmodem to transfer it to the machine. Using a Stock Hayes Modem A generic Hayes dialer is built into tip. Use at=hayes in /etc/remote. The Hayes driver is not smart enough to recognize some of the advanced features of newer modems messages like BUSY, NO DIALTONE, or CONNECT 115200. Turn those messages off when using tip with ATX0&W. The dial timeout for tip is 60 seconds. The modem should use something less, or else tip will think there is a communication problem. Try ATS7=45&W. Using <literal>AT</literal> Commands /etc/remote Create a direct entry in /etc/remote. For example, if the modem is hooked up to the first serial port, /dev/cuau0, use the following line: cuau0:dv=/dev/cuau0:br#19200:pa=none Use the highest bps rate the modem supports in the br capability. Then, type tip cuau0 to connect to the modem. Or, use cu as root with the following command: - &prompt.root; cu -lline -sspeed + &prompt.root; cu -lline -sspeed line is the serial port, such as /dev/cuau0, and speed is the speed, such as 57600. When finished entering the AT commands, type ~. to exit. The <literal>@</literal> Sign Does Not Work The @ sign in the phone number capability tells tip to look in /etc/phones for a phone number. But, the @ sign is also a special character in capability files like /etc/remote, so it needs to be escaped with a backslash: pn=\@ Dialing from the Command Line Put a generic entry in /etc/remote. For example: tip115200|Dial any phone number at 115200 bps:\ :dv=/dev/cuau0:br#115200:at=hayes:pa=none:du: tip57600|Dial any phone number at 57600 bps:\ :dv=/dev/cuau0:br#57600:at=hayes:pa=none:du: This should now work: &prompt.root; tip -115200 5551234 Users who prefer cu over tip, can use a generic cu entry: cu115200|Use cu to dial any number at 115200bps:\ :dv=/dev/cuau1:br#57600:at=hayes:pa=none:du: and type: &prompt.root; cu 5551234 -s 115200 Setting the <acronym>bps</acronym> Rate Put in an entry for tip1200 or cu1200, but go ahead and use whatever bps rate is appropriate with the br capability. tip thinks a good default is 1200 bps which is why it looks for a tip1200 entry. 1200 bps does not have to be used, though. Accessing a Number of Hosts Through a Terminal Server Rather than waiting until connected and typing - CONNECT host + CONNECT host each time, use tip's cm capability. For example, these entries in /etc/remote will let you type tip pain or tip muffin to connect to the hosts pain or muffin, and tip deep13 to connect to the terminal server. pain|pain.deep13.com|Forrester's machine:\ :cm=CONNECT pain\n:tc=deep13: muffin|muffin.deep13.com|Frank's machine:\ :cm=CONNECT muffin\n:tc=deep13: deep13:Gizmonics Institute terminal server:\ :dv=/dev/cuau2:br#38400:at=hayes:du:pa=none:pn=5551234: Using More Than One Line with <command>tip</command> This is often a problem where a university has several modem lines and several thousand students trying to use them. Make an entry in /etc/remote and use @ for the pn capability: big-university:\ :pn=\@:tc=dialout dialout:\ :dv=/dev/cuau3:br#9600:at=courier:du:pa=none: Then, list the phone numbers in /etc/phones: big-university 5551111 big-university 5551112 big-university 5551113 big-university 5551114 tip will try each number in the listed order, then give up. To keep retrying, run tip in a while loop. Using the Force Character Ctrl P is the default force character, used to tell tip that the next character is literal data. The force character can be set to any other character with the ~s escape, which means set a variable. Type - ~sforce=single-char + ~sforce=single-char followed by a newline. single-char is any single character. If single-char is left out, then the force character is the null character, which is accessed by typing Ctrl2 or CtrlSpace . A pretty good value for single-char is Shift Ctrl 6 , which is only used on some terminal servers. To change the force character, specify the following in ~/.tiprc: force=single-char Upper Case Characters This happens when Ctrl A is pressed, which is tip's raise character, specially designed for people with broken caps-lock keys. Use ~s to set raisechar to something reasonable. It can be set to be the same as the force character, if neither feature is used. Here is a sample ~/.tiprc for Emacs users who need to type Ctrl 2 and Ctrl A : force=^^ raisechar=^^ The ^^ is ShiftCtrl6 . File Transfers with <command>tip</command> When talking to another &unix;-like operating system, files can be sent and received using ~p (put) and ~t (take). These commands run cat and echo on the remote system to accept and send files. The syntax is: ~p local-file remote-file ~t remote-file local-file There is no error checking, so another protocol, like zmodem, should probably be used. Using <application>zmodem</application> with <command>tip</command>? To receive files, start the sending program on the remote end. Then, type ~C rz to begin receiving them locally. To send files, start the receiving program on the remote end. Then, type ~C sz - files to send them to the + files to send them to the remote system. Setting Up the Serial Console serial console &os; has the ability to boot a system with a dumb terminal on a serial port as a console. This configuration is useful for system administrators who wish to install &os; on machines that have no keyboard or monitor attached, and developers who want to debug the kernel or device drivers. As described in , &os; employs a three stage bootstrap. The first two stages are in the boot block code which is stored at the beginning of the &os; slice on the boot disk. The boot block then loads and runs the boot loader as the third stage code. In order to set up booting from a serial console, the boot block code, the boot loader code, and the kernel need to be configured. Quick Serial Console Configuration This section assumes the default setup and provides a fast overview of setting up the serial console. Connect the serial cable to COM1 and the controlling terminal. To see all the boot messages on the serial console, issue the following command as the superuser: &prompt.root; echo 'console="comconsole"' >> /boot/loader.conf Edit /etc/ttys and change off to on and dialup to vt100 for the ttyu0 entry. Otherwise, a password will not be required to connect via the serial console, resulting in a potential security hole. Reboot the system to see if the changes took effect. If a different configuration is required, see the next section for a more in-depth configuration explanation. In-Depth Serial Console Configuration Prepare a serial cable. null-modem cable Use either a null-modem cable or a standard serial cable and a null-modem adapter. See for a discussion on serial cables. Unplug the keyboard. Many PC systems probe for the keyboard during the Power-On Self-Test (POST) and will generate an error if the keyboard is not detected. Some machines will refuse to boot until the keyboard is plugged in. If the computer complains about the error, but boots anyway, no further configuration is needed. If the computer refuses to boot without a keyboard attached, the BIOS needs to be configured so that it ignores this error (if it can). Consult the motherboard's manual for details on how to do this. Try setting the keyboard to Not installed in the BIOS. The keyboard can still be used as this setting just tells the BIOS not to probe for a keyboard at power-on. The BIOS should not complain if the keyboard is absent. You can leave the keyboard plugged in even with this flag set to Not installed and the keyboard will still work. If the above option is not present in the BIOS, look for an Halt on Error option instead. Setting this to All but Keyboard or even to No Errors, will have the same effect. If the system has a &ps2; mouse, chances are good that both the mouse and keyboard need to be unplugged. This is because &ps2; mice share some hardware with the keyboard and leaving the mouse plugged in can fool the keyboard probe into thinking the keyboard is still there. Plug a dumb terminal into COM1 (sio0). If a dumb terminal is not available, use an old computer with a modem program, or the serial port on another &unix; box. If there is no COM1 (sio0), get one. At this time, there is no way to select a port other than COM1 for the boot blocks without recompiling the boot blocks. If COM1 is being used by another device, temporarily remove that device and install a new boot block and kernel once &os; is up and running. Make sure the configuration file of the custom kernel has appropriate flags set for COM1 (sio0). Relevant flags are: 0x10 Enables console support for this unit. The other console flags are ignored unless this is set. Currently, at most one unit can have console support. The first one, in config file order, with this flag set is preferred. This option alone will not make the serial port the console. Set the following flag or use as described below, together with this flag. 0x20 Forces this unit to be the console, unless there is another higher priority console, regardless of as discussed below. The flag 0x20 must be used together with the flag. 0x40 Reserves this unit (in conjunction with 0x10) and makes the unit unavailable for normal access. This flag should not be set to the serial port to use as the serial console. The only use of this flag is to designate the unit for kernel remote debugging. See The Developer's Handbook for more information on remote debugging. Here is an example setting: device sio0 flags 0x10 Refer to &man.sio.4; for more details. If the flags were not set, run UserConfig on a different console or recompile the kernel. Create boot.config in the root directory of the a partition on the boot drive. This file instructs the boot block code how to boot the system. In order to activate the serial console, one or more of the following options are needed. When using multiple options, include them all on the same line: Toggles between the internal and serial consoles. Use this to switch console devices. For instance, to boot from the internal (video) console, use to direct the boot loader and the kernel to use the serial port as its console device. Alternatively, to boot from the serial port, use to tell the boot loader and the kernel to use the video display as the console instead. Toggles between the single and dual console configurations. In the single configuration, the console will be either the internal console (video display) or the serial port, depending on the state of . In the dual console configuration, both the video display and the serial port will become the console at the same time, regardless of the state of . However, the dual console configuration takes effect only while the boot block is running. Once the boot loader gets control, the console specified by becomes the only console. Makes the boot block probe the keyboard. If no keyboard is found, the and options are automatically set. Due to space constraints in the current version of the boot blocks, is capable of detecting extended keyboards only. Keyboards with less than 101 keys and without F11 and F12 keys may not be detected. Keyboards on some laptops may not be properly found because of this limitation. If this is the case, do not use . Unfortunately there is no workaround for this problem. Use either to select the console automatically, or to activate the serial console. Other options are described in &man.boot.8;. The options, except for , are passed to the boot loader. The boot loader will determine whether the internal video or the serial port should become the console by examining the state of . This means that if is specified but is not specified in /boot.config, the serial port can be used as the console only during the boot block as the boot loader will use the internal video display as the console. Boot the machine. When &os; starts, the boot blocks echo the contents of /boot.config to the console. For example: /boot.config: -P Keyboard: no The second line appears only if is in /boot.config and indicates the presence or absence of the keyboard. These messages go to either the serial or internal console, or both, depending on the option in /boot.config. Options Message goes to none internal console serial console serial and internal consoles serial and internal consoles , keyboard present internal console , keyboard absent serial console After the message, there will be a small pause before the boot blocks continue loading the boot loader and before any further messages are printed to the console. Under normal circumstances, there is no need to interrupt the boot blocks, but one can do so in order to make sure things are set up correctly. Press any key, other than Enter, at the console to interrupt the boot process. The boot blocks will then prompt for further action: >> FreeBSD/i386 BOOT Default: 0:ad(0,a)/boot/loader boot: Verify that the above message appears on either the serial or internal console, or both, according to the options in /boot.config. If the message appears in the correct console, press Enter to continue the boot process. If there is no prompt on the serial terminal, something is wrong with the settings. Enter then Enter or Return to tell the boot block (and then the boot loader and the kernel) to choose the serial port for the console. Once the system is up, go back and check what went wrong. During the third stage of the boot process, one can still switch between the internal console and the serial console by setting appropriate environment variables in the boot loader. See for more information. Summary The following tables provide a summary of the various settings discussed in this section. Case 1: Set the Flags to 0x10 for <filename>sio0</filename> Options in /boot.config Console during boot blocks Console during boot loader Console in kernel nothing internal internal internal serial serial serial serial and internal internal internal serial and internal serial serial , keyboard present internal internal internal , keyboard absent serial and internal serial serial
Case 2: Set the Flags to 0x30 for <filename>sio0</filename> Options in /boot.config Console during boot blocks Console during boot loader Console in kernel nothing internal internal serial serial serial serial serial and internal internal serial serial and internal serial serial , keyboard present internal internal serial , keyboard absent serial and internal serial serial
Tips for the Serial Console Setting a Faster Serial Port Speed By default, the serial port settings are 9600 baud, 8 bits, no parity, and 1 stop bit. To change the default console speed, the following options are available: Recompile the boot blocks with BOOT_COMCONSOLE_SPEED set to the new console speed. See for detailed instructions about building and installing new boot blocks. If the serial console is configured in some other way than by booting with , or if the serial console used by the kernel is different from the one used by the boot blocks, add the following option to a custom kernel configuration file and compile a new kernel: options CONSPEED=19200 Add the boot option to /boot.config. See &man.boot.8; for a description of how to add options to /boot.config and a list of the supported options. Enable comconsole_speed in /boot/loader.conf. This option depends on console, boot_serial, and boot_multicons being set in /boot/loader.conf too. An example of using comconsole_speed to change the serial console speed is: boot_multicons="YES" boot_serial="YES" comconsole_speed="115200" console="comconsole,vidconsole" Using a Serial Port Other Than <filename>sio0</filename> for the Console Using a port other than sio0 as the console requires the boot blocks, the boot loader, and the kernel to be recompiled as follows. Get the kernel source as described in . Edit /etc/make.conf and set BOOT_COMCONSOLE_PORT to the address of the port to use: 0x3F8, 0x2F8, 0x3E8 or 0x2E8. Only sio0 through sio3 (COM1 through COM4) can be used as multiport serial cards will not work. No interrupt setting is needed. Create a custom kernel configuration file and add appropriate flags for the serial port to use. For example, to make sio1 (COM2) the console: device sio1 flags 0x10 or device sio1 flags 0x30 The console flags for the other serial ports should not be set. Recompile and install the boot blocks and the boot loader: &prompt.root; cd /sys/boot &prompt.root; make clean &prompt.root; make &prompt.root; make install Rebuild and install the kernel. Write the boot blocks to the boot disk with &man.bsdlabel.8; and boot from the new kernel. Entering the DDB Debugger from the Serial Line To drop into the kernel debugger from the serial console, compile a custom kernel with the following options. Note that while this is useful for remote diagnostics, it is also dangerous if a spurious BREAK is generated on the serial port. options BREAK_TO_DEBUGGER options DDB Getting a Login Prompt on the Serial Console While this is not required, it is possible to get a login prompt over the serial line. First, make sure that the boot messages are displayed and it is possible to enter the kernel debugging session through the serial console. Open /etc/ttys with a text editor and locate the lines: ttyu0 "/usr/libexec/getty std.9600" unknown off secure ttyu1 "/usr/libexec/getty std.9600" unknown off secure ttyu2 "/usr/libexec/getty std.9600" unknown off secure ttyu3 "/usr/libexec/getty std.9600" unknown off secure ttyu0 through ttyu3 correspond to COM1 through COM4. Change off to on for the desired port. If the speed of the serial port has been changed, change std.9600 to match the new setting. The terminal type can also be changed from unknown to the actual type of the serial terminal. After editing the file, type kill -HUP 1 to make this change take effect. Changing Console from the Boot Loader Previous sections described how to set up the serial console by tweaking the boot block. This section shows how to specify the console by entering some commands and environment variables in the boot loader. As the boot loader is invoked at the third stage of the boot process, the settings in the boot loader will override the settings in the boot block. Setting Up the Serial Console The boot loader and the kernel to use the serial console can be specified by writing one line in /boot/loader.conf: console="comconsole" This will take effect regardless of the settings in the boot block discussed in the previous section. This line should be the first line of /boot/loader.conf so as to see boot messages on the serial console as early as possible. Likewise, to specify the internal console: console="vidconsole" If the boot loader environment variable console is not set, the boot loader, and subsequently the kernel, will use whichever console is indicated by in the boot block. The console can be specified in /boot/loader.conf.local or in /boot/loader.conf. See &man.loader.conf.5; for more information. At the moment, the boot loader has no option equivalent to in the boot block, and there is no provision to automatically select the internal console and the serial console based on the presence of the keyboard. Using a Serial Port Other Than <filename>sio0</filename> for the Console The boot loader needs to be compiled in order to use a serial port other than sio0 for the serial console. Follow the procedure described in . Caveats While most systems will boot without a keyboard, quite a few will not boot without a graphics adapter. Machines with AMI BIOSes can be configured to boot with no graphics adapter installed by changing the graphics adapter setting in the CMOS configuration to Not installed. However, many machines do not support this option and will refuse to boot if there is no display hardware in the system. With these machines, leave some kind of graphics card plugged in, even if it is just a junky mono board. A monitor does not need to be attached. One might also try installing an AMI BIOS.