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

<?xml version="1.0" encoding="utf-8"?>
<section xml:id="keystone-install"
  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">
  <title>Install the Identity Service</title>
  <procedure>
    <step>
      <para>Install the OpenStack Identity Service on the controller node,
        together with <application>python-keystoneclient</application> (which is a
        dependency):</para>
      <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>apt-get install keystone</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 openstack-utils</userinput></screen>
    </step>
    <step os="debian">
      <para>Answer to the <systemitem class="library"
          >debconf</systemitem> and <systemitem class="library"
          >dbconfig-common</systemitem> questions for setting-up the
        database.</para>
    </step>
    <step os="rhel;centos;fedora;opensuse;sles;ubuntu">
      <para>The Identity Service uses a database to store information.
        Specify the location of the database in the configuration
        file. In this guide, we use a MySQL database on the controller
        node with the username <literal>keystone</literal>. Replace
            <literal><replaceable>KEYSTONE_DBPASS</replaceable></literal>
        with a suitable password for the database user.</para>
      <screen os="rhel;centos;fedora;opensuse;sles"><prompt>#</prompt> <userinput>openstack-config --set /etc/keystone/keystone.conf \
   database connection mysql://keystone:<replaceable>KEYSTONE_DBPASS</replaceable>@<replaceable>controller</replaceable>/keystone</userinput></screen>
      <para os="ubuntu">Edit
          <filename>/etc/keystone/keystone.conf</filename> and change
        the <literal>[database]</literal> section:</para>
      <programlisting os="ubuntu" language="ini">
...
[database]
# The SQLAlchemy connection string used to connect to the database
connection = mysql://keystone:<replaceable>KEYSTONE_DBPASS</replaceable>@<replaceable>controller</replaceable>/keystone
...
      </programlisting>
    </step>

    <step os="ubuntu">
      <para>By default, the Ubuntu packages create a SQLite database.
        Delete the <filename>keystone.db</filename> file created in
        the <filename>/var/lib/keystone/</filename> directory so that it
        does not get used by mistake:</para>
      <screen><prompt>#</prompt> <userinput>rm /var/lib/keystone/keystone.db</userinput></screen>
    </step>
    <step os="ubuntu;rhel;centos;fedora;opensuse;sles">
      <para>Use the password that you set previously to log in as
        root. Create a <literal>keystone</literal> database
        user:</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>
    </step>
    <step os="ubuntu;rhel;centos;fedora">
      <para>Create the database tables for the Identity Service:</para>
      <screen><prompt>#</prompt> <userinput>su -s /bin/sh -c "keystone-manage db_sync" keystone</userinput></screen>
    </step>
    <step os="debian">
      <para>Define an authorization token to use as a shared secret
        between the Identity Service and other OpenStack services.
        Respond to the <package>debconf</package> prompt with the
        value in the <code>admin_token</code> directive in the
          <filename>keystone.conf</filename> file. Use the
          <command>openssl rand -hex 10</command> command to generate
        this password.</para>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_1_admin_token.png"
            />
          </imageobject>
        </mediaobject>
      </informalfigure>
      <para>Later, you can verify that the
          <filename>/etc/keystone/keystone.conf</filename> file
        contains the password you have set using
          <package>debconf</package>:
        <programlisting language="ini">[DEFAULT]
# A "shared secret" between keystone and other openstack services
admin_token = ADMIN_TOKEN
...</programlisting></para>
      <para>If you omit a password (for example by pressing Enter at the
      <package>debconf</package> prompt, or installing Keystone
      using the Debconf non-interactive mode) the package generates a random
      <literal>ADMIN_TOKEN</literal> value.</para>
    </step>
    <step os="debian">
      <para>Respond to the prompts to create an administrative
        tenant:</para>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_2_register_admin_tenant_yes_no.png"
            />
          </imageobject>
        </mediaobject>
      </informalfigure>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_3_admin_user_name.png"
            />
          </imageobject>
        </mediaobject>
      </informalfigure>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_4_admin_user_email.png"
            />
          </imageobject>
        </mediaobject>
      </informalfigure>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_5_admin_user_pass.png"
            />
          </imageobject>
        </mediaobject>
      </informalfigure>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_6_admin_user_pass_confirm.png"
            />
          </imageobject>
        </mediaobject>
      </informalfigure>
    </step>
    <step os="debian">
      <para>If this is the first time you have installed the Identity
        Service, register the Identity Service in the service
        catalog:</para>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata scale="50"
              fileref="figures/debconf-screenshots/keystone_7_register_endpoint.png"
            />
          </imageobject>
        </mediaobject>
      </informalfigure>
    </step>
    <step os="rhel;centos;fedora;opensuse;sles;ubuntu">
      <para>Define an authorization token to use as a shared secret
        between the Identity Service and other OpenStack services. Use
          <command>openssl</command> to generate a random token and
        store it in the configuration file:</para>
      <screen os="rhel;centos;fedora;opensuse;sles"><prompt>#</prompt> <userinput>ADMIN_TOKEN=$(openssl rand -hex 10)</userinput>
<prompt>#</prompt> <userinput>echo $ADMIN_TOKEN</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/keystone/keystone.conf DEFAULT \
   admin_token $ADMIN_TOKEN</userinput></screen>
      <screen os="ubuntu"><prompt>#</prompt> <userinput>openssl rand -hex 10</userinput></screen>
      <para os="sles;opensuse">For SUSE Linux Enterprise use instead
        as first command:</para>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>ADMIN_TOKEN=$(openssl rand 10|hexdump  -e '1/1 "%.2x"')</userinput></screen>
      <para os="ubuntu">Edit
          <filename>/etc/keystone/keystone.conf</filename> and change
        the <literal>[DEFAULT]</literal> section, replacing
        ADMIN_TOKEN with the results of the command:</para>
      <programlisting os="ubuntu" language="ini">[DEFAULT]
# A "shared secret" between keystone and other openstack services
admin_token = ADMIN_TOKEN
...</programlisting>
    </step>
    <step os="rhel;centos;fedora;opensuse;sles">
      <para>By default, Keystone uses PKI tokens. Create the signing
        keys and certificates and restrict access to the generated data:</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">
      <para>Configure the log directory. Edit the
          <filename>/etc/keystone/keystone.conf</filename> file and update the
          <literal>[DEFAULT]</literal> section:</para>
       <programlisting language="ini">[DEFAULT]
...
log_dir = /var/log/keystone</programlisting>
    </step>
    <step os="ubuntu">
      <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 enable it to start when the
        system boots:</para>
      <screen os="rhel;fedora;centos;sles;opensuse"><prompt>#</prompt> <userinput>service openstack-keystone start</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-keystone on</userinput></screen>
    </step>
    <step>
      <para>By default, the Identity Service stores expired tokens in
        the database indefinitely. While potentially useful for auditing
        in production environments, the accumulation of expired tokens
        will considerably increase database size and may decrease
        service performance, particularly in test environments with
        limited resources. We recommend configuring a periodic task using
        <systemitem class="service">cron</systemitem> to purge expired
        tokens hourly.</para>
      <substeps>
        <step>
          <para>Run the following command to purge expired tokens every
            hour and log the output to
            <filename>/var/log/keystone/keystone-tokenflush.log</filename>:</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>
      </substeps>
    </step>
  </procedure>
</section>