diff --git a/doc/admin-guide-cloud/bk-admin-guide-cloud.xml b/doc/admin-guide-cloud/bk-admin-guide-cloud.xml index f11740ac49..135e1957c3 100644 --- a/doc/admin-guide-cloud/bk-admin-guide-cloud.xml +++ b/doc/admin-guide-cloud/bk-admin-guide-cloud.xml @@ -75,6 +75,7 @@ + diff --git a/doc/admin-guide-cloud/ch_compute.xml b/doc/admin-guide-cloud/ch_compute.xml index b2d9fe8592..cecab42273 100644 --- a/doc/admin-guide-cloud/ch_compute.xml +++ b/doc/admin-guide-cloud/ch_compute.xml @@ -334,138 +334,53 @@ -
- Identity management - The Identity Service, code-named Keystone, is the default identity service for OpenStack. - After you install the Identity Service, you configure it through the - etc/keystone.conf configuration file, the PasteDeploy - etc/keystone-paste.ini configuration file, and possibly a - separate logging configuration file. You use the keystone command-line client to - initialize data into the Identity Service. - -
- Memcached and system time - If you use memcached with the Identity Service—for example, using the - memcache token driver or the auth_token - middleware—ensure that the system time of memcached - hosts is set to UTC. Memcached uses the host's system time in - determining whether a key has expired, whereas the Identity Service sets key - expiry in UTC. The timezone used by the Identity Service and memcached must - match if key expiry is to behave as expected. -
-
- User CRUD - The Identity Service provides a user CRUD filter that can be - added to the public_api pipeline. This user crud filter allows - users to use a HTTP PATCH to change their own password. To - enable this extension you should define a - user_crud_extension filter, insert it after - the *_body middleware and before the - public_service app in the public_api WSGI - pipeline in keystone-paste.ini. For example: - [filter:user_crud_extension] -paste.filter_factory = keystone.contrib.user_crud:CrudExtension.factory - -[pipeline:public_api] -pipeline = stats_monitoring url_normalize token_auth admin_token_auth xml_body json_body debug ec2_extension user_crud_extension public_service - Each user can change their own password with a HTTP PATCH, - as follows: - $ curl -X PATCH http://localhost:5000/v2.0/OS-KSCRUD/users/<userid> -H "Content-type: application/json" \ - -H "X_Auth_Token: <authtokenid>" -d '{"user": {"password": "ABCD", "original_password": "DCBA"}}' - If the backend is kvs or sql, all users' passwords are - changed and their tokens are deleted. -
-
- Monitoring - The Identity Service provides some basic request/response monitoring - statistics. - To enable data collection, define a - stats_monitoring filter and include it at - the beginning of any desired WSGI pipelines in - keystone-paste.ini, as follows: - [filter:stats_monitoring] -paste.filter_factory = keystone.contrib.stats:StatsMiddleware.factory - -[pipeline:public_api] -pipeline = stats_monitoring [...] public_service - To enable reporting of collected data, define a - stats_reporting filter and include it near - the end of your admin_api WSGI pipeline after - *_body middleware and before - *_extension filters, as follows: - [filter:stats_reporting] -paste.filter_factory = keystone.contrib.stats:StatsExtension.factory - -[pipeline:admin_api] -pipeline = [...] json_body stats_reporting ec2_extension [...] admin_service - Query the admin API for statistics, as follows: - $ curl -H 'X-Auth-Token: ADMIN' http://localhost:35357/v2.0/OS-STATS/stats - Reset collected data, as follows: - $ curl -H 'X-Auth-Token: ADMIN' -X DELETE http://localhost:35357/v2.0/OS-STATS/stats -
- -
- Run the Identity Service - To start the Identity Service, run the following - command: - $ keystone-all - This command starts two wsgi.Server instances, configured by - the keystone.conf and - keystone-paste.ini configuration file. - One of these wsgi 'servers' is admin (the - administration API) and the other is main - (the primary/public API interface). Both of these run in a - single process. -
- -
- Image management - The OpenStack Image Service, code-named glance, - discovers, registers, and retrieves virtual machine images. - The service includes a RESTful API that - allows users to query VM image metadata and retrieve the actual image with HTTP requests. - You can also use the glance - command-line tool, or the Python API - to accomplish the same tasks. - VM images made available through OpenStack Image Service can be stored in a variety of - locations. The OpenStack Image Service supports the following backend stores: - - - OpenStack Object Storage - OpenStack Object Storage (code-named Image management + The OpenStack Image Service, code-named glance, + discovers, registers, and retrieves virtual machine images. + The service includes a RESTful API that + allows users to query VM image metadata and retrieve the actual image with HTTP requests. + You can also use the glance + command-line tool, or the Python API + to accomplish the same tasks. + VM images made available through OpenStack Image Service can be stored in a variety of + locations. The OpenStack Image Service supports the following backend stores: + + + OpenStack Object Storage - OpenStack Object Storage (code-named swift) is the highly-available object storage project - in OpenStack. - - - Filesystem - The default backend that OpenStack - Image Service uses to store virtual machine images is - the filesystem backend. This simple backend writes - image files to the local filesystem. - - - S3 - This backend allows OpenStack Image Service to - store virtual machine images in Amazon’s S3 - service. - - - HTTP - OpenStack Image Service can read virtual - machine images that are available through HTTP somewhere - on the Internet. This store is read only. - - - Rados Block Device (RBD) - This backend stores images inside of a Ceph storage - cluster using Ceph's RBD interface. - - - GridFS - This backend stores images inside of MongoDB. - - - You must have a working installation of the Image Service, with a working - endpoint and users created in the Identity Service. Also, you must source the environment - variables required by the nova and glance clients. + in OpenStack. + + + Filesystem - The default backend that OpenStack + Image Service uses to store virtual machine images is + the filesystem backend. This simple backend writes + image files to the local filesystem. + + + S3 - This backend allows OpenStack Image Service to + store virtual machine images in Amazon’s S3 + service. + + + HTTP - OpenStack Image Service can read virtual + machine images that are available through HTTP somewhere + on the Internet. This store is read only. + + + Rados Block Device (RBD) - This backend stores images inside of a Ceph storage + cluster using Ceph's RBD interface. + + + GridFS - This backend stores images inside of MongoDB. + + + You must have a working installation of the Image Service, with a working + endpoint and users created in the Identity Service. Also, you must source the environment + variables required by the nova and glance clients.
Instance management diff --git a/doc/admin-guide-cloud/ch_identity_mgmt.xml b/doc/admin-guide-cloud/ch_identity_mgmt.xml new file mode 100644 index 0000000000..f74d8d42b0 --- /dev/null +++ b/doc/admin-guide-cloud/ch_identity_mgmt.xml @@ -0,0 +1,219 @@ + + + Identity Management + + The default identity management system for OpenStack is the OpenStack Identity Service, code-named Keystone. + Once Identity is installed, it is configured via a primary + configuration file (etc/keystone.conf), possibly + a separate logging configuration file, and initializing data into + keystone using the command line client. + + +
+ User CRUD + + Keystone provides a user CRUD filter that can be added to the + public_api pipeline. This user crud filter allows users to use a + HTTP PATCH to change their own password. To enable this extension + you should define a user_crud_extension filter, insert it after + the *_body middleware and before the + public_service app in the public_api WSGI + pipeline in keystone.conf e.g.: + + +[filter:user_crud_extension] +paste.filter_factory = keystone.contrib.user_crud:CrudExtension.factory + +[pipeline:public_api] +pipeline = stats_monitoring url_normalize token_auth admin_token_auth xml_body json_body debug ec2_extension user_crud_extension public_service + + + Each user can then change their own password with a HTTP PATCH + + +> curl -X PATCH http://localhost:5000/v2.0/OS-KSCRUD/users/<userid> -H "Content-type: application/json" \ +-H "X_Auth_Token: <authtokenid>" -d '{"user": {"password": "ABCD", "original_password": "DCBA"}}' + + + In addition to changing their password all of the users current + tokens will be deleted (if the backend used is kvs or sql) + +
+
+ Logging + Logging is configured externally to the rest of Identity, + the file specifying the logging configuration is in the + [DEFAULT] section of the + keystone.conf file under + log_config. If you wish to route all your + logging through syslog, set use_syslog=true + option in the [DEFAULT] section. + + A sample logging file is available with the project in the + directory etc/logging.conf.sample. Like other + OpenStack projects, Identity uses the `python logging module`, + which includes extensive configuration options for choosing the + output levels and formats. + + + In addition to this documentation page, you can check the + etc/keystone.conf sample configuration files + distributed with keystone for example configuration files for each + server application. + + For services which have separate paste-deploy ini file, + auth_token middleware can be alternatively configured in + [keystone_authtoken] section in the main config file, such as + nova.conf. For + example in Nova, all middleware parameters can be removed from + api-paste.ini like these: + [filter:authtoken] + paste.filter_factory = + keystoneclient.middleware.auth_token:filter_factory + + and set in + nova.conf like these: + [DEFAULT] + ... + auth_strategy=keystone + + [keystone_authtoken] + auth_host = 127.0.0.1 + auth_port = 35357 + auth_protocol = http + auth_uri = http://127.0.0.1:5000/ + admin_user = admin + admin_password = SuperSekretPassword + admin_tenant_name = service + + Note that middleware parameters in + paste config take priority, they must be removed to use values + in [keystone_authtoken] section. +
+
+ Monitoring + + Keystone provides some basic request/response monitoring + statistics out of the box. + + + Enable data collection by defining a + stats_monitoring filter and including it at the + beginning of any desired WSGI pipelines: + + +[filter:stats_monitoring] +paste.filter_factory = keystone.contrib.stats:StatsMiddleware.factory + +[pipeline:public_api] +pipeline = stats_monitoring [...] public_service + + + Enable the reporting of collected data by defining a + stats_reporting filter and including it near + the end of your admin_api WSGI pipeline (After + *_body middleware and before + *_extension filters is recommended): + + +[filter:stats_reporting] +paste.filter_factory = keystone.contrib.stats:StatsExtension.factory + +[pipeline:admin_api] +pipeline = [...] json_body stats_reporting ec2_extension [...] admin_service + + + Query the admin API for statistics using: + + $ curl -H 'X-Auth-Token: ADMIN' http://localhost:35357/v2.0/OS-STATS/stats + + Reset collected data using: + + $ curl -H 'X-Auth-Token: ADMIN' -X DELETE http://localhost:35357/v2.0/OS-STATS/stats +
+
+ Running + + Running Identity is simply starting the services by using the + command: + + $ +keystone-all + + + Invoking this command starts up two wsgi.Server instances, + configured by the keystone.conf file as + described above. One of these wsgi 'servers' is + admin (the administration API) and the other is + main (the primary/public API interface). Both + of these run in a single process. + +
+
+ Example usage + The keystone client is set up to expect commands + in the general form of keystone + command + argument, followed by flag-like keyword arguments to + provide additional (often optional) information. For example, the + command user-list and + tenant-create can be invoked as follows: + +# Using token auth env variables +export SERVICE_ENDPOINT=http://127.0.0.1:5000/v2.0/ +export SERVICE_TOKEN=secrete_token +keystone user-list +keystone tenant-create --name=demo + +# Using token auth flags +keystone --token=secrete --endpoint=http://127.0.0.1:5000/v2.0/ user-list +keystone --token=secrete --endpoint=http://127.0.0.1:5000/v2.0/ tenant-create --name=demo + +# Using user + password + tenant_name env variables +export OS_USERNAME=admin +export OS_PASSWORD=secrete +export OS_TENANT_NAME=admin +keystone user-list +keystone tenant-create --name=demo + +# Using user + password + tenant_name flags +keystone --username=admin --password=secrete --tenant_name=admin user-list +keystone --username=admin --password=secrete --tenant_name=admin tenant-create --name=demo + +
+
+ Auth-Token Middleware with Username and Password + + It is also possible to configure Keystone's auth_token + middleware using the 'admin_user' and 'admin_password' options. + When using the 'admin_user' and 'admin_password' options the + 'admin_token' parameter is optional. If 'admin_token' is + specified it will by used only if the specified token is still + valid. + + + Here is an example paste config filter that makes use of the + 'admin_user' and 'admin_password' parameters: + + +[filter:authtoken] +paste.filter_factory = keystoneclient.middleware.auth_token:filter_factory +service_port = 5000 +service_host = 127.0.0.1 +auth_port = 35357 +auth_host = 127.0.0.1 +auth_token = 012345SECRET99TOKEN012345 +admin_user = admin +admin_password = keystone123 + + + It should be noted that when using this option an admin + tenant/role relationship is required. The admin user is granted + access to the 'Admin' role on the 'admin' tenant. + +
+ + diff --git a/doc/admin-guide-cloud/ch_networking.xml b/doc/admin-guide-cloud/ch_networking.xml index 0b70ddbd8f..f1c0f2bbbf 100644 --- a/doc/admin-guide-cloud/ch_networking.xml +++ b/doc/admin-guide-cloud/ch_networking.xml @@ -426,7 +426,7 @@
-
+
Place services on physical hosts Like other OpenStack services, Networking provides cloud administrators with significant flexibility in @@ -453,7 +453,7 @@ the neutron-l3-agent and other OpenStack services.
-
+
Network connectivity for physical hosts diff --git a/doc/common/ch_getstart.xml b/doc/common/ch_getstart.xml index 4d6c9767ba..7cc98a5a7e 100644 --- a/doc/common/ch_getstart.xml +++ b/doc/common/ch_getstart.xml @@ -69,7 +69,8 @@ provides a service catalog within a particular OpenStack cloud. Image Service - Glance. + Glance Provides a registry of virtual machine images. Compute Service uses it to provision instances. diff --git a/doc/common/section_config_keystone_ldap.xml b/doc/common/section_config_keystone_ldap.xml new file mode 100644 index 0000000000..db0d65766a --- /dev/null +++ b/doc/common/section_config_keystone_ldap.xml @@ -0,0 +1,155 @@ + +
+ Configuring OpenStack Identity for an LDAP backend + As an alternative to the SQL Database backing store, Identity can use + a directory server to provide the Identity service. An example schema + for AcmeExample would look like this: + +dn: dc=AcmeExample,dc=org +dc: AcmeExample +objectClass: dcObject +objectClass: organizationalUnit +ou: AcmeExample + +dn: ou=Groups,dc=AcmeExample,dc=org +objectClass: top +objectClass: organizationalUnit +ou: groups + +dn: ou=Users,dc=AcmeExample,dc=org +objectClass: top +objectClass: organizationalUnit +ou: users + +dn: ou=Roles,dc=AcmeExample,dc=org +objectClass: top +objectClass: organizationalUnit +ou: roles + + The corresponding entries in the keystone.conf + configuration file are: + +[ldap] +url = ldap://localhost +user = dc=Manager,dc=AcmeExample,dc=org +password = badpassword +suffix = dc=AcmeExample,dc=org +use_dumb_member = False +allow_subtree_delete = False + +user_tree_dn = ou=Users,dc=AcmeExample,dc=com +user_objectclass = inetOrgPerson + +tenant_tree_dn = ou=Groups,dc=AcmeExample,dc=com +tenant_objectclass = groupOfNames + +role_tree_dn = ou=Roles,dc=AcmeExample,dc=com +role_objectclass = organizationalRole + + The default object classes and attributes are intentionally + simplistic. They reflect the common standard objects according to the + LDAP RFCs. However, in a live deployment, the correct attributes can be + overridden to support a preexisting, more complex schema. For example, + in the user object, the objectClass posixAccount from RFC2307 is very + common. If this is the underlying objectclass, then the + uid field should probably be + uidNumber and username + field either uid or cn. To + change these two fields, the corresponding entries in the Keystone + configuration file are: + +[ldap] +user_id_attribute = uidNumber +user_name_attribute = cn + + There is a set of allowed actions per object type that you can modify + depending on your specific deployment. For example, the users are + managed by another tool and you have only read access, in such case the + configuration is: + +[ldap] +user_allow_create = False +user_allow_update = False +user_allow_delete = False + +tenant_allow_create = True +tenant_allow_update = True +tenant_allow_delete = True + +role_allow_create = True +role_allow_update = True +role_allow_delete = True + + There are some configuration options for filtering users, tenants and + roles, if the backend is providing too much output, in such case the + configuration will look like: + +[ldap] +user_filter = (memberof=CN=acme-users,OU=workgroups,DC=AcmeExample,DC=com) +tenant_filter = +role_filter = + + + In case that the directory server does not have an attribute enabled + of type boolean for the user, there are several configuration + parameters that can be used to extract the value from an integer + attribute like in Active Directory: + + +[ldap] +user_enabled_attribute = userAccountControl +user_enabled_mask = 2 +user_enabled_default = 512 + + + In this case the attribute is an integer and the enabled attribute + is listed in bit 1, so the if the mask configured + user_enabled_mask is different from 0, it gets + the value from the field user_enabled_attribute + and it makes an ADD operation with the value indicated on + user_enabled_mask and if the value matches the + mask then the account is disabled. + + + It also saves the value without mask to the user identity in the + attribute enabled_nomask. This is needed in + order to set it back in case that we need to change it to + enable/disable a user because it contains more information than the + status like password expiration. Last setting + user_enabled_mask is needed in order to create + a default value on the integer attribute (512 = NORMAL ACCOUNT on + AD) + + + In case of Active Directory the classes and attributes could not + match the specified classes in the LDAP module so you can configure + them like so: + + +[ldap] +user_objectclass = person +user_id_attribute = cn +user_name_attribute = cn +user_mail_attribute = mail +user_enabled_attribute = userAccountControl +user_enabled_mask = 2 +user_enabled_default = 512 +user_attribute_ignore = tenant_id,tenants +tenant_objectclass = groupOfNames +tenant_id_attribute = cn +tenant_member_attribute = member +tenant_name_attribute = ou +tenant_desc_attribute = description +tenant_enabled_attribute = extensionName +tenant_attribute_ignore = +role_objectclass = organizationalRole +role_id_attribute = cn +role_name_attribute = ou +role_member_attribute = roleOccupant +role_attribute_ignore = + +
diff --git a/doc/config-reference/ch_identityconfigure.xml b/doc/config-reference/ch_identityconfigure.xml index 5356b26dff..fe1f562c4d 100644 --- a/doc/config-reference/ch_identityconfigure.xml +++ b/doc/config-reference/ch_identityconfigure.xml @@ -13,5 +13,7 @@ + + diff --git a/doc/user-guide-admin/section_keystone_cli_manage_projects_users_roles.xml b/doc/user-guide-admin/section_keystone_cli_manage_projects_users_roles.xml index 56e3ed7b31..f4bda882a9 100644 --- a/doc/user-guide-admin/section_keystone_cli_manage_projects_users_roles.xml +++ b/doc/user-guide-admin/section_keystone_cli_manage_projects_users_roles.xml @@ -30,8 +30,78 @@ Before you can run keystone client commands, you must download and source an OpenStack RC file. See . +
+ Services + To look at your service catalog, use these keystone client commands. +
+ <literal>service-create</literal> + Keyword arguments: + + + Name + + + Type + + + Description + + + Example: + $ +keystone service create \ +--name=nova \ +--type=compute \ +--description="Nova Compute Service" + +
+
+ <literal>service-list</literal> + Arguments + + + service_id + + + Example: + +keystone service-list + +
+
+ <literal>service-get</literal> + Arguments + + + service_id + + + Example: + $ +keystone service-get 08741d8ed88242ca88d1f61484a0fe3b + +
+
+ <literal>service-delete</literal> + Arguments + + + service_id + + + Example: + $ +keystone service-delete 08741d8ed88242ca88d1f61484a0fe3b + +
- Create a project + Create a tenant (project) + A tenant is a group of zero or more users. In nova, a + tenant owns virtual machines. In swift, a tenant owns + containers. In the Dashboard, tenants are represented as projects. + Users can be associated with more than one tenant. + Each tenant and user pairing can have a role associated with + it. To list all projects with their ID, name, and @@ -309,4 +379,5 @@
+