co2logserver Python package

This package provides a simple server for logging data.

Documentation

You can find detailed documentation of this package here on on Gitlab.

Local installation

Install this module from the repository root via pip:

# local user library under ~/.local
pip3 install --user .
# also install msgpack support
pip3 install --user '.[msgpack]'
# also install OpenSenseMap support
pip3 install --user '.[opensensemap]'

Running

Development

To run the server in development mode, run after the installation:

python3 -m co2logserver

You might want to add the options -v -t -d.

Production

To run the server in a production environment, use the gunicorn WSGI-server for example:

pip3 install --user gunicon

gunicorn co2logserver

Configuration

You can always specify the path to a configuration file via the CO2LOGSERVER_CONFIG environment variable. See the file co2logserver/config_default.py for default settings.

Data Management

To upload data to the server, you may send POST requests to the /upload path:

New data columns are automatically added to the database. Every column name is converted to lowercase.

Authentication

If you want to control who is allowed to upload data to the server, you may use the PSK (pre-shared-key) salting mechanism built into the server.

Set CO2LOGSERVER_UPLOAD_REQUIRES_AUTH=True and specify one or more PSK salt strings, e.g. CO2LOGSERVER_CHECKSUM_SALTS = ["my-super-secret-psk"].

By default, the server then only accepts requests including at least one header field Content-HASHALGORITHM-Salted containing the hexadecimal hash of the sent payload with the salt appended calculated with HASHALGORITHM (e.g. MD5, SHA1, SHA256, etc...).

For example, if you want to upload the JSON data {"time_utc":[43,23],"co2":[1223,2351]} and your salt string is my-super-secret-psk, your header field Content-MD5-Salted would be b71e91feb2be18ccca019914a1da5b1d which is the MD5-sum of {"time_utc":[43,23],"co2":[1223,2351]}my-super-secret-psk.

This is a simple yet effective way of preventing spam uploads.

Security Note

Note, however, that communication to the server is still unencrypted (only HTTP, not HTTPS). The reason for this is that embedded devices like Arduinos do not have the capabilities for encrypted web traffic. Thus, the sent data including the checksums can theoretically be intercepted and reused to reupload the exact same dataset.

OpenSenseMap upload

Using the sensemapi package, co2logserver is able to redirect uploaded data to the OpenSenseMap. For this to work, an OpenSenseMap account is necessary whose login credentials are set in the co2logserver configuration. The default configuration takes the credentials from the environment variables SENSEMAP_EMAIL, SENSEMAP_USERNAME and SENSEMAP_PASSWORD. Also setting CO2LOGSERVER_OSEM_UPLOAD to True in the configuration enables uploaded data to also be redirected to the OpenSenseMap. The config_default.py contains explanations for further customization options.