Enabling UDP support in InfluxDB for SensorsIot/IOTstack

Enabling UDP support in InfluxDB.md

Tutorial: Enabling UDP support in InfluxDB

Assumptions:

• you are running SensorsIot/IOTstack with InfluxDB as one of the containers
• you want to enable UDP support
• your goal is to log traffic arriving on UDP port 8086 into an InfluxDB database named "udp".

This tutorial is specific to SensorsIot/IOTstack. You're on your own if you "get creative" and choose different ports or database names.

Definitions:

• compose = ~/IOTstack/docker-compose.yml
• the environment means environment variables in either:
  • ~/IOTstack/services/influxdb/influxdb.env; or
  • ~/IOTstack/docker-compose.yml

Step 0 – preamble

I define these aliases in my .profile and I use them in this tutorial.

alias DNET='docker ps --format "table {{.Names}}\t{{.Ports}}"'
alias DPS='docker ps --format "table {{.Names}}\t{{.RunningFor}}\t{{.Status}}"'
alias influx='docker exec -it influxdb influx -precision=rfc3339'

Although both DPS & DNET invoke docker ps, the formatting means the output usually fits without line wrapping. The influx alias is a quick way of getting into the Influx CLI, and also supports additional parameters (eg -database).

Step 1 – confirm that UDP is not enabled

$ DNET

NAMES               PORTS
influxdb            0.0.0.0:2003->2003/tcp, 0.0.0.0:8083->8083/tcp, 0.0.0.0:8086->8086/tcp

Interpretation: Docker is listening on TCP ports 2003, 8083 and 8086, and is routing the traffic to the same ports on the influxdb container. There is no mention of UDP.

Step 2 – create a database to receive the traffic

This tutorial uses the database name of "udp".

$ influx
> create database udp
> exit
> $

Step 3 – define a UDP port mapping

Edit compose to define a UDP port mapping (the second line in the ports grouping below):

  influxdb:
    container_name: influxdb
    image: "influxdb:latest"
    restart: unless-stopped
    ports:
      - "8086:8086"
      - "8086:8086/udp"
      - "8083:8083"
      - "2003:2003"
    env_file:
      - ./services/influxdb/influxdb.env
    volumes:
      - ./volumes/influxdb/data:/var/lib/influxdb
      - ./backups/influxdb/db:/var/lib/influxdb/backup

Step 4 – enable UDP support

Edit the environment to glue it all together:

1. Either by adding these lines to influxdb.env (old menu):

   INFLUXDB_UDP_DATABASE=udp
   INFLUXDB_UDP_ENABLED=true
   INFLUXDB_UDP_BIND_ADDRESS=0.0.0.0:8086
   

2. Or by adding these under the environment: directive in `docker-compose.yml':

   environment:
     - INFLUXDB_UDP_DATABASE=udp
     - INFLUXDB_UDP_ENABLED=true
     - INFLUXDB_UDP_BIND_ADDRESS=0.0.0.0:8086
   

In this context, the IP address "0.0.0.0" means "this host" (analogous to the way "255.255.255.255" means "all hosts").

Step 5 – rebuild the container

$ cd ~/IOTstack
$ docker-compose up -d influxdb

Recreating influxdb ... done

The up causes docker-compose to notice that both compose and the environment have changed, and to rebuild the container with the new settings.

Step 6 – confirm that UDP is enabled

$ DNET

NAMES               PORTS
influxdb            0.0.0.0:2003->2003/tcp, 0.0.0.0:8083->8083/tcp, 0.0.0.0:8086->8086/tcp, 0.0.0.0:8086->8086/udp

Interpretation: In addition to the TCP ports, Docker is now listening on UDP port 8086, and is routing the traffic to the same port on the influxdb container.

Step 7 – check your work

Check the log:

$ docker logs influxdb

If you see a line like this:

ts=2020-09-18T03:09:26.154478Z lvl=info msg="Started listening on UDP" log_id=0PJnqbK0000 service=udp addr=0.0.0.0:8086

then everything is probably working correctly. If you see anything that looks like an error message then you will need to follow your nose.

Step 8 – start sending traffic

Although the how-to is beyond the scope of this tutorial, you will need a process that can send "line format" payloads to InfluxDB using UDP port 8086.

Once that is set up, you can inspect the results like this:

$ influx -database udp
> show measurements

If data is being received, you will get at least one measurement name. An empty list implies no data is being received.

If you get at least one measurement name then you can inspect the data using:

> select * from «measurement»

where «measurement» is one of the names in the show measurements list.