OpenADMS Server is a set of scripts and configuration files to run an HTTP service for time series data, obtained from IoT sensor networks based on OpenADMS Node or 3rd party applications. A REST API is provided for storage and retrieval of sensor data, log messages, and heartbeats. Access the API from your web browser, with command-line tools like cURL or HTTPie, or directly from within your programming language (for instance, by using jQuery or Python Requests).

The OpenADMS Server is based on PostgreSQL and nginx/OpenResty. The following nginx modules are required:

• form-input
• headers-more
• http-realip
• lua
• postgres
• set-misc

Quick Start

The complete documentation is hosted on the project website.

PostgreSQL

Install PostgreSQL 11 or higher. On FreeBSD, run:

# pkg databases/postgresql11-server

Add the service to /etc/rc.conf:

# sysrc postgresql_enable="YES"

Create a new PostgreSQL database cluster:

# service postgresql initdb

Customise the PostgreSQL configuration file /var/db/postgres/data11/postgresql.conf. Set the password encryption to scram-sha-256:

password_encryption = scram-sha-256

Optionally, add another host IP address to listen_address. Change the client authentication in /var/db/postgres/data11/pg_hba.conf. Set the IP address for IPv4/IPv6 connections according to your set-up, for example:

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     trust
# IPv4 local connections:
host    all             all             127.0.0.1/32            scram-sha-256
host    all             all             <your ip>/32            scram-sha-256
# IPv6 local connections:
host    all             all             ::1/128                 scram-sha-256

Start the PostgreSQL server:

# service postgresql start

Set a new password for user postgres. After login, add a new database user (e.g., openadms) and a new database (e.g., timeseries):

# passwd postgres
# su - postgres
$ createuser --no-superuser --createdb --no-createrole --pwprompt <username>
Enter password for new role:
Enter it again:
$ createdb --encoding UTF8 --owner <username> <database>

You may want to create additional roles which have restricted privileges. Create the SQL schema by executing the file psql/openadms.sql from the repository with psql:

$ psql -h localhost -U <username> -d <database> -a -f psql/openadms.sql

The PostgreSQL database is now ready to store time series data. Configure nginx as a front-end.

nginx

Either install nginx or OpenResty with all required 3rd party modules.

Installation on FreeBSD

You can install nginx with most modules already included:

# pkg install www/nginx-full www/lua-resty-core

Or, instead, build nginx from ports:

# cd /usr/local/ports/www/nginx/
# make config

Select at least the following modules:

• HTTP_REALIP
• FORMINPUT
• HEADERS_MORE
• LUA
• POSTGRES
• SET_MISC

Then, build the port:

# make
# make install

Installation on Linux

On Linux, you probably prefer OpenResty. Binary packages are available for most distributions, but do not inluce the requires PostgreSQL module. Therefore, OpenResty has to be build from source.

At first, install all dependencies. On Debian:

$ sudo apt-get install libpcre3-dev libssl-dev perl make build-essential curl postgresql-contrib

On CentOS/RHEL, run instead:

$ sudo dnf install pcre-devel openssl-devel gcc curl postgres-devel

Then, download, unpack, and compile OpenResty:

$ wget https://openresty.org/download/openresty-VERSION.tar.gz
$ tar xfvz openresty-VERSION.tar.gz
$ cd openresty-VERSION/
$ ./configure --prefix=/usr/local/openresty \
              --with-luajit \
              --with-pcre-jit \
              --with-ipv6 \
              --with-http_iconv_module \
              --with-http_realip_module \
              --with-http_postgres_module \
              --j2
$ sudo make -j2
$ sudo make install

OpenResty is installed to /usr/local/openresty/, but you can choose any other path (for instance, /opt/openresty/). For more information, see this tutorial for Ubuntu.

Configuration

Copy the file nginx/nginx.conf and directory nginx/openadms-server from the GitHub repository to /usr/local/etc/nginx/ (FreeBSD) or /etc/nginx/ (Linux) and alter the configuration to your set-up. You have to set at least the name of the user the nginx process is running under, the connection details of your PostgreSQL database, and the actual server name:

user www;   # User to run nginx process under (or "nobody").

http {
    # PostgreSQL connection details. Change "localhost" to the IP address of
    # your database instance, if it is not running on the same host, and enter
    # user name and passwort.
    #
    # dbname:   PostgreSQL database name.
    # user:     PostgreSQL user name.
    # password: PostgreSQL password.
    upstream postgresql {
        postgres_server     localhost dbname=<database> user=<username> password=<password>;
        postgres_keepalive  max=200 overflow=reject;
    }

    server {
        server_name  www.example.com;   # CHANGE TO YOUR SERVER NAME!
    }
}

It is strongly adviced to add an X.509 certificate and change the port to 443. Please see the nginx manual on how to configure HTTPS servers.

The API uses HTTP Basic Auth for access restriction. Clients must send an authorisation header with encoded user name and password. Store login credentials in .htpasswd along your nginx.conf. If you use a different path, change nginx.conf accordingly. You can use security/py-htpasswd to generate the .htpasswd file, or simply run OpenSSL:

$ printf "<username>:$(openssl passwd -crypt <password>)\n" >> .htpasswd

API

Method	Endpoint	Description
GET	/api/v1/	Returns system info.
POST	/api/v1/heartbeats/	Stores heartbeat.
POST	/api/v1/logs/	Stores log message.
GET	/api/v1/logs/<id>/	Returns single log message.
POST	/api/v1/observations/	Stores observation.
GET	/api/v1/observations/<id>/	Returns observation.
GET	/api/v1/projects/	Returns project ids.
GET	/api/v1/projects/<pid>/nodes/	Returns sensor node ids.
GET	/api/v1/projects/<pid>/nodes/<nid>/heartbeat/	Returns last heartbeat.
GET	/api/v1/projects/<pid>/nodes/<nid>/logs/?start=<timestamp>&end=<timestamp>	Returns log messages.
GET	/api/v1/projects/<pid>/nodes/<nid>/sensors/	Returns sensor names.
GET	/api/v1/projects/<pid>/nodes/<nid>/sensors/<sensor>/targets/	Returns target names.
GET	/api/v1/projects/<pid>/nodes/<nid>/sensors/<sensor>/targets/<target>/ids/	Returns observation ids.
GET	/api/v1/projects/<pid>/nodes/<nid>/sensors/<sensor>/targets/<target>/observations/?start=<timestamp>&end=<timestamp>	Returns observations.

Build the Documentation

You can then generate the documentation with Sphinx. Install Sphinx with:

$ python3 -m venv virtual-environment
$ source virtual-environment/bin/activate
$ pip3 install sphinx sphinx_rtd_theme

Make the documentation with:

$ cd docs/
$ gmake clean
$ gmake html

If you are using PyPy3, run:

$ gmake html "SPHINXBUILD=pypy3 -msphinx"

You will find the compiled documentation in ./build/html/.

Licence

BSD-2-Clause.