The terminal multiplexer tmux(1)
lets you run multiple virtual terminals inside one OpenBSD terminal window. While standard virtual terminals disappear when you disconnect from the system, tmux
virtual terminals continue to run even after you disconnect. tmux
is small, fast, easy to use, and written with the same care as the rest of OpenBSD.
Why would you need tmux
? One example is for building programs. Just before I leave the office, I use my laptop to make an SSH connection into an OpenBSD server, create a virtual terminal, start building a huge program (such as OpenOffice.org), and shut down my laptop. Normally, the build on the server would terminate when my session is interrupted, but the tmux
virtual terminal continues to run even when I log out. The build continues in the disconnected virtual terminal while I drive home, and when I reconnect to it later, I can see how the build has progressed. Virtual terminal sessions even survive accidental disconnections caused by network or client failures.
This section provides an introduction to tmux
. For complete details on the features discussed here, as well as dozens of other features, read tmux(1)
.
To start a virtual terminal session, run tmux
. Your terminal window will show the command prompt and a green tmux
status bar along the bottom, with information like the following:
[0] 0:ksh* "caddis.blackhelicop" 11:55 26-Jun-13
This is a virtual terminal session. The left side of the status bar displays the tmux
session number in brackets [0]
and the list of tmux
windows 0:ksh*
(beginning with window number 0). The right side shows the first part of your machine name (caddis.blackhelicopters.org
), followed by the time and date. You’ll learn how to customize things in Setting tmux Options and Configuring tmux.
The window name defaults to the name of the program running in that tmux(1)
window. For example, if you start a command that continues until interrupted, such as iostat -w 5
, the session name will change to match the command. Interrupt the command, return to a shell prompt, and the status bar should change its name to match your shell.
The status bar is normally green, but if it turns yellow, tmux
is expecting input. When it’s yellow, any typing is interpreted as a tmux
command. If you reach this mode accidentally, press ENTER to return to a green status bar and normal operation.
Pressing CTRL-B tells tmux
that the next command is for tmux
, not for the program running in the virtual terminal. (If pressing CTRL-B interferes with another program you use frequently, you can change this key combination, as you’ll see in Unmapping and Remapping Keys.)
The most commonly used tmux
commands are single characters. For example, to create a second terminal window in this tmux
session, press CTRL-B-C. Your screen will display only a command prompt and a new status bar.
[0] 0:iostat- 1:ksh* "caddis.blackhelicopte" 11:58 26-Jun-13
You have two windows: window 0 shows iostat
output, and window 1 displays the ksh
prompt. The asterisk next to window 1 means that you’re currently looking at it. Run an ongoing command in your new window, such as top
, and the window name should automatically change to the name of that command.
To view another window, use one of the following key combinations:
To see the next window, press CTRL-B-N.
To switch to the previous window, press CTRL-B-P.
Keep in mind that window ordering wraps. For example, if you are on the last window and press CTRL-B-N, you should see the first window.
To jump directly to a window by number, press CTRL-B followed by the window number.
To open a menu of all windows, press CTRL-B-W, and then select a window with the arrow keys.
I find the next and previous sequences sufficient, but if you end up with a dozen windows in one terminal, you might think otherwise.
Terminal windows take the name of the currently running program, but that’s not always useful. For example, if I’m compiling the newest source with make build
, the window name will continually change to reflect the command running in the build at that moment. The only problem is that the constant flickering change in my status bar drives me nuts.
If you don’t want to see the window name change with each command, use CTRL-B to assign a static name to the window. A yellow [rename-window]
prompt will appear in the status bar. Enter your preferred window name, such as upgrade
, and then press ENTER.
To kill a window and end any processes running in it, change to that window and press CTRL-B-&. You will get a confirmation prompt.
Press CTRL-B-? to see a complete list of all tmux
commands.
C-b: send-prefix C-o: rotate-window C-z: suspend-client Space: next-layout !: break-pane ": split-window #: list-buffers …
Now you can easily explore tmux
without reading the manual page. You’ll use this list to remap keys in Unmapping and Remapping Keys.
A collection of tmux
windows is called a session. Conveniently, tmux
can disconnect from a running session without interrupting its windows. Press CTRL-B-D to disconnect your terminal from the current tmux
session. Your terminal should now show what it held before starting tmux
. To reconnect to your tmux
session, run tmux attach
.
You can have multiple tmux
sessions simultaneously. The session number appears on the far left of the status bar. (In our sample status bars, the tmux
session is 0.)
To start a new tmux
session without attaching to your previous session, run tmux
without any arguments. For example, I type tmux
instead of tmux attach
in order to spawn a new tmux
session when I want to pick up where I left off. You can change your tmux
session within tmux
itself, using a tmux
command, but I usually just end the session and enter the correct command.
If you can have all these tmux
sessions, how can you be sure that you haven’t left old, useless sessions lying around, with abandoned commands running in them? Use tmux list-sessions
.
$ tmux list-sessions
0: 4 windows (created Sun Feb 13 12:17:14 2011) [80x23]
2: 1 windows (created Mon Feb 21 21:57:59 2011) [131x36] (attached)
I can see from the last line of this output that I left session 2 running on my other workstation, and am still attached to it.
To connect to session 2, use attach-session
and option -t
to choose a target session. Here, I attach to tmux
session 2:
$ tmux attach-session -t 2
I’m now connected to the same session from two separate SSH sessions—in this case, from two separate client workstations. My typing in one screen is echoed on the other.
To destroy a session, use the kill-session
command, specifying the session number with -t
. Here, I kill tmux
session 2:
$ tmux kill-session -t 2
Any programs running in windows in tmux
session 2 will also be killed.
Command mode in tmux
offers a prompt for entering more complicated commands. To enter command mode, press CTRL-B-:. The status bar will turn yellow, and a single colon replaces all window names. For example, to create a new window dedicated to running systat(1)
, press CTRL-B-: and enter neww systat
. A window named systat
will appear. Switch to that window, and then press CTRL-C to stop systat
. That window will disappear.
You can do all sorts of things with tmux
commands, including split windows into multiple panels, copy and paste text, and so on. (Read tmux(1)
for the full list.) If you want to cut and paste from one window to another, it’s easiest if you use multiple terminal windows, but if you are working in a text-only console or another restricted environment, you might find these tmux
features useful.
Options change how tmux
windows, sessions, and the tmux
server itself behave. The most common changes involve the appearance of windows, colors, or items displayed in the status bar. Some options affect the entire tmux
session; others affect only a specific window. You can change options on the fly with the tmux
command set-option
.
Go ahead and open a tmux
session to follow along. Press CTRL-B-: to enter command mode. When the colon appears, enter set-option status-fg green
, and then press ENTER. Your status bar should now be solid green bar. Congratulations! You’ve set the status bar text color identical to the background color, making it unreadable. Return to command mode, and change the color to black to make it readable again. (If this bugs you, you can kill this tmux
session and start a new one to reset all options.)
When making changes, use set-option
(or just set
) for options that affect the tmux
server and the entire session. Use set-window-option
(abbreviated setw
) for options that affect only a single window.
Most people won’t need many (if any) tmux
options, but they can prove useful. For example, say you want the status bar clock to display time in 24-hour format, or you want a visual bell instead of a beep. Options let you control these behaviors, as well as run commands in the status bar. To change basic tmux
appearance and behavior, see the options in tmux(1)
.
Be sure to try any interesting options interactively. Once you have a tmux
session running the way you like, enter show-options
for an accurate list of the current options. Copy that list because we’ll use it to build a configuration file.
Modify $HOME/.tmux.conf in your home directory to configure your tmux
sessions, or use /etc/tmux.conf to inflict your tmux
preferences on every system user. Personal tmux
configurations override global settings.
As a simple example, I’ve set the left side of my status bar (containing the session number) to blue, and the right side (the hostname, time, and date) to red. If I decide I like this, I can make this change permanent by entering the following in tmux.conf:
set -g status-left-bg blue set -g status-right-bg red
The -g
flag sets an option globally, so it takes effect for all sessions and windows.
This should get you comfortable with using tmux
. If you need multiple terminal windows simultaneously, use a graphical desktop. Stay tuned.