.. _trackme_admin_maintenance:
Maintenance mode & knowledge database
######################################
Introduction to the maintenance mode features
=============================================
.. hint:: **The maintenance features are composed of two main components:**
- **The Maintenance Mode**, which allows to silence TrackMe alerts for a given period of time
- **The Maintenance Knowledge DataBase**, which allows to store maintenance information associated with the maintenance mode actions, or independently, for audit purposes and also to influence SLA calculations accordingly
.. admonition:: **Tenants scope selection from Trackme 2.0.97**
- Since TrackMe release 2.0.97, you can define the scope of the Virtual Tenants when enabling the maintenance mode.
- This allows defining which Virtual Tenants are concerned by the application of the maintenance mode.
- Tenants scope is also automatically taken into account in the maintenance mode knowledge database and for SLA calculation purposes.
TrackMe permissions requirements
=================================
**To access and manage the Maintenance Mode features, you need to have the following permissions:**
- TrackMe admin (capability: trackmeadminoperations)
**Regarding the Maintenance Knowledge DataBase, you need to have the following permissions to access the UI in read only:**
- TrackMe user (capability: trackmeuseroperations)
**To operate changes, adding new Maintenance records or manage existing records, you need to have the following permissions:**
- TrackMe admin (capability: trackmeadminoperations)
Maintenance Mode
================
**You can access the Maintenance Mode UI fron the maintenance menu on top of TrackMe:**
.. image:: img_v2/admin_maintenance/maintenance_mode.png
:alt: maintenance_mode.png
:align: center
:width: 1200px
:class: with-border
Enabling the Maintenance Mode
-----------------------------
**You can enable the Maintenance Mode to start immediately or at a given date and time:**
.. image:: img_v2/admin_maintenance/maintenance_mode_enable.png
:alt: maintenance_mode_enable.png
:align: center
:width: 1200px
:class: with-border
**If the start date is in the future, TrackMe schedules the start automatically:**
.. image:: img_v2/admin_maintenance/maintenance_mode_enable_scheduled.png
:alt: maintenance_mode_enable_scheduled.png
:align: center
:width: 1200px
:class: with-border
**When the start period is reached, or if you selected a start for now, TrackMe shows the Maintenance Mode enabled:**
.. image:: img_v2/admin_maintenance/maintenance_mode_enabled.png
:alt: maintenance_mode_enabled.png
:align: center
:width: 1200px
:class: with-border
**You can disable the Maintenance Mode at any time:**
.. image:: img_v2/admin_maintenance/maintenance_mode_disable.png
:alt: maintenance_mode_disable.png
:align: center
:width: 1200px
:class: with-border
Detection and management of the Maintenance Mode status is driven by a Tracker called ``trackme_maintenance_mode_tracker``.
Maintenance Knowledge DataBase
==============================
Accessing the Maintenance Knowledge DataBase
--------------------------------------------
**The interface for the Maintenance Knowledge DataBase is also accessible from the maintenance menu on top of TrackMe:**
.. image:: img_v2/admin_maintenance/maintenance_kdb.png
:alt: maintenance_kdb.png
:align: center
:width: 1200px
:class: with-border
Maintenance Knowledge DataBase behaviour
----------------------------------------
**Maintenance records are automatically created an updated when enabling a scheduled or immediate maintenance period via the Maintenance Mode user interface and REST API endpoints:**
- When the maintenance mode is enabled and then disabled, TrackMe automatically creates and maintains a record in the Maintenance Knowledge DataBase as a planned operation.
- Associated periods of times are excluded from SLA calculations in TrackMe.
- You can also optionally register unplanned operations for your own auditing
- Only planned operations are excluded by default from SLA calculations, but you can use the global setting maintenance_kdb_exclusion_behaviour to manage this behaviour.
- Both types of Maintenance periods can be registered via this UI, or via REST API and the maintenance_kdb resource group endpoints (See TrackMe Rest API Reference dashboard)
REST API endpoints for the Maintenance Mode and Maintenance Knowledge DataBase
==============================================================================
**Both features rely on different API endpoints, enabling their integration within and out of TrackMe, consult the REST API reference dashboard:**
.. image:: img_v2/admin_maintenance/maintenance_api_endpoints1.png
:alt: maintenance_api_endpoints1.png
:align: center
:width: 1200px
:class: with-border
.. image:: img_v2/admin_maintenance/maintenance_api_endpoints2.png
:alt: maintenance_api_endpoints2.png
:align: center
:width: 1200px
:class: with-border
.. image:: img_v2/admin_maintenance/maintenance_api_endpoints3.png
:alt: maintenance_api_endpoints3.png
:align: center
:width: 1200px
:class: with-border
REST API example: enable the maintenance mode for 1 hour
--------------------------------------------------------
**The following example immediately enables the maintenance mode for all tenants for a duration of 1 hour starting now:**
.. code-block:: bash
curl -u username https://mysplunk:8089/services/trackme/v2/maintenance/global_maintenance_enable -X "POST" -d "{\"maintenance_duration\": \"3600\", \"update_comment\": \"Enabling a TrackMe global maintenance for 1 hour of duration from now.\"}"
**The following example does the same but restricts the scope to a tenant name "secops":**
.. code-block:: bash
curl -u username https://mysplunk:8089/services/trackme/v2/maintenance/global_maintenance_enable -X "POST" -d "{\"maintenance_duration\": \"3600\", \"update_comment\": \"Enabling a TrackMe global maintenance for 1 hour of duration from now.\", \"tenants_scope\": \"secops\"}"
REST API example: disable the maintenance mode
----------------------------------------------
**The following example disables the maintenance mode:**
.. code-block:: bash
curl -u username https://mysplunk:8089/services/trackme/v2/maintenance/global_maintenance_disable -X "POST" -d "{\"update_comment\": \"Disabling the TrackMe global maintenance.\"}"