From 597fd0440b32e347f594834ff0fad78436f23e61 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Tue, 28 Apr 2020 11:41:27 +0100 Subject: [PATCH] docs: Add separate man page for each CLI tool Change-Id: Ifcfc88a67b038528f03756d550e1ddf8726cb37a Signed-off-by: Stephen Finucane --- doc/source/cli/common/default-opts.rst | 19 ++ doc/source/cli/common/enforcer-opts.rst | 4 + doc/source/cli/common/generator-opts.rst | 3 + doc/source/cli/common/rule-opts.rst | 8 + doc/source/cli/index.rst | 194 +----------------- doc/source/cli/oslopolicy-checker.rst | 94 +++++++++ doc/source/cli/oslopolicy-list-redundant.rst | 52 +++++ .../cli/oslopolicy-policy-generator.rst | 67 ++++++ .../cli/oslopolicy-sample-generator.rst | 68 ++++++ doc/source/cli/oslopolicy-validator.rst | 58 ++++++ doc/source/conf.py | 33 ++- 11 files changed, 413 insertions(+), 187 deletions(-) create mode 100644 doc/source/cli/common/default-opts.rst create mode 100644 doc/source/cli/common/enforcer-opts.rst create mode 100644 doc/source/cli/common/generator-opts.rst create mode 100644 doc/source/cli/common/rule-opts.rst create mode 100644 doc/source/cli/oslopolicy-checker.rst create mode 100644 doc/source/cli/oslopolicy-list-redundant.rst create mode 100644 doc/source/cli/oslopolicy-policy-generator.rst create mode 100644 doc/source/cli/oslopolicy-sample-generator.rst create mode 100644 doc/source/cli/oslopolicy-validator.rst diff --git a/doc/source/cli/common/default-opts.rst b/doc/source/cli/common/default-opts.rst new file mode 100644 index 00000000..d439893b --- /dev/null +++ b/doc/source/cli/common/default-opts.rst @@ -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. diff --git a/doc/source/cli/common/enforcer-opts.rst b/doc/source/cli/common/enforcer-opts.rst new file mode 100644 index 00000000..ae113541 --- /dev/null +++ b/doc/source/cli/common/enforcer-opts.rst @@ -0,0 +1,4 @@ +.. option:: --namespace NAMESPACE + + Option namespace under "oslo.policy.enforcer" in which to look for a + ``policy.Enforcer``. diff --git a/doc/source/cli/common/generator-opts.rst b/doc/source/cli/common/generator-opts.rst new file mode 100644 index 00000000..b88549f9 --- /dev/null +++ b/doc/source/cli/common/generator-opts.rst @@ -0,0 +1,3 @@ +.. option:: --output-file OUTPUT_FILE + + Path of the file to write to. Defaults to stdout. diff --git a/doc/source/cli/common/rule-opts.rst b/doc/source/cli/common/rule-opts.rst new file mode 100644 index 00000000..3167c7c7 --- /dev/null +++ b/doc/source/cli/common/rule-opts.rst @@ -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. diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst index bef7c99d..b8e54d8e 100644 --- a/doc/source/cli/index.rst +++ b/doc/source/cli/index.rst @@ -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 diff --git a/doc/source/cli/oslopolicy-checker.rst b/doc/source/cli/oslopolicy-checker.rst new file mode 100644 index 00000000..b72354fa --- /dev/null +++ b/doc/source/cli/oslopolicy-checker.rst @@ -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` diff --git a/doc/source/cli/oslopolicy-list-redundant.rst b/doc/source/cli/oslopolicy-list-redundant.rst new file mode 100644 index 00000000..ed565161 --- /dev/null +++ b/doc/source/cli/oslopolicy-list-redundant.rst @@ -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` diff --git a/doc/source/cli/oslopolicy-policy-generator.rst b/doc/source/cli/oslopolicy-policy-generator.rst new file mode 100644 index 00000000..a64595d9 --- /dev/null +++ b/doc/source/cli/oslopolicy-policy-generator.rst @@ -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` diff --git a/doc/source/cli/oslopolicy-sample-generator.rst b/doc/source/cli/oslopolicy-sample-generator.rst new file mode 100644 index 00000000..c7287712 --- /dev/null +++ b/doc/source/cli/oslopolicy-sample-generator.rst @@ -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` diff --git a/doc/source/cli/oslopolicy-validator.rst b/doc/source/cli/oslopolicy-validator.rst new file mode 100644 index 00000000..11b7cb9d --- /dev/null +++ b/doc/source/cli/oslopolicy-validator.rst @@ -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` diff --git a/doc/source/conf.py b/doc/source/conf.py index 0ec69f1d..d47d4bcb 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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 = {