.. _policy-reporting: Reporting Policies =================== Starting with LinOTP 2.9 a new reporting API was introduced. It can be used to query information about the number of tokens in the system. This can be useful amongst others for accounting in multitenancy environments. The comprehensive API documentation can be found here: https://www.linotp.org/doc/api/linotp.controllers.reporting.html The reporting API is to activated by policies and can be accessed by the token managers. The actions allowed for each management account can be configured by policies as described below. Please have a look at :ref:`reporting_queries` for example queries. Activate Reporting ------------------- The available queries must be activated with policies in the scope **reporting**. Total Number of Tokens ``````````````````````` This makes the reporting of the total numbers of tokens available. * Policy name: this is a unique name of the policy. * Scope: You need to set this to **reporting**. * Action: **token_total** * User: This is a comma separated list of usernames or resolver names the token count should be performed for. Please see :ref:`users_in_policies`. This should be set to ***** to cover all users. * Realm: Enter the names of the realms where reporting should be available. * Client: This is a list of IP addresses or subnets this policy is valid for. Token in certain States ````````````````````````` This policy configures the counting of tokens in certain states. If a state is not configured here it can not be used for a query. * Policy name: this is a unique name of the policy. * Scope: You need to set this to **reporting**. * Action: **token_status** **token_status** can be a list of: * *assigned* * *unassigned* * *active* * *inactive* ... or sensible combinations of those states. States can be joined with "**&**". The syntax is: .. code:: token_status = STATE1[&STATE2][, token_status=,STATE3[&STATE4]]... .. * User: This is a comma separated list of usernames or resolver names the token count should be performed for. Please see :ref:`users_in_policies`. This should be set to ***** to cover all users. * Realm: Enter the names of the realms where reporting should be available. * Client: This is a list of IP addresses or subnets this policy is valid for. **Explanation of the available token states:** ``active`` counts only active tokens ``inactive`` counts only deactivated tokens ``assigned`` counts only tokens assigned to users ``unassigned`` counts only tokens which are not assigned to any user ``active&assigned`` counts tokens which are activ and assigned to a user ``active&unassigned`` counts active tokens which are not assigned to any user ``inactive&assigned`` counts disabled tokens assigned to users ``inactive&unassigned`` counts disabled tokens which are not assigned to any user **Example:** This makes all possible state combinations available for queries. .. code:: [reporting] scope = reporting action = "token_status=assigned&active, token_status=unassigned&active, token_status=assigned&inactive, token_status=unassigned&inactive, token_status=active, token_status=inactive, token_status=assigned, token_status=unassigned" user = * realm = * client = "" time = "" active = True Configure Access ----------------- Token manager can be allowed to query selected activated information using the reporting interface. This is configured with policies in the scope **reporting.access**. Show Token ``````````` The action **show** returns the numbers of tokens with a certain state. The search can be limited to certain realms. * Policy name: this is a unique name of the policy. * Scope: You need to set this to **reporting.access**. * Action: **show** * User: This is a comma separated list of usernames or resolver names who are allowed to perform the queries. Please see :ref:`users_in_policies`. This can be set to ***** to cover all management users. * Realm: Enter the names of the realms the reporting should be allowed for. * Client: This is a list of IP addresses or subnets this policy is valid for. **Example** Allow the users managerA and managerB to query token information for realm realmA and realmB: .. code:: [reporting_access] scope = reporting.access action = "show," user = managerA, managerB realm = realmA, realmB client = "" time = "" active = True Please have a look at :ref:`reporting_queries` for example queries. Show Maximal Number of Tokens `````````````````````````````` The action **maximum** returns the the highest number counted of tokens with a certain state. The search can be limited to selected realms. This is useful for accounting purposes. E.g: the maximal number of active tokens can be queried at the end of the month. After this the counter is deleted and can be reused for the next month. * Policy name: this is a unique name of the policy. * Scope: You need to set this to **reporting.access**. * Action: **maximum** * User: This is a comma separated list of usernames or resolver names who are allowed to perform the queries. Please see :ref:`users_in_policies`. This can be set to ***** to cover all management users. * Realm: Enter the names of the realms the reporting should be allowed for. * Client: This is a list of IP addresses or subnets this policy is valid for. **Example** Allow the user managerA to query the highest number of tokens through time for realms realmA and realmB: .. code:: [reporting_access] scope = reporting.access action = "maximum" user = managerA realm = realmA, realmB client = "" time = "" active = True Please have a look at :ref:`reporting_queries` for example queries. Delete data from Reporting Database ````````````````````````````````````````` Delete all data ~~~~~~~~~~~~~~~~ The action **delete_all** removes all data from the reporting database. This is useful for cleaning the database, eg. if the data are already processed or to reset the maximum counter. * Policy name: this is a unique name of the policy. * Scope: You need to set this to **reporting.access**. * Action: **delete_all** * User: This is a comma separated list of usernames or resolver names who are allowed delete entries of the database. Please see :ref:`users_in_policies`. This is set to ***** to cover all management users. * Realm: Enter the names of the realms of which the reporting can be deleted. * Client: This is a list of IP addresses or subnets this policy is valid for. **Example** Allow the user managerA and managerB to delete reporting information for realms realmA and realmB: .. code:: [reporting_access] scope = reporting.access action = "maximum" user = managerA, managerB realm = realmA, realmB client = "" time = "" active = True Please have a look at :ref:`reporting_queries` for example queries. Delete data before a certain date ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The action **delete_before** removes all data from the reporting database older than the given date. This is useful for cleaning the database, e.g. if the data are already processed or to reset the maximum counter. * Policy name: this is a unique name of the policy. * Scope: You need to set this to **reporting.access**. * Action: **delete_before** * User: This is a comma separated list of usernames or resolver names who are allowed delete entries of the database. Please see :ref:`users_in_policies`. This is set to ***** to cover all management users. * Realm: Enter the names of the realms of which the reporting can be deleted. * Client: This is a list of IP addresses or subnets this policy is valid for. **Example** Allow the user managerA and managerB to delete reporting information before a certain date for realms realmA and realmB: .. code:: [reporting_access] scope = reporting.access action = "delete_before" user = managerA, managerB realm = realmA, realmB client = "" time = "" active = True Please have a look at :ref:`reporting_queries` for example queries.