The command tmux lets you manage several shell sessions from a single terminal. This has two main benefits:

1. If your connection to the Platform R login computer is interrupted, such as if it times out, or if your WIFI connection drops you, you can reconnect to the running sessions without losing any work.
2. You can have several shell sessions open, and move easily between them, without having to open several terminal windows.

Once a tmux session is running, the majority of commands to control it are given with Ctrl + b followed by some other character or characters.

Starting and Stopping

To start a new tmux session use the command: tmux new -s name where name is some meaningful name for the session. In the example below I used the name "kb-demo" which shows up in the mode line at the bottom of the terminal of a running tmux session.

You can disconnect from the session with Ctrl + b then d. The command tmux ls will now show you that you have one session running:

kb-demo: 1 windows (created date-and-time)

You reattach to your existing session with the command tmux attach. If you have more than one session running, you can specify the session you need with tmux attach -t name. For this example I would use tmux attach -t kb-demo

To exit a tmux session, you can quit the shell with the shell command exit, or you can use Ctrl + d (note, not with Ctrl + b in this instance).

TMUX Windows

In addition to preserving active shells after a disconnection, tmux can be used to create several active shell sessions which you can navigate between using tmux keyboard commands. This is useful if you do not have the space to create numerous separate terminals.

To create a new window use Ctrl+ b then c. After you have created this new window you will see in the mode line that there are two bash windows, numbered 0 and 1, both with the same name.

You can switch between windows with Ctrl + b then number. For example, I can switch to my original tmux shell with Ctrl + b then 0.

You can give a more meaningful name to the current active window with Ctrl + b then , (a comma) which will open up a input field to enter a new name.

Using tmux Windows to Profile a Workflow

This example demonstrates how to use tmux to profile a simple program. In the case of an actual workflow, it is useful to run tools such as htop to learn your work's memory and CPU requirements so you can set correct options for slurm batch files.

From the slurm login host, start a new tmux session, tmux new -s profile

From within the new tmux session, connect to an available compute node with srun --ntasks=1 --pty bash -i 

Once this has connected, note that the name of the base window is "srun," to reflect that this command is running. For clarity, rename the window "workflow" with Ctrl + b then ,(a comma).

Note the host that the srun command has connected you to. In this example, it is pr-sett-002 (if your shell prompt doesn't tell you this, you can use the command hostname). It will be something different if you run this example yourself.

Start a new tmux window with Ctrl + b then c. Rename this new window "htop." Your modeline should look similar to this:

Next run this command, changing "pr-sett-002" to whatever hostname you get when you run the example. This connects you to the same machine as your other session:

srun --ntasks=1 -w pr-sett-mmm --pty bash -i

When the srun command has connected run this command, which will give you the performance usage of just your own programs (use your own NetID): htop -u NetID

You will see something similar to this:

Next, switch to the "workflow" window, Ctrl + b then 0. From there run the following command, which will simply use up a single CPU for 30 seconds:

timeout 30 yes > /dev/null

Then switch to the "htop" window, Ctrl + b then 1, and note that the yes command is using close to 100% of a single CPU. When the time reaches 30 seconds, the yes command will stop.

Use the q key to quit out of htop, and you can use exit to leave your srun sessions and tmux shells (four times in total to exit all shells and tmux itself).

Command Summary

Command Line

The parts in parentheses are optional for the command.

• tmux new (-s name): start a new session
• tmux ls: show existing sessions
• tmux attach (-t name): reattach to a session

Keyboard Commands

• Ctrl + b then d: detach session
• Ctrl + d: quit session and all tmux windows
• Ctrl + b then c: create a new tmux window
• Ctrl + b then a number: switch to a different tmux window
• Ctrl + b then w: shows all windows, and you can use arrow keys to select the window you want to switch to

Related Documentation

• The Getting Started page from the tmux developers goes into much more detail.