Merge "docs: Add separate man page for each CLI tool"

This commit is contained in:
Zuul 2020-07-01 11:05:05 +00:00 committed by Gerrit Code Review
commit de85774686
11 changed files with 413 additions and 187 deletions

View File

@ -0,0 +1,19 @@
.. option:: -h, --help
Show help message and exit.
.. option:: --config-dir DIR
Path to a config directory to pull ``*.conf`` files from. This file set is
sorted, so as to provide a predictable parse order if individual options
are overridden. The set is parsed after the file(s) specified via previous
``--config-file``, arguments hence overridden options in the directory
take precedence.
This option must be set from the command-line.
.. option:: --config-file PATH
Path to a config file to use. Multiple config files can be specified, with
values in later files taking precedence. Defaults to None. This option must
be set from the command-line.

View File

@ -0,0 +1,4 @@
.. option:: --namespace NAMESPACE
Option namespace under "oslo.policy.enforcer" in which to look for a
``policy.Enforcer``.

View File

@ -0,0 +1,3 @@
.. option:: --output-file OUTPUT_FILE
Path of the file to write to. Defaults to stdout.

View File

@ -0,0 +1,8 @@
.. option:: --format FORMAT
Desired format for the output. Allowed values: ``json``, ``yaml``
.. option:: --namespace NAMESPACE
Option namespace(s) under "oslo.policy.policies" in which to query for
options.

View File

@ -5,189 +5,11 @@ 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
.. toctree::
:maxdepth: 1
oslopolicy-checker
oslopolicy-validator
oslopolicy-list-redundant
oslopolicy-policy-generator
oslopolicy-sample-generator

View File

@ -0,0 +1,94 @@
==================
oslopolicy-checker
==================
.. program:: oslopolicy-checker
Synopsis
--------
::
oslopolicy-checker [-h] [--access ACCESS] [--config-dir DIR]
[--config-file PATH]
[--enforcer_config ENFORCER_CONFIG] [--is_admin]
[--nois_admin] [--policy POLICY] [--rule RULE]
[--target TARGET]
Description
-----------
The ``oslopolicy-policy-generator`` command can be used to check policy against
the OpenStack Identity API access information.
Options
-------
.. include:: common/default-opts.rst
.. option:: --access ACCESS
Path to a file containing OpenStack Identity API access info in JSON
format.
.. option:: --enforcer_config ENFORCER_CONFIG
Configuration file for the oslopolicy-checker enforcer
.. option:: --is_admin
Set ``is_admin=True`` on the credentials used for the evaluation.
.. option:: --nois_admin
The inverse of ``--is_admin``
.. option:: --policy POLICY
Path to a policy file.
.. option:: --rule RULE
Rule to test.
.. option:: --target TARGET
Path to a file containing custom target info in JSON format. This will be
used to evaluate the policy with.
Examples
--------
Test all of Nova's policy with an admin token:
.. code-block:: bash
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
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
oslopolicy-checker \
--policy /opt/stack/nova/etc/nova/policy.json \
--access sample_data/auth_v3_token_member.json \
--rule compute_extension:flavorextraspecs:index
See Also
--------
:program:`oslopolicy-sample-generator`, :program:`oslopolicy-policy-generator`,
:program:`oslopolicy-list-redundant`, :program:`oslopolicy-validator`

View File

@ -0,0 +1,52 @@
=========================
oslopolicy-list-redundant
=========================
.. program:: oslopolicy-list-redundant
Synopsis
--------
::
oslopolicy-list-redundant [-h] [--config-dir DIR] [--config-file PATH]
[--namespace NAMESPACE]
Description
-----------
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.
Options
-------
.. include:: common/default-opts.rst
.. include:: common/enforcer-opts.rst
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
See Also
--------
:program:`oslopolicy-sample-generator`, :program:`oslopolicy-policy-generator`,
:program:`oslopolicy-checker`

View File

@ -0,0 +1,67 @@
===========================
oslopolicy-policy-generator
===========================
.. program:: oslopolicy-policy-generator
Synopsis
--------
::
oslopolicy-policy-generator [-h] [--config-dir DIR] [--config-file PATH]
[--namespace NAMESPACE]
[--output-file OUTPUT_FILE]
Description
-----------
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.
Options
-------
.. include:: common/default-opts.rst
.. include:: common/enforcer-opts.rst
.. include:: common/generator-opts.rst
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
See Also
--------
:program:`oslopolicy-sample-generator`, :program:`oslopolicy-list-redundant`,
:program:`oslopolicy-checker`

View File

@ -0,0 +1,68 @@
===========================
oslopolicy-sample-generator
===========================
.. program:: oslopolicy-sample-generator
Synopsis
--------
::
oslopolicy-sample-generator [-h] [--config-dir DIR]
[--config-file PATH] [--format FORMAT]
[--namespace NAMESPACE]
[--output-file OUTPUT_FILE]
Description
-----------
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.
Options
-------
.. include:: common/default-opts.rst
.. include:: common/rule-opts.rst
.. include:: common/generator-opts.rst
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
See Also
--------
:program:`oslopolicy-policy-generator`, :program:`oslopolicy-list-redundant`,
:program:`oslopolicy-checker`

View File

@ -0,0 +1,58 @@
====================
oslopolicy-validator
====================
.. program:: oslopolicy-policy-validator
Synopsis
--------
::
oslopolicy-policy-validator
Description
-----------
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.
Options
-------
.. include:: common/default-opts.rst
.. include:: common/enforcer-opts.rst
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
See Also
--------
:program:`oslopolicy-checker`

View File

@ -40,7 +40,7 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
copyright = u'2014, OpenStack Foundation'
copyright = '2014-2020, OpenStack Foundation'
source_tree = 'https://opendev.org/openstack/oslo.policy/src/branch/master'
# If true, '()' will be appended to :func: etc. cross-reference text.
@ -62,6 +62,37 @@ modindex_common_prefix = ['oslo_policy.']
# Sphinx are currently 'default' and 'sphinxdoc'.
html_theme = 'openstackdocs'
# -- Options for man page output ---------------------------------------------
# Grouping the document tree for man pages.
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
_man_pages = [
(
'oslopolicy-checker',
'Check policy against the OpenStack Identity API access information.',
),
(
'oslopolicy-list-redundant',
'Detect policies that are specified in policy files that are the same '
'as the defaults provided by the service',
),
(
'oslopolicy-policy-generator',
'Generate a policy file that shows the effective policy in use',
),
(
'oslopolicy-sample-generator',
'Generate a sample policy file based on the default policies in a '
'given namespace',
),
]
man_pages = [
(f'cli/{name}', name, description, 'OpenStack Community', 1)
for name, description in _man_pages
]
# -- sphinx.ext.extlinks configuration ---------------------------------------
extlinks = {