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>@controller/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:KEYSTONE_DBPASS@controller/keystone
...
      </programlisting>
    </step>

    <step os="rhel;centos;fedora;opensuse;sles">
      <para>Use the <command>openstack-db</command> command to create
        the database and tables, as well as a database user called
          <literal>keystone</literal> to connect to the database.
        Replace
          <literal><replaceable>KEYSTONE_DBPASS</replaceable></literal>
        with the same password used in the previous step.</para>
      <screen><prompt>#</prompt> <userinput>openstack-db --init --service keystone --password <replaceable>KEYSTONE_DBPASS</replaceable></userinput></screen>
    </step>
    <step os="ubuntu">
      <para>By default, the Ubuntu packages create an 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>
      </step>
    <step os="ubuntu">
      <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></screen>
    </step>
    <step os="ubuntu">
      <para>Create the database tables for the Identity Service:</para>
      <screen><prompt>#</prompt> <userinput>keystone-manage db_sync</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:</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 /etc/keystone/* /var/log/keystone/keystone.log</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>keystone-manage pki_setup --keystone-user openstack-keystone \
   --keystone-group openstack-keystone</userinput>
<prompt>#</prompt> <userinput>chown -R openstack-keystone:openstack-keystone /etc/keystone/* \
   /var/log/keystone/keystone.log</userinput></screen>
    </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>
  </procedure>
</section>