![[OpenBSD]](../images/smalltitle.gif){kind=small}
[FAQ Index] [To Section 6 - Networking] [To Section 8 - General Questions]
Most modern OpenBSD platforms use the wscons(4) console driver.
With wscons(4) consoles, 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"
For the alpha, amd64 and i386 platforms, OpenBSD provides wsmoused(8), a port of FreeBSD's moused(8). It can be enabled automatically at startup by copying and editing the appropriate line from rc.conf to rc.conf.local(8).
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.
Users needing this functionality may wish to use tmux instead, which provides scroll back and many other functions on all platforms.
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:
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.wsconscfg -t 80x25 6
Note that you will not get a "login:" prompt on the newly-created virtual console unless you set it to "on" in /etc/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).
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:
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 [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 also be entered at the command prompt, as root, or (better) using sudo(8).
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.
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.
Terminal sessions are controlled by the /etc/ttys file. Before OpenBSD will give you a "login:" prompt at a device, it has to be enabled in /etc/ttys, after all, there are other 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" activates the
getty
for that serial port so that a "login:" prompt will be
presented, the "secure" permits a root (uid 0) login at this
console (which may or may not be what you desire), and the
"9600" 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.
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 floppy, 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.
ok setenv input-device ttya
ok setenv output-device ttya
ok reset
If the keyboard and monitor (ttyC0) are active in /etc/ttys
(above), you can use the keyboard and monitor
in X.
ok setenv output-device scca
ok setenv input-device scca
ok reset-all
Set your serial console to 57600bps, 8N1.
# wsconsctl display.screen_off=60000
display.screen_off -> 60000
or set them permanently by editing
/etc/wsconsctl.conf
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".
Virtually all Unix commands and user names are entered using all lowercase. However, some very old terminals were only capable of uppercase characters, making them difficult, if not impossible, to use with Unix. As a workaround, if you entered your user name in all uppercase, getty(8) would assume your terminal was "lowercase challenged", and simply interpret everything you type as lowercase, while echoing it as uppercase. If you have a mixed-case or uppercase password, this will make login impossible.
Hitting CTRL-D at the login prompt will cause getty(8) to terminate, and init(8) will relaunch a new one, which will accept uppercase and lowercase properly.
For those not familiar with these programs, tmux is a terminal multiplexer. This is a program which allows a number of other processes to share the same screen for input and output. In tmux, such a collection of programs is known as a session, with each program contained in a tmux window.
In addition to sharing the terminal, tmux lets you detach a session and its windows from the screen, leave them continue running in the background, and later reattach them to the same or to a different screen. A session may be detached manually or through an unexpected event such as network disconnection, in either case the programs survive and continue running as normal.
tmux also has many other features such as splitting a single window into multiple sections (known as panes), a history of text printed in each window, copying and pasting text between windows, configurable key bindings, and terminal locking. Take a look at the tmux(1) man page for further information.
The first step is to run tmux:
$ tmux
This starts a new tmux with a single new session (called "0") and creates a client displaying it on screen. Most of the screen will show a window containing a shell prompt, and you will notice the last line is occupied by a status line. This shows the name of the session in square brackets on the left, the window title (normally empty for shells) and the time on the right, and a summary of the current open windows in the middle. In your new session, the currently open windows will contain one entry, for example:
0:ksh*
A brief aside regarding terminals: on OpenBSD, applications are made aware of the capabilities of the terminal by the TERM environment variable. This is set to the name of an entry in the terminfo(5) database and tells programs that the terminal, for example, supports colour, or has the ability to insert lines, or many other things. An important thing to note is that the "xterm" entry in the database does not include colour, so tmux will not use colour in xterm by default, TERM should be set to "xterm-xfree86" instead if colour is desired (the "XTerm*termName" X resource may be set in .Xdefaults to use this for all xterms). It is also important that TERM in shells started inside tmux is set to "screen" or programs run from them may not display correctly - tmux will set this itself, but care should be taken not to override it in shell startup files.
Returning to the status line, the number "0" is the window index, "ksh" the name of the window, and the "*" indicates this is the current window displayed above the status line. Any typing is passed on to the shell and any output displayed. For example, if you start "top":
$ top
It will run as normal, occupying the part of the screen above the status line. You may also notice that the window name in the status line has changed from "ksh" to "top" - tmux renames windows to reflect the program currently running in them.
Now, let's say you want to detach tmux from the screen and return to the original shell from which you started it. A tmux session may be detached by first pressing the Ctrl and b keys together, and then the d key. The Ctrl-b key combination (shortened in tmux and its man page to "C-b") is known as the prefix key and is used to tell tmux that the next key pressed is an instruction that it should perform some action, rather than passing the key through to the program in the window.
After pressing Ctrl-b d and returning to the shell prompt, reattach the tmux session using the "attach" command:
$ tmux attach
The tmux session will reappear, with the status line and "top" still happily running. (If you instead run tmux again without arguments, a second session will be created, named "1".)
Next, let's create a second window. This is done using the "c" key: press the prefix key, Ctrl-b, then the "c" key. A new window will be created and again a shell prompt displayed on screen. The status line will be updated to show the new window:
0:top- 1:ksh*
The "-" after "top" shows the previously current window (the last window). Pressing Ctrl-b c again creates another new shell:
0:top 1:ksh- 2:ksh*
There are several commands for moving between windows. From window 2, you can move the previous window, number 1, by typing Ctrl-b p. Ctrl-b n moves to the next window: in this case, there is no window 3 so the current window wraps to window 0. You can also press Ctrl-b w to get an interactive menu of open windows, Ctrl-b l to move to the last window (the one marked with "-"), or Ctrl-b 0 to move to window 0, Ctrl-b 1 for window 1 and so on up to Ctrl-b 9 for window 9. So, to get back to "top" in window 0, you can press Ctrl-b 0 to go directly to window 0, Ctrl-b p twice to move via window 1, Ctrl-b n to wrap from window 2 to window 0, or press Ctrl-b w and select window 0 from the list.
Sometimes you may want to create a window running a program directly, without using a shell first. This can be done from the tmux command prompt. Pressing the Ctrl-b : key sequence changes the status line to display a ":" prompt at which commands may be entered. All the tmux commands are documented in the man page. In this case the "new-window" command is needed. Each command has a shorthand alias which may be used instead of typing the full name, for "new-window" this is "neww". So, to create a new window running tetris(6), type:
neww tetris
The new window will close when tetris exits, or may be forcibly killed using the Ctrl-b & key binding. This will first prompt for confirmation and if given, close the window and terminate the program running in it.
Another common requirement is renaming a window. This can be done with the Ctrl-b , key binding. The status line will change to display a "(rename-window)" prompt at which the new name may be entered. Renaming a window turns off automatic renaming for that window, to reenable that feature, press Ctrl-b : to get to the command prompt and enter the following (more on what this means is in the next section):
setw -u automatic-rename
One other important key is worth remembering: Ctrl-b ?. This will show a list of all the tmux keys and the commands they execute. For example, Ctrl-b ? shows that the c key is bound to the "new-window" command and the n key to the "next-window" command.
Many users want to customise the way tmux looks or behaves. This is done through the configuration file, ~/.tmux.conf. This file is a list of tmux commands which are executed when tmux is initially started, before the first session is created. All tmux commands are documented in the man page, but a few common examples you might want to put in your configuration file are discussed below.
The most common requirement is setting options. There are two types of option in tmux: session options and window options. Session options control the behaviour of a session and window options of an individual window. For both there is a set of global options. When tmux comes to decide on an options value for a particular session or window, it looks first at the options local to that window; if the option has not been set, the global option value is used.
Session options are set with the "set-option" (alias "set") command and window options with the "set-window-option" command (alias "setw"). To set a global option, use the "-g" flag, if this is left out the option is set for the current window or session. These commands also accept a few other flags, such as "-u" to unset a local option and allow a window or session to inherit the global option again.
In the configuration file, it is usual to set global options. Let's look at some examples customising the status line:
set -g status-bg blue set -g status-right '#(sysctl vm.loadavg)' setw -g window-status-current-attr underscore
Putting these three commands in .tmux.conf and restarting tmux changes the status line background to blue, puts the current load average on the right side and underlines the current window. The status line may be turned off entirely with:
set -g status off
There are a large number of other options; another handy one is changing to vi(1)-style key bindings at the command prompt and in the window list and other tmux interactive modes:
set -g status-keys vi setw -g mode-keys vi
The current options and their values may be listed with the "show-options" and "show-window-options" commands. Like the set commands these accept "-g" to show the global options.
Another common task for the configuration file is adding or modifying tmux command key bindings, that is the commands that are executed after you press Ctrl-b with another key. These are added or changed with the "bind-key" command (alias "bind") and removed with the "unbind-key" command (alias "unbind"). Two examples of using "bind-key" are:
bind C-d detach bind / neww 'exec top'
The first line creates a binding for Ctrl-b Ctrl-d to detach tmux, the same as the default Ctrl-b d, and the second binds Ctrl-b / to create a new window running top.
Many people like to use a different prefix key than Ctrl-b. This can be achieved using both the "set-option" and key binding commands to alter the prefix key option and change so that pressing the prefix twice continues to pass the same key through to the window. To change the prefix key to Ctrl-a:
set -g prefix C-a unbind C-b bind C-a send-prefix
The final useful thing to do in the configuration file is to create an initial set of windows when tmux starts. This is slightly more complicated than the previous examples. In tmux, a session cannot have no windows, and you cannot create windows without a session. So, to have windows created by the configuration file you must first create a session to contain them. For example (note that "new" is the alias for the "new-session" command):
new -d 'exec top' neww -d neww -d
These commands create a new session with "top" running in the first window, then create two additional windows. The "-d" flags instruct tmux not to try to attach the new session or to make the new windows the current window. Before putting these lines into .tmux.conf, there is one other issue. When executed without arguments, tmux runs the "new-session" command, so when starting tmux with "tmux" from the shell, the configuration file tells tmux to create one session, then the command from the shell tells it to create another, so you end up with two sessions. To avoid this, tmux should be started with "tmux attach" when creating a session from the configuration file - this means it will create the session from .tmux.conf then immediately attach to it without creating a second session.
This section briefly covers some of the more advanced features available in tmux. See the man page for more information.
In tmux, you can copy and paste text between windows. This is done by copying the text in copy mode and then pasting it with the paste command. To enter copy mode, press Ctrl-b [. In copy mode (with the "mode-keys" window option set to emacs, for vi keys see the man page) the arrow keys may be used to position the cursor, Ctrl-Space starts the selection and Ctrl-w copies. You can also use Page Up, Page Down, Ctrl-a and Ctrl-e to move the cursor around. Press q or Escape to exit copy mode. After that, Ctrl-b ] will paste the copied text into the current window as if you had typed it directly.
tmux is quite scriptable, and most commands that may be entered from the command prompt or bound to a key may be executed from the shell. Almost all tmux commands accept an optional "-t" argument which specifies the session or window on which to act. For example, this command:
will kill window 1 in session 0. And:$ tmux kill-window -t0:1
$ tmux new-window -tmysession
creates a new window in the session named "mysession". Many commands accept other arguments, for example the "new-window" command accepts a "-n" option to give the name of the new window, and "new-session" accepts several arguments to specify the attributes of the initial window created with the session. These arguments may naturally be used when a command is bound to a key or executed from the command prompt as well.
Another useful feature is the ability to split a single window into several sections, called panes. You can split a window vertically (top to bottom) with the Ctrl-b " key combination. A pane can be resized up or down with Ctrl-b Alt-Up and Ctrl-b Alt-Down and the active pane changed with Ctrl-b o. In addition, a window split in that way may be changed into one of a number of fixed layouts, these are cycled through with Ctrl-b Space but panes in one of these layouts may not be resized. In -current, splitting has been extended to support horizontal splitting (Ctrl-b %) and the fixed layouts changed so they are applied once (with the same Ctrl-b Space key strokes) but then may be freely resized and modified both horizontally and vertically.
[FAQ Index] [To Section 6 - Networking] [To Section 8 - General Questions]