Hitchhiker's Guide to Openbsd

How do I use tmux?
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. 
http://www.openbsd.org/faq/faq7.html (9 of 14)9/4/2011 10:02:08 AM

---

7 - Keyboard and Display Controls
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 
http://www.openbsd.org/faq/faq7.html (10 of 14)9/4/2011 10:02:08 AM

---

7 - Keyboard and Display Controls
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.