## Chapter 18 Serial Communications [[!toc levels=3]] ## Synopsis 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: * How to connect terminals to your DragonFly system. * How to use a modem to dial out to remote hosts. * How to allow remote users to login to your system with a modem. * How to boot your system from a serial console. Before reading this chapter, you should: * Know how to configure and install a new kernel ([kernelconfig.html Chapter 10]). * Understand UNIX permissions and processes ([basics.html Chapter 3]). * Have access to the technical manual for the serial hardware (modem or multi-port card) that you would like to use with DragonFly. *** ## 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. #### 18.1.2.1 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. ##### 18.1.2.1.1 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. [[!table data=""" | 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 DCD | 8 | | 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. ##### 18.1.2.1.2 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. #### 18.1.2.2 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. ##### 18.1.2.2.1 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. ##### 18.1.2.2.2 Port Names In DragonFly, you access each serial port through an entry in the `/dev` directory. There are two different kinds of entries: * Call-in ports are named `/dev/ttyd`***N****** where `***N***` is the port number, starting from zero. Generally, you use the call-in port 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/cuaa`***N******. You usually do not use the call-out port for terminals, just for modems. You may use the call-out port if the serial cable or the terminal does not support the carrier detect signal. 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 10]. 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 You can comment-out or completely remove lines for devices you do not have. Please refer to the [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#sio§ion4) manual page for more information on serial ports and multiport boards configuration. **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/ttyd`***N****** (dial-in) and `/dev/cuaa`***N****** (call-out) devices. DragonFly also provides initialization devices (`/dev/ttyid`***N****** and `/dev/cuaia`***N******) and locking devices (`/dev/ttyld`***N****** and `/dev/cuala`***N******). 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)](http://leaf.dragonflybsd.org/cgi/web-man?command#termios§ion4), [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=sio§ion=4), and [stty(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=stty§ion=1) for information on the terminal settings, locking and initializing devices, and setting terminal options, respectively. #### 18.1.4.1 Making Device Special Files A shell script called `MAKEDEV` in the `/dev` directory manages the device special files. To use `MAKEDEV` to make dial-up device special files for `COM1` (port 0), `cd` to `/dev` and issue the command `MAKEDEV ttyd0`. Likewise, to make dial-up device special files for `COM2` (port 1), use `MAKEDEV ttyd1`. `MAKEDEV` not only creates the `/dev/ttyd`***N****** device special files, but also the `/dev/cuaa`***N******, `/dev/cuaia`***N******, `/dev/cuala`***N******, `/dev/ttyld`***N******, and `/dev/ttyid`***N****** nodes. After making new device special files, be sure to check the permissions on the files (especially the `/dev/cua*` files) to make sure that only users who should have access to those device special files can read and write on them -- you probably do not want to allow your average user to use your modems to dial-out. The default permissions on the `/dev/cua*` files should be sufficient: crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cuaa1 crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuaia1 crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cuala1 These permissions allow the user `uucp` and users in the group `dialer` to use the call-out devices. ### 18.1.5 Serial Port Configuration The `ttyd`***N****** (or `cuaa`***N******) 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](term.html#TERM-DUMB) * [ PCs acting as terminals](term.html#TERM-PCS) * [ X terminals](term.html#TERM-X) The remaining subsections describe each kind. #### 18.2.1.1 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. #### 18.2.1.2 PCs Acting as Terminals If a [ dumb terminal](term.html#TERM-DUMB) 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. #### 18.2.1.3 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 7] 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. 1. Specify that `/usr/libexec/getty` be run on the port, and specify the appropriate `***getty***` type from the `/etc/gettytab` file. 1. Specify the default terminal type. 1. Set the port to ***on.*** 1. Specify whether the port should be ***secure.*** 1. 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)](http://leaf.dragonflybsd.org/cgi/web-man?command#gettytab&section5) and the [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=getty&section=8) manual pages for more information. #### 18.2.2.1 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](term.html#CO-TTYS-LINE1COL1):: The first field normally specifies the name of the terminal special file as it is found in `/dev`.[ ./imagelib/callouts/2.png](term.html#CO-TTYS-LINE1COL2):: The second field is the command to execute for this line, which is usually [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#getty&section8). `getty` initializes and opens the line, sets the speed, prompts for a user name and then executes the [login(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=login&section=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)](http://leaf.dragonflybsd.org/cgi/web-man?command=gettytab&section=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](term.html#CO-TTYS-LINE1COL3):: 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)](http://leaf.dragonflybsd.org/cgi/web-man?command=termcap&section=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](term.html#CO-TTYS-LINE1COL4):: 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](term.html#CO-TTYS-LINE1COL5):: 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)](http://leaf.dragonflybsd.org/cgi/web-man?command=su&section=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. #### 18.2.2.2 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. #### 18.2.3.1 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. #### 18.2.3.2 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`. #### 18.2.3.3 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.*** ***