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

<?xml version="1.0" encoding="utf-8"?>
<section xml:id="ceilometer-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 Metering Service</title>
  <procedure>
    <title>Install the central Metering Service components</title>
    <para>The Metering service consists of an API service, collector,
      and a range of disparate agents. This procedure details how to
      install the core components before you install the agents
      elsewhere, such as on the compute node.</para>
    <step>
      <para>Install the Metering Service on the controller
        node:</para>
      <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>apt-get install ceilometer-api ceilometer-collector ceilometer-agent-central python-ceilometerclient</userinput></screen>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-ceilometer-api openstack-ceilometer-collector openstack-ceilometer-central python-ceilometerclient</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install openstack-ceilometer-api openstack-ceilometer-collector openstack-ceilometer-agent-central python-ceilometerclient</userinput></screen>
    </step>
    <step os="debian"><para>Answer to the <systemitem class="library">debconf</systemitem>
    prompts about the API endpoint registration, the RabbitMQ credentials,
    and the <code>keystone_autotoken</code>.</para>
    </step>
    <step>
      <para>The Metering Service uses a database to store information.
        Specify the location of the database in the configuration
        file. The examples in this guide use a MongoDB database on the
        controller node.</para>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install mongodb-server mongodb</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install mongodb</userinput></screen>
      <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>apt-get install mongodb</userinput></screen>
    </step>
    <step os="rhel;centos;fedora;opensuse;sles">
      <para>Start the MongoDB server and configure it to start when
        the system boots:</para>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>systemctl start mongodb.service</userinput>
<prompt>#</prompt> <userinput>systemctl enable mongodb.service</userinput></screen>
      <!-- NB: The use of mongod, and not mongodb, in the below screen is
           intentional. -->
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>service mongod start</userinput>
<prompt>#</prompt> <userinput>chkconfig mongod on</userinput></screen>
    </step>
    <step>
      <para>Create the database and a <literal>ceilometer</literal>
        user for it:</para>
      <screen><prompt>#</prompt> <userinput>mongo</userinput>
<prompt>></prompt> <userinput>use ceilometer</userinput>
<prompt>></prompt> <userinput>db.addUser( { user: "ceilometer",
              pwd: "<replaceable>CEILOMETER_DBPASS</replaceable>",
              roles: [ "readWrite", "dbAdmin" ]
            } )
</userinput></screen>
    </step>
    <step>
      <para>Tell the Metering Service to use the created
        database.</para>
      <screen os="rhel;centos;fedora;opensuse;sles"><prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf \
  database connection mongodb://ceilometer:<replaceable>CEILOMETER_DBPASS</replaceable>@<replaceable>controller</replaceable>:27017/ceilometer</userinput></screen>
      <para os="ubuntu;debian">Edit
          <filename>/etc/ceilometer/ceilometer.conf</filename> and
        change the <literal>[database]</literal> section.</para>
      <programlisting os="ubuntu;debian" language="ini">...
[database]
...
# The SQLAlchemy connection string used to connect to the
# database (string value)
connection = mongodb://ceilometer:<replaceable>CEILOMETER_DBPASS</replaceable>@<replaceable>controller</replaceable>:27017/ceilometer
...</programlisting>

    </step>
    <step>
      <para>You must define an secret key that is used as a shared
        secret between the Metering Service nodes. 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 publisher_rpc metering_secret $ADMIN_TOKEN</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>
      <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>openssl rand -hex 10</userinput></screen>
      <para os="ubuntu;debian">Edit
          <filename>/etc/ceilometer/ceilometer.conf</filename> and
        change the <literal>[DEFAULT]</literal> section, replacing
        ADMIN_TOKEN with the results of the command.</para>
      <programlisting os="ubuntu;debian" language="ini">...
[publisher_rpc]
...
# Secret value for signing metering messages (string value)
metering_secret = ADMIN_TOKEN
...</programlisting>
    </step>
    <step os="rhel;centos;fedora;opensuse;sles;ubuntu">
      <para>Create a user called <literal>ceilometer</literal> so that
        the Metering Service can use to authenticate with the Identity
        Service. Use the <literal>service</literal> tenant and give
        the user the <literal>admin</literal> role.</para>
      <screen><prompt>#</prompt> <userinput>keystone user-create --name=ceilometer --pass=<replaceable>CEILOMETER_PASS</replaceable> --email=<replaceable>ceilometer@example.com</replaceable></userinput>
<prompt>#</prompt> <userinput>keystone user-role-add --user=ceilometer --tenant=service --role=admin</userinput></screen>
    </step>
    <step os="rhel;centos;fedora;opensuse;sles;ubuntu">
      <para>Add the credentials to the configuration files for the
        Metering Service.</para>
      <screen os="centos;rhel;fedora;opensuse;sles"><prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf keystone_authtoken auth_host <replaceable>controller</replaceable></userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf keystone_authtoken admin_user ceilometer</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf keystone_authtoken admin_tenant_name service</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf keystone_authtoken auth_protocol http</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf keystone_authtoken admin_password <replaceable>CEILOMETER_PASS</replaceable></userinput></screen>
      <para os="ubuntu;debian">Edit
          <filename>/etc/ceilometer/ceilometer.conf</filename> and
        change the <literal>[keystone_authtoken]</literal>
        section.</para>
      <programlisting os="ubuntu;debian" language="ini">...
[keystone_authtoken]
auth_host = controller
auth_port = 35357
auth_protocol = http
admin_tenant_name = service
admin_user = ceilometer
admin_password = CEILOMETER_PASS
...</programlisting>
    </step>
    <step os="rhel;centos;fedora;opensuse;sles;ubuntu">
      <para>Register the Metering Service with the Identity Service so
        that other OpenStack services can locate it. Register the
        service and specify the endpoint using the
          <command>keystone</command> command.</para>
      <screen><prompt>#</prompt> <userinput>keystone service-create --name=ceilometer --type=metering \
  --description="Ceilometer Metering Service"</userinput></screen>
    </step>
    <step os="rhel;centos;fedora;opensuse;sles;ubuntu">
      <para>Note the <literal>id</literal> property for the service
        that was returned in the previous step. Use it when you create
        the endpoint.</para>
      <screen><prompt>#</prompt> <userinput>keystone endpoint-create \
  --service-id=<replaceable>the_service_id_above</replaceable> \
  --publicurl=http://<replaceable>controller</replaceable>:8777/ \
  --internalurl=http://<replaceable>controller</replaceable>:8777/ \
  --adminurl=http://<replaceable>controller</replaceable>:8777/</userinput></screen>
    </step>
    <step os="ubuntu;debian">
      <para>Restart the service with its new settings.</para>
      <screen><prompt>#</prompt> <userinput>service ceilometer-agent-central restart</userinput>
<prompt>#</prompt> <userinput>service ceilometer-api restart</userinput>
<prompt>#</prompt> <userinput>service ceilometer-collector restart</userinput></screen>
    </step>
    <step os="rhel;fedora;centos;opensuse;sles">
      <para>Start the <systemitem class="service"
          >ceilometer-api</systemitem>, <systemitem class="service"
          >ceilometer-agent-central</systemitem> and <systemitem
          class="service">ceilometer-collector</systemitem> services
        and configure them to start when the system boots.</para>
      <screen os="rhel;fedora;centos;sles"><prompt>#</prompt> <userinput>service openstack-ceilometer-api start</userinput>
<prompt>#</prompt> <userinput>service openstack-ceilometer-agent-central start</userinput>
<prompt>#</prompt> <userinput>service openstack-ceilometer-collector start</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-ceilometer-api on</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-ceilometer-agent-central on</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-ceilometer-collector on</userinput></screen>
    </step>
  </procedure>
</section>