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 on the
    controller node.</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>As the <literal>root</literal> user, connect to the database to create the
          <literal>keystone</literal> database and grant the proper access to it:</para>
      <screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput>
<prompt>mysql></prompt> <userinput>CREATE DATABASE keystone;</userinput>
<prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'localhost' \
  IDENTIFIED BY '<replaceable>KEYSTONE_DBPASS</replaceable>';</userinput>
<prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'%' \
  IDENTIFIED BY '<replaceable>KEYSTONE_DBPASS</replaceable>';</userinput>
<prompt>mysql></prompt> <userinput>exit</userinput></screen>
      <para>Replace <replaceable>KEYSTONE_DBPASS</replaceable> with a suitable password.</para>
    </step>
    <step>
      <para>Generate a random value to use as the administration token during initial
        configuration:</para>
      <screen os="ubuntu;rhel;centos;fedora"><prompt>#</prompt> <userinput>openssl rand -hex 10</userinput></screen>
      <screen os="sles;opensuse"><prompt>#</prompt> <userinput>openssl rand 10 | hexdump -e '1/1 "%.2x"'</userinput></screen>
    </step>
  </procedure>
  <procedure os="debian">
    <title>To configure prerequisites</title>
    <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 components</title>
    <step>
      <para>Run the following command to install the packages:</para>
      <screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install keystone python-keystoneclient</userinput></screen>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-keystone python-keystoneclient</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install openstack-keystone python-keystoneclient</userinput></screen>
    </step>
    <step os="ubuntu;rhel;centos;fedora;sles;opensuse">
      <para>Edit the <filename>/etc/keystone/keystone.conf</filename> file.</para>
      <substeps>
        <step os="ubuntu;rhel;centos;fedora;sles;opensuse">
          <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 os="ubuntu;rhel;centos;fedora;sles;opensuse">
          <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 os="ubuntu">
          <para>In the <literal>[DEFAULT]</literal> section, configure the log directory:</para>
          <programlisting language="ini">[DEFAULT]
...
log_dir = /var/log/keystone</programlisting>
        </step>
      </substeps>
    </step>
    <step os="rhel;centos;fedora;opensuse;sles">
      <para>By default, the Identity service uses public key infrastructure (PKI).</para>
      <para>Create generic certificates and keys and restrict access to the associated files:</para>
      <screen os="rhel;centos;fedora;opensuse;sles"><prompt>#</prompt> <userinput>keystone-manage pki_setup --keystone-user keystone --keystone-group 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;sles;opensuse">
      <para>Run the following command to 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 python-keystoneclient</userinput></screen>
    </step>
    <step>
      <para>Respond to prompts for <xref linkend="debconf-dbconfig-common"/>.</para>
    </step>
    <step>
      <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>
    </step>
    <step>
      <para>Create the <literal>admin</literal> tenant and user:</para>
      <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>
      <para>Register the Identity service in the catalog:</para>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_7_register_endpoint.png"/>
          </imageobject>
        </mediaobject>
      </informalfigure>
    </step>
  </procedure>
  <procedure>
    <title>To finalize installation</title>
    <step os="ubuntu;debian">
      <para>Restart the Identity service:</para>
      <screen><prompt>#</prompt> <userinput>service keystone restart</userinput></screen>
    </step>
    <step os="rhel;fedora;centos;opensuse;sles">
      <para>Start the Identity service and configure it to start when the system boots:</para>
      <screen><prompt>#</prompt> <userinput>service openstack-keystone start</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-keystone on</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 /var/lib/keystone/keystone.db</userinput></screen>
    </step>
    <step>
      <para>By default, the Identity service stores expired tokens in the database indefinitely. The
        accumulation of expired tokens considerably increases the database size and might degrade
        service performance, particularly in test environments with limited resources.</para>
      <para>We recommend that you use <systemitem class="service">cron</systemitem> to configure a
        periodic task that purges expired tokens hourly.</para>
      <para>Run the following command to purge expired tokens every hour and log the output to the
          <filename>/var/log/keystone/keystone-tokenflush.log</filename> file:</para>
      <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>(crontab -l -u keystone 2>&amp;1 | grep -q token_flush) || \
echo '@hourly /usr/bin/keystone-manage token_flush >/var/log/keystone/keystone-tokenflush.log 2>&amp;1' \
>> /var/spool/cron/crontabs/keystone</userinput></screen>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>(crontab -l -u keystone 2>&amp;1 | grep -q token_flush) || \
echo '@hourly /usr/bin/keystone-manage token_flush >/var/log/keystone/keystone-tokenflush.log 2>&amp;1' \
>> /var/spool/cron/keystone</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>(crontab -l -u keystone 2>&amp;1 | grep -q token_flush) || \
echo '@hourly /usr/bin/keystone-manage token_flush >/var/log/keystone/keystone-tokenflush.log 2>&amp;1' \
>> /var/spool/cron/tabs/keystone</userinput></screen>
    </step>
  </procedure>
</section>