Serial Consoles
All of these nifty boot functions let you do useful stuff when your system is in trouble, but how can you use them when your computer isn’t right in front of you? If your computer is in a data center on the other side of the country, or sitting in the basement behind the last decade of payroll records, a serial console will make your life far more pleasant.
A hardware serial console allows you to run a serial cable between a computer and a terminal server (on another computer) to access BIOS messages and operating system boot and startup messages which simplifies managing remote systems. Serial consoles are invaluable when debugging system crashes, too; error messages come over the serial port, where you can easily capture them.[12]
True UNIX hardware has serial console capabilities, as does most server-grade i386 and amd64 hardware. Most desktop-grade hardware, however, does not. But fortunately, even if you don’t have a hardware serial console, you can access all of OpenBSD’s startup messages with a serial port and a software serial console. While OpenBSD’s software serial console won’t give you access to the hardware BIOS, it will let you interface with the boot loader and remotely access the system console, even when the network is down.
Other Platform Serial Consoles
Every hardware platform has its own standards for serial consoles. If you’re running a less common platform, check your hardware’s documentation.
If your hardware supports a real serial console, you should usually configure it in the BIOS. OpenBSD supports whatever the hardware supports, so your Sparc64 hardware will support OpenBSD’s serial console just as well as it supports any other operating system’s serial console.
Serial Console Physical Setup
A serial console requires a null modem cable, which you should be able to get from any computer store or an online vendor. While gold-plated cables aren’t worth the money, don’t buy the cheapest cable you can find either. If you have an emergency and need the serial console right now, you won’t be in the mood to deal with a defective cable.
Plug one end of the null modem cable into your OpenBSD machine’s first serial port. (The serial console is supported on only the first serial port, or com0 on i386 and amd64 hardware.) Plug the null modem cable’s other end into an open serial port on another system. (For simplicity’s sake, use either another OpenBSD or Unix-like system.)
If you have two OpenBSD machines at a remote location and you want to use serial consoles on both, you can have each machine act as the console client for the other. Attach the first serial port on each server to the second serial port on the other. If you have three machines, you can daisy-chain them in a loop. If you have four or more machines, pick up a used terminal server from your favorite auction site.
You can also use two DB9-to-RJ45 converters, one standard and one crossover, which will allow you to run your console connections over a standard CAT5 cable. If you have a lights-out data center where human beings are forbidden unless they are installing or removing equipment, you can stretch your serial console cables about 12 meters, which should reach into your warm room. (Most modern data facilities are better equipped to handle CAT5 cables than serial cables.)
Serial Console Configuration
Now that you have the console physically ready, the next step is to configure your client to access the serial console. Then you can set up the serial console.
Configuring the Serial Console Client
The following are the default settings for an OpenBSD i386 or amd64 system:
-
9600 baud
-
8 bits
-
No parity
-
1 stop bit
Enter these values into any terminal emulator on the client computer, and the serial console should Just Work. You can find terminal emulators for Microsoft platforms (I recommend PuTTY), OS X, and just about any other operating system.
OpenBSD includes the terminal emulator tip(1), which reads its configuration from /etc/remote. The configuration tty00 in /etc/remote matches the default OpenBSD serial console configuration for i386 and amd64 systems (as well as several other platforms). If you’ve attached your null modem cable to the first serial port on the client, connect with this command:
# tip tty00
connected
If it doesn’t say connected, your serial client is misconfigured. Fix your client before enabling your serial console on the server. You want your serial client ready before configuring the console.
Setting Up the Serial Console
OpenBSD normally uses the local physical keyboard, video, and mouse as the console, but it can also use the first serial port as a serial console.
To set the console, use the boot loader. You must know the loader’s device name for your preferred console: com0 for the first serial port or pc0 for the physically attached video and keyboard.
The first time you try to use a serial console, use a local test machine. Set up your client beforehand and start your terminal emulator, and then boot your test machine. At the boot loader prompt, enter this command:
boot> set tty com0
Your server’s monitor and keyboard should stop responding, and if you’ve set up everything correctly, you should see the boot loader prompt in your terminal emulator.
To switch back to the physical console, tell the boot loader to use the pc0 device:
boot> set tty pc0
Poof! The server’s keyboard and monitor should work again.
To have your machine use the serial console at every boot, add this statement in /etc/boot.conf:
set tty com0
Be sure to test your serial console after the machine is installed in its permanent location, and always screw the serial cables to the server. A loose serial cable provides only a comforting illusion that betrays you when it will hurt the most.
Changing the Serial Console Speed
Newer serial ports (meaning anything made within the past 10 years) can run at speeds far above 9600 baud. I have servers with serial consoles that run only at 115,200 baud. The BIOS messages display at 115,200 baud, but then the OpenBSD console runs at 9600 baud. My client displays one or the other as gibberish. (A lot of OpenBSD folks think that anything that won’t do serial at 9600 baud is broken, but you won’t always have control over the hardware you work with.)
To use these ports, I can either change my connection speed in my serial console client when switching between the BIOS messages and the OpenBSD messages, or change the speed of my OpenBSD console to match the hardware.
At the boot loader, tell the serial console to run at 115,200 baud:
boot> stty com0 115200 boot> set tty com0
If these settings work, copy them to /etc/boot.conf.
Now configure your serial client. Modify tip to use the higher speed. First, find the entry for tty00 in /etc/remote:
tty00|For hp300,i386,mac68k,macppc,vax:
:dv=/dev/tty00:tc=direct:tc=unixhost:
But don’t modify this entry! We’ll use it to illustrate the style of /etc/remote entries.
Note
/etc/remote is designed much like a termcap(5) database. If you ever need to write your own termcap entries from scratch, you’re living your life wrong. But you can recognize the contents and modify existing entries without much pain. If you really want to learn everything about these entries, read the remote(5) man page.
Backslashes () in this entry mean “continued on the next line.” Colons separate fields. Each line after the first must start with a colon, and each field is a key/value pair.
Now, to create a console entry that runs at 115,200 baud, use the following:
console:br#115200:tc=tty00:
The first field in an /etc/remote entry is the name, and every entry must have a unique name. I named this entry console. The second field is the br value. According to remote(5), br stands for bit rate. I’ve set the bit rate to 115,200 baud. The third field is tc, for “table continues,” which is equal to tty00. This means that the description of this entry continues in entry tty00.
Taken as a whole, this entry means “copy the tty00 entry, and add a bit rate of 115,200.”
Changing the Client Serial Port
If you have two OpenBSD machines, each sending its serial console out its first serial port to the other machine’s second serial port, you must tell tip to connect to the second serial port. The command tip tty00 doesn’t actually connect to the serial port named tty00—it connects to a port defined by the /etc/remote entry named tty00. That means that you can’t run, say, tip tty03 and connect to serial port tty03 unless you have an /etc/remote entry named tty03. By default, there isn’t one, but you can define one easily, as follows:
tty03:dv=/dev/tty03:tc=tty00:
This entry is named tty01. The dv setting tells /etc/remote the physical device to use. Other than this, all settings are copied from the entry called tty00.
With these examples, you should be able to use OpenBSD’s tip to connect to almost any serial console.
Serial Logins
The serial console lets you interact with the boot process. Once your machine is fully multiuser, however, a default serial console will not let you actually log in to OpenBSD. In multiuser mode, OpenBSD uses getty(8) to initialize terminals and handle logins, and in order to log in to your machine over a serial port, you will need to tell getty to take charge of the serial line by configuring /etc/ttys.
We’ll discuss /etc/ttys further in Chapter 14, but for now, here’s how to allow logins over the first serial port. Find the entry for tty00, which should look like this:
tty00 "/usr/libexec/getty std.9600" unknown off
Remove the last two words, and replace them to match the following:
tty00 "/usr/libexec/getty std.9600" vt220 on secure
Now run kill -1 1, and you should get a login prompt over your serial line.