.. _patrole-configuration:

Patrole Configuration Guide
===========================

Patrole can be customized by updating Tempest's ``tempest.conf`` configuration
file. All Patrole-specific configuration options should be included under
the ``patrole`` group.

RBAC Test Role
--------------

The RBAC test role governs which role is used when running Patrole tests. For
example, setting ``rbac_test_role`` to "admin" will execute all RBAC tests
using admin credentials. Changing the ``rbac_test_role`` value will `override`
Tempest's primary credentials to use that role.

This implies that, if ``rbac_test_role`` is "admin", regardless of the Tempest
credentials used by a client, the client will be calling APIs using the admin
role. That is, ``self.os_primary.servers_client`` will run as though it were
``self.os_admin.servers_client``.

Similarly, setting ``rbac_test_role`` to a non-admin role results in Tempest's
primary credentials being overriden by the role specified by
``rbac_test_role``.

.. note::

    Only the role of the primary Tempest credentials ("os_primary") is
    modified. The ``user_id`` and ``project_id`` remain unchanged.

Enable RBAC
-----------

Given the value of ``enable_rbac``, enables or disables Patrole tests. If
``enable_rbac`` is ``False``, then Patrole tests are skipped.

Custom Policy Files
-------------------

Patrole supports testing custom policy file definitions, along with default
policy definitions. Default policy definitions are used if custom file
definitions are not specified. If both are specified, the custom policy
definition takes precedence (that is, replaces the default definition,
as this is the default behavior in OpenStack).

The ``custom_policy_files`` option allows a user to specify a comma-separated
list of custom policy file locations that are on the same host as Patrole.
Each policy file must include the name of the service that is being tested:
for example, if "compute" tests are executed, then Patrole will use the first
policy file contained in ``custom_policy_files`` that contains the "nova"
keyword.

.. note::

    Patrole currently does not support policy files located on a host different
    than the one on which it is running.