26.3. Terminals

Contributed by Sean Kelly.

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

26.3.1. Uses and Types of Terminals

The original UNIX® systems did not have consoles. Instead, users logged in and ran programs through terminals that were connected to the computer's serial ports.

The ability to establish a login session on a serial port still exists in nearly every UNIX®-like operating system today, including FreeBSD. By using a terminal attached to an unused serial port, a user can log in and run any text program that can normally be run on the console or in an xterm window.

Many terminals can be attached to a FreeBSD system. An older spare computer can be used as a terminal wired into a more powerful computer running FreeBSD. This can turn what might otherwise be a single-user computer into a powerful multiple user system.

This section describes three kinds of terminals supported by FreeBSD: dumb terminals, computers acting as terminals, and X terminals. Dumb Terminals

Dumb terminals are specialized hardware that connect to computers over serial lines. They are called dumb because they have only enough computational power to display, send, and receive text. No programs can be run on these devices. Dumb terminals connect to a computer that has all the power to run text editors, compilers, email, games, and so forth.

There are hundreds of kinds of dumb terminals made by many manufacturers, and just about any kind will work with FreeBSD. Some high-end terminals can even display graphics, but only certain software packages can take advantage of these advanced features.

Dumb terminals are popular in work environments where workers do not need access to graphical applications. Computers Acting as Terminals

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

This configuration can be useful. For example, if one user is busy working at the FreeBSD system's console, another user can do some text-only work at the same time from a less powerful personal computer hooked up as a terminal to the FreeBSD system.

There are at least two utilities in the base-system of FreeBSD that can be used to work through a serial connection: cu(1) and tip(1).

To connect from a client system that runs FreeBSD to the serial connection of another system, use:

# cu -l serial-port-device

Where serial-port-device is the name of a special device file denoting a serial port on the system. These device files are called /dev/cuauN.

The N-part of a device name is the serial port number.


Note that device numbers in FreeBSD start from zero and not one. This means that COM1 is /dev/cuau0 in FreeBSD.


Some people prefer to use other programs available through the Ports Collection, such as comms/minicom. X Terminals

X terminals are the most sophisticated kind of terminal available. Instead of connecting to a serial port, they usually connect to a network like Ethernet. Instead of being relegated to text-only applications, they can display any X application.

This chapter does not cover the setup, configuration, or use of X terminals.

26.3.2. Configuration

This section describes how to configure a FreeBSD system to enable a login session on a terminal. It assumes that the kernel is configured to support the serial port to which the terminal is connected and that the terminal is connected.

The init process is responsible for all process control and initialization at system startup. One of the tasks performed by init is to read /etc/ttys and start a getty process on the available terminals. The getty process is responsible for reading a login name and starting the login program.

To configure terminals for a FreeBSD system, the following steps should be taken as root:

  1. Add a line to /etc/ttys for the entry in /dev 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 /etc/gettytab.

  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 /etc/ttys.

As an optional step, create a custom getty type for use in step 2 by making an entry in /etc/gettytab. For more information, refer to gettytab(5) and getty(8). Adding an Entry to /etc/ttys

/etc/ttys lists all of the ports on the FreeBSD system which allow logins. For example, the first virtual console, ttyv0, has an entry in this file, allowing logins on the console. This file also contains entries for the other virtual consoles, serial ports, and pseudo-ttys. For a hardwired terminal, list the serial port's /dev entry without the /dev part. For example, /dev/ttyv0 would be listed as ttyv0.

A default FreeBSD install includes an /etc/ttys with support for the first four serial ports: ttyu0 through ttyu3. When attaching a terminal to one of those ports, this file does not need to be edited.

Example 26.1. Adding Terminal Entries to /etc/ttys

This example configures two terminals: a Wyse-50 and an old 286 IBM PC running Procomm terminal software emulating a VT-100 terminal. The Wyse is connected to the second serial port and the 286 to the sixth serial port on a multiport serial card. The corresponding entries in /etc/ttys would look like this:

ttyu11 "/usr/libexec/getty std.38400"2 wy503 on4 insecure5 ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure


The first field normally specifies the name of the terminal special file as it is found in /dev.


The second field is the command to execute for this line, which is usually getty(8). getty initializes and opens the line, sets the speed, prompts for a user name, and then executes login(1).

The getty program accepts one (optional) parameter on its command line, the getty type. A getty type configures characteristics on the terminal line, like bps rate and parity. getty reads these characteristics from /etc/gettytab.

/etc/gettytab contains many entries for terminal lines, both old and new. In almost all cases, the entries that start with the text std will work for hardwired terminals as these entries ignore parity. There is a std entry for each bps rate from 110 to 115200. gettytab(5) provides more information.

When setting the getty type in /etc/ttys, make sure that the communications settings on the terminal match.

For this example, the Wyse-50 uses no parity and connects at 38400 bps. The 286 PC uses no parity and connects at 19200 bps.


The third field is the type of terminal usually connected to that terminal line. For dial-up ports, unknown or dialup is typically used since users may dial up with practically any type of terminal or software. Since the terminal type does not change for hardwired terminals, a real terminal type from termcap(5) can be used in this field.

For this example, the Wyse-50 uses the real terminal type while the 286 PC running Procomm will be set to emulate at VT-100.


The fourth field specifies if the port should be enabled. If set to on, the init process will start the program in the second field, getty. If this field is set to off, there will be no getty, and hence no logins on the port.


The final field is used to specify whether the port is secure. Marking a port as secure means that it is trusted enough to allow root, or any account with a UID of 0, to login from that port. Insecure ports do not allow root logins. On an insecure port, users must login from unprivileged accounts and then use su(1) or a similar mechanism to gain superuser privileges.

It is highly recommended to use insecure, even for terminals that are behind locked doors. It is quite easy to login and use su when superuser privileges are needed. Force init to Reread /etc/ttys

After making any changes to /etc/ttys, send a SIGHUP (hangup) signal to the init process to force it to re-read its configuration file:

# kill -HUP 1


init is always the first process run on a system, therefore it will always have a process ID of 1.

If everything is set up correctly, all cables are in place, and the terminals are powered up, then a getty process should be running on each terminal and login prompts should be available on each terminal.

26.3.3. Troubleshooting the Connection

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

Make sure the terminal and FreeBSD agree on the bps rate and parity settings. For a video display terminal, make sure the contrast and brightness controls are turned up. If it is a printing terminal, make sure paper and ink are in good supply.

Make sure that a getty process is running and serving the terminal. For example, to get a list of running getty processes with ps, type:

# ps -axww|grep getty

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

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

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

If the getty process is running but the terminal still does not display a login prompt, or if it displays a prompt but will not accept typed input, the terminal or cable may not support hardware handshaking. Try changing the entry in /etc/ttys from std.38400 to 3wire.38400, then run kill -HUP 1 after modifying /etc/ttys. The 3wire entry is similar to std, but ignores hardware handshaking. The baud rate may need to be reduced or software flow control enabled when using 3wire to prevent buffer overflows. If Garbage Appears Instead of a Login Prompt

Make sure the terminal and FreeBSD 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 and the Password Appears When Typed

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

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.

Send questions about this document to <freebsd-doc@FreeBSD.org>.