..
      Copyright 2012 Nicolas Barcet for Canonical
                2013 New Dream Network, LLC (DreamHost)

      Licensed under the Apache License, Version 2.0 (the "License"); you may
      not use this file except in compliance with the License. You may obtain
      a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
      License for the specific language governing permissions and limitations
      under the License.

.. _installing_manually:

=====================
 Installing Manually
=====================


Storage Backend Installation
============================

This step is a prerequisite for the collector and API services. You may use
one of the listed database backends below to store Ceilometer data.

Gnocchi
-------

1. Follow `Gnocchi installation`_ instructions

2. Initialize Gnocchi for Ceilometer::

     gnocchi-upgrade --create-legacy-resource-types

   .. note::

      Prior to Gnocchi 2.1, Ceilometer resource types were included, therefore
      --create-legacy-resource-types flag is not needed.

3. Edit `/etc/ceilometer/ceilometer.conf` for the collector service::

     [DEFAULT]
     meter_dispatchers = gnocchi
     event_dispatchers = gnocchi

     [dispatcher_gnocchi]
     filter_service_activity = False # Enable if using swift backend
     filter_project = <project name associated with gnocchi user> # if using swift backend

     [service_credentials]
     auth_url = <auth_url>:5000
     region_name = RegionOne
     password = password
     username = ceilometer
     project_name = service
     project_domain_id = default
     user_domain_id = default
     auth_type = password

4. Copy gnocchi_resources.yaml to config directory (e.g./etc/ceilometer)

5. To minimize data requests, caching and batch processing should be enabled:

   1. Enable resource caching (oslo.cache_ should be installed)::

        [cache]
        backend_argument = redis_expiration_time:600
        backend_argument = db:0
        backend_argument = distributed_lock:True
        backend_argument = url:redis://localhost:6379
        backend = dogpile.cache.redis

   2. Enable batch processing::

        [collector]
        batch_size = 100
        batch_timeout = 5

6. Start collector service

.. _oslo.cache: http://docs.openstack.org/developer/oslo.cache/opts.html


MongoDB
-------

   Follow the instructions to install the MongoDB_ package for your operating
   system, then start the service. The required minimum version of MongoDB is
   2.4.x. You will also need to have pymongo_ 2.4 installed

   To use MongoDB as the storage backend, change the 'database' section in
   ceilometer.conf as follows::

    [database]
    connection = mongodb://username:password@host:27017/ceilometer

SQLalchemy-supported DBs
------------------------

   You may alternatively use any SQLAlchemy-supported DB such as
   `PostgreSQL` or `MySQL`.

   To use MySQL as the storage backend, change the 'database' section in
   ceilometer.conf as follows::

    [database]
    connection = mysql+pymysql://username:password@host/ceilometer?charset=utf8

HBase
-----

   HBase backend is implemented to use HBase Thrift interface, therefore it is
   mandatory to have the HBase Thrift server installed and running. To start
   the Thrift server, please run the following command::

    ${HBASE_HOME}/bin/hbase thrift start

   The implementation uses `HappyBase`_, which is a wrapper library used to
   interact with HBase via Thrift protocol. You can verify the Thrift
   connection by running a quick test from a client::

    import happybase

    conn = happybase.Connection(host=$hbase-thrift-server,
                                port=9090,
                                table_prefix=None,
                                table_prefix_separator='_')
    print conn.tables() # this returns a list of HBase tables in your HBase server

   .. note::

      HappyBase version 0.5 or greater is required. Additionally, version 0.7
      is not currently supported.

   In the case of HBase, the required database tables (`project`, `user`, `resource`,
   `meter`) should be created manually with `f` column family for each one.

   To use HBase as the storage backend, change the 'database' section in
   ceilometer.conf as follows::

    [database]
    connection = hbase://hbase-thrift-host:9090

   It is possible to customize happybase's `table_prefix` and `table_prefix_separator`
   via query string. By default `table_prefix` is not set and `table_prefix_separator`
   is '_'. When `table_prefix` is not specified `table_prefix_separator` is not taken
   into account. E.g. the resource table in the default case will be 'resource' while
   with `table_prefix` set to 'ceilo' and `table_prefix_separator` to '.' the resulting
   table will be 'ceilo.resource'. For this second case this is the database connection
   configuration::

    [database]
    connection = hbase://hbase-thrift-host:9090?table_prefix=ceilo&table_prefix_separator=.

   To ensure proper configuration, please add the following lines to the
   `hbase-site.xml` configuration file::

    <property>
      <name>hbase.thrift.minWorkerThreads</name>
      <value>200</value>
    </property>

.. _`Gnocchi installation`: http://docs.openstack.org/developer/gnocchi/install.html
.. _HappyBase: http://happybase.readthedocs.org/en/latest/index.html#
.. _MongoDB: http://www.mongodb.org/
.. _pymongo: https://pypi.python.org/pypi/pymongo/


Installing the notification agent
=================================

.. index::
   double: installing; agent-notification

1. Clone the ceilometer git repository to the management server::

   $ cd /opt/stack
   $ git clone https://git.openstack.org/openstack/ceilometer.git

2. As a user with ``root`` permissions or ``sudo`` privileges, run the
   ceilometer installer::

   $ cd ceilometer
   $ sudo python setup.py install

3. Copy the sample configuration files from the source tree
   to their final location::

   $ mkdir -p /etc/ceilometer
   $ cp etc/ceilometer/*.json /etc/ceilometer
   $ cp etc/ceilometer/*.yaml /etc/ceilometer
   $ cp etc/ceilometer/ceilometer.conf.sample /etc/ceilometer/ceilometer.conf

4. Edit ``/etc/ceilometer/ceilometer.conf``

   1. Configure messaging::

        [oslo_messaging_notifications]
        topics = notifications

        [oslo_messaging_rabbit]
        rabbit_userid = stackrabbit
        rabbit_password = openstack1
        rabbit_hosts = 10.0.2.15

   2. Set the ``telemetry_secret`` value.

      Set the ``telemetry_secret`` value to a large, random, value. Use
      the same value in all ceilometer configuration files, on all
      nodes, so that messages passing between the nodes can be
      validated. This value can be left empty to disable message signing.

      .. note::

         Disabling signing will improve message handling performance

   Refer to :doc:`/configuration` for details about any other options
   you might want to modify before starting the service.

5. Start the notification daemon::

     $ ceilometer-agent-notification

   .. note::

      The default development configuration of the collector logs to
      stderr, so you may want to run this step using a screen session
      or other tool for maintaining a long-running program in the
      background.


Installing the collector
========================

.. index::
   double: installing; collector

.. _storage_backends:

1. Clone the ceilometer git repository to the management server::

   $ cd /opt/stack
   $ git clone https://git.openstack.org/openstack/ceilometer.git

2. As a user with ``root`` permissions or ``sudo`` privileges, run the
   ceilometer installer::

   $ cd ceilometer
   $ sudo python setup.py install

3. Copy the sample configuration files from the source tree
   to their final location::

   $ mkdir -p /etc/ceilometer
   $ cp etc/ceilometer/*.json /etc/ceilometer
   $ cp etc/ceilometer/*.yaml /etc/ceilometer
   $ cp etc/ceilometer/ceilometer.conf.sample /etc/ceilometer/ceilometer.conf

4. Edit ``/etc/ceilometer/ceilometer.conf``

   1. Configure messaging::

        [oslo_messaging_notifications]
        topics = notifications

        [oslo_messaging_rabbit]
        rabbit_userid = stackrabbit
        rabbit_password = openstack1
        rabbit_hosts = 10.0.2.15

   2. Set the ``telemetry_secret`` value (if enabled for notification agent)

   Refer to :doc:`/configuration` for details about any other options
   you might want to modify before starting the service.

5. Start the collector::

     $ ceilometer-collector

   .. note::

      The default development configuration of the collector logs to
      stderr, so you may want to run this step using a screen session
      or other tool for maintaining a long-running program in the
      background.

Installing the Polling Agent
============================

.. index::
   double: installing; agent

.. note::

   The polling agent needs to be able to talk to Keystone and any of
   the services being polled for updates. It also needs to run on your compute
   nodes to poll instances.

1. Clone the ceilometer git repository to the server::

   $ cd /opt/stack
   $ git clone https://git.openstack.org/openstack/ceilometer.git

2. As a user with ``root`` permissions or ``sudo`` privileges, run the
   ceilometer installer::

   $ cd ceilometer
   $ sudo python setup.py install

3. Copy the sample configuration files from the source tree
   to their final location::

   $ mkdir -p /etc/ceilometer
   $ cp etc/ceilometer/*.json /etc/ceilometer
   $ cp etc/ceilometer/*.yaml /etc/ceilometer
   $ cp etc/ceilometer/ceilometer.conf.sample /etc/ceilometer/ceilometer.conf

4. Configure messaging by editing ``/etc/ceilometer/ceilometer.conf``::

     [oslo_messaging_notifications]
     topics = notifications

     [oslo_messaging_rabbit]
     rabbit_userid = stackrabbit
     rabbit_password = openstack1
     rabbit_hosts = 10.0.2.15

5. In order to retrieve object store statistics, ceilometer needs
   access to swift with ``ResellerAdmin`` role. You should give this
   role to your ``os_username`` user for tenant ``os_tenant_name``::

     $ openstack role create ResellerAdmin
     +-----------+----------------------------------+
     | Field     | Value                            |
     +-----------+----------------------------------+
     | domain_id | None                             |
     | id        | f5153dae801244e8bb4948f0a6fb73b7 |
     | name      | ResellerAdmin                    |
     +-----------+----------------------------------+

     $ openstack role add f5153dae801244e8bb4948f0a6fb73b7 \
                          --project $SERVICE_TENANT \
                          --user $CEILOMETER_USER

6. Start the agent::

   $ ceilometer-polling

7. By default, the polling agent polls the `compute` and `central` namespaces.
   You can specify which namespace to poll in the `ceilometer.conf`
   configuration file or on the command line::

     $ ceilometer-polling --polling-namespaces central,ipmi


Installing the API Server
=========================

.. index::
   double: installing; API

.. note::

   The API server needs to be able to talk to keystone and ceilometer's
   database. It is only required if you choose to store data in legacy
   database or if you inject new samples via REST API.

1. Clone the ceilometer git repository to the server::

   $ cd /opt/stack
   $ git clone https://git.openstack.org/openstack/ceilometer.git

2. As a user with ``root`` permissions or ``sudo`` privileges, run the
   ceilometer installer::

   $ cd ceilometer
   $ sudo python setup.py install

3. Copy the sample configuration files from the source tree
   to their final location::

   $ mkdir -p /etc/ceilometer
   $ cp etc/ceilometer/api_paste.ini /etc/ceilometer
   $ cp etc/ceilometer/*.json /etc/ceilometer
   $ cp etc/ceilometer/*.yaml /etc/ceilometer
   $ cp etc/ceilometer/ceilometer.conf.sample /etc/ceilometer/ceilometer.conf

4. Configure messaging by editing ``/etc/ceilometer/ceilometer.conf``::

     [oslo_messaging_notifications]
     topics = notifications

     [oslo_messaging_rabbit]
     rabbit_userid = stackrabbit
     rabbit_password = openstack1
     rabbit_hosts = 10.0.2.15

5. Create a service for ceilometer in keystone::

     $ openstack service create metering --name=ceilometer \
                                         --description="Ceilometer Service"

6. Create an endpoint in keystone for ceilometer::

     $ openstack endpoint create $CEILOMETER_SERVICE \
                                 --region RegionOne \
                                 --publicurl "http://$SERVICE_HOST:8777" \
                                 --adminurl "http://$SERVICE_HOST:8777" \
                                 --internalurl "http://$SERVICE_HOST:8777"

   .. note::

     CEILOMETER_SERVICE is the id of the service created by the first command
     and SERVICE_HOST is the host where the Ceilometer API is running. The
     default port value for ceilometer API is 8777. If the port value
     has been customized, adjust accordingly.

7. Choose and start the API server.

   Ceilometer includes the ``ceilometer-api`` command. This can be
   used to run the API server. For smaller or proof-of-concept
   installations this is a reasonable choice. For larger installations it
   is strongly recommended to install the API server in a WSGI host
   such as mod_wsgi (see :doc:`mod_wsgi`). Doing so will provide better
   performance and more options for making adjustments specific to the
   installation environment.

   If you are using the ``ceilometer-api`` command it can be started
   as::

    $ ceilometer-api

.. note::

   The development version of the API server logs to stderr, so you
   may want to run this step using a screen session or other tool for
   maintaining a long-running program in the background.


Enabling Service Notifications
==============================

See the `install guide`_ for instructions on how to enable meters for specific
OpenStack services.

.. _`install guide`: https://docs.openstack.org/project-install-guide/telemetry/draft/install-controller.html
