FAQ - Keyboard and Display Controls
Remapping the keyboard
The kbd(8) utility can be used to
change the keyboard encoding.
Most keyboard options can be controlled using the
For example, to change keymappings with
one would execute the following:
Remap [Caps Lock] to be [Control L], the left control key:
# wsconsctl keyboard.encoding=uk
To make changes permanent, use the
# wsconsctl keyboard.map+="keysym Caps_Lock = Control_L"
Console mouse support
For the alpha, amd64
and i386 platforms, OpenBSD provides
It can be enabled with the rcctl(8)
See also the FAQ on the rc script.
On a few platforms and hardware combinations, OpenBSD provides a console
This allows you to see information that has already scrolled past your screen.
To move up and down in the buffer, use [SHIFT]+[PGUP] and
The number of pages that you can move up and view is 8.
Switching consoles will clear the scrollback buffer.
Due to space limitations, the install kernels do not have this feature.
This is a feature of the vga(4) driver,
so it will not work without a VGA card, or on hardware that uses
On alpha, amd64 and i386 systems with
vga(4) cards, OpenBSD provides six
virtual terminals by default, /dev/ttyC0 through /dev/ttyC5.
You can switch between them using [CTRL]+[ALT] together with
[F1] through [F6].
The virtual terminal ttyC4 is reserved for use by the X Window system,
leaving five text consoles available.
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.
This will create a virtual terminal for ttyC6, accessed by
To get a login: prompt on the newly created virtual console, you need
to set it to on in ttys(5),
and either reboot or send init(8)
a HUP signal using kill(1).
Add this command to rc.local(8)
if you want the extra screen the next time you boot the computer.
# wsconscfg -t 80x25 6 # this will not work on systems using drm(4)
Blanking the console after a period of inactivity
If you wish to blank your console after a period of inactivity without using X,
modify the following wscons(4)
determines the blanking time in milliseconds.
if set to on, keyboard activity will unblank the screen.
if set to on, console mouse
activity will unblank the screen.
if set to on, screen output will unblank the screen.
if set to on will disable the vertical sync pulse.
This will cause many monitors to go into an energy saver mode.
Set them permanently by editing
The blanker is activated when either display.kbdact or
display.outact is set to on.
Note that one of those two must be off.
# wsconsctl display.screen_off=60000
display.screen_off -> 60000
Changing console font and resolution
alpha, amd64 and i386 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
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:
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.
wsfontload -h 8 -e ibm /usr/share/misc/pcvtfonts/vt220l.808
wsconscfg -dF 5
wsconscfg -t 80x50 5
The first line above loads the 8x8 font.
The second line deletes screen 5 (which would be accessed by
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
requires to achieve the 80x50 text mode.
In these cases, you might wish to consider running X.
Cards supported by the
driver will have a higher resolution anyway, but can not use these uploaded
Configuring a serial console
There are many reasons you may wish to use a serial console for your OpenBSD
OpenBSD supports serial console on most platforms, however details vary greatly
- Recording console output (for documentation)
- Remote management
- Easier maintenance of a large quantity of machines
- Providing a useful dmesg from machines which might otherwise be difficult
to get one from
- Providing an accurate trace and ps output if your system
crashes so developers can have a chance to fix the problem
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.
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
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:
to read something like:
tty00 "/usr/libexec/getty std.9600" unknown off
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.
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
tty00 "/usr/libexec/getty std.9600" vt220 on secure
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
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
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 default baud rate is 9600bps.
This can be changed with a /etc/boot.conf line using the stty
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 of
boot(8) for a one-time serial console
set tty com0
amd64 and i386 notes:
- OpenBSD numbers the serial ports starting at tty00,
DOS/Windows labels them starting at COM1.
So, keep in mind tty02 is COM3, not COM2.
- Some systems may be able to operate without a video card in the
machine, but certainly not all -- many systems consider this an error
Some machines will even refuse to work easily without a keyboard attached.
- Some systems are capable of redirecting all BIOS keyboard and screen
activity to a serial port through a configuration option, so the machine
can be completely maintained through the serial port.
Your results may vary -- when using this feature, some BIOSs may prevent
the boot loader from seeing the serial port, and thus, the kernel will
not be told to use it.
Some BIOSs have an option to "Continue Console Redirection after POST"
(Power On Self Test), this should be set to "OFF", so the boot loader
and the kernel can handle their own console.
Unfortunately, this feature is not universal.
- PC-compatible computers are not designed to be run from a serial
console, unlike some other platforms.
Even those systems that support a serial console usually have it as a
BIOS configuration option -- and should the configuration information
get corrupted, you will find the system looking for a standard monitor
and keyboard again.
You generally must have some way to get a monitor and keyboard to your
amd64 and i386 systems in an emergency.
- You will need to edit /etc/ttys as above.
These machines are designed to be completely maintainable with a serial
Simply remove the keyboard from the machine, and the system will run serial.
- On some systems, the serial ports are labeled ttya, ttyb,
ttyh0 and/or ttyh1.
- Unlike some other platforms, it is not necessary to make any changes to
/etc/ttys to use a serial console.
- The sparc64 systems interpret a BREAK signal on the console
port to be the same as a STOP-A command, and kicks the system back to
the Forth prompt, stopping any application and operating system at that
This is handy when desired, but unfortunately, some serial terminals at
power-down and some RS-232 switching devices send something the computer
interprets as a break signal, halting the machine.
Test before you go into production.
- If you have a keyboard and monitor attached, you can still force
the serial console to be used instead by using the following commands
at the ok prompt:
If the keyboard and monitor (ttyC0) are active in /etc/ttys
(above), you can use the keyboard and monitor in X.
ok setenv input-device ttya
ok setenv output-device ttya
The MacPPC machines are configured for a serial console through OpenFirmware.
Use the commands:
Set your serial console to 57600bps, 8N1.
ok setenv output-device scca
ok setenv input-device scca
- Unfortunately, serial console is not directly possible on most MacPPCs.
While most of these machines do have serial hardware, it isn't accessible
outside the machine.
Fortunately, a few companies offer add-on devices for several Macintosh
models which will make this port available for use as a serial console
(or other uses).
Use your favorite search engine and look for "Macintosh internal serial port."
- You will have to change tty00 in /etc/ttys to
on and set the speed to 57600 instead of the default of 9600 as
detailed above in single user mode before
booting multi-user and having the serial console functional.
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
While it was possible to use the tty devices in the past, the OpenBSD kernel
is no longer compatible with this usage.
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
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.
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
process will deal with it properly, without having noticed the intervening