Improve keystone.conf [DEFAULT] documentation

Change-Id: Ib46ae96c2a7985a321b3ee32fbeea3e673f59505
This commit is contained in:
Dolph Mathews 2016-06-27 21:18:31 +00:00
parent 83472401ef
commit 4eb93c070f
1 changed files with 79 additions and 48 deletions

View File

@ -15,22 +15,29 @@ from oslo_config import cfg
from keystone.conf import utils
_DEPRECATE_DII_MSG = utils.fmt("""
_DEPRECATE_MUTABLE_DOMAIN_IDS = utils.fmt("""
The option to set domain_id_immutable to false has been deprecated in the M
release and will be removed in the O release.
""")
_DEPRECATE_PROXY_SSL = utils.fmt("""
Use oslo.middleware.http_proxy_to_wsgi configuration instead.
""")
admin_token = cfg.StrOpt(
'admin_token',
secret=True,
help=utils.fmt("""
A "shared secret" that can be used to bootstrap Keystone. This "token" does not
represent a user, and carries no explicit authorization. If set to `None`, the
value is ignored and the `admin_token` log in mechanism is effectively
disabled. To completely disable `admin_token` in production (highly
recommended), remove AdminTokenAuthMiddleware from your paste application
pipelines (for example, in keystone-paste.ini).
Using this feature is *NOT* recommended. Instead, use the `keystone-manage
bootstrap` command. The value of this option is treated as a "shared secret"
that can be used to bootstrap Keystone through the API. This "token" does not
represent a user (it has no identity), and carries no explicit authorization
(it effectively bypasses most authorization checks). If set to `None`, the
value is ignored and the `admin_token` middleware is effectively disabled.
However, to completely disable `admin_token` in production (highly recommended,
as it presents a security risk), remove `AdminTokenAuthMiddleware`
(the `admin_token_auth` filter) from your paste application pipelines (for
example, in `keystone-paste.ini`).
"""))
public_endpoint = cfg.StrOpt(
@ -38,10 +45,11 @@ public_endpoint = cfg.StrOpt(
help=utils.fmt("""
The base public endpoint URL for Keystone that is advertised to clients (NOTE:
this does NOT affect how Keystone listens for connections). Defaults to the
base host URL of the request. E.g. a request to http://server:5000/v3/users
will default to http://server:5000. You should only need to set this value if
the base URL contains a path (e.g. /prefix/v3) or the endpoint should be found
on a different server.
base host URL of the request. For example, if keystone receives a request to
`http://server:5000/v3/users`, then this will option will be automatically
treated as `http://server:5000`. You should only need to set option if either
the value of the base URL contains a path that keystone does not automatically
infer (`/prefix/v3`), or if the endpoint should be found on a different host.
"""))
admin_endpoint = cfg.StrOpt(
@ -49,10 +57,11 @@ admin_endpoint = cfg.StrOpt(
help=utils.fmt("""
The base admin endpoint URL for Keystone that is advertised to clients (NOTE:
this does NOT affect how Keystone listens for connections). Defaults to the
base host URL of the request. E.g. a request to http://server:35357/v3/users
will default to http://server:35357. You should only need to set this value if
the base URL contains a path (e.g. /prefix/v3) or the endpoint should be found
on a different server.
base host URL of the request. For example, if keystone receives a request to
`http://server:35357/v3/users`, then this will option will be automatically
treated as `http://server:35357`. You should only need to set option if either
the value of the base URL contains a path that keystone does not automatically
infer (`/prefix/v3`), or if the endpoint should be found on a different host.
"""))
max_project_tree_depth = cfg.IntOpt(
@ -60,8 +69,8 @@ max_project_tree_depth = cfg.IntOpt(
default=5,
help=utils.fmt("""
Maximum depth of the project hierarchy, excluding the project acting as a
domain at the top of the hierarchy. WARNING: setting it to a large value may
adversely impact performance.
domain at the top of the hierarchy. WARNING: Setting it to a large value may
adversely impact performance.
"""))
max_param_size = cfg.IntOpt(
@ -76,24 +85,33 @@ max_token_size = cfg.IntOpt(
'max_token_size',
default=8192,
help=utils.fmt("""
Similar to max_param_size, but provides an exception for token values.
Similar to `[DEFAULT] max_param_size`, but provides an exception for token
values. With PKI / PKIZ tokens, this needs to be set close to 8192 (any higher,
and other HTTP implementations may break), depending on the size of your
service catalog and other factors. With Fernet tokens, this can be set as low
as 255. With UUID tokens, this should be set to 32).
"""))
member_role_id = cfg.StrOpt(
'member_role_id',
default='9fe2ff9ee4384b1894a90878d3e92bab',
help=utils.fmt("""
Similar to the member_role_name option, this represents the default role ID
used to associate users with their default projects in the v2 API. This will be
used as the explicit role where one is not specified by the v2 API.
Similar to the `[DEFAULT] member_role_name` option, this represents the default
role ID used to associate users with their default projects in the v2 API. This
will be used as the explicit role where one is not specified by the v2 API. You
do not need to set this value unless you want keystone to use an existing role
with a different ID, other than the arbitrarily defined `_member_` role (in
which case, you should set `[DEFAULT] member_role_name` as well).
"""))
member_role_name = cfg.StrOpt(
'member_role_name',
default='_member_',
help=utils.fmt("""
This is the role name used in combination with the member_role_id option; see
that option for more detail.
This is the role name used in combination with the `[DEFAULT] member_role_id`
option; see that option for more detail. You do not need to set this option
unless you want keystone to use an existing role (in which case, you should set
`[DEFAULT] member_role_id` as well).
"""))
# NOTE(lbragstad/morganfainberg): This value of 10k was measured as having an
@ -107,29 +125,38 @@ crypt_strength = cfg.IntOpt(
min=1000,
max=100000,
help=utils.fmt("""
The value passed as the keyword "rounds" to passlib\'s encrypt method.
The value passed as the keyword "rounds" to passlib's encrypt method. This
option represents a trade off between security and performance. Higher values
lead to slower performance, but higher security. Changing this option will only
affect newly created passwords as existing password hashes already have a fixed
number of rounds applied, so it is safe to tune this option in a running
cluster. For more information, see
https://pythonhosted.org/passlib/password_hash_api.html#choosing-the-right-rounds-value
"""))
list_limit = cfg.IntOpt(
'list_limit',
help=utils.fmt("""
The maximum number of entities that will be returned in a collection, with no
limit set by default. This global limit may be then overridden for a specific
driver, by specifying a list_limit in the appropriate section (e.g.
[assignment]).
The maximum number of entities that will be returned in a collection. This
global limit may be then overridden for a specific driver, by specifying a
list_limit in the appropriate section (for example, `[assignment]`). No limit
is set by default. In larger deployments, it is recommended that you set this
to a reasonable number to prevent operations like listing all users and
projects from placing an unnecessary load on the system.
"""))
domain_id_immutable = cfg.BoolOpt(
'domain_id_immutable',
default=True,
deprecated_for_removal=True,
deprecated_reason=_DEPRECATE_DII_MSG,
deprecated_reason=_DEPRECATE_MUTABLE_DOMAIN_IDS,
help=utils.fmt("""
Set this to false if you want to enable the ability for user, group and project
entities to be moved between domains by updating their domain_id. Allowing such
movement is not recommended if the scope of a domain admin is being restricted
by use of an appropriate policy file (see policy.v3cloudsample as an example).
This ability is deprecated and will be removed in a future release.
entities to be moved between domains by updating their `domain_id` attribute.
Allowing such movement is not recommended if the scope of a domain admin is
being restricted by use of an appropriate policy file (see
`etc/policy.v3cloudsample.json` as an example). This feature is deprecated and
will be removed in a future release, in favor of strictly immutable domain IDs.
"""))
strict_password_check = cfg.BoolOpt(
@ -146,9 +173,7 @@ secure_proxy_ssl_header = cfg.StrOpt(
'secure_proxy_ssl_header',
default='HTTP_X_FORWARDED_PROTO',
deprecated_for_removal=True,
deprecated_reason=utils.fmt("""
Use http_proxy_to_wsgi middleware configuration instead.
"""),
deprecated_reason=_DEPRECATE_PROXY_SSL,
help=utils.fmt("""
The HTTP header used to determine the scheme for the original request, even if
it was removed by an SSL terminating proxy.
@ -158,16 +183,17 @@ insecure_debug = cfg.BoolOpt(
'insecure_debug',
default=False,
help=utils.fmt("""
If set to true the server will return information in the response that may
allow an unauthenticated or authenticated user to get more information than
normal, such as why authentication failed. This may be useful for debugging but
is insecure.
If set to true, then the server will return information in HTTP responses that
may allow an unauthenticated or authenticated user to get more information than
normal, such as additional details about why authentication failed. This may be
useful for debugging but is insecure.
"""))
default_publisher_id = cfg.StrOpt(
'default_publisher_id',
help=utils.fmt("""
Default publisher_id for outgoing notifications
Default `publisher_id` for outgoing notifications. If left undefined, Keystone
will default to using the server's host name.
"""))
notification_format = cfg.StrOpt(
@ -175,19 +201,24 @@ notification_format = cfg.StrOpt(
default='basic',
choices=['basic', 'cadf'],
help=utils.fmt("""
Define the notification format for Identity Service events. A "basic"
notification has information about the resource being operated on. A "cadf"
notification has the same information, as well as information about the
initiator of the event.
Define the notification format for identity service events. A `basic`
notification only has information about the resource being operated on. A
`cadf` notification has the same information, as well as information about the
initiator of the event. The `cadf` option is entirely backwards compatible with
the `basic` option, but is fully CADF-compliant, and is recommended for
auditing use cases.
"""))
notification_opt_out = cfg.MultiStrOpt(
'notification_opt_out',
default=[],
help=utils.fmt("""
Define the notification options to opt-out from. The value expected is:
identity.<resource_type>.<operation>. This field can be set multiple times in
order to add more notifications to opt-out from. For example:
If left undefined, keystone will emit notifications for all types of events.
You can reduce the number of notifications keystone emits by using this option
to enumerate notification topics that should be suppressed. Values are expected
to be in the form `identity.<resource_type>.<operation>`. This field can be set
multiple times in order to opt-out of multiple notification topics. For
example:
notification_opt_out=identity.user.create
notification_opt_out=identity.authenticate.success
"""))