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>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 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="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="sles;opensuse"><prompt>#</prompt> <userinput>zypper install openstack-keystone python-keystoneclient</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>[token]</literal> section, configure the UUID
            token provider and SQL driver:</para>
          <programlisting language="ini">[token]
...
provider = keystone.token.providers.uuid.Provider
driver = keystone.token.persistence.backends.sql.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>keystone tenant-create --name admin --description "Admin Tenant"</userinput>
<prompt>#</prompt> <userinput>keystone user-create --name admin --pass <replaceable>ADMIN_PASS</replaceable> --email root@localhost</userinput>
<prompt>#</prompt> <userinput>keystone role-create --name admin</userinput>
<prompt>#</prompt> <userinput>keystone user-role-add user-role-add --user admin --role admin --tenant admin</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>keystone service-create --name keystone --type identity --description "OpenStack Identity"</userinput>
<prompt>#</prompt> <userinput>keystone endpoint-create \
  --service-id $(keystone service-list | awk '/ identity / {print $2}') \
  --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</userinput></screen>
      <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">
      <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 os="rhel;centos;fedora"><prompt>#</prompt> <userinput>systemctl enable openstack-keystone.service</userinput>
<prompt>#</prompt> <userinput>systemctl start openstack-keystone.service</userinput></screen>
      <para os="sles">On SLES:</para>
      <screen os="sles"><prompt>#</prompt> <userinput>service openstack-keystone start</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-keystone on</userinput></screen>
      <para os="opensuse">On openSUSE:</para>
      <screen os="opensuse"><prompt>#</prompt> <userinput>systemctl enable openstack-keystone.service</userinput>
<prompt>#</prompt> <userinput>systemctl start openstack-keystone.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>
      <para os="ubuntu;rhel;centos;fedora;opensuse;sles">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 environments with limited resources.</para>
      <para os="debian">The Keystone package already contains 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
        hourly. You can however have a look at (and eventually customize) the already
        configured script.</para>
      <para os="opensuse;sles">The Keystone package already contains a cron job
        under <filename>/etc/cron.hourly/openstack-keystone</filename>, so it is not
        necessary to manually configure a periodic task that purges expired tokens
        hourly. You can however have a look at (and eventually customize) the already
        configured script.</para>
      <para os="ubuntu;rhel;centos;fedora">We recommend that you use
        <systemitem class="service">cron</systemitem> to configure a periodic
        task that purges expired tokens hourly:</para>
      <screen os="ubuntu"><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>
    </step>
  </procedure>
</section>