Using Tmux

Tmux is a terminal multiplexer, enabling a number of terminals to be created, accessed, and controlled from a single screen. Tmux may be detached from a screen, continue running in the background, and then later reattached, even after logging out from CARC systems.

Some use cases for tmux on CARC systems are:

• Backgrounding long-running data transfers
• Splitting the screen of one terminal into "panes" for interactive jobs
  • For developing scripts and programs interactively
  • For process monitoring
• Saving terminal sessions
• Restarting dropped terminal sessions

Using tmux on CARC systems

Begin by logging in. You can find instructions for this in the Getting Started with Discovery or Getting Started with Endeavour user guides.

You can use tmux by loading a corresponding software module. For example:

module load gcc/11.3.0 tmux/3.3a

A tmux process is unique to a node, so if you're using tmux on a login node, make sure to always log in to the same login node if you want to reattach to previous tmux sessions. Instead of logging in to discovery.usc.edu or endeavour.usc.edu, choose a specific login node:

• discovery1.usc.edu
• discovery2.usc.edu
• endeavour1.usc.edu
• endeavour2.usc.edu

The tmux module sets the TMUX_TMPDIR to a /scratch1/<username>/tmux/<hostname> directory. All tmux session information will be saved here. You can set this variable manually, after loading the module, if you want to save the session information to a different location.

Also keep in mind that login nodes are rebooted every so often, such as during maintenance periods. If you want to keep tmux session information across reboots, then you would need to use a plugin like Tmux Resurrect.

To see the manual page, enter man tmux.

Basic tmux workflow

After loading the module, tmux can be used on a login or transfer node as well as on a compute node during an interactive job.

A typical tmux workflow looks like the following:

1. Start a new session
2. Work
3. Detach from session
4. Reattach to session
5. Work (return to step 3 if needed)
6. End session

Start a new session

To start a new named session, enter:

tmux new -s <name>

Make sure to use a descriptive session name.

If you want to use tmux with an interactive job, first start a new tmux session on a login node, and then use salloc from within that session to start an interactive job. This will keep the job running even if you detach from the session and log out (e.g., disconnections). For general information on jobs, see our Running Jobs user guide.

Work

After the tmux session opens, you can then run a process, develop scripts or programs, etc.

The following table describes some useful key bindings:

Detach from session

To detach from a tmux session, use the key binding Ctrl+B then D. This will return you to the original shell where you started the tmux session.

Reattach to session

At a later time, even after logging out of CARC systems, you can reattach to a previous tmux session as long as you are on the same login or transfer node where the tmux session was created. If you only have one previous tmux session, to reattach simply enter:

tmux a

If you have multiple sessions, first list the sessions:

tmux ls

Then use the session name or ID to reattach to that session:

tmux a -t <name>

End session

Once you are done with a session, you can end the session by entering exit or using the key binding Ctrl+D from within the session (multiple times if you have multiple panes open).

Alternatively, from outside the tmux session, enter:

tmux kill-session -t <name>

Customizing tmux

The look and behavior of tmux can be customized by creating and modifying the configuration file ~/.tmux.conf. For more information, see the following guide: https://www.hamvocke.com/blog/a-guide-to-customizing-your-tmux-conf/.

There are also a number of tmux plugins available. For more information, see the tmux plugin manager: https://github.com/tmux-plugins/tpm.

Additional resources

If you have questions about or need help with tmux, please submit a help ticket and we will assist you.

Tmux source code
Tmux documentation
Tmux cheat sheet
Tmux plugin manager

Tutorials:

Getting Started guide
A Quick and Easy Guide to tmux
A Guide to Customizing your tmux.conf

Web books:

The Tao of tmux