Keep SSH Sessions Alive with Byobu Windows and Sessions

Your SSH connection drops at 2am and takes a three-hour job with it. Byobu keeps that from happening. You will finish with a session that survives a disconnect, a repeatable set of windows, and a status bar you can adjust without editing system files. This guide uses Byobu 6.11 with tmux 3.4 on the local machine.

Allow about 15 minutes. You need a normal shell account, a terminal emulator and the installed byobu package. No elevated privileges are needed.

Byobu is a wrapper around a text-based window manager. This installation chooses tmux when it is available, while the same command can use GNU Screen if you select that backend. Byobu adds configuration, keyboard shortcuts and two status lines; it does not replace SSH or make a disconnected network connection live again.

1. Check the installed backend

Run the version check before starting a session:

$ byobu --version
byobu version 6.11
tmux 3.4

The exact backend version can differ on another host. The second line confirms this installation found tmux. If the command is missing, install the distribution's Byobu package before continuing. Do not run the package manager as root merely because Byobu itself needs no elevated privileges.

2. Start one named session

Start Byobu from the shell:

$ byobu

The first launch may seed your user configuration. The default session name is byobu. Inside the session, these keys do the basics:

• F2 creates a window.
• F3 or F4 moves between windows.
• F6 detaches the client but leaves the session and its processes running.

A window is a separate shell or command context, so a long-running job can stay in one while you work in another. To come back after detaching, run byobu again. If several sessions exist, use the session selector rather than guessing which one holds your work.

3. Choose a deliberate session name

Named sessions are easier to recognise when one host has several tasks. Pass the backend's session option through Byobu:

$ byobu -S maintenance

The installed manpage documents -S for naming a session. A name beginning with a dot, such as .private, is hidden from byobu-select-session. Use that only when hiding a session from the selector is genuinely useful; it is not access control and does not encrypt anything.

4. Build a repeatable window set

Byobu reads its user configuration from $XDG_CONFIG_HOME/byobu when XDG_CONFIG_HOME is defined, or from $HOME/.byobu otherwise. On this installation the fallback is /home/alice/.byobu. Find your actual location without changing it:

config_dir="${BYOBU_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/byobu}"
printf '%s\n' "$config_dir"
if [ -d "$config_dir" ]; then
    printf '%s\n' 'configuration directory exists'
else
    printf '%s\n' 'configuration directory will be seeded on first use'
fi

For tmux, create a file named windows.tmux in that directory. This file uses tmux commands, one per line. For example:

new-session 'bash' ;
new-window -n logs 'tail -f /var/log/syslog' ;
new-window -n shell 'bash' ;
select-window -t 2 ;

To select a named set rather than the default files, store it as windows.tmux.NAME and start Byobu with BYOBU_WINDOWS=NAME:

$ BYOBU_WINDOWS=work byobu

cp -a "$config_dir/windows.tmux" "$config_dir/windows.tmux.backup"
mv "$config_dir/windows.tmux" "$config_dir/windows.tmux.disabled"

Those commands change only your Byobu configuration. Starting a new session then falls back to the remaining configuration. Restore the original with mv "$config_dir/windows.tmux.disabled" "$config_dir/windows.tmux" if the layout was useful.

5. Adjust status information safely

Press F9 inside Byobu to open its configuration menu. Use it to enable or disable status notifications without guessing file names. The manpage describes indicators such as memory, load average, network traffic, disk usage, time and hostname. The menu changes user configuration, not system-wide policy.

For a direct setting, edit the user file statusrc inside the configuration directory. For example, these settings change the monitored network interface and make the displayed network units bytes:

MONITORED_NETWORK=eth0
NETWORK_UNITS=bytes

Use the interface name that exists on your host. Check it first with ip link. If the name is wrong, the indicator may be empty or misleading. Press F5 to reload the Byobu profile after saving a setting.

Removing a custom statusrc returns that file to the package or seeded default, but copy it first if it contains other choices:

cp -a "$config_dir/statusrc" "$config_dir/statusrc.backup"
rm "$config_dir/statusrc"

6. Avoid the common session traps

A detached session is not the same as a logged-out shell. Keep sensitive commands out of shared sessions, and remember that another user with suitable access to the account can inspect the session.

Keys worth knowing before you need them:

• Do not use Ctrl-a k casually. The Byobu manpage defines it as killing the current window, which terminates the shell or foreground command in it. To leave temporarily, use F6.
• Splits. If you split the display with Shift-F2 or Ctrl-F2, Ctrl-F6 removes the current split and Shift-F5 joins all splits again.
• Scrollback. Use Alt-PgUp or Alt-PgDn. Press the spacebar to begin selecting, move through the text, and press Enter to copy it. Press Alt-Insert to paste.
• Function keys dead in PuTTY or similar. Check that the terminal sends the expected xterm function-key sequences and that UTF-8 is enabled.