Using the tmux command#

The tmux command is available to execute long-running commands (for example, when upgrading) in the background.

Note

From release 25.2, the screen command is no longer available on the Automate CLI - typing in screen on the CLI will return a message to use tmux instead.

The following commands require the running of tmux:

  • backup create <location-name>

  • cluster provision

  • cluster upgrade

  • app template

  • voss export type <args>

  • voss export group <args>

  • voss subscriber_data_export

A message is displayed to indicate that tmux should be run first:

This is a potentially long-running command and should be executed in a tmux session
Run tmux and then execute the command again

The use of tmux is not affected by the use of the --force parameter with any of these commands.

The commands then run in a tmux session that can be reconnected. The standard tmux command parameters are available, in particular:

  • List sessions:

tmux list-sessions
0: 1 windows (created Thu Apr 10 22:32:29 2025)
1: 1 windows (created Thu Apr 10 22:32:41 2025) (attached)

  • Detach

Ctrl+b + d

  • Exit (kill session)

Ctrl+d

  • Attach to a session

tmux attach -t 0

  • Scroll

Ctrl+b + [

  • Scroll off

Esc

  • Execute a command (example)

$ tmux -c 'voss export type license_audit'
Starting license_audit export, please wait...
Completed license_audit export, created vlf_[...]

To create a tmux log file in the /var/log/platform/tmux/ directory:

tmux -Log

For details, refer to the on-line help - also referenced below.

If the tmux session times out, you can obtain console output from the log file, for example:

$ sftp platform@<host>:media/<tmux-logfilename>.log

On-line help#

The platform CLI offers an enhanced online help to the tmux command that also includes details and examples, as well as custom parameters to output the session to a log file.

The enhanced, full on-line help information available from the CLI is shown below:

platform@VOSS:~$ tmux -h
usage: tmux [-2CDlNuvV] [-c shell-command] [-f file] [-L socket-name]
            [-S socket-path] [-T features] [command [flags]]

COMMON COMMANDS
 attach-session (alias: attach) [-t target-session]    target-session is the number
                                                        from 'tmux ls'.
 list-commands  (alias: lscm) [command]                List the syntax of command or
                                                        - if omitted - of all commands
                                                        supported by tmux.
 list-sessions  (alias: ls)                            List all sessions managed by
                                                        the server.
 man                                                   Displays tmux manual.

COMMON KEY BINDINGS
 tmux may be controlled from an attached client by using a key combination of a
 prefix key, 'Ctrl-b', followed by a command key

 d           Detach the current client.
 :           Enter the tmux command prompt.

VOSS LOGGING ENHANCEMENTS:

 -Log                    Turn on output logging. Log folder /var/log/platform/tmux/
 -LogPrefix [prefix]     Prefix added to the log filename.

LOG NAME PATTERN:

<[PREFIX]->tmuxlog-[TIMESTAMP]-[USER_ID]-S[SESSION_NAME]-W[WINDOW_ID]-P[PROCESS_ID].log
 I.e.
   tmuxlog-20250527120013-1401-0-W0-P1329199.log
   my-prefix-tmuxlog-20250527120013-1401-S0-W0-P1329199.log

Examples:
  1. Start a logged session with default name pattern:
  tmux -Log
      I.e. tmuxlog-20250527120013-1401-S0-W0-P1329199.log
  2. Run specific command with custom log prefix:
  tmux -LogPrefix my-log -c "my-long-running-command"
      I.e. my-log-tmuxlog-20250527120013-1401-S0-W0-P1329199.log

The list-commands parameter offers details on available commands, such as shown in the snippet below:

platform@VOSS:~$ tmux list-commands
attach-session (attach) [-dErx] [-c working-directory] [-f flags] [-t target-session]
bind-key (bind) [-nr] [-T key-table] [-N note] key [command [arguments]]
break-pane (breakp) [-abdP] [-F format] [-n window-name] [-s src-pane] [-t dst-window]
capture-pane (capturep) [-aCeJNpPq] [-b buffer-name] [-E end-line] [-S start-line] [-t target-pane]
choose-buffer [-NrZ] [-F format] [-f filter] [-K key-format] [-O sort-order] [-t target-pane] [template]
choose-client [-NrZ] [-F format] [-f filter] [-K key-format] [-O sort-order] [-t target-pane] [template]
choose-tree [-GNrswZ] [-F format] [-f filter] [-K key-format] [-O sort-order] [-t target-pane] [template]
clear-history (clearhist) [-t target-pane]
clock-mode [-t target-pane]
command-prompt [-1kiNTW] [-I inputs] [-p prompts] [-t target-client] [template]
[...]