Table Of Contents

Previous topic

Installing Keystone

Next topic

keystone-manage

This Page

Configuring Keystone

Once Keystone 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.

Starting and Stopping Keystone

Start Keystone services using the command:

$ keystone-all

Invoking this command starts up two wsgi.Server instances, admin (the administration API) and main (the primary/public API interface). Both services are configured by keystone.conf as run in a single process.

Stop the process using Control-C.

Note

If you have not already configured Keystone, it may not start as expected.

Configuration Files

The keystone configuration file is an ini file based on Paste, a common system used to configure python WSGI based applications. In addition to the paste configuration entries, general and driver-specific configuration values are organized into the following sections:

  • [DEFAULT] - general configuration
  • [sql] - optional storage backend configuration
  • [ec2] - Amazon EC2 authentication driver configuration
  • [identity] - identity system driver configuration
  • [catalog] - service catalog driver configuration
  • [token] - token driver configuration
  • [policy] - policy system driver configuration for RBAC

The Keystone configuration file is expected to be named keystone.conf. When starting keystone, you can specify a different configuration file to use with --config-file. If you do not specify a configuration file, keystone will look in the following directories for a configuration file, in order:

  • ~/.keystone/
  • ~/
  • /etc/keystone/
  • /etc/

Your Keystone service catalog can also be defined in a flat template_file defined by [catalog] template_file in keystone.conf. The default template_file is included in Keystone as an example, but you must create your own to reflect your deployment and update the path in keystone.conf. If you are migrating from a legacy deployment, a tool is available to help with this task (see Migrating your Service Catalog from legacy versions of Keystone).

Logging is configured externally to the rest of keystone. Configure the path to your logging configuration file using the [DEFAULT] log_config option of keystone.conf. If you wish to route all your logging through syslog, set the [DEFAULT] use_syslog option.

A sample log_config file is included with the project at etc/logging.conf.sample. Like other OpenStack projects, Keystone uses the python logging module, which includes extensive configuration options for choosing the output levels and formats.

Sample Configuration Files

The etc/ folder distributed with Keystone contains example configuration files for each Server application.

  • etc/keystone.conf
  • etc/logging.conf.sample

Preparing your Essex deployment

Step 1: Configure keystone.conf

Ensure that your keystone.conf is configured to use a SQL driver:

[identity]
driver = keystone.identity.backends.sql.Identity

You may also want to configure your [sql] settings to better reflect your environment:

[sql]
connection = sqlite:///keystone.db
idle_timeout = 200

Note

It is important that the database that you specify be different from the one containing your existing install.

Step 2: Sync your new, empty database

You should now be ready to initialize your new database without error, using:

$ keystone-manage db_sync

To test this, you should now be able to start keystone-all and use the Keystone Client to list your tenants (which should successfully return an empty list from your new database):

$ keystone --token ADMIN --endpoint http://127.0.0.1:35357/v2.0/ tenant-list
+----+------+---------+
| id | name | enabled |
+----+------+---------+
+----+------+---------+

Note

We’re providing the default SERVICE_TOKEN and SERVICE_ENDPOINT values from keystone.conf to connect to the Keystone service. If you changed those values, or deployed Keystone to a different endpoint, you will need to change the provided command accordingly.

Migrating from legacy versions of Keystone

Migration support is provided for the following legacy Keystone versions:

  • diablo-5
  • stable/diablo
  • essex-2
  • essex-3

Note

Before you can import your legacy data, you must first prepare your Essex deployment.

Step 1: Ensure your Essex deployment can access your legacy database

Your legacy keystone.conf contains a SQL configuration section called [keystone.backends.sqlalchemy] connection string which, by default, looks like:

sql_connection = sqlite:///keystone.db

This connection string needs to be accessible from your Essex deployment (e.g. you may need to copy your SQLite *.db file to a new server, adjust the relative path as appropriate, or open a firewall for MySQL, etc).

Step 2: Import your legacy data

Use the following command to import your old data using the value of sql_connection from step 3:

$ keystone-manage import_legacy <sql_connection>

You should now be able to run the same command you used to test your new database above, but now you’ll see your legacy Keystone data in Essex:

$ keystone --token ADMIN --endpoint http://127.0.0.1:35357/v2.0/ tenant-list
+----------------------------------+----------------+---------+
|                id                |      name      | enabled |
+----------------------------------+----------------+---------+
| 12edde26a6224199a66ece67b762a065 | project-y      | True    |
| 593715ed4359404999915ea7005a7da1 | ANOTHER:TENANT | True    |
| be57fed798b049bc9637d2be30bfa857 | coffee-tea     | True    |
| e3c382f4757a4385b502056431763cca | customer-x     | True    |
+----------------------------------+----------------+---------+

Migrating your Service Catalog from legacy versions of Keystone

While legacy Keystone deployments stored the service catalog in the database, the service catalog in Essex is stored in a flat template_file. An example service catalog template file may be found in etc/default_catalog.templates. You can change the path to your service catalog template in keystone.conf by changing the value of [catalog] template_file.

Import your legacy catalog and redirect the output to your template_file:

$ keystone-manage export_legacy_catalog <sql_connection> > <template_file>

Note

After executing this command, you will need to restart the Keystone service to see your changes.

Migrating from Nova Auth

Migration of users, projects (aka tenants), roles and EC2 credentials is supported for the Essex release of Nova. To migrate your auth data from Nova, use the following steps:

Note

Before you can migrate from nova auth, you must first prepare your Essex deployment.

Step 1: Export your data from Nova

Use the following command to export your data from Nova to a dump_file:

$ nova-manage export auth > /path/to/dump

It is important to redirect the output to a file so it can be imported in the next step.

Step 2: Import your data to Keystone

Import your Nova auth data from a dump_file created with nova-manage:

$ keystone-manage import_nova_auth <dump_file>

Note

Users are added to Keystone with the user ID from Nova as the user name. Nova’s projects are imported with the project ID as the tenant name. The password used to authenticate a user in Keystone will be the API key (also EC2 access key) used in Nova. Users also lose any administrative privileges they had in Nova. The necessary admin role must be explicitly re-assigned to each user.

Note

Users in Nova’s auth system have a single set of EC2 credentials that works with all projects (tenants) that user can access. In Keystone, these credentials are scoped to a single user/tenant pair. In order to use the same secret keys from Nova, you must prefix each corresponding access key with the ID of the project used in Nova. For example, if you had access to the ‘Beta’ project in your Nova installation with the access/secret keys ‘ACCESS’/’SECRET’, you should use ‘Beta:ACCESS’/’SECRET’ in Keystone. These credentials are active once your migration is complete.

Initializing Keystone

keystone-manage is designed to execute commands that cannot be administered through the normal REST API. At the moment, the following calls are supported:

  • db_sync: Sync the database schema.
  • import_legacy: Import data from a legacy (pre-Essex) database.
  • export_legacy_catalog: Export service catalog from a legacy (pre-Essex) database.
  • import_nova_auth: Load auth data from a dump created with nova-manage.

Invoking keystone-manage by itself will give you additional usage information.

Adding Users, Tenants, and Roles with python-keystoneclient

User, tenants, and roles must be administered using admin credentials. There are two ways to configure python-keystoneclient to use admin credentials, using the either an existing token or password credentials.

Authenticating with a Token

Note

If your Keystone deployment is brand new, you will need to use this authentication method, along with your [DEFAULT] admin_token.

To use Keystone with a token, set the following flags:

  • --endpoint SERVICE_ENDPOINT: allows you to specify the Keystone endpoint to communicate with. The default endpoint is http://localhost:35357/v2.0
  • --token SERVICE_TOKEN: your service token

To administer a Keystone endpoint, your token should be either belong to a user with the admin role, or, if you haven’t created one yet, should be equal to the value defined by [DEFAULT] admin_token in your keystone.conf.

You can also set these variables in your environment so that they do not need to be passed as arguments each time:

$ export SERVICE_ENDPOINT=http://localhost:35357/v2.0
$ export SERVICE_TOKEN=ADMIN

Authenticating with a Password

To administer a Keystone endpoint, the following user referenced below should be granted the admin role.

  • --os_username OS_USERNAME: Name of your user
  • --os_password OS_PASSWORD: Password for your user
  • --os_tenant_name OS_TENANT_NAME: Name of your tenant
  • --os_auth_url OS_AUTH_URL: URL of your Keystone auth server, e.g. http://localhost:35357/v2.0

You can also set these variables in your environment so that they do not need to be passed as arguments each time:

$ export OS_USERNAME=my_username
$ export OS_PASSWORD=my_password
$ export OS_TENANT_NAME=my_tenant

Example usage

keystone 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:35357/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:35357/v2.0/ user-list
keystone --token=secrete --endpoint=http://127.0.0.1:35357/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 --os_username=admin --os_password=secrete --os_tenant_name=admin user-list
keystone --os_username=admin --os_password=secrete --os_tenant_name=admin tenant-create --name=demo

Tenants

Tenants are the high level grouping within Keystone that represent groups of users. A tenant is the grouping that owns virtual machines within Nova, or containers within Swift. A tenant can have zero or more users, Users can be associated with more than one tenant, and each tenant - user pairing can have a role associated with it.

tenant-create

keyword arguments

  • name
  • description (optional, defaults to None)
  • enabled (optional, defaults to True)

example:

$ keystone tenant-create --name=demo

creates a tenant named “demo”.

tenant-delete

arguments

  • tenant_id

example:

$ keystone tenant-delete f2b7b39c860840dfa47d9ee4adffa0b3

Users

user-create

keyword arguments

  • name
  • pass
  • email
  • default_tenant (optional, defaults to None)
  • enabled (optional, defaults to True)

example:

$ keystone user-create
--name=admin \
--pass=secrete \
--email=admin@example.com

user-delete

keyword arguments

  • user_id

example:

$ keystone user-delete f2b7b39c860840dfa47d9ee4adffa0b3

user-list

list users in the system, optionally by a specific tenant (identified by tenant_id)

arguments

  • tenant_id (optional, defaults to None)

example:

$ keystone user-list

user-update

arguments

  • user_id

keyword arguments

  • name Desired new user name (Optional)
  • email Desired new email address (Optional)
  • enabled <true|false> Enable or disable user (Optional)

example:

$ keystone user-update 03c84b51574841ba9a0d8db7882ac645 --email=newemail@example.com

user-password-update

arguments

  • user_id
  • password

example:

$ keystone user-password-update --pass foo 03c84b51574841ba9a0d8db7882ac645

Roles

role-create

arguments

  • name

example:

$ keystone role-create --name=demo

role-delete

arguments

  • role_id

example:

$ keystone role-delete 19d1d3344873464d819c45f521ff9890

role-list

example:

$ keystone role-list

role-get

arguments

  • role_id

example:

$ keystone role-get 19d1d3344873464d819c45f521ff9890

user-role-add

keyword arguments

  • user <user-id>
  • role <role-id>
  • tenant_id <tenant-id>

example:

$ keystone user-role-add  \
  --user=96a6ebba0d4c441887aceaeced892585  \
  --role=f8dd5a2e4dc64a41b96add562d9a764e  \
  --tenant_id=2395953419144b67955ac4bab96b8fd2

user-role-remove

keyword arguments

  • user <user-id>
  • role <role-id>
  • tenant_id <tenant-id>

example:

$ keystone user-role-remove  \
  --user=96a6ebba0d4c441887aceaeced892585  \
  --role=f8dd5a2e4dc64a41b96add562d9a764e  \
  --tenant_id=2395953419144b67955ac4bab96b8fd2

Services

service-create

keyword arguments

  • name
  • type
  • description

example:

$ keystone service-create \
--name=nova \
--type=compute \
--description="Nova Compute Service"

service-list

arguments

  • service_id

example:

$ keystone service-list

service-get

arguments

  • service_id

example:

$ keystone service-get 08741d8ed88242ca88d1f61484a0fe3b

service-delete

arguments

  • service_id

example:

$ keystone service-delete 08741d8ed88242ca88d1f61484a0fe3b

Configuring the LDAP Identity Provider

As an alternative to the SQL Databse backing store, Keystone can Use a Directory server to provide the Identity service. An example Schema for openstack would look like this:

dn: cn=openstack,cn=org
dc: openstack
objectClass: dcObject
objectClass: organizationalUnit
ou: openstack

dn: ou=Groups,cn=openstack,cn=org
objectClass: top
objectClass: organizationalUnit
ou: groups

dn: ou=Users,cn=openstack,cn=org
objectClass: top
objectClass: organizationalUnit
ou: users

dn: ou=Roles,cn=openstack,cn=org
objectClass: top
objectClass: organizationalUnit
ou: users

The corresponding entries in the Keystone configuration file are:

[ldap]
url = ldap://localhost
suffix = dc=openstack,dc=org
user = dc=Manager,dc=openstack,dc=org
password = badpassword

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