.. _screen-command:

Using the ``screen`` command
------------------------------

.. _20.1.1|VOSS-724|EKB-5299:

.. index:: screen
.. 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

.. note::

   If you are upgrading from earlier than 25.2, use ``screen``.     

Overview 
.........

The ``screen`` command is used to execute long-running commands in the background, for example, 
when upgrading. 

The following commands require the running of ``screen``:

* ``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 ``screen`` should be run first:

::

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

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

The commands then run in a screen session that can be reconnected.

Standard ``screen`` command parameters are available, in particular:

* ``screen`` - start a new session
* ``screen -ls`` - show sessions already available
* ``screen -r [screen PID]`` - reconnect to a disconnected session

The version of ``screen`` used in VOSS Automate also supports the creation of a
log file. If long-running commands will be run, the log file
captures screen console output up to the session timeout. The following message displays: 

:: 

  timed out waiting for input: auto-logout


Create a screen log file 
..........................

To create a screen log file:

1. Run ``screen`` and wait for screen to open.
2. Press **<Ctrl>-a** then **:** (colon). This will enter screen command mode
   at the bottom of the console.
3. Create your screen logfile in the ``media/`` directory:

   a. In screen command mode, type **logfile media/<screen-logfilename>.log**
   #. Press **<Enter>**
   #. Press **<Ctrl>-a** and then **H** to start writing to the log file
   #. Run your commands.

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

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