Skip to content

Advanced node usage

Node configuration file

The behaviour of node could be changed by tweaking configurations stored in .env file. Here are described parameters, which could be changed by user:

NODE_ENV="development"

organisation organization

  • possible values: development / production
  • Determine level of logging and some security enforcement

EXTERNAL_PORT=81

  • Port used for API and Docs
  • By default 81

GTW_ID="0000-0000-0000-0000-0000000000" - AGID generated by NM

GTW_PWD="test" - Node password, setted up in NM

WOT_ENABLED="true" - disable/enable WOT integration

WOT_HOST="http://wothive"

  • Address of wothive instance
  • default - http://wothive [local WoT-hive in docker]

WOT_PORT=9000

  • WoT-hive port
  • default - 9000 [local WoT-hive in docker]

ADAPTER_MODE=semantic \ ADAPTER_HOST=http://adapter \ ADAPTER_PORT=3001

  • There are three adapter modes:

    • Dummy - Agent will respond consumption requests with some automated random value. Use for testing.
    • Proxy - Agent will redirect the consumption requests to the host specified with ADAPTER_HOST and _PORT. In future versions we will include adapters developed in AURORAL and how to run them alongside the node.
    • Semantic - Agent will use the URL specified in thing description for feach interaction pattern

  • Use mappings:

    • You can set up the node to enrich your data with the adapters mapping automatically. Default behaviour when using node-red adapter.

    use_mapping=true

Node CLI

The Node client provides a CLI script that allows to install the software in few easy steps. It also provides support to perform some common tasks.

There is script node_cli for simplifying installation. It is asking questions and filling .env file properly. Based on you answers proper components will be activated. If you change your decision later, you can change these settings manually in .env file.

NOTE: Updating .env file manually is for advanced users. Node configuration description.

Useful parameters

There are multiple parameters which are described in scripts help: ./node_cli.sh -h

Update images - Docker will by default download images once. If you want to update images, you can run ./node_cli.sh -u

Reset node - ./node_cli -r will reset all locally saved data (Except back up, see below). Use only if you want to remove or migrate the node. Afterwards it is still needed to remove node in Auroral NM, unless you only plan to migrate the node to a different machine.

Backup and restore

Enables the migration of the node to a different machine or just to keep your data safe in case of docker issues.

See this entry for more info

Interactive mode By default node is started in background (using docker-compose -d). If you want to run it in foreground, you can run node with command ./node_cli -i

**Stop node ** ./node_cli -s stops a node

Regenerating keys ./node_cli -k regenerates public/private key and writes public key to terminal (for inserting to neighbourhood manager)

Node deployment script

For automating deployment process there is python script deployment.py. It is not asking questions like node_cli, but all the settings are defined using command line arguments. This script can be useful especially for automated deployment process, as it does not require any user interaction and also automatically generates and store node's certificates in AURORAL platform.

Automated certificate storing is done through AURORAL external API. For that user needs to provide key and secret through command line arguments.

API-KEYS

API-KEYS are used for authentication and authorization of external applications. They are generated in AURORAL platform and are used for communication with AURORAL platform. For more information see API-KEYS TODO. For generating one user needs to have Infrastructure Operator role in AURORAL platform.

TODO: Add link to API-KEYS feature description

Requirements

  • Python 3.6+

Usage

For help use -h argument: 

usage: deployment.py [-h] [-k [KEYID]] [-s--secret [SECRET]] [-p [PORT]] [-e [{dev,prod}]]
                     [-a [{dummy,custom,helio,nodered}]] [-n [NODE_NAME]] [-S] [-O] [-u]
                     [-d] [-D] [-b] [-r] [-c] [-A] [-v]

Initialisation script for Auroral node

options:
  -h, --help            show this help message and exit
  -k [KEYID], --keyid [KEYID]
                        token for communication with platform
  -s--secret [SECRET]   secret for communication with platform
  -p [PORT], --port [PORT]
                        Port for Agent API (default: 81)
  -e [{dev,prod}], --env [{dev,prod}]
                        Which platform to use (default: dev)
  -a [{dummy,custom,helio,nodered}], --adapter [{dummy,custom,helio,nodered}]
                        ADAPTER mode
  -n [NODE_NAME], --name [NODE_NAME]
                        Your node name (default: hostname)
  -S, --SHACL           Use SHACL validation
  -O, --ODRL            Use ODRL validation
  -u, --unattended      Use unattended mode
  -d, --deleteLocal     Delete node locally
  -D, --deleteRemote    Delete node from platform and locally
  -b, --backupNode      Create tgz backup of node
  -r, --restoreNode     Restores node from backup
  -c, --regenerateCertificates
                        Regenerate certificates for gateway and send them to platform
  -A, --showAgid        Once registered, shows AGID to stdout
  -v, --version         show program's version number and exit

Requests library error

In some installations python3 does not contain requests library. To fix this error you need to install it pip install requests.

Example usage

Creating node with nodered adapter: 

python3 deployment.py -k <API-KEY> -s <API-SECRET> -e dev -a nodered -n myFirstNode -u

Creating node with helio adapter including SHACL validation: 

python3 deployment.py -k <API-KEY> -s <API-SECRET> -e dev -a dummy -n myFirstNode -S -u

Removing node: 

python3 deployment.py -e dev  -u -d

Removing node options

This will remove node from AURORAL platform and locally. If you want to remove node only locally, use -d argument. This option can be used for example when you want to migrate node to different machine.

Backup and restore node: 

python3 deployment.py -e dev  -u -b
This creates tgz file, that can be restored later using -r argument. 
python3 deployment.py -e dev  -u -r

Backup and restore

Since both scripts are creating backups differently, it is not possible to restore node created by node_cli using deployment.py and vice versa.

Node extension

TBD

Use modes

Set up HTTP endpoint and pub DNS

Auroral node does not require opening any ports on the host machine, because it is using xmpp protocol for communication with other nodes. However there is a possibility to use HTTP for retrieving data from the node.

To enable HTTP endpoint, you need to specify publicly available endpoint in the Thing Description href field. Auroral node is checking if provided URL is publicly available and if it is, it will use it for retrieving data.

Requirements:

  • Set up public DNS
  • Expose API to the internet
  • Use public endpoint in Thing Description

If you don't want to expose your endpoint publicly, you can ...

TODO: describe how to validate auth header

Auroral mapping

If you are using this option, you need to responde in auroral mapping format. Automatic mapping is not supported in this mode.

Example of Thing Description with public endpoint

 {
  "@context": [
    "https://www.w3.org/2019/wot/td/v1",
    { 
     "adp": "https://auroral.iot.linkeddata.es/def/adapters#",
     "om": "http://www.ontology-of-units-of-measure.org/resource/om-2/",
     "geo": "http://www.w3.org/2003/01/geo/wgs84_pos#"
    }
  ],
  "security": [
    "nosec_sc"
  ],
  "securityDefinitions": {
    "nosec_sc": {
      "scheme": "nosec"
    }
  },

  "title": "TestDevice",
  "@type": "adp:Thermometer",
  "description": "Room temperature sensor",
  "properties": {
    "room_temperature": {
      "title": "room_temperature",
      "description": "temperature in the room",
      "@type": "adp:AmbientTemperature",
      "unit": "om:degree_Celsius",
      "readOnly": true,
      "type": "number",
      "forms": [
        {
          "op": "readproperty",
          "href": "https://mydomain.com/auroral/api/temperature",
        }
      ]
    }
  }
}

Set up SSL and basic auth

The Node can run without exposing ports to the public internet. However, if you plan to make its APIs accessible online, ensure proper security. We recommend deploying the Node behind a proxy that handles SSL termination and enables Basic Authentication.

Terminate SSL using Nginx

For instructions on how to terminate SSL connections with Nginx, refer to the official Nginx documentation.

Setup Basic Authentication using Nginx

For instructions on how to setup Basic Authentication with Nginx, refer to the official Nginx documentation.