Long Sessions with tmux

The problem

Start a big copy or an upgrade on the server over SSH, and then the Wi-Fi drops or the laptop sleeps. The connection ends, the shell on the server ends with it, and so does whatever it was running ¹. A terminal multiplexer fixes this: it runs your shells on the server, independently of the connection, so you can disconnect and later reattach to exactly where you were ^{2 1}.

tmux is the usual one, and it’s installed on Ubuntu Server already; on the desktop, sudo apt install tmux ². It’s useful locally too, for splitting one terminal into several ³.

The prefix key

Every tmux command is two steps: press Ctrl-b, let go, then press a key ^{2 3}. Ctrl-b is the prefix; on its own it does nothing visible. Below, “Ctrl-b d” means Ctrl-b, release, then d.

Sessions: detach and attach

A session is a workspace that keeps running whether or not anyone’s looking at it, kept alive by a tmux server process on the machine ^{2 4}:

me@garden-server:~$ tmux new -s backup

starts one named backup, and you’re inside it: a shell, with a status bar along the bottom. Run things as usual. Then:

• Ctrl-b d detaches: you’re back at your ordinary shell, and the session carries on in the background ². You can log out, or lose the connection; it doesn’t matter.
• tmux ls lists sessions ².
• tmux attach -t backup (or tmux a -t backup) reattaches; plain tmux attach takes the most recent ².
• tmux kill-session -t backup ends one, or type exit in its last shell ².

Windows and panes

Inside a session, windows are like browser tabs, each a full screen with its own shell ²:

• Ctrl-b c creates a window; Ctrl-b n and Ctrl-b p go to the next and previous; Ctrl-b 0 to 9 jump by number; Ctrl-b , renames one; Ctrl-b w lists them to pick from ².

Panes split one window into several shells side by side ²:

• Ctrl-b % splits side by side; Ctrl-b “ splits top and bottom.
• Ctrl-b and an arrow key moves between panes; Ctrl-b z zooms one to full size and back ³.
• Ctrl-b x closes a pane, ending its shell ².

A typical layout on the server: the job running in one pane, journalctl -f or htop watching in another.

Scrolling back works differently in tmux, since it manages the screen itself: Ctrl-b [ enters scroll mode, then arrows or Page Up and Page Down, and q to leave ².

A worked example

Copying a photo collection to the server, which will take an hour:

me@garden-laptop:~$ ssh server
me@garden-server:~$ tmux new -s copy
me@garden-server:~$ rsync -av /mnt/backup/photos/ ~/photos/

Press Ctrl-b d, then exit, and close the laptop. Next morning:

me@garden-laptop:~$ ssh server
me@garden-server:~$ tmux attach -t copy

and there’s the rsync, finished, with its full output above the prompt.

A ~/.tmux.conf

tmux reads ~/.tmux.conf at start ². Two settings from Ubuntu’s documentation are worth having:

# Click to choose panes and windows, drag borders, scroll with the wheel
set -g mouse on
# Keep 10,000 lines of scrollback instead of 2,000
set-option -g history-limit 10000

After changing it, reload it inside tmux with Ctrl-b : and then source-file ~/.tmux.conf, which keeps your sessions running ². Add it to your dotfiles (as tmux.conf, with a line in install.sh’s LINKS) so every machine gets it.

Ubuntu’s documentation also mentions Mosh, a replacement for the SSH connection itself that survives changing networks and sleep, if your connection is often flaky ². tmux is enough most of the time.

Your turn

So

tmux keeps shells running on the server whether or not you’re connected. tmux new -s name starts a session, Ctrl-b d detaches, tmux ls lists, and tmux attach -t name reattaches. Inside, Ctrl-b c makes windows (n and p to move), Ctrl-b % and ” split panes (arrows to move, z to zoom), and Ctrl-b [ scrolls back. Start anything long-running on another machine inside tmux, and put a ~/.tmux.conf with mouse support and more history in your dotfiles.