tmux is a "terminal multiplexer", it enables a number of terminals (or windows) to be accessed and controlled from a single terminal. tmux is a great way to save an interactive session between connections you make to the clusters. You can reconnect to the session from a workstation in your lab or from your laptop from home!

Getting Started

To begin a tmux session named myproject, type

tmux new -s myproject

You should see a bar across the bottom of your terminal window now that gives you some information about your session. If you are disconnected or detached from this session, anything you were doing will still be there waiting when you reattach

The most important shortcut to remember is Ctrl+b (hold the ctrl or control key, then type "b"). This is how you signal to tmux that the following keystroke is meant for it and not the session you are working in. For example: if you want to gracefully detach from your session, you can type Ctrl+b, then d for detach. To reattach to our sample tmux session after detatching, type:

tmux attach -t myproject
#If you are lazy and have only one session running,
#This works too:
tmux a

Finally, to exit, you can type exit or Ctrl+d

Using Tmux on the clusters

Using tmux on the cluster allows you to create interactive allocations that you can detach from. Normally, if you get an interactive allocation (e.g. srun --pty, qsub -I), and then close your connection to the cluster, for example by putting your laptop to sleep, your allocation will be terminated and your job killed. Using Tmux, you can detach gracefully and tmux will maintain your allocation. Here is how to do this correctly:

1. ssh to login node
2. start tmux
3. inside tmux, do srun ....
4. inside srun (on compute node), start your application (e.g. matlab)
5. detach from tmux by doing ctrl-b d
6. later, on the same login node, reattach by doing tmux attach

Make sure to:
- run tmux on the login node, NOT the compute node
- run srun inside tmux, not the reverse.

Windows and Panes

tmux allows you to create, toggle between and manipulate panes and windows in your session. A window is the whole screen that tmux displays to you. Panes are subdivisions in the curent window, where each runs an independent terminal. Especially at first, you probably won't need more than one pane at a time. Multiple windows can be created and run off-screen. Here is an example where this may be useful.

Say you just submitted an interactive job that is running on a compute node inside your tmux session.

[be59@farnam2 ~]$ tmux new -s analysis
[be59@farnam2 ~]$ #I am in my tmux session now
[be59@farnam2 ~]$ srun --pty -p interactive bash
[be59@c23n08 ~]$ ./

Now you can easily monitor its cpu an memory utilization without ever taking your eyes off of it by creating a new pane and running top there. Split your window by typing Ctrl+b then %. ssh into the compute node you are working on, then run top to watch your work as it runs all from the same window.

[be59@farnam2 ~]$ #I'm in a new pane now.
[be59@farnam2 ~]$ ssh c23n08
[be59@c23n08 ~]$ top

Your view will look something like this:


To switch back and forth between panes, type Ctrl+b then o

More shortcuts

Customizing tmux