Software for the server
Python
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
scripts
.gitignore
.gitmodules
.landscape.yaml
README.md
license.txt
logging.conf
requirements.txt
solserver.config.sample
solserver.py
solserver.sites.sample
solserver_version.py

README.md

Master branch Develop branch
Code Health Code Health

This repo contains the software to run on the solserver. This server:

  • runs a JSON API for managers in the field to report data
  • stores that data in a database
  • runs a web interface for users to see sensor/health data

Installing and Running

  • download a release of this repo as well as a release from the https://github.com/realms-team/sol repo side by side

  • Generate a private key solserver.ppk and associated (self-signed) certification solserver.cert for SSL protection:

    • openssl genrsa -out solserver.ppk 1024
    • openssl req -new -x509 -key solserver.ppk -out solserver.cert -days 1825 (you MUST enter the hostname in the entry "Common Name")
  • place both solserver.ppk and solserver.cert files in the solserver directory

  • copy solserver.cert in the solmanager directory as well

  • make sure InfluxDB is running on your computer

  • double-click/run on solserver.py to start the server

  • periodic database backup can be done using the following line (every hour)

    • 0 * * * * /path/to/influxd backup -database realms /path/to/backup_dir/$(date +\%y.\%m.\%d-\%H)

JSON API documentation

The server offers a JSON API for managers to report data.

The JSON API is available over HTTP, secured using SSL.

Security

Access over HTTPS is REQUIRED (i.e. non-encrypted HTTP access is not allowed). HTTPS ensures that the communication is encrypted. To authenticate, the client connecting to this API MUST provide a token in each JSON API command. This token (a string) is passed as the custom HTTP header X-REALMS-Token.

Before taking any action, the server MUST verify that this token is authorized, and issue a 401 "Unauthorized" HTTP status code with no body.

Compression

The basestation MAY compress the HTTP body before sending it to the server, resulting in reduce bandwidth utilization. When doing so, the basestation MUST use the gzip utility and add the Content-Encoding: gzip HTTP header to the request.

Base URI

The base URI of the JSON API is:

https://<ip address>/api/v1/

Only v1 of the API is defined in this document. Future revisions of this document MIGHT define new API versions.

API endpoints

verifying connectivity

To verify the API is up and running, one can a POST command to the API endpoint:

/echo.json

Any data passed in the payload of body of that request is echoed back untouched

One of the following HTTP status codes is returned:

Code Meaning Action required
200 OK Success. The body contains the same body as the request
401 Unauthorized Invalid X-REALMS-Token passed
500 Internal Server Error Server error. The body MIGHT contain a description.

The body of the reply contains the same contents as the body of the request.

retrieve status

To retrieve the status of the server, issue a GET command to the API endpoint:

/status.json

No HTTP body is required. A HTTP body can be present, but will be ignored.

One of the following HTTP status codes is returned:

Code Meaning Action required
200 OK Request received successfully, snapshot is started.
401 Unauthorized Invalid X-REALMS-Token passed
500 Internal Server Error Server error. The body MIGHT contain a description.

The HTTP reply contains the following body:

{
    "version server":   [1,0,0,0],
    "version Sol":      [1,0,0,0],
    "uptime computer":  "21:01:36 up 21:49,  2 users,  load average: 0.04, 0.08, 0.05",
    "last reboot":      'wtmp begins Wed Aug 12 21:01:33 2015',
    "date":             "Tue, 18 Aug 2015 11:57:56"
    "utc":              1439899076,
    "stats": {
        "NUM_REQ_RX":   1
    },    
}

With:

  • software version is read from the version file of the server Python script.
  • uptime is the output of the uptime Linux command.
  • date is the output of the date Linux command.
  • last reboot is the output of the last reboot Linux command.

reporting data

To report a new set of objects, issue a PUT HTTP request on the API endpoint:

/o.json

With as body the JSON representation of the objects.

One of the following HTTP status codes is returned:

Code Meaning Action required
200 OK Objects received successfully. Thank you.
400 Bad Request Something is wrong with your request. The body MIGHT contain a description.
401 Unauthorized Invalid X-REALMS-Token passed
500 Internal Server Error Server error. The body MIGHT contain a description.

Database

mongoDB, inserting JSON objects to database

Web Interface

TODO