tmux

tmux is a "terminal multiplexer" similar to screen that permits multiple terminal sessions in one window (in a manner not unlike tiling window managers). It is potentially useful for several reasons: it can be used to work with multiple programs in a single SSH session or create persistent sessions that can be accessed from any computer and will not stop if the connection is lost. These features are particularly useful to those who like to work from home or have multiple computers. They are also available with the graphical tool FastX if you prefer a graphical interface.

It is important to note that cluster interactive nodes' usage policies still apply when using tmux. More information can be found in the General HPC Cluster Policies page. If you will be running long tasks or consuming extensive resources, you must use a compute node. If you are performing interactive graphical work, consider using the frisco nodes in place of cluster interactive nodes.

September 4, 2024 update to tmux in the Protected Environment

Users may utilize tmux for applications that need to persist through idle session termination. Please note that to have tmux session persist the idle session termination, it needs to be started up a bit differently:

systemd-run --scope --user tmux

We have set up a system alias to help users to have quick access to these: pe-tmux will be defined on fresh logins.

Users are encouraged to make their own according to the parameters they would like to use with either tool. Starting a tmux session without these will result in it being terminated with the idle session timeout. The CHPC documentation for these commands will be updated to include the extra details to start a tmux session in the PE.

On this page

The table of contents requires JavaScript to load.

Starting Sessions and Running Commands

tmux can be started by running the tmux command. When running, tmux can be identified by a green status bar at the bottom of the terminal window. The commands available in tmux can be seen with Ctrl+b followed by the ? character or through the manual, which provides more extensive coverage. (The keyboard shortcut Ctrl+b is the "prefix" for most commands.) The q key can be used to close the list of commands.

Controlling Sessions

You can see the sessions you have open with tmux ls.

$ tmux ls
0: 2 windows (created Thu Apr 19 12:00:00 2018) [100x24]

You can reconnect to a session with tmux a -t <id>. For example, to connect to the session above, use tmux a -t 0. When an ID is not specified, the last session will be opened. To create a new session, use tmux; to create a session with a name (in place of the "0" in the previous example), use tmux new -s <name>. In this way, you can differentiate sessions if you have multiple open.

To close a tmux session, you can exit as you would in a standard terminal session. If, instead, you would like to keep the session to reconnect later, you can "detach" with the prefix followed by d. (Please remember to close the session when you are done!)

Interpreting Shortcuts

An example of the commands visible in the help menu (Ctrl+b then ?) follows.

bind-key    -T prefix !                break-pane
bind-key    -T prefix "                split-window
bind-key    -T prefix #                list-buffers
bind-key    -T prefix $                command-prompt -I #S "rename-session '%%'"
bind-key    -T prefix %                split-window -h
bind-key    -T prefix &                confirm-before -p "kill-window #W? (y/n)" kill-window
bind-key    -T prefix '                command-prompt -p index "select-window -t ':%%'"

Where "prefix" is mentioned, it refers to the bindings used to run commands (Ctrl+b by default). To split the window vertically, then, you can use the prefix followed by ". This command is equivalent to the prefix followed by :split-window. All other commands in this list follow the same convention.

Using Multiple Programs

tmux can be used to run multiple programs simultaneously in one terminal. In this way, you can avoid using multiple SSH sessions. Each tmux session contains "windows" and "panes," where a window is a group of panes (and only one is visible at a time) and a pane is an individual terminal. In the example below, for instance, two panes (split vertically) are visible. The two can be used independently.

Example tmux session with two panes visible. The top pane is currently being used.

In the above example, the top pane (terminal) is currently in-use. This can be verified visually by identifying the cursor or the green bar in the center. The border between panes is gray everywhere except the active pane, where it is green; here, since the top pane is selected, the left half of the border appears green. (The convention is that left-to-right and top-to-bottom coincide. If there is no ambiguity—borders surround a pane—the border will be green without gray segments.) When a pane is selected, all its borders become green.

A pane can be split by selecting it and entering the prefix followed by " to split vertically and the prefix followed by % to split horizontally. You can cycle through panes with o (after the prefix). To close a pane, simply exit the terminal.

Panes can be resized by specifying a direction and a scale, such as :resize-pane -L <number> to expand to the left.

Using Persistent Sessions

tmux will not close if the remote connection closes when working over SSH. Any programs you are running inside the session will also be preserved. As a result, tmux is useful to continue running a program in the background if the connection is not dependable or you must close the connection before programs finish (to work from a different computer, for example). Again, the interactive node usage policies need still be considered when doing this. FastX can be used for persistent sessions with a GUI.

To keep a tmux session running but continue working on the host, use the prefix (Ctrl+b) followed by d or the prefix followed by :detach-client instead of exiting the terminal windows. Remember to close the session (exit all the terminals in it) when you are finished.

On general CHPC cluster interactive nodes, the hostname cluster.chpc.utah.edu round-robins between two individual servers, cluster1.chpc.utah.edu and cluster2.chpc.utah.edu. When using tmux, you will need to choose one of the two nodes by using one of the individual hostnames; sessions run only on the host they were started on. You may be placed on either of the interactive nodes unless you specify one explicitly. If you started tmux on notchpeak1, for example, the session would not be available on notchpeak2 (where you might be placed by connecting to notchpeak.chpc.utah.edu).

If you have questions or would like to see a complete list of commands, please consult the documentation first (with man tmux or online).