"Fossies" - the Fresh Open Source Software Archive

Member "keystone-18.0.0/doc/source/admin/domain-specific-config.inc" (14 Oct 2020, 9684 Bytes) of package /linux/misc/openstack/keystone-18.0.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) fasm source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "domain-specific-config.inc" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 17.0.0_vs_18.0.0.

    1 .. -*- rst -*-
    2 
    3 .. _domain_specific_configuration:
    4 
    5 Domain-specific configuration
    6 =============================
    7 
    8 The Identity service supports domain-specific Identity drivers.
    9 The drivers allow a domain to have its own LDAP or SQL back end.
   10 By default, domain-specific drivers are disabled.
   11 
   12 Domain-specific Identity configuration options can be stored in
   13 domain-specific configuration files, or in the Identity SQL
   14 database using API REST calls.
   15 
   16 .. note::
   17 
   18    Storing and managing configuration options in an SQL database is
   19    experimental in Kilo, and added to the Identity service in the
   20    Liberty release.
   21 
   22 .. _enable_drivers_for_domain:
   23 
   24 Enable drivers for domain-specific configuration files
   25 ------------------------------------------------------
   26 
   27 To enable domain-specific drivers, set these options in the
   28 ``/etc/keystone/keystone.conf`` file:
   29 
   30 .. code-block:: ini
   31 
   32    [identity]
   33    domain_specific_drivers_enabled = True
   34    domain_config_dir = /etc/keystone/domains
   35 
   36 When you enable domain-specific drivers, Identity looks in the
   37 ``domain_config_dir`` directory for configuration files that are named as
   38 ``keystone.DOMAIN_NAME.conf``. A domain without a domain-specific
   39 configuration file uses options in the primary configuration file.
   40 
   41 Enable drivers for storing configuration options in SQL database
   42 ----------------------------------------------------------------
   43 
   44 To enable domain-specific drivers, set these options in the
   45 ``/etc/keystone/keystone.conf`` file:
   46 
   47 .. code-block:: ini
   48 
   49    [identity]
   50    domain_specific_drivers_enabled = True
   51    domain_configurations_from_database = True
   52 
   53 Any domain-specific configuration options specified through the
   54 Identity v3 API will override domain-specific configuration files in the
   55 ``/etc/keystone/domains`` directory.
   56 
   57 Unlike the file-based method of specifying domain-specific configurations,
   58 options specified via the Identity API will become active without needing to
   59 restart the keystone server. For performance reasons, the current state of
   60 configuration options for a domain are cached in the keystone server, and in
   61 multi-process and multi-threaded keystone configurations, the new
   62 configuration options may not become active until the cache has timed out. The
   63 cache settings for domain config options can be adjusted in the general
   64 keystone configuration file (option ``cache_time`` in the ``domain_config``
   65 group).
   66 
   67 .. NOTE::
   68 
   69     It is important to notice that when using either of these methods of
   70     specifying domain-specific configuration options, the main keystone
   71     configuration file is still maintained. Only those options that relate
   72     to the Identity driver for users and groups (i.e. specifying whether the
   73     driver for this domain is SQL or LDAP, and, if LDAP, the options that
   74     define that connection) are supported in a domain-specific manner. Further,
   75     when using the configuration options via the Identity API, the driver
   76     option must be set to an LDAP driver (attempting to set it to an SQL driver
   77     will generate an error when it is subsequently used).
   78 
   79 For existing installations that already use file-based domain-specific
   80 configurations who wish to migrate to the SQL-based approach, the
   81 ``keystone-manage`` command can be used to upload all configuration files to
   82 the SQL database:
   83 
   84 .. code-block:: bash
   85 
   86     $ keystone-manage domain_config_upload --all
   87 
   88 Once uploaded, these domain-configuration options will be visible via the
   89 Identity API as well as applied to the domain-specific drivers. It is also
   90 possible to upload individual domain-specific configuration files by
   91 specifying the domain name:
   92 
   93 .. code-block:: bash
   94 
   95     $ keystone-manage domain_config_upload --domain-name DOMAINA
   96 
   97 .. NOTE::
   98 
   99     It is important to notice that by enabling either of the domain-specific
  100     configuration methods, the operations of listing all users and listing all
  101     groups are not supported, those calls will need either a domain filter to
  102     be specified or usage of a domain scoped token.
  103 
  104 .. NOTE::
  105 
  106     Keystone does not support moving the contents of a domain (i.e. "its" users
  107     and groups) from one backend to another, nor group membership across
  108     backend boundaries.
  109 
  110 .. NOTE::
  111 
  112     When using the file-based domain-specific configuration method, to delete a
  113     domain that uses a domain specific backend, it's necessary to first disable
  114     it, remove its specific configuration file (i.e. its corresponding
  115     keystone.<domain_name>.conf) and then restart the Identity server. When
  116     managing configuration options via the Identity API, the domain can simply
  117     be disabled and deleted via the Identity API; since any domain-specific
  118     configuration options will automatically be removed.
  119 
  120 .. NOTE::
  121 
  122     Although keystone supports multiple LDAP backends via the above
  123     domain-specific configuration methods, it currently only supports one SQL
  124     backend. This could be either the default driver or a single
  125     domain-specific backend, perhaps for storing service users in a
  126     predominantly LDAP installation.
  127 
  128 .. NOTE::
  129 
  130     Keystone has deprecated the ``keystone-manage domain_config_upload``
  131     option. The keystone team recommends setting domain config options via the
  132     API instead.
  133 
  134 Due to the need for user and group IDs to be unique across an OpenStack
  135 installation and for keystone to be able to deduce which domain and backend to
  136 use from just a user or group ID, it dynamically builds a persistent identity
  137 mapping table from a public ID to the actual domain, local ID (within that
  138 backend) and entity type. The public ID is automatically generated by keystone
  139 when it first encounters the entity. If the local ID of the entity is from a
  140 backend that does not guarantee to generate UUIDs, a hash algorithm will
  141 generate a public ID for that entity, which is what will be exposed by
  142 keystone.
  143 
  144 The use of a hash will ensure that if the public ID needs to be regenerated
  145 then the same public ID will be created. This is useful if you are running
  146 multiple keystones and want to ensure the same ID would be generated whichever
  147 server you hit.
  148 
  149 While keystone will dynamically maintain the identity mapping, including
  150 removing entries when entities are deleted via the keystone, for those entities
  151 in backends that are managed outside of keystone (e.g. a read-only LDAP),
  152 keystone will not know if entities have been deleted and hence will continue to
  153 carry stale identity mappings in its table. While benign, keystone provides an
  154 ability for operators to purge the mapping table of such stale entries using
  155 the keystone-manage command, for example:
  156 
  157 .. code-block:: bash
  158 
  159     $ keystone-manage mapping_purge --domain-name DOMAINA --local-id abc@de.com
  160 
  161 A typical usage would be for an operator to obtain a list of those entries in
  162 an external backend that had been deleted out-of-band to keystone, and then
  163 call keystone-manage to purge those entries by specifying the domain and
  164 local-id. The type of the entity (i.e. user or group) may also be specified if
  165 this is needed to uniquely identify the mapping.
  166 
  167 Since public IDs can be regenerated **with the correct generator
  168 implementation**, if the details of those entries that have been deleted are
  169 not available, then it is safe to simply bulk purge identity mappings
  170 periodically, for example:
  171 
  172 .. code-block:: bash
  173 
  174     $ keystone-manage mapping_purge --domain-name DOMAINA
  175 
  176 will purge all the mappings for DOMAINA. The entire mapping table can be purged
  177 with the following command:
  178 
  179 .. code-block:: bash
  180 
  181     $ keystone-manage mapping_purge --all
  182 
  183 Generating public IDs in the first run may take a while, and most probably
  184 first API requests to fetch user list will fail by timeout. To prevent this,
  185 ``mapping_populate`` command should be executed. It should be executed right after
  186 LDAP has been configured or after ``mapping_purge``.
  187 
  188 .. code-block:: bash
  189 
  190     $ keystone-manage mapping_populate --domain DOMAINA
  191 
  192 Public ID Generators
  193 --------------------
  194 
  195 Keystone supports a customizable public ID generator and it is specified in the
  196 ``[identity_mapping]`` section of the configuration file. Keystone provides a
  197 sha256 generator as default, which produces regenerable public IDs. The
  198 generator algorithm for public IDs is a balance between key size (i.e. the
  199 length of the public ID), the probability of collision and, in some
  200 circumstances, the security of the public ID. The maximum length of public ID
  201 supported by keystone is 64 characters, and the default generator (sha256) uses
  202 this full capability. Since the public ID is what is exposed externally by
  203 keystone and potentially stored in external systems, some installations may
  204 wish to make use of other generator algorithms that have a different trade-off
  205 of attributes. A different generator can be installed by configuring the
  206 following property:
  207 
  208 * ``generator`` - identity mapping generator. Defaults to ``sha256``
  209   (implemented by :class:`keystone.identity.id_generators.sha256.Generator`)
  210 
  211 .. WARNING::
  212 
  213     Changing the generator may cause all existing public IDs to be become
  214     invalid, so typically the generator selection should be considered
  215     immutable for a given installation.
  216 
  217 Migrate domain-specific configuration files to the SQL database
  218 ---------------------------------------------------------------
  219 
  220 You can use the ``keystone-manage`` command to migrate configuration
  221 options in domain-specific configuration files to the SQL database:
  222 
  223 .. code-block:: console
  224 
  225    # keystone-manage domain_config_upload --all
  226 
  227 To upload options from a specific domain-configuration file, specify the
  228 domain name:
  229 
  230 .. code-block:: console
  231 
  232    # keystone-manage domain_config_upload --domain-name DOMAIN_NAME