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 module</title>
  <procedure>
    <para>Telemetry provides 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 \
  openstack-ceilometer-alarm-evaluator openstack-ceilometer-alarm-notifier</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>
      <note>
        <para>
          By default MongoDB is configured to create several 1 GB files
          in the <filename>/var/lib/mongodb/journal/</filename> directory
          to support database journaling.
        </para>
        <para>
          If you need to minimize the space allocated to support database
          journaling then set the <option>smallfiles</option> configuration
          key to <literal>true</literal> in the <filename>/etc/mongodb.conf</filename>
          configuration file. This will reduce the size of each journaling file
          to 512 MB.
        </para>
        <para os="ubuntu;debian">
          As the files are created the first time the MongoDB service starts
          you must stop the service and remove the files for this change to
          take effect:
        </para>
        <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>service mongodb stop</userinput>
<prompt>#</prompt> <userinput>rm /var/lib/mongodb/journal/j._0</userinput>
<prompt>#</prompt> <userinput>rm /var/lib/mongodb/journal/prealloc.1</userinput>
<prompt>#</prompt> <userinput>rm /var/lib/mongodb/journal/prealloc,2</userinput>
<prompt>#</prompt> <userinput>service mongodb start</userinput></screen>
        <para>
          For more information on the <option>smallfiles</option>
          configuration key refer to the MongoDB documentation at
          <link xlink:href="http://docs.mongodb.org/manual/reference/configuration-options/#smallfiles"/>.
        </para>
        <para>
          For instructions detailing the steps to disable database journaling
          entirely refer to
          <link xlink:href="http://docs.mongodb.org/manual/tutorial/manage-journaling/"/>.
        </para>
      </note>
    </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>service mongodb start</userinput>
<prompt>#</prompt> <userinput>chkconfig mongodb on</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 --host <replaceable>controller</replaceable> --eval '
db = db.getSiblingDB("ceilometer");
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>CEILOMETER_TOKEN=$(openssl rand -hex 10)</userinput>
<prompt>#</prompt> <userinput>echo $CEILOMETER_TOKEN</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf publisher_rpc metering_secret $CEILOMETER_TOKEN</userinput></screen>
      <para os="sles;opensuse">For SUSE Linux Enterprise, run the
        following command:</para>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>CEILOMETER_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>CEILOMETER_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>CEILOMETER_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 <replaceable>controller</replaceable></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="opensuse;sles">
        <para>Configure collector dispatcher:</para>
        <screen os="opensuse;sles"><prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf \
  collector dispatcher database</userinput></screen>
    </step>

    <step os="ubuntu">
      <para>Configure the log directory.</para>
      <para>Edit the <filename>/etc/ceilometer/ceilometer.conf</filename> file
      and update the <literal>[DEFAULT]</literal> section:</para>
       <programlisting os="ubuntu" language="ini">[DEFAULT]
log_dir = /var/log/ceilometer</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 auth_uri http://<replaceable>controller</replaceable>:5000</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf \
  keystone_authtoken admin_password <replaceable>CEILOMETER_PASS</replaceable></userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf \
  service_credentials os_username ceilometer</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf \
  service_credentials os_tenant_name service</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/ceilometer/ceilometer.conf \
  service_credentials os_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
auth_uri = http://<replaceable>controller</replaceable>:5000
admin_tenant_name = service
admin_user = ceilometer
admin_password = <replaceable>CEILOMETER_PASS</replaceable></programlisting>
      <para os="ubuntu;debian">Also set the
        <literal>[service_credentials]</literal> section:</para>
      <programlisting os="ubuntu;debian" language="ini">[service_credentials]
os_username = ceilometer
os_tenant_name = service
os_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>
<prompt>#</prompt> <userinput>keystone endpoint-create \
  --service-id=$(keystone service-list | awk '/ metering / {print $2}') \
  --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>,
          <systemitem class="service">openstack-ceilometer-collector</systemitem>,
          <systemitem class="service" os="opensuse;sles">openstack-ceilometer-alarm-evaluator</systemitem>,
          and <systemitem class="service" os="opensuse;sles">openstack-ceilometer-alarm-notifier</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>
<prompt>#</prompt> <userinput>service openstack-ceilometer-alarm-evaluator start</userinput>
<prompt>#</prompt> <userinput>service openstack-ceilometer-alarm-notifier start</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-ceilometer-alarm-evaluator on</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-ceilometer-alarm-notifier 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>