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 Telemetry service</title>
  <procedure>
    <para>OpenStack Telemetry is an API service that
      provides a collector and a range of disparate agents. Before
      you can install these agents on nodes such as the compute
      node, you must use this procedure to install the core
      components on the controller node.</para>
    <step>
      <para>Install the Telemetry 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>Respond to the prompts for <link
          linkend="debconf-keystone_authtoken"
            ><literal>[keystone_authtoken]</literal> settings</link>,
          <link linkend="debconf-rabbitqm">RabbitMQ credentials</link>
        and <link linkend="debconf-api-endpoints">API endpoint</link>
        registration.</para>
    </step>
    <step>
      <para>The Telemetry Service uses a database to store information.
        Specify the location of the database in the configuration
        file. The examples 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="ubuntu;debian;sles;opensuse">
      <para>Configure MongoDB to make it listen on the controller public IP
      address. Edit the <filename>/etc/mongodb.conf</filename> file and modify the
      <literal>bind_ip</literal> key:</para>
      <programlisting language="ini">bind_ip = 192.168.0.10</programlisting>
    </step>
    <step os="debian;ubuntu">
      <para>Restart the MongoDB service to apply the configuration change:</para>
      <screen><prompt>#</prompt> <userinput>service mongodb restart</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>
        database user:</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>Configure the Telemetry Service to use the 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 the
          <filename>/etc/ceilometer/ceilometer.conf</filename> file
        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 among Telemetry 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/ceilometer/ceilometer.conf publisher_rpc metering_secret $ADMIN_TOKEN</userinput></screen>
      <para os="sles;opensuse">For SUSE Linux Enterprise, run the
        following 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 the
          <filename>/etc/ceilometer/ceilometer.conf</filename> file
        and change the <literal>[publisher_rpc]</literal> section. Replace
          <replaceable>ADMIN_TOKEN</replaceable> with the results of
        the <literal>openssl</literal> command:</para>
      <programlisting os="ubuntu;debian" language="ini">...
[publisher_rpc]
...
# Secret value for signing metering messages (string value)
metering_secret = <replaceable>ADMIN_TOKEN</replaceable>
...</programlisting>
    </step>

    <step os="opensuse;sles;ubuntu">
      <para>Configure the RabbitMQ access:</para>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf DEFAULT rabbit_host controller</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf DEFAULT rabbit_password <replaceable>RABBIT_PASS</replaceable></userinput></screen>
      <para os="ubuntu">Edit the <filename>/etc/ceilometer/ceilometer.conf</filename> file and update the <literal>[DEFAULT]</literal> section.</para>
      <programlisting os="ubuntu" language="ini">rabbit_host = <replaceable>controller</replaceable>
rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
    </step>

    <step os="rhel;centos;fedora;opensuse;sles;ubuntu">
      <para>Create a <literal>ceilometer</literal> user that the
        Telemetry Service uses 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>
      <para>Add the credentials to the configuration files for the
        Telemetry 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 the
          <filename>/etc/ceilometer/ceilometer.conf</filename> file
        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 = <replaceable>CEILOMETER_PASS</replaceable></programlisting>
    </step>
    <step os="rhel;centos;fedora;opensuse;sles;ubuntu">
      <para>Register the Telemetry Service with the Identity Service so
        that other OpenStack services can locate it. Use the
          <command>keystone</command> command to register the service
        and specify the endpoint:</para>
      <screen><prompt>#</prompt> <userinput>keystone service-create --name=ceilometer --type=metering \
  --description="Ceilometer Telemetry Service"</userinput></screen>
    </step>
    <step os="rhel;centos;fedora;opensuse;sles;ubuntu">
      <para>Note the <literal>id</literal> property that is returned
        for the service. 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 services with their 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"
          >openstack-ceilometer-api</systemitem>, <systemitem class="service"
          os="opensuse;sles">openstack-ceilometer-agent-central</systemitem><systemitem
          class="service" os="rhel;fedora;centos">openstack-ceilometer-central</systemitem>
          and <systemitem class="service">openstack-ceilometer-collector</systemitem>
          services and configure them to start when the system boots:</para>
      <screen os="opensuse;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>
      <screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>service openstack-ceilometer-api start</userinput>
<prompt>#</prompt> <userinput>service openstack-ceilometer-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-central on</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-ceilometer-collector on</userinput></screen>
    </step>
  </procedure>
</section>