OpenBSD FAQ - Keyboard and Display Controls [FAQ Index]



Remapping the keyboard

OpenBSD uses the wscons(4) console driver.

Most options can be controlled using the wsconsctl(8) utility. For example, to change keymappings with wsconsctl(8), one would execute the following:

# wsconsctl keyboard.encoding=uk
In the next example, we will remap "Caps Lock" to be "Control L" (the left control key):
# wsconsctl keyboard.map+="keysym Caps_Lock = Control_L"

Console mouse support

For the alpha, amd64 and i386 platforms, OpenBSD provides wsmoused(8). It can be enabled automatically at startup by with the rcctl(8) utility.

Accessing the Console Scrollback Buffer

On a few platforms and hardware combinations, OpenBSD provides a console scrollback buffer. This allows you to see information that has already scrolled past your screen. To move up and down in the buffer, simply use the key combinations [SHIFT]+[PGUP] and [SHIFT]+[PGDN].

The default scrollback buffer, or the number of pages that you can move up and view, is 8. This is a feature of the vga(4) driver, so it will not work without a VGA card on any platform (many Alpha systems have TGA video), or on hardware that uses drm(4).

Due to space limitations, the install kernels do not provide the scrollback function. Switching consoles will clear the scrollback buffer.

Switching consoles

On amd64, i386 and Alpha systems with vga(4) cards, OpenBSD provides six virtual terminals by default, /dev/ttyC0 through /dev/ttyC5. ttyC4 is reserved for use by the X Window system, leaving five text consoles available. You can switch between them using [CTRL]+[ALT]+[F1], [CTRL]+[ALT]+[F2], [CTRL]+[ALT]+[F3], [CTRL]+[ALT]+[F4] and [CTRL]+[ALT]+[F6].

The X environment uses ttyC4, [CTRL]+[ALT]+[F5]. When using X, the [CTRL]+[ALT]+[Fn] keys will take you to the text screens; [CTRL]+[ALT]+[F5] will take you back to the graphical environment.

If you wish to have more than the default number of virtual consoles, use the wsconscfg(8) command to create screens for ttyC6, ttyC7 and above. For example:

# wsconscfg -t 80x25 6
This will create a virtual terminal for ttyC6, accessed by [CTRL]+[ALT]+[F7]. Don't forget to add this command to your rc.local(8) file if you want the extra screen the next time you boot the computer.

Note that you will not get a login: prompt on the newly created virtual console unless you set it to "on" in ttys(5), and either reboot or send init(8) a HUP signal using kill(1).

On the Zaurus, two virtual terminals (/dev/ttyC0 and /dev/ttyC1) are available by default, accessible with [ALT]+[CALENDAR] and [ALT]+[ADDRESS] (The [ALT] key is the one right of the left [CTRL] key).

Changing console font and resolution

amd64, i386, and Alpha users with VGA but non-drm(4) display adapters normally get a console screen of 25 lines of 80 characters. However, many VGA video cards are capable of displaying a higher text resolution of 50 lines of 80 characters.

First, a font that supports the desired resolution must be loaded using the wsfontload(8) command. The standard 80x25 text screen uses 8x16 pixel fonts; to double the number of lines we will have to use 8x8 pixel fonts.

After that, we will have to delete and recreate a virtual console at the desired screen resolution, using the wsconscfg(8) command.

This can be done automatically at boot by adding the following lines to the end of your rc.local(8) file:

wsfontload -h 8 -e ibm /usr/share/misc/pcvtfonts/vt220l.808
wsconscfg -dF 5
wsconscfg -t 80x50 5
As with any modification to your system configuration, it is recommended you spend some time with the man pages to understand what these commands do.

The first line above loads the 8x8 font. The second line deletes screen 5 (which would be accessed by [CTRL]+[ALT]+[F6]). The third line creates a new screen 5 with 50 lines of 80 characters each. If you do this, you will see your primary screen, and the other three default virtual consoles, come up in the standard 80x25 mode, but a new screen 5 at 80x50 accessible through [CTRL]+[ALT]+[F6].

Remember that [CTRL]+[ALT]+[F1] is screen 0 (ttyC0). If you wish to alter other screens, simply repeat the delete and add screen steps for whichever screens you want running at the 80x50 resolution.

You should avoid changing screen 4 (ttyC4, [CTRL]+[ALT]+[F5]), which is used by X as a graphical screen. It is also not possible to change the resolution of the primary console device (i.e., ttyC0).

As one might expect, all these commands can be run as root at the console.

Note: this will not work on all video cards. Unfortunately, not all video cards support the uploaded fonts that wscons(4) requires to achieve the 80x50 text mode. In these cases, you might wish to consider running X. Cards supported by the drm(4) driver will have a higher resolution anyway, but can not use these uploaded fonts.

Configuring a serial console

There are many reasons you may wish to use a serial console for your OpenBSD system: OpenBSD supports serial console on most platforms, however details vary greatly between platforms.

Note that serial interfacing is NOT a trivial task -- you will often need unusual cables, and ports are not standardized between machines, in some cases, not even consistent on one machine. It is assumed you know how to select the appropriate cable to go between your computer and the device acting as your serial terminal. A full tutorial on serial interfacing is beyond the scope of this article, however, we offer one hint: just because the ends plug in doesn't mean it will work.

/etc/ttys change

There are two parts to getting a functional serial console on an OpenBSD system. First, you must have OpenBSD use your serial port as a console for status and single user mode. This part is very platform-dependent. Second, you must enable the serial port to be used as an interactive terminal, so a user can log into it when running multi-user. This part is fairly similar between platforms, and is detailed here.

Terminal sessions are controlled by the ttys(5) file. Before OpenBSD will give you a login: prompt at a device, it has to be enabled in /etc/ttys. After all, there are uses for a serial port other than for a terminal. In platforms which typically have an attached keyboard and screen as a console, the serial terminal is typically disabled by default. We'll use the i386 platform as an example. In this case, you must edit the line that reads:

tty00   "/usr/libexec/getty std.9600"   unknown off
to read something like:
tty00   "/usr/libexec/getty std.9600"   vt220   on secure
Here, tty00 is the serial port we are using as a console. vt220 is the termcap(5) entry that matches YOUR terminal (other likely options might include vt100, xterm, etc.). The on bit activates the getty(8) for that serial port, so that a login: prompt will be presented. The secure bit permits a root (uid 0) login at this console (which may or may not be what you desire). The 9600 bit is the terminal baud rate. Resist the urge to crank the baud rate up to the maximum your hardware can support, as you are more likely to create problems than benefit. Most systems have a "default" speed (supported by default by the boot ROM and/or the boot loader, often 9600), use this unless you have real reason to use something different.

Note that you can use a serial console for install without doing this step, as the system is running in single user mode, and not using getty for login.

On some platforms and some configurations, you must bring the system up in single user mode to make this change if a serial console is all you have available.

amd64 and i386

To direct the boot process to use the serial port as a console, create or edit your boot.conf(5) file to include the line...
set tty com0
...to use the first serial port as your console. The default baud rate is 9600bps. This can be changed with a /etc/boot.conf line using the stty option. This file is put on your boot drive, which could also be your install media, or the command can be entered at the boot> prompt from the OpenBSD second-stage boot loader for a one-time (or first time) serial console usage.

amd64 and i386 notes:

SPARC and UltraSPARC

These machines are designed to be completely maintainable with a serial console. Simply remove the keyboard from the machine, and the system will run serial.

SPARC and UltraSPARC notes

MacPPC

The MacPPC machines are configured for a serial console through OpenFirmware. Use the commands:
ok setenv output-device scca
ok setenv input-device scca
ok reset-all
Set your serial console to 57600bps, 8N1.

MacPPC notes

I get input/output error when trying to use my tty devices

You need to use /dev/cuaXX for connections initiated from the OpenBSD system, the /dev/ttyXX devices are intended only for terminal or dial-in usage. While it was possible to use the tty devices in the past, the OpenBSD kernel is no longer compatible with this usage.

From cua(4):

For hardware terminal ports, dial-out is supported through matching device nodes called calling units. For instance, the terminal called /dev/tty03 would have a matching calling unit called /dev/cua03. These two devices are normally differentiated by creating the calling unit device node with a minor number 128 greater than the dial-in device node. Whereas the dial-in device (the tty) normally requires a hardware signal to indicate to the system that it is active, the dial-out device (the cua) does not, and hence can communicate unimpeded with a device such as a modem. This means that a process like getty(8) will wait on a dial-in device until a connection is established. Meanwhile, a dial-out connection can be established on the dial-out device (for the very same hardware terminal port) without disturbing anything else on the system. The getty(8) process does not even notice that anything is happening on the terminal port. If a connecting call comes in after the dial-out connection has finished, the getty(8) process will deal with it properly, without having noticed the intervening dial-out action.

Blanking the console after a period of inactivity

If you wish to blank your console after a period of inactivity without using X, you can alter the following wscons(4) variables: You can set these variables at the command line using the wsconsctl(8) command:
# wsconsctl display.screen_off=60000
display.screen_off -> 60000
or set them permanently by editing wsconsctl.conf(5) so these changes take place at next boot:
display.vblank=on               # enable vertical sync blank
display.screen_off=600000       # set screen blank timeout to 10 minutes
display.kbdact=on               # Restore screen on keyboard input
display.outact=off              # Restore screen on display output
The blanker is activated when either display.kbdact or display.outact is set to on. Yes, one of those two must be off.