26.3. Terminals
Prev | Chapter 26. Serial Communications | Next

## 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.

#### 26.3.1.1. 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.

#### 26.3.1.2. 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/cuau`N``.

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

### Note:

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

### Note:

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

#### 26.3.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.

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).

#### 26.3.2.1. 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:

ttyu1 "/usr/libexec/getty std.38400" wy50 on insecure 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.

#### 26.3.2.2. 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`

### Note:

`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.

#### 26.3.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 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.

#### 26.3.3.2. 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`.

#### 26.3.3.3. 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.”

Prev | Up | Next
26.2. Introduction | Home | 26.4. Dial-in Service

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>.