Monitoring Interface
====================

Starting with LinOTP 2.8.1 a new controller is available for monitoring LinOTP.
It provides the following functions:

 * **monitoring/tokens**: Generates a list of tokens. `assigned`, `unassigned`,
   `active` and `inactive` are the available statuses for the search.  The
   search criteria can be combined with **%26** (e.g. assigned+inactiv:
   ``monitoring/tokens?status=assigned%26inactive``)
 * **monitoring/userinfo**: lists users with assigned tokens for realms
 * **monitoring/license**: shows license details and the number of active tokens in
   the system
 * **monitoring/config**: shows configuration entries
 * **monitoring/storageEncryption**: tests, if encryption is working correctly

Session parameter
-----------------

The LinOTP administrative API (e.g. */manage*, */admin*, */system*,
*/monitoring*) requires an additional **session** parameter and
**admin_session** cookie.  This provides CSRF (Cross Site Request Forgery)
protection. Then only requirement is that both values match but they should be
sufficiently random so that an attacker can not simply guess it.

Accessing the API with your Browser
````````````````````````````````````

To access the administrative API in your Browser first open the Manage UI
(https://FQDN/manage) and enter your admin user credentials. Then check the
value of the **admin_session** cookie.

In Firefox this can be done as follows:

1. Open the menu *Tools/Page Info*
2. Open the tab *Security*
3. Click on the *View Cookies* button
4. Select the **admin_session** cookie
5. Copy the content (something like *90dd0f1ac...*).

.. tip::
    Advanced users can also open a JavaScript console (e.g. Firebug) and
    execute the *getsession()* function.

Then open another browser window, type in the API call you want to make and
append **session**. For example:

https://FQDN/admin/unassign?serial=LSSP0001F4E0&session=90dd0f1ac...

For more details about the session handling please refer to:

:ref:`session_parameter`

Examples
--------

Tokens
```````

* **Display all tokens from all realms:**

.. code::

 https://LINOTP/monitoring/tokens?session=SESSIONCOOKIE


* **Display all tokens from certain realms:**

.. code::

 https://LINOTP/monitoring/tokens?realms=realm1,realm2&session=SESSIONCOOKIE

* **Display only assigned tokens from certain realm:**

.. code::

 https://LINOTP/monitoring/tokens?realms=realm1&status=assigned&session=SESSIONCOOKIE

* **Display only unassigned tokens from all realms:**

.. code::

 https://LINOTP/monitoring/tokens?status=unassigned&session=SESSIONCOOKIE


* **Display assigned tokens which are inactive from all realms (please mind
  %26 for combining assigned + inactive):**

.. code::

 https://LINOTP/monitoring/tokens?status=assigned%26inactive&session=SESSIONCOOKIE

User information
`````````````````

* **Display number of users for all realms:**

.. code::

 https://LINOTP/monitoring/userinfo?session=SESSIONCOOKIE

* **Display number of users in certain realm:**

.. code::

 https://LINOTP/monitoring/userinfo?realms=ldap&session=SESSIONCOOKIE

License
````````

* **Show license information:**

.. code::

 https://LINOTP/monitoring/license?session=SESSIONCOOKIE


.. code::

 {
   "detail": {
      "valid": true
   }, 
   "version": "LinOTP 2.8.1", 
   "jsonrpc": "2.0", 
   "result": {
      "status": true, 
      "value": {
         "token-num": 2000, 
         "token-active": 1800, 
         "token-left": 200
      }
   }, 
   "id": 1
 }

Configuration
`````````````

* **Show configuration overview:**

.. code::

 https://LINOTP/monitoring/config?session=SESSIONCOOKIE

Encryption
``````````

* **Show encryption status:**

.. code::

 https://LINOTP/monitoring/storageEncryption?session=SESSIONCOOKIE