openstack-manuals/doc/install-guide/section_keystone-install.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section[
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
%openstack;
]>
<section xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  version="5.0"
  xml:id="keystone-install">
  <title>Install and configure</title>
  <para>This section describes how to install and configure the OpenStack
    Identity service, code-named keystone, on the controller node. For
    performance, this configuration deploys the Apache HTTP server to
    handle requests and Memcached to store tokens instead of a SQL
    database.</para>
  <procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
    <title>To configure prerequisites</title>
    <para>Before you configure the OpenStack Identity service, you must create
      a database and an administration token.</para>
    <step>
      <para>To create the database, complete these steps:</para>
      <substeps>
        <step>
          <para>Use the database access client to connect to the database
            server as the <literal>root</literal> user:</para>
          <screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput></screen>
        </step>
        <step>
          <para>Create the <literal>keystone</literal> database:</para>
          <screen><userinput>CREATE DATABASE keystone;</userinput></screen>
        </step>
        <step>
          <para>Grant proper access to the <literal>keystone</literal>
            database:</para>
          <screen><userinput>GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'localhost' \
  IDENTIFIED BY '<replaceable>KEYSTONE_DBPASS</replaceable>';</userinput>
<userinput>GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'%' \
  IDENTIFIED BY '<replaceable>KEYSTONE_DBPASS</replaceable>';</userinput></screen>
          <para>Replace <replaceable>KEYSTONE_DBPASS</replaceable> with a suitable password.</para>
        </step>
        <step>
          <para>Exit the database access client.</para>
        </step>
      </substeps>
    </step>
    <step>
      <para>Generate a random value to use as the administration token during
        initial configuration:</para>
      <screen><prompt>$</prompt> <userinput>openssl rand -hex 10</userinput></screen>
    </step>
  </procedure>
  <procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
    <title>To install and configure the Identity service components</title>
    <note>
       <para>Default configuration files vary by distribution. You might need
         to add these sections and options rather than modifying existing
         sections and options. Also, an ellipsis (...) in the configuration
         snippets indicates potential default configuration options that you
         should retain.</para>
    </note>
    <step os="ubuntu">
      <para>By default, the <systemitem class="service">keystone</systemitem>
        service listens on ports 5000 and 35357. However, this guide
        configures the Apache HTTP server to listen on those ports. To avoid
        port conflicts, disable the
        <systemitem class="service">keystone</systemitem> service from starting
        automatically after installation:</para>
      <screen><prompt>#</prompt> <userinput>echo "manual" > /etc/init/keystone.override</userinput></screen>
    </step>
    <step>
      <para>Run the following command to install the packages:</para>
      <screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install keystone python-openstackclient apache2 libapache2-mod-wsgi memcached python-memcache</userinput></screen>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-keystone httpd mod_wsgi python-openstackclient memcached python-memcached</userinput></screen>
      <screen os="sles;opensuse"><prompt>#</prompt> <userinput>zypper install openstack-keystone python-openstackclient apache2-mod_wsgi memcached python-python-memcached</userinput></screen>
    </step>
    <step os="rhel;fedora;centos;sles;opensuse">
      <para>Start the Memcached service and configure it to start when the
        system boots:</para>
      <screen><prompt>#</prompt> <userinput>systemctl enable memcached.service</userinput>
<prompt>#</prompt> <userinput>systemctl start memcached.service</userinput></screen>
    </step>
    <step>
      <para>Edit the <filename>/etc/keystone/keystone.conf</filename> file and
        complete the following actions:</para>
      <substeps>
        <step>
          <para>In the <literal>[DEFAULT]</literal> section, define the value
            of the initial administration token:</para>
          <programlisting language="ini">[DEFAULT]
...
admin_token = <replaceable>ADMIN_TOKEN</replaceable></programlisting>
          <para>Replace <replaceable>ADMIN_TOKEN</replaceable> with the random
            value that you generated in a previous step.</para>
        </step>
        <step>
          <para>In the <literal>[database]</literal> section, configure
            database access:</para>
          <programlisting language="ini">[database]
...
connection = mysql://keystone:<replaceable>KEYSTONE_DBPASS</replaceable>@<replaceable>controller</replaceable>/keystone</programlisting>
          <para>Replace <replaceable>KEYSTONE_DBPASS</replaceable> with the
            password you chose for the database.</para>
        </step>
        <step>
          <para>In the <literal>[memcache]</literal> section, configure
            the Memcache service:</para>
          <programlisting language="ini">[memcache]
...
servers = localhost:11211</programlisting>
        </step>
        <step>
          <para>In the <literal>[token]</literal> section, configure the UUID
            token provider and Memcached driver:</para>
          <programlisting language="ini">[token]
...
provider = keystone.token.providers.uuid.Provider
driver = keystone.token.persistence.backends.memcache.Token</programlisting>
        </step>
        <step>
          <para>In the <literal>[revoke]</literal> section, configure
          the SQL revocation driver:</para>
          <programlisting language="ini">[revoke]
...
driver = keystone.contrib.revoke.backends.sql.Revoke</programlisting>
        </step>
        <step>
          <para>(Optional) To assist with troubleshooting,
            enable verbose logging in the <literal>[DEFAULT]</literal> section:</para>
          <programlisting language="ini">[DEFAULT]
...
verbose = True</programlisting>
        </step>
      </substeps>
    </step>
    <step os="rhel;centos;fedora">
      <para>Create generic certificates and keys and restrict access to the
        associated files:</para>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>keystone-manage pki_setup --keystone-user keystone --keystone-group keystone</userinput>
<prompt>#</prompt> <userinput>chown -R keystone:keystone /var/log/keystone</userinput>
<prompt>#</prompt> <userinput>chown -R keystone:keystone /etc/keystone/ssl</userinput>
<prompt>#</prompt> <userinput>chmod -R o-rwx /etc/keystone/ssl</userinput></screen>
    </step>
    <step os="ubuntu;rhel;centos;fedora">
      <para>Populate the Identity service database:</para>
      <screen><prompt>#</prompt> <userinput>su -s /bin/sh -c "keystone-manage db_sync" keystone</userinput></screen>
    </step>
  </procedure>
  <procedure os="debian">
    <title>To install and configure the components</title>
    <step>
      <para>Run the following command to install the packages:</para>
      <screen><prompt>#</prompt> <userinput>apt-get install keystone</userinput></screen>
      <note><para><package>python-keystoneclient</package> will automatically be installed as
      it is a dependency of the <package>keystone</package> package.</para></note>
    </step>
    <step>
      <para>Respond to prompts for <xref linkend="debconf-dbconfig-common"/>, which
      will fill the below database access directive.</para>
      <programlisting language="ini">[database]
...
connection = mysql://keystone:<replaceable>KEYSTONE_DBPASS</replaceable>@<replaceable>controller</replaceable>/keystone</programlisting>
      <para>If you decide to not use <command>dbconfig-common</command>, then you will have to
      create the database and manage its access rights yourself, and run the
      following by hand.</para>
      <screen><prompt>#</prompt> <userinput>keystone-manage db_sync</userinput></screen>
    </step>
    <step>
      <para>Generate a random value to use as the administration token during
        initial configuration:</para>
      <screen><prompt>$</prompt> <userinput>openssl rand -hex 10</userinput></screen>
      <para>Configure the initial administration token:</para>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50" fileref="figures/debconf-screenshots/keystone_1_admin_token.png"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
      <para>Use the random value that you generated in a previous step. If you
        install using non-interactive mode or you do not specify this token,
        the configuration tool generates a random value.</para>
      <para>Later on, the package will configure the below directive with the
        value you entered:</para>
      <programlisting language="ini">[DEFAULT]
...
admin_token = <replaceable>ADMIN_TOKEN</replaceable></programlisting>
    </step>
    <step>
      <para>Create the <literal>admin</literal> tenant and user:</para>
      <para>During the final stage of the package installation, it is possible
        to automatically create an admin tenant and an admin user. This can
        later be used for other OpenStack services to contact the Identity
        service. This is the equivalent of running the below commands:</para>
      <screen><prompt>#</prompt> <userinput>openstack project create --description "Admin Tenant" admin</userinput>
<prompt>#</prompt> <userinput>openstack user create --password <replaceable>ADMIN_PASS</replaceable> --email root@localhost admin</userinput>
<prompt>#</prompt> <userinput>openstack role create admin</userinput>
<prompt>#</prompt> <userinput>openstack role add --project demo --user demo user</userinput></screen>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_2_register_admin_tenant_yes_no.png"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
      <para>&nbsp;</para>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_3_admin_user_name.png"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
      <para>&nbsp;</para>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_4_admin_user_email.png"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
      <para>&nbsp;</para>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_5_admin_user_pass.png"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
      <para>&nbsp;</para>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_6_admin_user_pass_confirm.png"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
    </step>
    <step>
      <title>Create the Identity service endpoints</title>
      <para>In Debian, the Keystone package offers automatic registration of Keystone
        in the service catalogue. This is equivalent of running the below commands:</para>
      <screen><prompt>#</prompt> <userinput>openstack service create --name keystone --description "OpenStack Identity"  identity</userinput>
<prompt>#</prompt> <userinput>keystone endpoint-create \
  --publicurl http://<replaceable>controller</replaceable>:5000/v2.0 \
  --internalurl http://<replaceable>controller</replaceable>:5000/v2.0 \
  --adminurl http://<replaceable>controller</replaceable>:35357/v2.0 \
  --region RegionOne \
  identity</userinput></screen>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_7_register_endpoint.png"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
    </step>
  </procedure>
  <procedure os="ubuntu;rhel;centos;fedora;opensuse;sles">
    <title>To configure the Apache HTTP server</title>
    <step os="ubuntu;rhel;centos;fedora">
      <para>Edit the <filename os="ubuntu">/etc/apache2/apache2.conf</filename>
        <filename os="rhel;centos;fedora">/etc/httpd/conf/httpd.conf</filename>
        file and configure the <literal>ServerName</literal> option to
        reference the controller node:</para>
      <programlisting>ServerName <replaceable>controller</replaceable></programlisting>
    </step>
    <step os="opensuse;sles">
      <para>Edit the <filename>/etc/sysconf/apache2</filename>
        file and
        configure the <literal>APACHE_SERVERNAME</literal> option to reference the
        controller node:</para>
      <programlisting>APACHE_SERVERNAME="<replaceable>controller</replaceable>"</programlisting>
    </step>
    <step>
      <para>Create the
        <filename os="ubuntu">/etc/apache2/sites-available/wsgi-keystone.conf</filename>
        <filename os="rhel;centos;fedora">/etc/httpd/conf.d/wsgi-keystone.conf</filename>
        <filename os="opensuse;sles">/etc/apache2/conf.d/wsgi-keystone.conf</filename>
        file with the following content:</para>
      <programlisting os="ubuntu">Listen 5000
Listen 35357

&lt;VirtualHost *:5000&gt;
    WSGIDaemonProcess keystone-public processes=5 threads=1 user=keystone display-name=%{GROUP}
    WSGIProcessGroup keystone-public
    WSGIScriptAlias / /var/www/cgi-bin/keystone/main
    WSGIApplicationGroup %{GLOBAL}
    WSGIPassAuthorization On
    &lt;IfVersion &gt;= 2.4&gt;
      ErrorLogFormat "%{cu}t %M"
    &lt;/IfVersion&gt;
    LogLevel info
    ErrorLog /var/log/apache2/keystone-error.log
    CustomLog /var/log/apache2/keystone-access.log combined
&lt;/VirtualHost&gt;

&lt;VirtualHost *:35357&gt;
    WSGIDaemonProcess keystone-admin processes=5 threads=1 user=keystone display-name=%{GROUP}
    WSGIProcessGroup keystone-admin
    WSGIScriptAlias / /var/www/cgi-bin/keystone/admin
    WSGIApplicationGroup %{GLOBAL}
    WSGIPassAuthorization On
    &lt;IfVersion &gt;= 2.4&gt;
      ErrorLogFormat "%{cu}t %M"
    &lt;/IfVersion>
    LogLevel info
    ErrorLog /var/log/apache2/keystone-error.log
    CustomLog /var/log/apache2/keystone-access.log combined
&lt;/VirtualHost&gt;</programlisting>
      <programlisting os="rhel;fedora;centos">Listen 5000
Listen 35357

&lt;VirtualHost *:5000&gt;
    WSGIDaemonProcess keystone-public processes=5 threads=1 user=keystone display-name=%{GROUP}
    WSGIProcessGroup keystone-public
    WSGIScriptAlias / /var/www/cgi-bin/keystone/main
    WSGIApplicationGroup %{GLOBAL}
    WSGIPassAuthorization On
    LogLevel info
    ErrorLogFormat "%{cu}t %M"
    ErrorLog /var/log/httpd/keystone-error.log
    CustomLog /var/log/httpd/keystone-access.log combined
&lt;/VirtualHost&gt;

&lt;VirtualHost *:35357&gt;
    WSGIDaemonProcess keystone-admin processes=5 threads=1 user=keystone display-name=%{GROUP}
    WSGIProcessGroup keystone-admin
    WSGIScriptAlias / /var/www/cgi-bin/keystone/admin
    WSGIApplicationGroup %{GLOBAL}
    WSGIPassAuthorization On
    LogLevel info
    ErrorLogFormat "%{cu}t %M"
    ErrorLog /var/log/httpd/keystone-error.log
    CustomLog /var/log/httpd/keystone-access.log combined
&lt;/VirtualHost&gt;</programlisting>
      <programlisting os="opensuse;sles">Listen 5000
Listen 35357

&lt;VirtualHost *:5000&gt;
    WSGIDaemonProcess keystone-public processes=5 threads=1 user=keystone display-name=%{GROUP}
    WSGIProcessGroup keystone-public
    WSGIScriptAlias / /srv/www/cgi-bin/keystone/main
    WSGIApplicationGroup %{GLOBAL}
    WSGIPassAuthorization On
    ErrorLogFormat "%{cu}t %M"
    LogLevel info
    ErrorLog /var/log/apache2/keystone-error.log
    CustomLog /var/log/apache2/keystone-access.log combined
&lt;/VirtualHost&gt;

&lt;VirtualHost *:35357&gt;
    WSGIDaemonProcess keystone-admin processes=5 threads=1 user=keystone display-name=%{GROUP}
    WSGIProcessGroup keystone-admin
    WSGIScriptAlias / /srv/www/cgi-bin/keystone/admin
    WSGIApplicationGroup %{GLOBAL}
    WSGIPassAuthorization On
    ErrorLogFormat "%{cu}t %M"
    LogLevel info
    ErrorLog /var/log/apache2/keystone-error.log
    CustomLog /var/log/apache2/keystone-access.log combined
&lt;/VirtualHost&gt;</programlisting>
    </step>
    <step os="ubuntu">
      <para>Enable the Identity service virtual hosts:</para>
      <screen><prompt>#</prompt> <userinput>ln -s /etc/apache2/sites-available/wsgi-keystone.conf /etc/apache2/sites-enabled</userinput></screen>
    </step>
    <step>
      <para>Create the directory structure for the WSGI components:</para>
      <screen os="ubuntu;fedora;centos;rhel"><prompt>#</prompt> <userinput>mkdir -p /var/www/cgi-bin/keystone</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>mkdir -p /srv/www/cgi-bin/keystone</userinput></screen>
    </step>
    <step>
      <para>Copy the WSGI components from the upstream repository into this
        directory:</para>
      <screen os="ubuntu;fedora;centos;rhel"><prompt>#</prompt> <userinput>curl http://git.openstack.org/cgit/openstack/keystone/plain/httpd/keystone.py?h=stable/kilo \
  | tee /var/www/cgi-bin/keystone/main /var/www/cgi-bin/keystone/admin</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>curl http://git.openstack.org/cgit/openstack/keystone/plain/httpd/keystone.py?h=stable/kilo \
  | tee /srv/www/cgi-bin/keystone/main /srv/www/cgi-bin/keystone/admin</userinput></screen>
    </step>
    <step>
      <para>Adjust ownership and permissions on this directory and the files
        in it:</para>
      <screen os="ubuntu;fedora;centos;rhel"><prompt>#</prompt> <userinput>chown -R keystone:keystone /var/www/cgi-bin/keystone</userinput>
<prompt>#</prompt> <userinput>chmod 755 /var/www/cgi-bin/keystone/*</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>chown -R keystone:keystone /srv/www/cgi-bin/keystone</userinput>
<prompt>#</prompt> <userinput>chmod 755 /srv/www/cgi-bin/keystone/*</userinput></screen>
    </step>
    <step os="rhel;centos;fedora">
      <para>Restore the default SELinux security context:</para>
      <screen><prompt>#</prompt> <userinput>restorecon /var/www/cgi-bin</userinput></screen>
    </step>
    <step os="opensuse;sles">
      <para>
        Change the ownership of
        <filename>/etc/keystone/keystone.conf</filename> to give the
        <literal>keystone</literal> system access to it:
      </para>
      <screen><prompt>#</prompt> <userinput>chown keystone /etc/keystone/keystone.conf</userinput></screen>
    </step>
    <step os="rhel;fedora;centos">
      <para>Add the <literal>apache</literal> system user to the
        <literal>keystone</literal> system group to permit access to the
        Identity service configuration files by the Apache HTTP server:</para>
      <screen><prompt>#</prompt> <userinput>usermod -a -G keystone apache</userinput></screen>
    </step>
  </procedure>
  <procedure>
    <title>To finalize installation</title>
    <step os="ubuntu;rhel;fedora;centos;opensuse;sles">
      <para>Restart the Apache HTTP server:</para>
      <screen os="ubuntu"><prompt>#</prompt> <userinput>service apache2 restart</userinput></screen>
      <screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>systemctl enable httpd.service</userinput>
<prompt>#</prompt> <userinput>systemctl start httpd.service</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>systemctl enable apache2.service</userinput>
<prompt>#</prompt> <userinput>systemctl start apache2.service</userinput></screen>
    </step>
    <step os="ubuntu">
      <para>By default, the Ubuntu packages create a SQLite database.</para>
      <para>Because this configuration uses a SQL database server, you can
        remove the SQLite database file:</para>
      <screen><prompt>#</prompt> <userinput>rm -f /var/lib/keystone/keystone.db</userinput></screen>
    </step>
    <step os="sles;opensuse;debian">
      <para>By default, the Identity service stores expired tokens in the
        SQL database indefinitely. The accumulation of expired tokens
        considerably increases the database size and degrades performance
        over time, particularly in environments with limited resources.</para>
      <para>The packages already contain a cron job under
        <filename>/etc/cron.hourly/keystone</filename>, so it is not necessary
        to manually configure a periodic task that purges expired tokens.</para>
    </step>
  </procedure>
</section>