Merge "docs: Add separate man page for each CLI tool"
This commit is contained in:
Zuul
Gerrit Code Review
commit
de85774686
19
doc/source/cli/common/default-opts.rst
Normal file
19
doc/source/cli/common/default-opts.rst
Normal 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.
|
||||
4
doc/source/cli/common/enforcer-opts.rst
Normal file
4
doc/source/cli/common/enforcer-opts.rst
Normal file
@ -0,0 +1,4 @@
|
||||
.. option:: --namespace NAMESPACE
|
||||
|
||||
Option namespace under "oslo.policy.enforcer" in which to look for a
|
||||
``policy.Enforcer``.
|
||||
3
doc/source/cli/common/generator-opts.rst
Normal file
3
doc/source/cli/common/generator-opts.rst
Normal file
@ -0,0 +1,3 @@
|
||||
.. option:: --output-file OUTPUT_FILE
|
||||
|
||||
Path of the file to write to. Defaults to stdout.
|
||||
8
doc/source/cli/common/rule-opts.rst
Normal file
8
doc/source/cli/common/rule-opts.rst
Normal 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.
|
||||
@ -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
|
||||
|
||||
94
doc/source/cli/oslopolicy-checker.rst
Normal file
94
doc/source/cli/oslopolicy-checker.rst
Normal 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`
|
||||
52
doc/source/cli/oslopolicy-list-redundant.rst
Normal file
52
doc/source/cli/oslopolicy-list-redundant.rst
Normal 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`
|
||||
67
doc/source/cli/oslopolicy-policy-generator.rst
Normal file
67
doc/source/cli/oslopolicy-policy-generator.rst
Normal 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`
|
||||
68
doc/source/cli/oslopolicy-sample-generator.rst
Normal file
68
doc/source/cli/oslopolicy-sample-generator.rst
Normal 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`
|
||||
58
doc/source/cli/oslopolicy-validator.rst
Normal file
58
doc/source/cli/oslopolicy-validator.rst
Normal 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`
|
||||
@ -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 = {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user