Work in the Labs with tmux

Every lab runs in one tmux session on the deployment node. It opens a shell on each lab host, grouped into windows, so you see the whole environment from a single SSH connection. A deployment that runs for an hour keeps running when your connection drops, you just reattach.

Start the session

The session is not built by hand. tmuxp, a session manager for tmux, reads a YAML file with the windows, the panes and the command each pane runs, and builds the whole session in one go. Each lab keeps that file in conf/tmuxp.yaml of its repository.

Log in to the deployment node as shown in Prepare a Bare-Metal Server and run the alias lab-stack:

lab-stack
# is an alias for
tmuxp load -y ~/<LAB_NAME>/conf/tmuxp.yaml

The session is named after the lab, for example lab-ceph. If it already runs, -y attaches to it instead of asking.

How the session is laid out

The ceph window of the Ceph lab:

┌──────────────────────────────────┬──────────────────────────────────┬──────────────────────────────────┐
│ root@cephmon01:~#                │ root@cephmon02:~#                │ root@cephmon03:~#                │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
├──────────────────────────────────┼──────────────────────────────────┼──────────────────────────────────┤
│ root@cephosd01:~#                │ root@cephosd02:~#                │ root@cephosd03:~#                │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
├──────────────────────────────────┼──────────────────────────────────┼──────────────────────────────────┤
│ root@deployment:~#               │ root@deployment:~#               │ deploy@deployment:~/ceph$        │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
│                                  │                                  │                                  │
└──────────────────────────────────┴──────────────────────────────────┴──────────────────────────────────┘
 [lab-ceph] 0:ceph* 1:infra                                                  "deployment" 14:32 05-Nov-26 

The green bar at the bottom is the status line: the session name, the windows with * on the current one, and the host. The green frame marks the pane you type into.

Leave and come back

# detach: ctrl-b, d, the session keeps running
# reattach after a new login
tmux attach -t <LAB_NAME>
# end the session and close all shells in it
tmux kill-session -t <LAB_NAME>

Keys you need every day

All keys start with the prefix ctrl-b. Press ctrl and b together, let go of both, then press the next key.

Keys Action
ctrl-b, d detach from the session
ctrl-b, n / p next / previous window
ctrl-b, 0 … 9 go to window by number
ctrl-b, w pick a window from a list
ctrl-b, ← ↑ ↓ → move to the pane in that direction
ctrl-b, q show pane numbers, press a number to jump
ctrl-b, z zoom the current pane, again to restore
ctrl-b, Space switch to the next pane layout
ctrl-b, PgUp scroll up, then PgUp/PgDn, q to leave
ctrl-b, c new window
ctrl-b, , rename the current window
ctrl-b, % / " split pane left/right / top/bottom
ctrl-b, x close the current pane

Type into all panes at once

Useful when the same command must run on every host of a window, for example a package update or a quick ping:

ctrl-b, :set synchronize-panes

The same command turns it on and off again. Turn it off right after use. Everything you type goes to every pane, including the local shells on the deployment node.