.. _tmux-command:

Using the ``tmux`` command
------------------------------

.. _25.2|EKB-24140:

.. index:: tmux
.. index:: cluster;cluster provision
.. index:: cluster;cluster upgrade
.. index:: app;app template
.. index:: voss export;voss export type
.. index:: voss export;voss export group
.. index:: voss subscriber_data_export

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]
  [...]