Hitchhiker's Guide to Openbsd

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

---

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

---

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