DragonFly BSD

serial communications

Chapter 18 Serial Communications

*Reorganized, and parts rewritten by Ivailo Mladenov. *


UNIX® has always had support for serial communications. In fact, 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 will cover some of the ways in which DragonFly uses serial communications.

After reading this chapter, you will know:

Before reading this chapter, you should:

18.1 Introduction

18.1.1 Terminology

bps:: Bits per Second -- the rate at which data is transmitted;

DTE:: Data Terminal Equipment -- for example, your computer;

DCE:: Data Communications Equipment -- your modem;

RS-232:: EIA standard for hardware serial communications.

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 (bits per second) is the correct term to use (at least it does not seem to bother the curmudgeons quite as much).

18.1.2 Cables and Ports

To connect a modem or terminal to your DragonFly system, you will need a serial port on your computer and the proper cable to connect to your serial device. If you are already familiar with your hardware and the cable it requires, you can safely skip this section. Cables

There are several different kinds of serial cables. The two most common types for our purposes are null-modem cables and standard (straight) RS-232 cables. The documentation for your hardware should describe the type of cable required. Null-modem Cables

A null-modem cable passes some signals, such as signal ground, straight through, but switches other signals. For example, the send data pin on one end goes to the receive data pin on the other end.

If you like making your own cables, you can construct a null-modem cable for use with terminals. This table shows the RS-232C signal names and the pin numbers on a DB-25 connector.

Signal Pin # Pin # Signal
SG 7 connects to 7 SG
TxD 2 connects to 3 RxD
RxD 3 connects to 2 TxD
RTS 4 connects to 5 CTS
CTS 5 connects to 4 RTS
DTR 20 connects to 6 DSR
DSR 6 connects to 20 DTR

Note: Connect Data Set Ready (DSR) and Data Carrier Detect (DCD) internally in the connector hood, and then to Data Terminal Ready (DTR) in the remote hood. Standard RS-232C Cables

A standard serial cable passes all the RS-232C signals straight-through. That is, the send data pin on one end of the cable goes to the send data pin on the other end. This is the type of cable to use to connect a modem to your DragonFly system, and is also appropriate for some terminals. Ports

Serial ports are the devices through which data is transferred between the DragonFly host computer and the terminal. This section describes the kinds of ports that exist and how they are addressed in DragonFly. Kinds of Ports

Several kinds of serial ports exist. Before you purchase or construct a cable, you need to make sure it will fit the ports on your terminal and on the DragonFly system.

Most terminals will have DB25 ports. Personal computers, including PCs running DragonFly, will have DB25 or DB9 ports. If you have a multiport serial card for your PC, you may have RJ-12 or RJ-45 ports.

See the documentation that accompanied the hardware for specifications on the kind of port in use. A visual inspection of the port often works too. Port Names

In DragonFly, you access each serial port through an entry in the /dev directory. There are two different kinds of entries:

If you have connected a terminal to the first serial port (COM1 in MS-DOS®), then you will use /dev/ttyd0 to refer to the terminal. If the terminal is on the second serial port (also known as COM2), use /dev/ttyd1, and so forth.

18.1.3 Kernel Configuration

DragonFly supports four serial ports by default. In the MS-DOS world, these are known as COM1, COM2, COM3, and COM4. DragonFly 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 your kernel recognizes any of your serial ports, watch for messages while the kernel is booting, or use the /sbin/dmesg command to replay the kernel's boot messages. In particular, look for messages that start with the characters sio.

Tip: To view just the messages that have the word sio, use the command:

# /sbin/dmesg | grep 'sio'

For example, on a system with four serial ports, these are the serial-port specific kernel boot messages:

sio0 at 0x3f8-0x3ff irq 4 on isa

sio0: type 16550A

sio1 at 0x2f8-0x2ff irq 3 on isa

sio1: type 16550A

sio2 at 0x3e8-0x3ef irq 5 on isa

sio2: type 16550A

sio3 at 0x2e8-0x2ef irq 9 on isa

sio3: type 16550A

If your kernel does not recognize all of your serial ports, you will probably need to configure a custom DragonFly kernel for your system. For detailed information on configuring your kernel, please see [kernelconfig.html Chapter 12].

The relevant device lines for your kernel configuration file would look like this:

device      sio0    at isa? port IO_COM1 irq 4

device      sio1    at isa? port IO_COM2 irq 3

device      sio2    at isa? port IO_COM3 irq 5

device      sio3    at isa? port IO_COM4 irq 9

Note: port IO_COM1 is a substitution for port 0x3f8, IO_COM2 is 0x2f8, IO_COM3 is 0x3e8, and IO_COM4 is 0x2e8, which are fairly common port addresses for their respective serial ports; interrupts 4, 3, 5, and 9 are fairly common interrupt request lines. Also note that 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).

18.1.4 Device Special Files

Most devices in the kernel are accessed through device special files, which are located in the /dev directory. The sio devices are accessed through the /dev/ttydN (dial-in) and /dev/cuaaN (call-out) devices. DragonFly also provides initialization devices (/dev/ttyidN and /dev/cuaiaN) and locking devices (/dev/ttyldN and /dev/cualaN). 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; see the manual pages termios(4), sio(4), and stty(1) for information on the terminal settings, locking and initializing devices, and setting terminal options, respectively.

18.1.5 Serial Port Configuration

The ttydN (or cuaaN) device is the regular device you will want to open for your applications. When a process opens the device, it will have a default set of terminal I/O settings. You can see these settings with the command

# stty -a -f /dev/ttyd1

When you change the settings to this device, the settings are in effect until the device is closed. When it is reopened, it goes back to the default set. To make changes to the default set, you can open and adjust the settings of the initial state device. For example, to turn on CLOCAL mode, 8 bit communication, and XON/XOFF flow control by default for ttyd5, type:

# stty -f /dev/ttyid5 clocal cs8 ixon ixoff

System-wide initialization of the serial devices is controlled in /etc/rc.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 ttyd5 to 57600 bps, type:

# stty -f /dev/ttyld5 57600

Now, an application that opens ttyd5 and tries to change the speed of the port will be stuck with 57600 bps.

Naturally, you should make the initial state and lock state devices writable only by the root account.

18.2 Terminals

Terminals provide a convenient and low-cost way to access your DragonFly system when you are not at the computer's console or on a connected network. This section describes how to use terminals with DragonFly.

18.2.1 Uses and Types of Terminals

The original UNIX® systems did not have consoles. Instead, people logged in and ran programs through terminals that were connected to the computer's serial ports. It is quite similar to using a modem and terminal software to dial into a remote system to do text-only work.

Today's PCs have consoles capable of high quality graphics, but the ability to establish a login session on a serial port still exists in nearly every UNIX style operating system today; DragonFly is no exception. By using a terminal attached to an unused serial port, you can log in and run any text program that you would normally run on the console or in an xterm window in the X Window System.

For the business user, you can attach many terminals to a DragonFly system and place them on your employees' desktops. For a home user, a spare computer such as an older IBM PC or a Macintosh® can be a terminal wired into a more powerful computer running DragonFly. You can turn what might otherwise be a single-user computer into a powerful multiple user system.

For DragonFly, there are three kinds of terminals: Dumb Terminals

Dumb terminals are specialized pieces of hardware that let you connect to computers over serial lines. They are called dumb because they have only enough computational power to display, send, and receive text. You cannot run any programs on them. It is the computer to which you connect them 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, including Digital Equipment Corporation's VT-100 and Wyse's WY-75. Just about any kind will work with DragonFly. 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 such as those provided by the X Window System. PCs Acting as Terminals

If a dumb terminal has just enough ability to display, send, and receive text, then certainly any spare personal computer can be a dumb terminal. All you need is the proper cable and some terminal emulation software to run on the computer.

Such a configuration is popular in homes. For example, if your spouse is busy working on your DragonFly system's console, you can do some text-only work at the same time from a less powerful personal computer hooked up as a terminal to the DragonFly system. 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.

We introduce X terminals just for the sake of completeness. However, this chapter does not cover setup, configuration, or use of X terminals.

18.2.2 Configuration

This section describes what you need to configure on your DragonFly system to enable a login session on a terminal. It assumes you have already configured your kernel to support the serial port to which the terminal is connected--and that you have connected it.

Recall from [boot.html Chapter 10] that the init process is responsible for all process control and initialization at system startup. One of the tasks performed by init is to read the /etc/ttys file and start a getty process on the available terminals. The getty process is responsible for reading a login name and starting the login program.

Thus, to configure terminals for your DragonFly system the following steps should be taken as root:

  1. Add a line to /etc/ttys for the entry in the /dev directory for the serial port if it is not already there.

  2. Specify that /usr/libexec/getty be run on the port, and specify the appropriate ***getty*** type from the /etc/gettytab file.

  3. Specify the default terminal type.

  4. Set the port to on.

  5. Specify whether the port should be secure.

  6. Force init to reread the /etc/ttys file.

As an optional step, you may wish to create a custom ***getty*** type for use in step 2 by making an entry in /etc/gettytab. This chapter does not explain how to do so; you are encouraged to see the gettytab(5) and the getty(8) manual pages for more information. Adding an Entry to /etc/ttys

The /etc/ttys file lists all of the ports on your DragonFly system where you want to allow logins. For example, the first virtual console ttyv0 has an entry in this file. You can log in on the console using this entry. This file also contains entries for the other virtual consoles, serial ports, and pseudo-ttys. For a hardwired terminal, just list the serial port's /dev entry without the /dev part (for example, /dev/ttyv0 would be listed as ttyv0).

A default DragonFly install includes an /etc/ttys file with support for the first four serial ports: ttyd0 through ttyd3. If you are attaching a terminal to one of those ports, you do not need to add another entry.

Example 17-1. Adding Terminal Entries to /etc/ttys

Suppose we would like to connect two terminals to the system: a Wyse-50 and an old 286 IBM PC running Procomm terminal software emulating a VT-100 terminal. We connect the Wyse to the second serial port and the 286 to the sixth serial port (a port on a multiport serial card). The corresponding entries in the /etc/ttys file would look like this:

ttyd1./imagelib/callouts/1.png  "/usr/libexec/getty std.38400"./imagelib/callouts/2.png  wy50./imagelib/callouts/3.png  on./imagelib/callouts/4.png  insecure./imagelib/callouts/5.png

ttyd5   "/usr/libexec/getty std.19200"  vt100  on  insecure

./imagelib/callouts/1.png:: The first field normally specifies the name of the terminal special file as it is found in /dev. ./imagelib/callouts/2.png:: The second field is the command to execute for this line, which is usually getty(8). getty initializes and opens the line, sets the speed, prompts for a user name and then executes the login(1) program.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. The getty program reads these characteristics from the file /etc/gettytab.The file /etc/gettytab contains lots of 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. These entries ignore parity. There is a std entry for each bps rate from 110 to 115200. Of course, you can add your own entries to this file. The gettytab(5) manual page provides more information.When setting the ***getty*** type in the /etc/ttys file, make sure that the communications settings on the terminal match.For our example, the Wyse-50 uses no parity and connects at 38400 bps. The 286 PC uses no parity and connects at 19200 bps. ./imagelib/callouts/3.png:: The third field is the type of terminal usually connected to that tty line. For dial-up ports, unknown or dialup is typically used in this field since users may dial up with practically any type of terminal or software. For hardwired terminals, the terminal type does not change, so you can put a real terminal type from the termcap(5) database file in this field.For our example, the Wyse-50 uses the real terminal type while the 286 PC running Procomm will be set to emulate at VT-100. ./imagelib/callouts/4.png:: The fourth field specifies if the port should be enabled. Putting on here will have the init process start the program in the second field, getty. If you put off in this field, there will be no getty, and hence no logins on the port. ./imagelib/callouts/5.png:: The final field is used to specify whether the port is secure. Marking a port as secure means that you trust it enough to allow the root account (or any account with a user ID 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 su(1) or a similar mechanism to gain superuser privileges.It is highly recommended that you use insecure even for terminals that are behind locked doors. It is quite easy to login and use su if you need superuser privileges. Force init to Reread /etc/ttys

After making the necessary changes to the /etc/ttys file you should send a SIGHUP (hangup) signal to the init process to force it to re-read its configuration file. For example:

# kill -HUP 1

Note: init is always the first process run on a system, therefore it will always have PID 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 you should see login prompts on your terminals at this point.

18.2.3 Troubleshooting Your Connection

Even with the most meticulous attention to detail, something could still go wrong while setting up a terminal. Here is a list of symptoms and some suggested fixes. 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 DragonFly computer. Make sure it is the right kind of cable.

Make sure the terminal and DragonFly agree on the bps rate and parity settings. If you have 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:

# ps -axww|grep getty

You should see an entry for the terminal. For example, the following display shows that a getty is running on the second serial port ttyd1 and is using the std.38400 entry in /etc/gettytab:

22189  d1  Is+    0:00.03 /usr/libexec/getty std.38400 ttyd1

If no getty process is running, make sure you have enabled the port in /etc/ttys. Also remember to run kill -HUP 1 after modifying the ttys file.

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 allow you to type, your terminal or cable may not support hardware handshaking. Try changing the entry in /etc/ttys from std.38400 to 3wire.38400 remember to run kill -HUP 1 after modifying /etc/ttys). The 3wire entry is similar to std, but ignores hardware handshaking. You may need to reduce the baud rate or enable software flow control when using 3wire to prevent buffer overflows. If Garbage Appears Instead of a Login Prompt

Make sure the terminal and DragonFly 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. Characters Appear Doubled, the Password Appears When Typed

Switch the terminal (or the terminal emulation software) from half duplex or local echo to full duplex.

18.3 Dial-in Service

Configuring your DragonFly system for dial-in service is very similar to connecting terminals except that you are dealing with modems instead of terminals.

18.3.1 External vs. Internal Modems

External modems seem to be more convenient for dial-up, because external modems 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. Blinking lights impress visitors, but lights are also very useful to see whether a modem is operating properly.

Internal modems usually lack non-volatile RAM, so their configuration may be limited only to setting DIP switches. If your internal modem has any signal indicator lights, it is probably difficult to view the lights when the system's cover is in place. Modems and Cables

If you are using an external modem, then you will of course need the proper cable. A standard RS-232C serial cable should suffice as long as all of the normal signals are wired:

DragonFly 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 you have problems, such as a login session not going away when the line hangs up, you may have a problem with your cable.

Like other UNIX® like operating systems, DragonFly 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. DragonFly avoids sending commands to the modem or watching for status reports from the modem. If you are familiar with connecting modems to PC-based bulletin board systems, this may seem awkward.

18.3.2 Serial Interface Considerations

DragonFly supports 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 much 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.

18.3.3 Quick Overview

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/ttyd0, the command ps ax might show this:

 4850 ??  I      0:00.09 /usr/libexec/getty V19200 ttyd0

When a user dials the modem's line and the modems connect, the CD (Carrier Detect) line is reported by the modem. The kernel notices that carrier has been detected and completes getty's open of 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.

After the user enters his/her 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.

18.3.4 Configuration Files

There are three system configuration files in the /etc directory that you will probably need to edit to allow dial-up access to your DragonFly system. The first, /etc/gettytab, contains configuration information for the /usr/libexec/getty daemon. Second, /etc/ttys holds information that tells /sbin/init what tty devices should have getty processes running on them. Lastly, you can place port initialization commands in the /etc/rc.serial script.

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 school 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 the Enter key 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 can continue ad nauseam, but normally only takes a keystroke or two before the user sees a good prompt. Obviously, this login sequence does not look as clean as the former 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. /etc/gettytab

/etc/gettytab is a termcap(5)-style file of configuration information for getty(8). Please see the gettytab(5) manual page for complete information on the format of the file and the list of capabilities. Locked-speed Config

If you are locking your modem's data communications rate at a particular speed, you probably will not need to make any changes to /etc/gettytab. Matching-speed Config

You will need to set up an entry in /etc/gettytab to give getty information about the speeds you wish to use for your modem. If you have a 2400 bps modem, you can probably use the existing D2400 entry.


# Fast dialup terminals, 2400/1200/300 rotary (can start either way)








If you have a higher speed modem, you will probably need to add an entry in /etc/gettytab; here is an entry you could use 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:\


un|V1200|High Speed Modem at 1200,8-bit:\


uo|V2400|High Speed Modem at 2400,8-bit:\


up|V9600|High Speed Modem at 9600,8-bit:\


uq|V19200|High Speed Modem at 19200,8-bit:\


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.

If you have a 28.8 Kbps modem and/or you want to take advantage of compression on a 14.4 Kbps modem, you need to 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:\


vn|VH1200|Very High Speed Modem at 1200,8-bit:\


vo|VH2400|Very High Speed Modem at 2400,8-bit:\


vp|VH9600|Very High Speed Modem at 9600,8-bit:\


vq|VH57600|Very High Speed Modem at 57600,8-bit:\


If you have a slow CPU or a heavily loaded system and do not have 16550A-based serial ports, you may receive sio silo errors at 57.6 Kbps. /etc/ttys

Configuration of the /etc/ttys file was covered in Example 17-1. Configuration for modems is similar but we must pass a different argument to getty and specify a different terminal type. The general format for both locked-speed and matching-speed configurations is:

ttyd0   "/usr/libexec/getty `***xxx***`"   dialup on

The first item in the above line is the device special file for this entry -- ttyd0 means /dev/ttyd0 is the file that this getty will be watching. The second item, "/usr/libexec/gettyxxx" (***xxx*** will be replaced by the initial gettytab capability) 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 the example above) 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. However, the author finds it easier at his site to specify vt102 as the default terminal type, since the users just use VT102 emulation on their remote systems.

After you have made changes to /etc/ttys, you may send the init process a HUP signal to re-read the file. You can use the command

# kill -HUP 1

to send the signal. If this is your first time setting up the system, you may want to wait until your modem(s) are properly configured and connected before signaling init. Locked-speed Config

For a locked-speed configuration, your 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:

ttyd0   "/usr/libexec/getty std.19200"   dialup on

If your modem is locked at a different data rate, substitute the appropriate value for std.speed* instead of std.19200. Make sure that you use a valid type listed in /etc/gettytab. Matching-speed Config

In a matching-speed configuration, your ttys entry needs to reference the appropriate beginning auto-baud (sic) entry in /etc/gettytab. For example, if you added the above suggested entry for a matching-speed modem that starts at 19.2 Kbps (the gettytab entry containing the V19200 starting point), your ttys entry might look like this:

ttyd0   "/usr/libexec/getty V19200"   dialup on /etc/rc.serial

High-speed modems, like V.32, V.32bis, and V.34 modems, need to use hardware (RTS/CTS) flow control. You can add stty commands to /etc/rc.serial to set the hardware flow control flag in the DragonFly kernel for the modem ports.

For example to set the termios flag crtscts on serial port #1's (COM2) dial-in and dial-out initialization devices, the following lines could be added to /etc/rc.serial:

# Serial port initial configuration

stty -f /dev/ttyid1 crtscts

stty -f /dev/cuaia1 crtscts

18.3.5 Modem Settings

If you have a modem whose parameters may be permanently set in non-volatile RAM, you will need to use a terminal program (such as Telix under MS-DOS® or tip under DragonFly) 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:

Please read the documentation for your modem to find out what commands and/or DIP switch settings you need to give it.

For example, to set the above parameters on a U.S. Robotics® Sportster® 14,400 external modem, one could give these commands to the modem:



You might also want to take this opportunity to adjust other settings in the modem, such as whether it will use V.42bis and/or MNP5 compression.

The U.S. Robotics Sportster 14,400 external modem also has some DIP switches that need to be set; for other modems, perhaps you can use these settings as an example:

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 a extended, silly conversation between getty and the modem. Locked-speed Config

For a locked-speed configuration, you will need to configure the modem to maintain a constant modem-to-computer data rate independent of the communications rate. On a U.S. Robotics Sportster 14,400 external modem, these commands will lock the modem-to-computer data rate at the speed used to issue the commands:


AT&B1&W Matching-speed Config

For a variable-speed configuration, you will need to configure your modem to adjust its serial port data rate to match the incoming call rate. On a U.S. Robotics Sportster 14,400 external modem, these commands will lock the modem's error-corrected data rate to the speed used to issue the commands, but allow the serial port rate to vary for non-error-corrected connections:


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 U.S. Robotics Sportster 14,400 external modems, the command 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 the commands ATZ and then ATI4.

If you have a different brand of modem, check your modem's manual to see how to double-check your modem's configuration parameters.

18.3.6 Troubleshooting

Here are a few steps you can follow to check out the dial-up modem on your system. Checking Out the DragonFly System

Hook up your modem to your DragonFly system, boot the system, and, if your 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 DragonFly 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 DragonFly system through the console and issue a ps ax to see if DragonFly is trying to run a getty process on the correct port. You should see lines like these among the processes displayed:

  114 ??  I      0:00.10 /usr/libexec/getty V19200 ttyd0

  115 ??  I      0:00.10 /usr/libexec/getty V19200 ttyd1

If you see something different, like this:

  114 d0  I      0:00.10 /usr/libexec/getty V19200 ttyd0

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 mis-configured modem, because getty should not be able to open the communications port until CD (carrier detect) has been asserted by the modem.

If you do not see any getty processes waiting to open the desired ttydN* port, double-check your entries in /etc/ttys to see if there are any mistakes there. Also, check the log file /var/log/messages to see if there are any log messages from init or getty regarding any problems. If there are any messages, triple-check the configuration files /etc/ttys and /etc/gettytab, as well as the appropriate device special files /dev/ttydN, for any mistakes, missing entries, or missing device special files. Try Dialing In

Try dialing into the system; be sure to use 8 bits, no parity, and 1 stop bit on the remote system. If you do not get a prompt right away, or get garbage, try pressing Enter about once per second. If you still do not see a login: prompt after a while, try sending a BREAK. If you are using a high-speed modem to do the dialing, try dialing again after locking the dialing modem's interface speed (via AT&B1 on a U.S. Robotics Sportster modem, for example).

If you dial but the modem on the DragonFly 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 has any).

If you have gone over everything several times and it still does not work, take a break and come back to it later. If it still does not work, perhaps you can send an electronic mail message to the DragonFly User related mailing list describing your modem and your problem, and the good folks on the list will try to help.

18.4 Dial-out Service

The following are tips for getting your host to be able to connect over the modem to another computer. This is appropriate for establishing a terminal session with a remote host.

This is useful to log onto a BBS.

This kind of connection can be extremely helpful to get a file on the Internet if you have problems with PPP. If you need to FTP something and PPP is broken, use the terminal session to FTP it. Then use zmodem to transfer it to your machine.

18.4.1 My Stock Hayes Modem Is Not Supported, What Can I Do?

Actually, the manual page for tip is out of date. There is a generic Hayes dialer already built in. Just use at=hayes in your /etc/remote file.

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 will just confuse it. You should turn those messages off when you use tip (using ATX0&W).

Also, the dial timeout for tip is 60 seconds. Your modem should use something less, or else tip will think there is a communication problem. Try ATS7=45&W.

Note: As shipped, tip does not yet support Hayes modems fully. The solution is to edit the file tipconf.h in the directory /usr/src/usr.bin/tip/tip. Obviously you need the source distribution to do this.

Edit the line #define HAYES 0 to #define HAYES 1. Then make and make install. Everything works nicely after that.

18.4.2 How Am I Expected to Enter These AT Commands?

Make what is called a direct entry in your /etc/remote file. For example, if your modem is hooked up to the first serial port, /dev/cuaa0, then put in the following line:


Use the highest bps rate your modem supports in the br capability. Then, type tip cuaa0 and you will be connected to your modem.

Or use cu as root with the following command:

# cu -l`***line***` -s`***speed***`

***line*** is the serial port (e.g./dev/cuaa0) and ***speed*** is the speed (e.g.57600). When you are done entering the AT commands hit ~. to exit.

18.4.3 The @ Sign for the pn Capability 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. Escape it with a backslash:


18.4.4 How Can I Dial a Phone Number on the Command Line?

Put what is called a generic entry in your /etc/remote file. For example:

tip115200|Dial any phone number at 115200 bps:\


tip57600|Dial any phone number at 57600 bps:\


Then you can do things like:

# tip -115200 5551234

If you prefer cu over tip, use a generic cu entry:

cu115200|Use cu to dial any number at 115200bps:\


and type:

# cu 5551234 -s 115200

18.4.5 Do I Have to Type in the bps Rate Every Time I Do That?

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. You do not have to use 1200 bps, though.

18.4.6 I Access a Number of Hosts Through a Terminal Server

Rather than waiting until you are connected and typing CONNECT <host> each time, use tip's cm capability. For example, these entries in /etc/remote:

pain|pain.deep13.com|Forrester's machine:\

        :cm#CONNECT pain\n:tcdeep13:

muffin|muffin.deep13.com|Frank's machine:\

        :cm#CONNECT muffin\n:tcdeep13:

deep13:Gizmonics Institute terminal server:\


will let you type tip pain or tip muffin to connect to the hosts pain or muffin, and tip deep13 to get to the terminal server.

18.4.7 Can Tip Try More Than One Line for Each Site?

This is often a problem where a university has several modem lines and several thousand students trying to use them.

Make an entry for your university in /etc/remote and use @ for the pn capability:





Then, list the phone numbers for the university in /etc/phones:

big-university 5551111

big-university 5551112

big-university 5551113

big-university 5551114

tip will try each one in the listed order, then give up. If you want to keep retrying, run tip in a while loop.

18.4.8 Why Do I Have to Hit Ctrl + P Twice to Send Ctrl + P Once?

Ctrl + P is the default force character, used to tell tip that the next character is literal data. You can set the force character to any other character with the ~s escape, which means set a variable.

Type ~sforce=single-char* followed by a newline. ***single-char*** is any single character. If you leave out ***single-char***, then the force character is the nul character, which you can get by typing Ctrl + 2 or Ctrl + Space . A pretty good value for ***single-char*** is Shift + Ctrl + 6 , which is only used on some terminal servers.

You can have the force character be whatever you want by specifying the following in your $HOME/.tiprc file:


18.4.9 Suddenly Everything I Type Is in Upper Case??

You must have pressed Ctrl + A , tip's raise character, specially designed for people with broken caps-lock keys. Use ~s as above and set the variable raisechar to something reasonable. In fact, you can set it to the same as the force character, if you never expect to use either of these features.

Here is a sample .tiprc file perfect for Emacs users who need to type Ctrl + 2 and Ctrl + A a lot:



The ^^ is Shift + Ctrl + 6 .

18.4.10 How Can I Do File Transfers with tip?

If you are talking to another UNIX® system, you can send and receive files with ~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 you probably should use another protocol, like zmodem.

18.4.11 How Can I Run zmodem with tip?

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 szfiles* to send them to the remote system.

18.5 Setting Up the Serial Console

18.5.1 Introduction

DragonFly has the ability to boot on a system with only a dumb terminal on a serial port as a console. Such a configuration should be useful for two classes of people: system administrators who wish to install DragonFly on machines that have no keyboard or monitor attached, and developers who want to debug the kernel or device drivers.

As described in [boot.html Chapter 10], DragonFly employs a three stage bootstrap. The first two stages are in the boot block code which is stored at the beginning of the DragonFly slice on the boot disk. The boot block will then load and run the boot loader (/boot/loader) as the third stage code.

In order to set up the serial console you must configure the boot block code, the boot loader code and the kernel.

18.5.2 Serial Console Configuration, Terse Version

This section assumes that you are using the default setup, know how to connect serial ports and just want a fast overview of a serial console. If you encounter difficulty with these steps, please see the more extensive explanation of all the options and advanced settings in [serialconsole-setup.html#SERIALCONSOLE-HOWTO Section 18.5.3].

  1. Connect the serial port. The serial console will be on COM1.

  2. echo -h > /boot.config to enable the serial console for the boot loader and kernel.

  3. Edit /etc/ttys and change off to on for the ttyd0 entry. This enables a login prompt on the serial console, which mirrors how video consoles are typically setup.

  4. shutdown -r now will reboot the system with the serial console.

18.5.3 Serial Console Configuration

  1. Prepare a serial cable.

    You will need either a null-modem cable or a standard serial cable and a null-modem adapter. See Section 18.1.2 for a discussion on serial cables.

  2. Unplug your keyboard.

    Most 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 complain loudly about the lack of a keyboard and will not continue to boot until it is plugged in.

    If your computer complains about the error, but boots anyway, then you do not have to do anything special. (Some machines with Phoenix BIOS installed merely say Keyboard failed and continue to boot normally.)

    If your computer refuses to boot without a keyboard attached then you will have to configure the BIOS so that it ignores this error (if it can). Consult your motherboard's manual for details on how to do this.

    Tip: Setting the keyboard to Not installed in the BIOS setup does not mean that you will not be able to use your keyboard. All this does is tell the BIOS not to probe for a keyboard at power-on, so it will not complain if the keyboard is not plugged in. You can leave the keyboard plugged in even with this flag set to Not installed and the keyboard will still work.

    Note: If your system has a PS/2® mouse, chances are very good that you may have to unplug your mouse as well as your keyboard. This is because PS/2 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. In general, this is not a problem since the mouse is not much good without the keyboard anyway.

  3. Plug a dumb terminal into COM1 (sio0).

    If you do not have a dumb terminal, you can use an old PC/XT with a modem program, or the serial port on another UNIX® box. If you do not have a 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 you are already using COM1 for another device, you will have to temporarily remove that device and install a new boot block and kernel once you get DragonFly up and running. (It is assumed that COM1 will be available on a file/compute/terminal server anyway; if you really need COM1 for something else (and you cannot switch that something else to COM2 (sio1)), then you probably should not even be bothering with all this in the first place.)

  4. Make sure the configuration file of your 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 the -h option described below, together with this flag.0x20:: Forces this unit to be the console (unless there is another higher priority console), regardless of the -h option discussed below. This flag replaces the COMCONSOLE option in DragonFly versions 2.***X***. The flag 0x20 must be used together with the 0x10 flag.0x40:: Reserves this unit (in conjunction with 0x10) and makes the unit unavailable for normal access. You should not set this flag to the serial port unit which you want to use as the serial console. This reserves this port for "low-level IO", i.e. kernel debugging.0x80:: This port will be used for remote kernel debugging.


    device sio0 at isa? port IO_COM1 flags 0x10 irq 4

    See the sio(4) manual page for more details.

    If the flags were not set, you need to run UserConfig (on a different console) or recompile the kernel.

  5. Create boot.config in the root directory of the a partition on the boot drive.

    This file will instruct the boot block code how you would like to boot the system. In order to activate the serial console, you need one or more of the following options--if you want multiple options, include them all on the same line:

    -h:: Toggles internal and serial consoles. You can use this to switch console devices. For instance, if you boot from the internal (video) console, you can use -h to direct the boot loader and the kernel to use the serial port as its console device. Alternatively, if you boot from the serial port, you can use the -h to tell the boot loader and the kernel to use the video display as the console instead.-D:: Toggles 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 the -h option above. 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 the -h option. However, note that the dual console configuration takes effect only during the boot block is running. Once the boot loader gets control, the console specified by the -h option becomes the only console.-P:: Makes the boot block probe the keyboard. If no keyboard is found, the -D and -h options are automatically set.

    Note: Due to space constraints in the current version of the boot blocks, the -P option 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 laptop computers may not be properly found because of this limitation. If this is the case with your system, you have to abandon using the -P option. Unfortunately there is no workaround for this problem.

    Use either the -P option to select the console automatically, or the -h option to activate the serial console.

    You may include other options described in boot(8) as well.

    The options, except for -P, will be passed to the boot loader (/boot/loader). The boot loader will determine which of the internal video or the serial port should become the console by examining the state of the -h option alone. This means that if you specify the -D option but not the -h option in /boot.config, you can use the serial port as the console only during the boot block; the boot loader will use the internal video display as the console.

  6. Boot the machine.

    When you start your DragonFly box, the boot blocks will echo the contents of /boot.config to the console. For example:

    /boot.config: -P

    Keyboard: no

    The second line appears only if you put -P in /boot.config and indicates presence/absence of the keyboard. These messages go to either serial or internal console, or both, depending on the option in /boot.config.

    || Options || Message goes to ||

    || none || internal console ||

    || -h || serial console ||

    || -D || serial and internal consoles ||

    || -Dh || serial and internal consoles ||

    || -P, keyboard present || internal console ||

    || -P, keyboard absent || serial console ||

    After the above messages, there will be a small pause before the boot blocks continue loading the boot loader and before any further messages printed to the console. Under normal circumstances, you do not need to interrupt the boot blocks, but you may want to do so in order to make sure things are set up correctly.

    Hit any key, other than Enter, at the console to interrupt the boot process. The boot blocks will then prompt you for further action. You should now see something like:

    >> DragonFly/i386 BOOT

    Default: 0:ad(0,a)/boot/loader


    Verify the above message appears on either the serial or internal console or both, according to the options you put in /boot.config. If the message appears in the correct console, hit Enter to continue the boot process.

    If you want the serial console but you do not see the prompt on the serial terminal, something is wrong with your settings. In the meantime, you enter -h and hit Enter/Return (if possible) 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.

After the boot loader is loaded and you are in the third stage of the boot process you can still switch between the internal console and the serial console by setting appropriate environment variables in the boot loader. See [serialconsole-setup.html#SERIALCONSOLE-LOADER Section 18.5.6].

18.5.4 Summary

Here is the summary of various settings discussed in this section and the console eventually selected. Case 1: You Set the Flags to 0x10 for sio0

device sio0 at isa? port IO_COM1 flags 0x10 irq 4
Options in /boot.config Console during boot blocks Console during boot loader Console in kernel
nothing internal internal internal
-h serial serial serial
-D serial and internal internal internal
-Dh serial and internal serial serial
-P, keyboard present internal internal internal
-P, keyboard absent serial and internal serial serial Case 2: You Set the Flags to 0x30 for sio0

device sio0 at isa? port IO_COM1 flags 0x30 irq 4
Options in /boot.config Console during boot blocks Console during boot loader Console in kernel
nothing internal internal serial
-h serial serial serial
-D serial and internal internal serial
-Dh serial and internal serial serial
-P, keyboard present internal internal serial
-P, keyboard absent serial and internal serial serial

18.5.5 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. If you wish to change the speed, you need to recompile at least the boot blocks. Add the following line to /etc/make.conf and compile new boot blocks:


If the serial console is configured in some other way than by booting with -h, or if the serial console used by the kernel is different from the one used by the boot blocks, then you must also add the following option to the kernel configuration file and compile a new kernel:

options CONSPEED=19200 Using Serial Port Other Than sio0 for the Console

Using a port other than sio0 as the console requires some recompiling. If you want to use another serial port for whatever reasons, recompile the boot blocks, the boot loader and the kernel as follows.

  1. Get the kernel source.

  2. Edit /etc/make.conf and set BOOT_COMCONSOLE_PORT to the address of the port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only sio0 through sio3 (COM1 through COM4) can be used; multiport serial cards will not work. No interrupt setting is needed.

  3. Create a custom kernel configuration file and add appropriate flags for the serial port you want to use. For example, if you want to make sio1 (COM2) the console:

    device sio1 at isa? port IO_COM2 flags 0x10 irq 3


    device sio1 at isa? port IO_COM2 flags 0x30 irq 3

    The console flags for the other serial ports should not be set.

  4. Recompile and install the boot blocks and the boot loader:

    # cd /sys/boot

    # make

    # make install

  5. Rebuild and install the kernel.

  6. Write the boot blocks to the boot disk with disklabel(8) and boot from the new kernel. Entering the DDB Debugger from the Serial Line

If you wish to drop into the kernel debugger from the serial console (useful for remote diagnostics, but also dangerous if you generate a spurious BREAK on the serial port!) then you should compile your kernel with the following options:


options DDB Getting a Login Prompt on the Serial Console

While this is not required, you may wish to get a login prompt over the serial line, now that you can see boot messages and can enter the kernel debugging session through the serial console. Here is how to do it.

Open the file /etc/ttys with an editor and locate the lines:

ttyd0 "/usr/libexec/getty std.9600" unknown off secure

ttyd1 "/usr/libexec/getty std.9600" unknown off secure

ttyd2 "/usr/libexec/getty std.9600" unknown off secure

ttyd3 "/usr/libexec/getty std.9600" unknown off secure

ttyd0 through ttyd3 corresponds to COM1 through COM4. Change off to on for the desired port. If you have changed the speed of the serial port, you need to change std.9600 to match the current setting, e.g. std.19200.

You may also want to change the terminal type from unknown to the actual type of your serial terminal.

After editing the file, you must kill -HUP 1 to make this change take effect.

18.5.6 Changing Console from the Boot Loader

Previous sections described how to set up the serial console by tweaking the boot block. This section shows that you can 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, after the boot block, the settings in the boot loader will override the settings in the boot block. Setting Up the Serial Console

You can easily specify the boot loader and the kernel to use the serial console by writing just one line in /boot/loader.rc:

set console=comconsole

This will take effect regardless of the settings in the boot block discussed in the previous section.

You had better put the above line as the first line of /boot/loader.rc so as to see boot messages on the serial console as early as possible.

Likewise, you can specify the internal console as:

set console=vidconsole

If you do not set the boot loader environment variable console, the boot loader, and subsequently the kernel, will use whichever console indicated by the -h option in the boot block.

In versions 3.2 or later, you may specify the console in /boot/loader.conf.local or /boot/loader.conf, rather than in /boot/loader.rc. In this method your /boot/loader.rc should look like:

include /boot/loader.4th


Then, create /boot/loader.conf.local and put the following line there.




Note: At the moment, the boot loader has no option equivalent to the -P option 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 sio0 for the Console

You need to recompile the boot loader to use a serial port other than sio0 for the serial console. Follow the procedure described in [serialconsole-setup.html#SERIALCONSOLE-COM2 Section].

18.5.7 Caveats

The idea here is to allow people to set up dedicated servers that require no graphics hardware or attached keyboards. Unfortunately, while most systems will let you boot without a keyboard, there are quite a few that will not let you boot without a graphics adapter. Machines with AMI BIOSes can be configured to boot with no graphics adapter installed simply by changing the graphics adapter setting in the CMOS configuration to Not installed.