oslo.policy/doc/source/cli/index.rst

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

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

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

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:

oslopolicy-policy-generator --namespace keystone

To generate the effective policy file in JSON:

oslopolicy-policy-generator --namespace keystone --format json

To generate the effective policy file and output directly to a file:

oslopolicy-policy-generator \
  --namespace keystone \
  --format yaml \
  --output-file keystone-policy.yaml

To show the additional options and arguments supported by oslopolicy-policy-generator:

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:

oslopolicy-sample-generator --namespace keystone

To generate sample policies in JSON use:

oslopolicy-sample-generator --namespace keystone --format json

To generate a sample policy file and output directly to a file:

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:

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:

oslopolicy-list-redundant --namespace keystone --config-dir /etc/keystone

For more information regarding the options supported by this tool:

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:

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