.. _system-voss-commands:

System Specific Commands
------------------------

.. index:: voss;voss finalize_transaction

.. _21.2|EKB-10978:

.. important::

   The ``voss`` system specific commands can *not* be run on:

   * web proxy nodes

   The ``voss`` system specific commands can *only* be run on:
  
   * application nodes on a Modular Architecture deployment,
   * unified nodes on Unified and Single Node architectures

* **voss finalize_transaction <id>[,<id> ...]** - If a transaction status incorrectly
  shows as processing *after a service restart* - for example where a service 
  has stopped - use this command to mark it as finalized.

  Example:

  ::

     platform@VOSS:~$ voss finalize_transaction 50276
     This will mark the given transaction(s) as failed. Do you wish to continue? y
     Transaction state changed to failed for [50276].

  More than one transaction can be marked to be finalized - enter these as a
  comma-separated list of transaction sequence IDs.

  If a transaction in a 'Processing' state has child transactions in a
  'Processing' state, the tool will attempt to finalise these as well.
  The output will indicate any transaction IDs that could not be finalized
  and that require further user action.

  .. important::

     * The **voss finalize_transaction** command should never be run for transactions
       that are still processing. It should *only* be used for transactions that are still
       in a 'Processing' state after a service restart or other event influencing the
       ``voss-deviceapi`` queue and ``wsgi`` processes. 

     * The **voss finalize_transaction** command does *not* cancel or stop a running or queued
       transaction, but only sets the **Status** flag to 'Failed'.



.. index:: voss;voss get_extra_functions_version
  
* **voss get_extra_functions_version <[-h] [-c] [-d] [-m] [-q]>** - Display
  details of the currently installed extra functions file (``extra_functions.py``).
  Details can be the checksum (md5), created date and modified date - with or
  without titles. The command **voss get_extra_functions_version -h** displays
  information on these parameters.


.. index:: voss;voss migrate_summary_attributes
  
* **voss migrate_summary_attributes <model_type>** - Migrates the summary 
  attribute schema for instances of the specified model.

  For example: ::

    voss migrate_summary_attributes data/InternalNumberInventory



.. index:: voss;voss reset_device_concurrency
  
* **voss reset_device_concurrency [all | device <device_name> | --show_locks]** - Call Manager can handle eight concurrent
  connections. |VOSS Automate| monitors the number of connections it continuously
  makes and removes or adds to the number as connections are made and closed. 
  For debugging purposes, this "tracking number" can be reset.

  If the concurrency remains at the maximum for more than 10 minutes, it is
  automatically reset to zero and a log error message ``Resetting stale Device Concurrency..``
  (containing details) is displayed. The parameters are as follows:

  * **all** - this is the default parameter if no parameter is provided. Concurrent
    connections on *all* devices are reset.
  * **device <device_name>** - reset the concurrent connections on a specific device with ``<device_name>``,
    for example **voss reset_device_concurrency device 192.168.100.15**
  * **--show_locks** - For all devices, show device type, device name , concurrent connections and max current concurrent connections. 
    For example:

    ::
      
       $ voss reset_device_concurrency --show_locks

       INFO:__main__:[device/hcmf - 192.168.100.11:8443] [0/1]
       INFO:__main__:[CUCM - 192.168.100.15:8443] [0/8]
       INFO:__main__:[CUC - 192.168.100.12:8443] [0/8]

.. index:: voss;voss clear_device_pending_changes
  
* **voss clear_device_pending_changes <device_name | all>** - Since |Unified CM|
  version 10.0, a Change Notification Feature is available that stores changes
  to device objects in a cache. The |VOSS Automate| application service called 
  ``voss-deviceapi::voss-cnf_collector`` collects these changes from *all*
  the |Unified CM| devices as they are added, manages and stores the changes
  in a data collection.
 
  This collection can then be used to update the system
  by means of a Data Sync option on the GUI. An additional tool on the GUI
  displays the status and manages the collection on a specified device and also
  allows for the polling interval between collections to be configured.
  Each device keeps the last time that a collection
  process ran on it, so that a new collection will only be run on it
  once its interval has expired.

  The **voss clear_device_pending_changes** command clears all pending changes
  by the Change Notification Collector for a particular device or for all devices.
 
  To clear the collection of pending changes from a single
  device, the command and output is for example:

  ::

     $ voss reset_device_pending_changes 10.120.10.190
     This will clear all pending changes.
     Do you wish to continue? yes

  The status of changes collected from a device can be checked from the
  GUI.


.. index:: voss;voss set_debug
  
* **voss set_debug <level[0/1]>** - By default, the level is "level0", so no
  debug information is present in the logs. 

  Setting the value to "level1" is not supported and will for example result 
  in performance degradation.


.. index:: voss;voss unlock_sysadmin_account
  
* **voss unlock_sysadmin_account** - Unlocks and forces a password reset on the
  system administrator account. The system administrator is prompted to enter
  a new password and is then prompted to verify the new password.


.. index:: voss;voss update_device_schemas
  
* **voss update_device_schemas <schema models>** - Regenerate device model
  schemas in the database and in the device schemas fixtures file. No data is
  lost, so this can be done on a production system, although the system should
  not be used while this is happening. Parameters can be passed through
  (indicated as "<schema models>"). The available parameters are shown by
  using the "--help" parameter. Used by developers.


.. index:: voss;voss post-upgrade-migrations
  
* **voss post-upgrade-migrations** - Schedule a transaction to execute
  long running data migrations after an upgrade.

  Data migrations that are not critical to system operation can have significant
  execution time at scale. These need to be performed after the primary upgrade,
  allowing the migration to proceed whilst the system is in use - thereby limiting
  upgrade windows.

  * This command is a mandatory step after an upgrade.
  * The command only needs to be run on a single node of a cluster.
  * The command will display progress information of the migration transaction
    until the transaction concludes, or until the user exits the command using Ctrl-c.
  * Transaction progress can also be followed on the Transaction GUI.
  * If the transaction is cancelled on the GUI or interrupted by a system or queue
    restart, the command can be run again to re-queue a migration transaction, which will
    resume the migration process.
  * Console examples are shown below:

    ::

      $ voss post-upgrade-migrations
      Queueing post upgrade migrations, please wait...
      Post upgrade migrations transaction queued, ID 6.
      Transaction progress(ctrl-c to exit, transaction will continue to execute):
      -Post upgrade migrations:   0%|             | 0/1 [00:00<?]
      --Migrating objects in TRANSACTION colle...:  27%|#######   | 53814/200000 [00:30<01:21]
      ^C
      Aborting progress monitoring, transaction ID 6 is continuing execution, exiting...
      
    Subsequent re-execution with the same previously queued transaction still executing -
    progress display is resumed and displayed until the transaction concludes:

    ::

      $ voss post-upgrade-migrations
      Existing post upgrade migrations transaction found, not requeuing.
      Transaction progress(ctrl-c to exit, transaction will continue to execute):
      -Post upgrade migrations: 100%|####################| 1/1 [01:40<00:00]
      --Migrating objects in TRANSACTION colle...: 100%|##########| 200000/200000 [01:40<00:00]
      
      Post upgrade migrations complete, exiting...




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