Introduction to InfluxDB

InfluxDB is an open source time series database with high availability and high performance features included. It’s written in the Golang programming language. Distributed with no dependencies but still highly extensible.

Several key features of InfluxDB:

• Simple to install with no dependencies.
• Specific purpose for time series data. no special schema design or custom app logic required to use InfluxDB.
• Support for hundreds of thousands of writes per seconds.
• Native HTTP API, no need to manage server side code.
• Time-centric functions and easy to use SQL-like query language.
• Data tagging for flexible querying.
• Every data point indexed as it comes in and immediately available in less than 100ms

We can use InfluxDB to manage any time series data. In server or data center environment, we can use influxDB to store system and application performance data. We can also collect and store data center temperature data in InfluxDB.

You can even use InfluxDB outside IT related usage for example you want to store time series market price of a commodity. You can also use InfluxDB to store metrics for your Internet Of Things (IoT) projects.

In this tutorial we’ll learn how-to install and configure InfluxDB 0.11 on Ubuntu Server 14.04 Trusty Tahr.

Networking Requirements

By default, InfluxDB uses the following ports:
* TCP port 8083 is used by InfluxDB Admin Panel
* TCP port 8086 is used for client server communication over HTTP API.

If you use firewall make sure that you allow both port above as needed.

Install InfluxDB on Ubuntu 14.04

Before we install InfluxDB let’s update the base system to the latest release.

    $ sudo apt-get update
    $ sudo apt-get -y upgrade

Add the influxdata repository key so apt can verify packages that will be installed.

    $ curl -sL https://repos.influxdata.com/influxdb.key | sudo apt-key add -
    OK

Create repository file for influxdb.

    $ echo "deb https://repos.influxdata.com/ubuntu trusty stable" | sudo tee /etc/apt/sources.list.d/influxdb.list

Update apt metadata by running command below.

    $ sudo apt-get update

Now we are ready to install InfluxDB.

    $ sudo apt-get -y install influxdb

InfluxDB is not running after installation. We will disable influxDB reporting feature first before starting InfluxDB.

Disable Reporting

By default, InfluxDB will report anonymous data to m.influxdb.com. The data sent includes a raft id (random 8 bytes), OS, architecture and version. The IP address of servers reporting is not tracked. This reporting feature being used by Influxdata team to track number of instances running and the versions.
In this section we’ll disable this feature so our server will not report to m.influxdb.com. Find line below:

    reporting-disabled = false 

replace false value to “`true:

    reporting-disabled = true

Start InfluxDB for the first time –

    $ sudo service influxdb start
    Starting the process influxdb [ OK ]
    influxdb process was started [ OK ]

Let’s check whether InfluxDB already listen on its ports –

    $ sudo netstat -naptu | grep LISTEN | grep influxd
    tcp6       0      0 :::8083                 :::*                    LISTEN      2741/influxd    
    tcp6       0      0 :::8086                 :::*                    LISTEN      2741/influxd    
    tcp6       0      0 :::8088                 :::*                    LISTEN      2741/influxd    

InfluxDB Admin Panel

InfluxDB comes with web based admin panel. We can access the admin panel by pointing our browser to http://:8083.

HP_NO_IMG/data/uploads/users/120811e7-591a-4d04-b59b-4bcc78522225/663055797.png” alt=”” />

We can access connection settings by clicing gear icon on top right of the page.

HP_NO_IMG/data/uploads/users/120811e7-591a-4d04-b59b-4bcc78522225/1705167554.png” alt=”” />

From the web based admin panel, you can also do query by entering your query on Query field like shown above.

You can cheat by using Query Templates drop down below Query field.

HP_NO_IMG/data/uploads/users/70fed463-d441-452e-bb7e-e0e3fa684498/1312724539.png” alt=”” />

This query template is really useful for learning operations on InfluxDB.

Connecting to a DB Using Influx CLI

InfluxDB also comes with CLI application named influx. You can connect to InfluxDB using influx by running it wihout options. By default it will connect to local influxdb installation on default port 8086.

    $ influx
    Visit https://enterprise.influxdata.com to register for updates, InfluxDB server management, and monitoring.
    Connected to http://localhost:8086 version 0.13.0
    InfluxDB shell version: 0.13.0
    > 

Creating an Admin User

InfluxDB comes with no users at all. We need to create users including admin user.

In this tutorial we will use web base admin panel to do queries instead of using influx CLI tool, but all commands can be used from both admin panel and CLI.

Let’s check whether InfluxDB already has users or not using command SHOW USERS.

HP_NO_IMG/data/uploads/users/70fed463-d441-452e-bb7e-e0e3fa684498/568308080.png” alt=”” />

As we can see above there are no users listed on the page.

Now let’s create an admin user with the name admin using command below:

    CREATE USER "admin" WITH PASSWORD 'verysecret' WITH ALL PRIVILEGES 

We need to press enter for the query to be executed. Don’t forget to change the verysecret password above with your own random password.

We should see a Success! (no result to display) message if our command is correct and executed properly.

HP_NO_IMG/data/uploads/users/70fed463-d441-452e-bb7e-e0e3fa684498/1393494892.png” alt=”” />

Now let’s see the list of users again using command SHOW USERS. The new admin user is listed with admin listed as true.

HP_NO_IMG/data/uploads/users/70fed463-d441-452e-bb7e-e0e3fa684498/923088878.png” alt=”” />

Creating a Normal User

Now let’s create a normal / non-admin user named hostpresto using command below:

    CREATE USER "hostpresto" WITH PASSWORD 'newsecret'

HP_NO_IMG/data/uploads/users/70fed463-d441-452e-bb7e-e0e3fa684498/1635481958.png” alt=”” />

Let’s check again list of users using command SHOW USERS

HP_NO_IMG/data/uploads/users/70fed463-d441-452e-bb7e-e0e3fa684498/1833985587.png” alt=”” />

The key to create an admin user is by adding GRANT ALL PRIVILEGES.

Using a Query URL

As we see above when connecting to InfluxDB using the influx CLI tool, it’s connected to http://localhost:8086. InfluxDB client can use HTTP REST to do queries.

From admin panel we can use the Generate Query URL button to generate query URL. For example the SHOW USERS command will be translated to http://192.168.33.10:8086/query?q=SHOW+USERS&db=_internal as query URL.

HP_NO_IMG/data/uploads/users/70fed463-d441-452e-bb7e-e0e3fa684498/339126409.png” alt=”” />

Let’s do the query using the curl command. Don’t forget to put the query URL inside quotes.

    $ curl "http://192.168.33.10:8086/query?q=SHOW+USERS&db=_internal"
    {"results":[{"series":[{"columns":["user","admin"],"values":[["admin",true],["hostpresto",false]]}]}]}

The result from the query is that one line JSON file that could not be read easily. We can append &pretty=true at the end of the query URL so we get pretty JSON output.

    $ curl "http://192.168.33.10:8086/query?q=SHOW+USERS&db=_internal&pretty=true"
    {
        "results": [
            {
                "series": [
                    {
                        "columns": [
                            "user",
                            "admin"
                        ],
                        "values": [
                            [
                                "admin",
                                true
                            ],
                            [
                                "hostpresto",
                                false
                            ]
                        ]
                    }
                ]
            }
        ]
    }

The pretty option is useful when we are debugging output from InfluxDB query.

Enable Authentication

We already have two users, one admin and one normal user, but we’ll still able to access InfluxDB both via web based admin panel and cli without authentication.

The reason for this is because authentication is disabled by default and not enabled automatically when we have users. We can enable authentication from InfluxDB configuration file.

Open /etc/influxdb/influxdb.conf file (you might need sudo to open the file).

Find [http] section. Replace auth-enabled from false

    [http]
    ...
      auth-enabled = false

to true

    [http]
    ...
      auth-enabled = true

Restart InfluxDB server:

    $ sudo service influxdb restart
    influxdb process was stopped [ OK ]
    Starting the process influxdb [ OK ]
    influxdb process was started [ OK ]

Authenticaton from Web Admin Panel

Now when we are connecting from admin panel, we’ll get error message:

HP_NO_IMG/data/uploads/users/70fed463-d441-452e-bb7e-e0e3fa684498/1382750577.png” alt=”” />

We need to input the username and password and click Save. Unfortunately the web admin panel UI still show the password and doesn’t hide it 🙂

HP_NO_IMG/data/uploads/users/70fed463-d441-452e-bb7e-e0e3fa684498/1094273515.png” alt=”” />

After setting up credential you should be able to do queries from admin panel as usual.

Authentication from HTTP API

After enabling authentication, we will also get error when querying InfluxDB directly via HTTP API if we don’t provide credentials.

    $ curl "http://192.168.33.10:8086/query?q=SHOW+USERS&db=_internal&pretty=true"
    {"error":"unable to parse Basic Auth credentials"}

As we can see above, InfluxDB sent an error reply that it was unable to parse basic auth credentials.

There are two methods that we can use to pass credentials when we are accessing directly via HTTP API.

• Authenticate with Basic Authentication as described in RFC 2617, Section 2 – this is the preferred method for providing user credentials. For example:

    $ curl -G http://192.168.33.10:8086/query -u admin:verysecret --data-urlencode "q=SHOW USERS"
    {"results":[{"series":[{"columns":["user","admin"],"values":[["admin",true],["hostpresto",false]]}]}]}

• Authenticate by providing query parameters in the URL. Set u as the username and p as the password. For example:

    curl -G http://localhost:8086/query --data-urlencode "u=admin" --data-urlencode "p=verysecret" --data-urlencode "q=SHOW USERS"
    {"results":[{"series":[{"columns":["user","admin"],"values":[["admin",true],["hostpresto",false]]}]}]}

Authentication from CLI

When authentication is enabled, and we do not supply correct username and password we wil get error message when sending a query to InfluxDB.

    $ influx
    Visit https://enterprise.influxdata.com to register for updates, InfluxDB server management, and monitoring.
    Connected to http://localhost:8086 version 0.13.0
    InfluxDB shell version: 0.13.0
    > SHOW USERS
    ERR: unable to parse Basic Auth credentials
    Warning: It is possible this error is due to not setting a database.
    Please set a database with the command "use ".

There are two options to authenticate via the CLI.

• Authenticate with auth after starting the CLI.

    $ influx
    Visit https://enterprise.influxdata.com to register for updates, InfluxDB server management, and monitoring.
    Connected to http://localhost:8086 version 0.13.0
    InfluxDB shell version: 0.13.0
    > auth admin verysecret
    > SHOW USERS
    user    admin
    admin   true
    hostpresto  false

• Authenticate by using username and password flags when starting the CLI.

    $ influx -username admin -password verysecret

Creating a Database

We can use this command to create database:

    CREATE DATABASE ""

For example, we’ll create a new database named metrics:

HP_NO_IMG/data/uploads/users/e6aa7e0d-ea1e-4fe3-bc97-bf51bf40fd0e/864631604.png” alt=”” />

Now let’s see list of databases:

HP_NO_IMG/data/uploads/users/e6aa7e0d-ea1e-4fe3-bc97-bf51bf40fd0e/1080018100.png” alt=”” />

The new database that we just created is already listed there.

Inserting Data

InfluxDB is a schemaless database. We don’t have to define the schema first before input the data.

However we cannot mix data types, for example if we already put data for cpu as float, we cannot input another data for cpu as boolean.

Unfortunately the web based admin panel only supports these commands: SELECT, DELETE, SHOW, CREATE, DROP, GRANT, REVOKE, ALTER, SET, KILL.

To insert data we can use either influx CLI tool or using curl to send data directly via HTTP API.

Before we insert data we need to specify which database to be used. Since we already have metrics database we created earlier, we will use that database.

    > USE metrics
    Using database metrics
    > INSERT cpu,host=serverA,region=us_west value=0.50

If you need large amount of data for testing InfluxDB, you can try data sample from InfluxDB.

Querying Data

Now we have data inside our metrics database, let’s query the data from database metrics.

    > SELECT * from cpu
    name: cpu
    ---------
    time      host  region  value
    1466385059333872686 serverA us_west 0.5

Enable https Endpoint

If you want to add additional security for your data when it’s being transmitted from the client to InfluxDB server you can enable https endpoint. You will need :

1. A valid SSL certificate, you can use a certificate signed by known Certificate Authority (CA) or self-signed. If you use self-signed SSL you can either make sure all machine connected to the InfluxDB server have the root certificate that sign the certificate used on InfluxDB or use -unsafeSsl when connecting via CLI so the client will not try to verify the certificate.

2. A domain name for influxDB server that is resolvable from all clients that need to connect to influxDB server.

You can enable https only on the HTTP API endpoint or both HTTP API endpoint and web based admin panel. If you enable https on admin panel you have to also enable https on HTTP API endpoint.

To enable https on both HTTP API and admin panel, you can open /etc/influxdb/influxdb.conf

Find the line :

    [admin]
    ...
      https-enabled = false
    ...

Replace with

    [admin]
    ...
      https-enabled = true

and find the [http] section

    [http]
    ...
      https-enabled = false
    ...

replace with

    [http]
    ...
      https-enabled = true
    ...

You can copy your https certificate to /etc/ssl/influxdb.pem. This certificate should contain both the certificate and private key.

After setting up https you will need to restart the InfluxDB server by running command below:

    $ sudo service influxdb restart

Stats and Diagnostics

There are two commands that can be helpful for administering InfluxDB. The first one is diagnostics that can show us the InfluxDB version in detail. We can run command SHOW DIAGNOSTICS

HP_NO_IMG/data/uploads/users/e6aa7e0d-ea1e-4fe3-bc97-bf51bf40fd0e/1904651150.png” alt=”” />

We can also show current stats of InfluxDB by running the command SHOW STATS

HP_NO_IMG/data/uploads/users/e6aa7e0d-ea1e-4fe3-bc97-bf51bf40fd0e/40679075.png” alt=”” />

Summary

In this tutorial we’ve learned how to install InfluxDB on Ubuntu 14.04 (Trusty Tahr), disable data reporting, change default admin credentials and do basic things with the database like create database, insert data to the database and query the database. Now you’re ready to use InfluxDB whenever you need to store time series data.