Linux Server Hacks, Volume Two

Hack #37. Turn Your Laptop into a Makeshift Console

Use minicom and a cable (or two, if your laptop doesn't have a serial port) to connect to the console port of any server.

There are many situations in which the ability to connect to the serial console port of a server can be a real lifesaver. In my day-to-day work, I sometimes do this for convenience, so I can type commands on a server's console while at the same time viewing some documentation that is inevitably available only in PDF format (something I can't do from a dumb terminal). It's also helpful if you're performing tasks on a machine that is not yet hooked up to any other kind of console or if you're on a client site and want to get started right away without having to learn the intricacies of the client's particular console server solution.

Introducing minicom

How is this possible? There's an age-old solution that's provided as a binary package by just about every Linux distribution, and it's called minicom. If you need to build from source, you can download it at http://alioth.debian.org/projects/minicom/. minicom can do a multitude of great things, but what I use it for is to provide a console interface to a server over a serial connection, using a null modem cable (otherwise known as a crossover serial cable).

Actually, that's a big, fat lie. My laptop, as it turns out, doesn't have a serial port! I didn't even look to confirm that it had one when I ordered it, but I've found that many newer laptops don't come with one. If you're in the same boat, fear not! Available at online shops everywhere, for your serial connection pleasure, are USB-to-serial adapters. Just plug this thing into a USB port, then connect one end of the null modem cable to the adapter and the other end to the server's serial port, and you're in business.

With hardware concerns taken care of, you can move on to configuring minicom. A default configuration directory is usually provided on Debian systems in /etc/minicom. On Red Hat systems, the configuration files are usually kept under /etc and do not have their own directory. Customizing the configuration is generally done by running this command as root:

	# minicom –s

This opens a text-based interface where you can make the necessary option changes. The configuration gets saved to a file called minirc.dfl by default, but you can use the "Save setup as" menu option to give the configuration a different name. You might want to do that in order to provide several configuration files to meet different needs—the profile used at startup time can be passed to minicom as a lone argument.

For example, if I run minicom -s, and I already have a default profile stored in minicom.dfl, I can, for instance, change the baud rate from the default 9,600 to 115,200 and then save this as a profile named fast. The file created by this procedure will be named minicom.fast, but when I start up I just call the profile name, not the filename, like this:

	$ minicom fast

Of course, this assumes that a regular user has access to that profile. There is a user access file, named minicom.users, that determines which users can get to which profiles. On both Debian and Red Hat systems, all users have access to all profiles by default.

A slightly simpler way to get a working configuration is to steal it. Here is a barebones configuration for minicom. Though it's very simple, it's really the only one I've ever needed:

	# Machine-generated file - use "minicom -s" to change parameters.
	pu port			/dev/ttyUSB0
	pu baudrate		9600
	pu bits			8
	pu parity		N
	pu stopbits		1
	pu minit
	pu mreset
	pu mconnect
	pu mhangup

I included here the options stored to the file by default, even though they're not used. The unused settings are specific to situations in which minicom needs to perform dialups using a modem. Note in this config file that the serial device I'm using (the local device through which minicom will communicate) is /dev/ttyUSB0. This device is created and assigned by a Linux kernel module called usbserial. If you're using a USB-to-serial adapter and there's no indication that it's being detected and assigned to a device by the kernel, check to make sure that you have this module. Almost every distribution these days provides the ubserial module and dynamically loads it when needed, but if you build your own kernels, make sure you don't skip over this module! In your Linux kernel configuration file, the option CONFIG_USB_SERIAL should be set to y or m. It should not be commented out.

The next setting is the baudrate, which has to be the same on both the client and the server. In this case, I've picked 9,600, not because I want to have a turtle-slow terminal, but because that's the speed configured on the servers to which I usually connect. It's plenty fast enough for most things that don't involve tailing massive logfiles that are updated multiple times per second.

The next three settings dictate how the client will be sending its data to the server. In this case, a single character will be eight bits long, followed by no parity bit and one stop bit. This setting (referred to as "8N1") is by far the most common setting for asynchronous serial communication. These settings are so standard that I've never had to change them in my minicom.conf file—in fact, the only setting I do change is the baud rate.

Testing It

Once you have your configuration in place, connect your null modem or USB-to-serial adapter to your laptop and connect the other end to the serial console port on the server. If you're doing this for the first time, the serial console port on the server is a 15-pin male connection that looks a lot like the male version of a standard VGA port. It's also likely to be the only place you can plug in a null modem cable! If there are two of them, generally the one on the top (in a vertical configuration) or on the left (in a horizontal configuration) will be ttyS0 on the server, and the other will be ttyS1.

After you've physically connected the laptop to the server, the next thing to do is fire up a terminal application and launch minicom:

	$ minicom

This command will launch minicom with its default configuration. Note that on many systems, launching the application alone doesn't do much: you have to hit Enter once or twice to get a login prompt returned to you.

Troubleshooting

I've rarely had trouble using minicom in this way, especially when the server end is using agetty to provide its of the communication, because agetty is pretty forgiving and can adjust for things like seven-bit characters and other unusual settings. In the event that you have no output or your output looks garbled, check to make sure that the baud rate on the client matches the baud rate on the server. Also make sure that you are, in fact, connected to the correct serial port! On the server, try typing the following to get a quick rundown of the server settings:

	$ grep agetty /etc/inittab
	co:2345:respawn:/sbin/agetty ttyS0 9600 vt100-nav
	$

This output shows that agetty is in fact running on ttyS0 at 9600 baud. The vt100-nav option on the end is put there by the Fedora installation program, which sets up your inittab entry by default if something is connected to the console port during installation. The vt100-nav option sets the TERM environment variable. If you leave this setting off, most Linux machines will just set this to vt100 by default, which is generally fine. If you want, you can tell minicom to use an alternate terminal type on the client end with the -t flag.

If you're having trouble launching minicom, make sure you don't have restrictions in place in the configuration file regarding who is allowed to use the default profile.