.. _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

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

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.
The 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.
A message shows: 

:: 

  timed out waiting for input: auto-logout

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**


.. |VOSS Automate| replace:: VOSS Automate
.. |Unified CM| replace:: Unified CM
.. |Platform Guide| replace:: Platform Guide