194 lines
5.5 KiB
ReStructuredText
194 lines
5.5 KiB
ReStructuredText
======================
|
|
Command Line Interface
|
|
======================
|
|
|
|
This document describes the various command line tools exposed by
|
|
``oslo.policy`` to manage policies and policy files.
|
|
|
|
oslopolicy-checker
|
|
==================
|
|
|
|
Run the command line ``oslopolicy-checker`` to check policy against the
|
|
OpenStack Identity API access information.
|
|
|
|
Command-line arguments:
|
|
|
|
* ``--policy POLICY`` path to policy file.
|
|
* ``--access ACCESS`` path to access token file.
|
|
* ``--rule RULE`` (optional) rule to test. If omitted, tests all rules.
|
|
* ``--is_admin IS_ADMIN`` (optional) set is_admin=True on the credentials.
|
|
|
|
Sample access tokens are provided in the ``sample_data`` directory.
|
|
|
|
Examples
|
|
--------
|
|
|
|
Test all of Nova's policy with an admin token
|
|
|
|
.. code-block:: bash
|
|
|
|
tox -e venv -- oslopolicy-checker \
|
|
--policy /opt/stack/nova/etc/nova/policy.json
|
|
--access sample_data/auth_v3_token_admin.json
|
|
|
|
Test the ``compute_extension:flavorextraspecs:index`` rule in Nova's policy
|
|
with the admin member token and ``is_admin`` set to ``True``
|
|
|
|
.. code-block:: bash
|
|
|
|
tox -e venv -- oslopolicy-checker \
|
|
--policy /opt/stack/nova/etc/nova/policy.json \
|
|
--access sample_data/auth_v3_token_admin.json \
|
|
--is_admin=true --rule compute_extension:flavorextraspecs:index
|
|
|
|
Test the ``compute_extension:flavorextraspecs:index`` rule in Nova's policy
|
|
with the plain member token
|
|
|
|
.. code-block:: bash
|
|
|
|
tox -e venv -- oslopolicy-checker \
|
|
--policy /opt/stack/nova/etc/nova/policy.json \
|
|
--access sample_data/auth_v3_token_member.json \
|
|
--rule compute_extension:flavorextraspecs:index
|
|
|
|
oslopolicy-policy-generator
|
|
===========================
|
|
|
|
The ``oslopolicy-policy-generator`` command can be used to generate a policy
|
|
file that shows the effective policy in use. This is generated by merging the
|
|
registered defaults and policies loaded from a configuration file.
|
|
|
|
Examples
|
|
--------
|
|
|
|
The generate the effective policy file for a namespace called ``keystone``:
|
|
|
|
.. code-block:: bash
|
|
|
|
oslopolicy-policy-generator --namespace keystone
|
|
|
|
To generate the effective policy file in JSON:
|
|
|
|
.. code-block:: bash
|
|
|
|
oslopolicy-policy-generator --namespace keystone --format json
|
|
|
|
To generate the effective policy file and output directly to a file:
|
|
|
|
.. code-block:: bash
|
|
|
|
oslopolicy-policy-generator \
|
|
--namespace keystone \
|
|
--format yaml \
|
|
--output-file keystone-policy.yaml
|
|
|
|
To show the additional options and arguments supported by
|
|
``oslopolicy-policy-generator``:
|
|
|
|
.. code-block:: bash
|
|
|
|
oslopolicy-policy-generator --help
|
|
|
|
oslopolicy-sample-generator
|
|
===========================
|
|
|
|
The ``oslopolicy-sample-generator`` command can be used to generate a sample
|
|
policy file based on the default policies in a given namespace. This tool
|
|
requires a namespace to query for policies and supports output in JSON or YAML.
|
|
|
|
Examples
|
|
--------
|
|
|
|
To generate sample policies for a namespace called ``keystone``:
|
|
|
|
.. code-block:: bash
|
|
|
|
oslopolicy-sample-generator --namespace keystone
|
|
|
|
To generate sample policies in JSON use:
|
|
|
|
.. code-block:: bash
|
|
|
|
oslopolicy-sample-generator --namespace keystone --format json
|
|
|
|
To generate a sample policy file and output directly to a file:
|
|
|
|
.. code-block:: bash
|
|
|
|
oslopolicy-sample-generator --namespace keystone \
|
|
--format yaml \
|
|
--output-file keystone-policy.yaml
|
|
|
|
Use the following to generate help text for additional options and arguments
|
|
supported by ``oslopolicy-sample-generator``:
|
|
|
|
.. code-block:: bash
|
|
|
|
oslopolicy-sample-generator --help
|
|
|
|
oslopolicy-list-redundant
|
|
=========================
|
|
|
|
The ``oslopolicy-list-redundant`` tool is useful for detecting policies that
|
|
are specified in policy files that are the same as the defaults provided by the
|
|
service. Operators can use this tool to find policies that they can remove from
|
|
their policy files, making maintenance easier.
|
|
|
|
This tool assumes a policy file containing overrides exists and is specified
|
|
through configuration.
|
|
|
|
Examples
|
|
--------
|
|
|
|
To list redundant default policies:
|
|
|
|
.. code-block:: bash
|
|
|
|
oslopolicy-list-redundant --namespace keystone --config-dir /etc/keystone
|
|
|
|
For more information regarding the options supported by this tool:
|
|
|
|
.. code-block:: bash
|
|
|
|
oslopolicy-list-redundant --help
|
|
|
|
oslopolicy_validator
|
|
====================
|
|
|
|
The ``oslopolicy-validator`` tool can be used to perform basic sanity checks
|
|
against a policy file. It will detect the following problems:
|
|
|
|
* A missing policy file
|
|
* Rules which have invalid syntax
|
|
* Rules which reference non-existent other rules
|
|
* Rules which form a cyclical reference with another rule
|
|
* Rules which do not exist in the specified namespace
|
|
|
|
This tool does very little validation of the content of the rules. Other tools,
|
|
such as ``oslopolicy-checker``, should be used to check that rules do what is
|
|
intended.
|
|
|
|
``oslopolicy-validator`` exits with a ``0`` return code on success and ``1`` on
|
|
failure.
|
|
|
|
.. note:: At this time the policy validator can only handle single policy
|
|
files, not policy dirs.
|
|
|
|
Examples
|
|
--------
|
|
|
|
Validate the policy file used for Keystone:
|
|
|
|
.. code-block:: bash
|
|
|
|
oslopolicy-validator --config-file /etc/keystone/keystone.conf --namespace keystone
|
|
|
|
Sample output from a failed validation::
|
|
|
|
$ oslopolicy-validator --config-file keystone.conf --namespace keystone
|
|
WARNING:oslo_policy.policy:Policies ['foo', 'bar'] are part of a cyclical reference.
|
|
Invalid rules found
|
|
Failed to parse rule: (role:admin and system_scope:all) or (role:foo and oken.domain.id:%(target.user.domain_id)s))
|
|
Unknown rule found in policy file: foo
|
|
Unknown rule found in policy file: bar
|