Sender configuration

Audit module is the most important module, it provides user management, licensing and auditing services to the other modules. It automatically recognizes other modules, that are running on the same machine or on different servers - either using multicast or IP white list. Audit module is the main communication channel for the BellaDati IoT console too.

Running module

Sender can be started using the provided starting script, automatically when installed using the installer or manually, by executing following command:

java -Dapplication.name=audit-1 -Dvertx.hazelcast.config=cluster.xml -Dfile.encoding=UTF8 -jar iot-collector-generic-sender-x.y.z.jar -conf config.json

Runtime parameters explained

Parameter name	Description	Example
-Dapplication.name	Mandatory JVM parameter. Defines the name of the sender.	-Dapplication.name=sender-1
-Dvertx.hazelcast.config	Mandatory JVM parameter. Specifies the file containing the cluster configuration.	-Dvertx.hazelcast.config=cluster.xml
-Dfile.encoding	Optional JVM parameter. Specifies the encoding used when working with byte streams or reading messages and files.	-Dfile.encoding=UTF8
-jar	Specifies the collector JAR file to be started.	-jar iot-collector-generic-sender-x.y.z.jar
-conf	Specifies the module configuration file	-conf config.json

Configuration

Configuration is provided in config.json, which is passed to the application as -conf parameter

Options are listed in dot notation - dot is refering to nested enttiy (e.g. senders[].license means { "senders" : [ { "license" : "abcdefgh" } ] }

It is possible to run multiple senders using single JAR - by defining multiple receivers in senders array. See below.

Common options

Option/Entity	Type	Default	Description
senders	Array of objects		Array of senders configuration.
senders[].license	String	empty	License provided by BellaDati
senders[].name	String	empty	Name of the module
senders[].host	String	localhost	HTTP host on which HTTP endpoints are running
senders[].port	Integer	8101	HTTP port on which HTTP endpoints are running
senders[].source	Object		Contains source receiver configuration.
senders[].source.receiver	String		Identification of associated receiver
senders[].source.inputMode	String	SINGLE	Data input mode: SINGLE - message payload contains only single record BULK - message payload contains multiple records Must correspond to the receiver's configuration.
senders[].source.auth	Object		Contains authentication configuration
senders[].source.auth.enabled	Boolean	true	Flag indicating if Basic authentication is configured on receiver
senders[].source.auth.username	String		Username (as defined in receiver's configuration)
senders[].source.auth.password	String		Plain text password (as defined in receiver's configuration)
senders[].bodyLimit	Integer	2097152	Maximum allowed request body size (in bytes)

senders[].exposeEndpointsData	Boolean	true	Flag indicating if endpoints GET /data and DELETE /data should be exposed
senders[].messageRules	Object		Contains message rules configuration.
senders[].messageRules.contentConstraints	Array of objects		Contains array of content constraint definition object
senders[].messageRules.contentConstraints[].name	String		Name of the field
senders[].messageRules.contentConstraints[].required	Boolean	false	Determines whether field value is required
senders[].messageRules.contentConstraints[].type	String	STRING	Type of the field. Available values: STRING, BOOLEAN, INTEGER, FLOAT
senders[].messageRules.contentConstraints[].validate	String		Validation REGEXP
senders[].messageRules.sensorFilter	Array of strings		Array of strings defining whitelist of accepted device IDs.
senders[].db	Object		Contains database configuration. You can keep the default values unless you use some specific database.
senders[].db.url	String	jdbc:hsqldb:file:hsql/instance-db;shutdown=true	Database connection string
senders[].db.user	String	SA	Database username
senders[].db.password	String	empty	Database password
senders[].db.driverclass	String	org.hsqldb.jdbcDriver	Database JDBC driver class
senders[].db.max_pool_size	Integer	100	Database maximum pool size
senders[].db.drop	Boolean	false	Flag indicating if database should be dropped during module startup
senders[].auth	Object		Configuration of administrators common for all modules
senders[].auth.enabled	Boolean	true	Flag indicating if administrator authentication is enabled
senders[].auth.drop	Boolean	false	Flag indicating if administrators should be dropped during module startup
senders[].auth.merge	Boolean	true	Flag indicating if administrators should be merged during module startup
senders[].auth.users	Array		Array of administrators to merge (insert new or update existing)
senders[].auth.users.username	String	admin	Unique username
senders[].auth.users.password	String		Hashed password if 'salt' is defined, otherwise plain text password
senders[].auth.users.salt	String		Salt used to hash password
senders[].auth.users.roles	String array	[ "VIEWER", "EDITOR" ]	Array of user roles

Configuration sample

{
  "instance": {
    "license": "n5NkzaEOALzvGs7LOExyAulYdqo8X+5==",                  
    "name": "Awesome Company - TEST_ENV",                            
    "db": {                                                          
      "url": "jdbc:hsqldb:file:/path/to/instance-db;shutdown=true",  
      "user": "SA",                                                  
      "password": "",                                                
      "driverclass": "org.hsqldb.jdbcDriver",                        
      "max_pool_size": 100,                                           
      "drop": false                                                   
    },
    "auth": {                                                         
      "enabled": true,                                                
      "drop": false,                                                  
      "merge": true,                                                  
      "users": [                                                      
        {
          "username": "admin",                                        
          "password": "DAAF8173380C604B392A1EF8D7559AA0",             
          "salt": "BA1170DE9ADE8D29D2C18FD789EAB3BD",                 
          "roles": [ "ADMIN" ]                                        
        }
      ]
    }
  },
  "audit": {
    "license": "n5NkzaEOALzvGs7LOExyAulYdqo8X+5==",                   
    "name": "Audit 01",                                               
    "host": "localhost",                                              
    "port": 8000,                                                     
    "bodyLimit": 2097152,                                             
    "db": {                                                           
      "url": "jdbc:hsqldb:file:/path/to/my-audit-db;shutdown=true",   
      "user": "SA",                                                   
      "password": "",                                                 
      "driverclass": "org.hsqldb.jdbcDriver",                         
      "max_pool_size": 100,                                           
      "jsonVarcharLength": 2047,                                      
      "drop": false                                                   
    },
    "auth": {
      "enabled": true,                                                
      "drop": false,                                                  
      "merge": true,                                                  
      "users": [                                                      
        {
          "username": "viewer",                                       
          "password": "DAAF8173380C604B392A1EF8D7559AA0",             
          "salt": "BA1170DE9ADE8D29D2C18FD789EAB3BD",                 
          "roles": [ "VIEWER" ]                                       
        }
      ]
    },
    "ssl": {
      "enabled": true,                                                
      "keystorePath": "/path/to/server-keystore.jks",                 
      "keystorePassword": "wibble"                                    
    }
  }
}

Roles

This module supports following roles:

Verticle	Role	Permitted operations
Instance	ADMIN	All operations in all modules
Audit	VIEWER	GET_STATUS, GET_MODULES, GET_SENSORS

Module states

This module can have one of following statuses:

Verticle	Status	Description
Audit	UP	Verticle is up and running. It operates without any specific limitations.
Audit	PAUSED	Verticle is paused but it operates without any specific limitations. Request to "GET /" ends with response code 405.

Audit module API

This module provides following HTTP endpoints:

Path	Method	Description	URL Parameters	Example
/	GET	Returns plain text with ECHO message (should be used in load balancer to detect UP/DOWN status)	-	https://localhost:8000/
/status	GET	Returns JSON object that contains internal state of audit verticle (e.g. total count of sensors)	-	https://localhost:8000/status
/modules	GET	Returns JSON array that contains all modules registered in service discovery infrastructure	-	https://localhost:8000/modules
/sensors	GET	Returns JSON array that contains status of all sensors	- order = "ASC" / "DESC" (default: "ASC") - start = from timestamp (default: 0) - stop = to timestamp - receiver_id = receiver identification - sensor_id = sensor identification - limit = page size (default: 100)	https://localhost:8000/sensors
/pause	GET	Sets status PAUSED for audit verticle immediately. Returns response from "GET /status" endpoint (see above)	-	https://localhost:8000/pause
/resume	GET	Sets status UP for audit verticle immediately. Returns response from "GET /status" endpoint (see above)	-	https://localhost:8000/resume
/logout	GET	Executes logout of currently logged in user	-	https://localhost:8000/logout

On this page

Page tree