SAYMON Documentation
Page tree

SAYMON документация

Skip to end of metadata
Go to start of metadata

Server configuration is performed in the file /etc/saymon/saymon-server.conf.

To apply changes the service saymon-server must be restarted:

sudo service saymon-server restart

The following is description of the sections and settings.


Section/Parameter                        Description

Cache

The section contains Redis server settings.

"cache": {
      "host": "127.0.0.1",
      "port": 6379
}
cache.auth_passPassword for access to the Redis server.
cache.host

The Redis server address.

By default "127.0.0.1".

cache.port

The Redis server port.

By default 6379.

cache.cluster

The subsection contains settings which are applied when Redis Cluster is used.

"cache": {
      "cluster": {
        "nodes": [
            {
                "port": 7000,
                "host": "127.0.0.1"
            },
            {
                "port": 7001,
                "host": "127.0.0.1"
            }
        ],
        "options": {}
      }
    }

If this subsection is set, then the system uses connection settings specified here. The parameters cache.host and cache.port are ignored.

cache.cluster.optionsAdditional connection parameters.
cache.cluster.nodes

Servers of the cluster which are needed to be connected to.

cache.cluster.nodes.hostThe address of the server of the cluster. 
cache.cluster.nodes.portThe port of the server of the cluster. 

Custom_scripts

The section contains the settings of the custom scripts, which are executed with object creation or deletion.

"custom_scripts": {
    "entity_triggers_path": "/opt/saymon-extensions/entity-triggers-path"
}
custom_scripts.
entity_triggers_path		The full path to the folder with the files of the scripts.

DB

The section contains the settings for connecting to the database with the object model. MongoDB is used as the database.

"db" : {
	"mongodb": {
		"url": "mongodb://localhost:27017/saymon?w=1"
	}
}

db.mongodb

Data for connecting to MongoDB.

db.mongodb.url

The MongoDB server address and additional сonnection settings.

By default "mongodb://localhost:27017/saymon?w=1".

When using a cluster with several hosts their addresses are specified comma-separated in arbitrary order:

"url": "mongodb://host01:27017,host02:27017,host03:27017/saymon?w=1"

All possible additional URL parameters are presented in MongoDB documentation.

Elasticsearch

The section contains the settings of Elasticsearch.

"elasticsearch": {
   "node": "http://127.0.0.1:9200",
   "auth": {
       "username": "elastic",
       "password": "ypezA1ZoVv46fJh8Abj4"
   },
   "index_pattern": "myindex*",
   "request_timeout": 30000, 
   "hits_per_request": 1000
 }
elasticsearch.hits_per_request

Maximum number of records, which are requested in one query to Elasticsearch.

With increasing the value of this parameter the number of queries to Elasticsearch is decreased. However, memory consumption and time of flow blocking on the Saymon server during answer processing is raised.

By default 1000.

elasticsearch.index_patternElasticsearch index, which the search occurs within.
elasticsearch.nodeIP address of the Elasticsearch instance.
elasticsearch.request_timeout

Waiting time for response from the Elasticsearch server (in milliseconds).

By default 30000 | 30 seconds.

elasticsearch.auth

Elasticsearch user credentials.
elasticsearch.auth.passwordElasticsearch user password.
elasticsearch.auth.usernameElasticsearch user login.

Kafka 

This section contains settings for connection to Kafka broker. 

"kafka" : {
        "host" : "localhost",
        "port" : 9092,
        "requestTimeout" : 30000,
        "fetch_latest" : false,
		"logLevel" : 2
    }
kafka.brokers

Аddress pool to connect while using Kafka Cluster.

"kafka" : {
    ...    
    "brokers": [
		"192.168.1.10:9092",
		"192.168.1.11:9092"
	],
    ...
}

If this parameter is set, the system ignores the kafka.host and kafka.port parameters.

It is necessary to make additional settings in the agent configuration file while using Kafka Cluster.

kafka.fetch_latest

Sets the processing rule for messages which have come to Kafka while the system has been turned off;

    • false | process accumulated data,
    • true | ignore accumulated data.

By default false.

kafka.host

Kafka broker address.

By default "localhost".

kafka.logLevel

Kafka logging level;

0 | NOTHING,
1 | ERROR,
2 | WARN,
4 | INFO,
5 | DEBUG.

By default 2 | WARN.

kafka.port

Kafka broker port.

By default 9092.

kafka.requestTimeout

The client waiting time for answer (in milliseconds).

By default 30000 | 30 seconds.

kafka.ssl

Encryption settings. The key and certificate can be set as the paths to the files:

"kafka" : {
...
    "ssl": {
      "certFile": "/opt/kafka/for-saymon-server/cert.pem",
      "keyFile": "/opt/kafka/for-saymon-server/key.pem"
    },
...
}

kafka.sasl

Authentication settings. The parameters depend on authentication mechanism, which is used in Kafka.

Settings example for the PLAIN/SCRAM mechanism:

"kafka" : {
...
    "sasl": {
      "mechanism": "plain",
      "username": "user",
      "password": "password"
    },
...
}
kafka..sasl.mechanismAuthentication mechanism.

Keycloak

This section contains parameters for interacting with the Keycloak server to authorize users.

"keycloak": {
    "realm_certificate": "<data of keycloak_realm_certificate>",
    "realm_certificate_file": "/etc/saymon/keycloak_realm_certificate",
    "config_file": "/etc/saymon/keycloak_backend.json" 
}

The parameters in the example are listed in descending order of priority when specified simultaneously. To work with Keycloak, it is sufficient to specify one of the parameters.

keycloak.config_file

Path to the configuration file, generated by the Keycloak server for the Backend-client.

keycloak.realm_certificate

Data of the Realm Certificate, with which the Keycloak server signs user tokens.

keycloak.
realm_certificate_file

Path to the file with the data of the Keycloak Realm Certificate.

LDAP 

This section contains parameters of external LDAP server for user authorization.

"ldap" : {
      "url" : "ldaps://192.168.1.1:636",
      "suffix" : "dc=example,dc=com",
      "login" : "cn=admin,dc=example,dc=com",
      "pass" : "root",
      "allow_self_signed" : true,
      "create_user_for_existing_group_only": true,
      "import_non_existing_groups": false,
      "update_existing_groups": false
      }
ldap.allow_self_signed

It enables connection with LDAPs to a server with a self-signed certificate;

    • false | connection is disabled,
    • true | connection is enabled.

By default false | connection is disabled.

ldap.create_user_for_existing_group_only

It restricts authorization of new users with only those users, who have a group on the LDAP server, name of which matches the name of an existing group (previously created) in Saymon:

    • false | authorization is allowed for any new LDAP users,
    • true | authorization is allowed for only the new LDAP users, for whom groups in Saymon are exist.

By default false | authorization of any new LDAP users is allowed.

This parameter does not apply to LDAP users, who already have a Saymon account.

ldap.group_name_attribute

The attribute which contains names of user groups.

It is set when it is necessary to use non-standard attribute.

The standard attribute is "cn".

ldap.import_non_existing_
groups

It allows automatic creation of the groups, which the user belongs to on the LDAP server, but does not exist in Saymon:

    • false | with login of an LDAP user new groups are not created in Saymon,
    • true | with login of an LDAP user all of their groups are created in Saymon, the user is automatically added to the groups.

By default false |  with authorization of an LDAP user new groups are not created in Saymon.

ldap.loginLDAP administrator login.
ldap.login_attribute_name

The attribute which contains users' names to log in the system.

It is set when it is necessary to use not the standard attribute.

The standard attribute is "name".

ldap.passLDAP administrator password.
ldap.suffixThe root element (as a rule it is the organization's domain name).
ldap.update_existing_groups

It allows to convert user groups, created in Saymon, to LDAP groups, if with import of user groups from LDAP the groups' names match:

    • false | with login of LDAP users, groups are not updated,
    • true | with login of an LDAP user, their groups in Saymon, which are matched with their groups in LDAP, are updated to LDAP groups.

By default false | with login of LDAP users, groups are not updated.

ldap.urlLDAP server address. The protocols LDAP and LDAPs are supported.

Monitoring

The section contains the settings of the custom monitoring probes.

"monitoring": {
    "custom_tasks_path": "/opt/saymon-agent/custom_tasks"
}
monitoring.
custom_tasks_path		The full path to the folder with the files of the probes.

MQTT

This section contains settings for connection to MQTT broker.

"mqtt" : {
"broker" : "mqtt://username:password@localhost:1883"
}
mqtt.broker

Broker address and port.

By default "mqtt://localhost:1883"

In order to use authentication by username and password it is necessary to specify credentials before the server address.

OpenTSDB

This section contains access parameters to OpenTSDB.
openTsdb.enabled

Recording historical data to OpenTSDB;

    • false | recording is disabled,
    • true | recording is enabled.

By default true | recording is enabled.

openTsdb.host

Address of the host with OpenTSDB.

By default "localhost".

openTsdb.port

OpenTSDB port.

By default 4242.

openTsdb.timeout

Requests timeout in milliseconds.

By default 15000 | 15 seconds.

Push_notification

This section contains parameters of push notifications in the mobile application. Firebase Cloud Messaging (FCM) is used for work with push notifications.
push_notification.disabled

It disables the notifications;

    • true | notifications are disabled,
    • false | notifications are enabled.

By default true | notifications are disabled.

push_notification.key_path

Path to SAYMON server autorization key on the Firebase server.

By default "/etc/saymon/saymon-mobile-firebase-adminsdk.json".

push_notification.
on_state_change

It enables sending notifications when state changes, in case of another notification source - MQTT messages;

    • true | sending is enabled,
    • false | sending is disabled.

By default true | sending is enabled.

push_notification.timeout

Time after which a notification is sent to each user (in milliseconds).

By default 0 | no delay.

push_notification.url

URL, obtained by user from Firebase, to receive notifications content from the server.

By default "https://saymon-mobile.firebaseio.com".

Resource_server

This section contains parameters bonded with storage files, uploaded to Saymon.
resource_server.debug

It enables debug mode for logging into the file /var/log/saymon/saymon-server.log;

    • false | debug mode is disabled,
    • true | debug mode is enabled.

By default false | debug mode is disabled.

resource_server.
file_storage_dir

Path to the directory for storage documents, added to objects.

By default "/var/saymon/resources".

resource_server.ip_address

Resouce server address.

By default "127.0.0.1".

resource_server.port

Resouce server port.

By default 8092.

Rest_server 

This section contains REST server settings.
rest_server.base_url

Path to API.

By default "/api".

rest_server.colorize_log

It enables colorizing log;

    • false | colorizing is disabled,
    • true | colorizing is enabled.

By default false | colorizing is disabled.

rest_server.debug

It enables debug mode for logging into the file /var/log/saymon/saymon-server.log;

    • false | debug mode is disabled,
    • true | debug mode is enabled.

By default false | debug mode is disabled.

rest_server.
document_download_url

URL to files stored in $document_storage_dir.

By default "http://localhost/node/api/docs".

rest_server.ip_address

Host address to run REST server.

By default "127.0.0.1".

rest_server.
keepAliveTimeout

The server waiting time for the next request before termination the current session (in milliseconds).

By default 5000 | 5 seconds.

rest_server.num_workers

Number of processes to upload data.

By deafult 1.

rest_server.port

REST server port.

By deafult 8090.

rest_server.public_urlAddress for access to the web interface from notifications.
rest_server.session.ttl

Amount of time a user can be inactive before the user's session expires and closes (in milliseconds).

By default 3600000 | 1 hour.

rest_server.snmp_mib_urlAddress of the service for translation numeric SNMP OIDs to the text format.
rest_server.
update_download_url

Path to agent update file.

By deafult "http://localhost/node/api/agents/update".

rest_server.limits

 This subsection contains limits for number of requests to API.

"limits" : [
	{
		"__comment": "unlimited number of requests for the admin user",
		"user": "5048c849d7b6e40593dfee71"
	},
 	{
		"__comment": "unlimited number of requests for the duty shift group",
		"group": "60e591928196105ec9c74636"
	},   
	{
		"__comment": "unlimited requests to States and Classes",
		"uri": ["/states", "/classes"] 
	},
	{
		"__comment": "limit for requests to Objects",
		"uri": ["/objects"],
		"rate": "100/minute"
	},
	{
		"__comment": "limits for users authorized from 127.0.0.1",
		"user": true,
		"ip": '127.0.0.1', 
		"rate": "120/minute"
	},
	{
		"__comment": "limits for unauthorized users",
		"user": false,
		"rate": "10/minute"
	}
]

By default there are no any limits.

For each request the search of rules is implemented from the top down. Only one (first matched) rule is applied.

rest_server.limits.group

The user groups, which the limit is set to;

    • string|string[] | the group ID or the list of the group IDs, which the rule is applied to.

Examples:

"limits": [
	{
		"group": "60e562277936944ebf158282",
		...
	}
]
"limits": [
	{
		"group": [
			"60e562277936944ebf158282",
			"616406e1a3db5948cd815438"
		],
		...
	}
]
rest_server.limits.ip

The IP addresses, which the limit is set for:

    • true | separate limit for each IP address;
    • string/string[] | the IP address or the list of the IP addresses, which the rule is applied for.

Examples:

"limits": [
	{
		"ip": true,
		...
	}
]
"limits": [
	{
		"ip": "127.0.0.1",
		...
	}
]
"limits": [
	{
		"ip": [
			"127.0.0.1",
			"192.168.1.2"
		],
		...
	}
]
rest_server.limits.rate

The number of requests per time unit. If it is not specified, there are no limits.

It is set in the format number_of_requests/time_unit.

Supported time units:

y - year,

Q - quarter,

M - month,

w - week,

d - day,

h - hour,

m/minute - minute,

s - second,

ms - millisecond.

Example:

"limits": [
	{
		"rate": 100/minute,
		...
	}
]
rest_server.limits.uri

The REST methods, which the limit is set to;

    • true | separate limit for each method;
    • string/string[] | the method or the list of the methods, which the rule is applied to.

Any API method can be set without /node/api prefix, e.g. "/time".

Examples:

"limits": [
	{
		"uri": true,
		...
	}
]
"limits": [
	{
		"uri": "/ping",
		...
	}
]
"limits": [
	{
		"uri": [
			"/ping",
			"/node/api/objects/:id/stat"
		],
		...
	}
]
rest_server.limits.user

The users, which the limit is set to;

    • true | separate limit for each authorized user;
    • false | limit by IP address for each authorized user;
    • string/string[] | the user ID or the list of the user IDs, which the rule is applied to.

Examples:

"limits": [
	{
		"user": true,
		...
	}
]
"limits": [
	{
		"user": false,
		...
	}
]
"limits": [
	{
		"user": "6048c849d7b6e40593dfee71",
		...
	}
]
"limits": [
	{
		"user": [
			"57ff6853fa6db3a63d16d07b",
			"6048c849d7b6e40593dfee71"
		],
		...
	}
]

Server

This section contains general server parameters.
server.
agent_registration_parent_id

ID of the object where agents appear in case of the self-registration process.

By default "1".

server.analytics_enabled

It involves analytics of the metric values in the data processing;

    • false | analytics is disabled,
    • true | analytics is enabled.

By default false | analytics is disabled.

server.analytics_processes

The amount of logical cores used to process the times series analytics.

By default all available cores are used.

server.colorize_log

It enables colorizing log;

    • false | colorizing is disabled,
    • true | colorizing is enabled.

By default false | colorizing is disabled.

server.comet_ping_interval

Time interval between sending messages by comet server (in milliseconds).

By default 5000 | 5 seconds.

server.comet_ping_timeout

Waiting time for the message from the comet server (in milliseconds).

By default 12000 | 12 seconds.

server.comet_port

Port for the connection.

By default 8091.

server.comet_secure

It enables SSL connection;

    • false | connection is disabled,
    • true | connection is enabled.

By default false | connection is disabled.

server.
comet_ssl_certificate		Path to the sertificate.
server.comet_ssl_keyPath to the key.
server.conditional_
incidents_enabled

It enables incidents functionality;

    • false | functionality is disabled,
    • true | functionality is enabled.

By default false | functionality is disabled.

server.conditional_
incidents_script

The path to the script which is executed when the incident is occured.

It is used only if the incidents functionality is enabled:
server.conditional_incidents_enabled = true

server.debug

It enables debug mode for logging into the file /var/log/saymon/saymon-server.log;

    • false | debug mode is disabled,
    • true | debug mode is enabled.

By default false | debug mode is disabled.

server.
default_result_timeout

Time after which the condition No data on object is triggered since object creation or obtainig the last data (in milliseconds).

By default 120000 | 2 minutes.

server.default_state_id

Object default state.

By default 7 | "No data".

server.discovery_parent_id

ID of the object to place new network devices, discovered by agents.

By default "1".

server.
event_log_max_bytes

Event Log size at which the data is rotated (in bytes).

By default "1 G" | 1 gigabyte.

server.extension_path

Path to the directory with server extensions.
server.history_temporary_
storage_period

Time period (in milliseconds) during which the data is buffered in Redis and then transferred to OpenTSDB.

This parameter works only if history_update_period is equal to 0.

server.
history_update_period

History data recording period (in milliseconds).

0 - immediate recording incoming values.

By default 60000 | 1 minute.

server.
history_write_length

Limit of the number of points in one request to OpenTSDB. With specifying this parameter the data is written to the database in parts.

This function is useful with exceeding the size of the data which is written at once. The recommended value in this case is 100000.

By default, there is no limit, data is written to OpenTSDB without splitting into parts.

server.
incident_timeout

Transition time of an alarm from the active alarms list to the alarm history list after clearing the alarm.

By default 120000 | 2 minutes.

server.notification_
buffering_period

Time period to hoard all messages about object state changes and send grouped notification to the users (in milliseconds).

By default 0 | buffering is disabled.

server.retain_expired_stat

It enables storage of the latest received data after their obsolescence;

    • false | storage is disabled,
    • true | storage is enabled.

By default false | storage is disabled.

server.
script_trigger_timeout

The maximum execution time of triggers and operations (in milliseconds).

By default 30000 | 30 seconds.

server.self_object_idID of an object, used for self-monitoring.
server.sms_scriptPath to a script for sending SMS notifications.
server.sql_history_enabled

It enables recording history data to MySQL;

    • false | recording is disabled,
    • true | recording is enabled.

By default false | recording is disabled.

server.stat_local_
timestamp_field_name

Name of the field in which the time with which the data must be saved in OpenTSDB is displayed.

By default "LocalTimestamp".

server.stat_scan_period

Validation period of incoming data expiration (in milliseconds).

By default 3000 | 3 seconds.

server.use_stat_timestamp

It saves the timestamp from agent's data;

    • false - the value of the timestamp field from agent's data is replaced with the server's timestamp,
    • true - the value of the timestamp field from agent's data is used, it is not replaced with the server's timestamp.

By default false | the value of the timestamp field from agent's data is replaced with server's timestamp.

server.voice_call_scriptPath to a script for implementing voice calls.

server.email

This subsection contains email-server settings.

"email" : {
	"disabled" : false,
	"fields" : {
		"from" : "saymon@saas.saymon.info"
		},
	"max_json_length": 1000,
	"transport" : {
		"auth" {
			"user" : "saymon@saas.saymon.info",
			"pass" : "P@ssw0rd"
		},
		"host" : "smtp.gmail.com",
	    "port" : 465,
	    "secure" : true
	},
}
server.email.disabled

It disables sending email notifications;

    • true | sending is disabled,
    • false | sending is enabled.

By default true | sending is disabled.

server.email.
max_json_length

Size limit of notification emails (in symbols).

By default 1000 | 1000 symbols.

server.email.fieldsInformation about the sender.
server.email.fields.fromSender's email address
server.email.transportPost server data.
server.email.transport.hostMail server address.
server.email.transport.portMail server port.
server.email.transport.
secure

It enables TLS while connection to the serve;

    • false | using TLS is disabled,
    • true | using TLS is enabled.

Default value depends on the port.

server.email.transport.
service

Service kit, embedded in the connector.

When using it sets host, port, secure automatically.

By default "Gmail".

server.email.transport.authUser's credentials.
server.email.transport.auth.
pass		User's password.
server.email.transport.auth.
user		User's login.

server.user

This subsection contains user settings.

"user" : {
	"auth_enabled": "true",
	"new_user_access": "all",
	"template": {
		"permissions": ["manage-objects", "view-section-stat"],
		"objectPermissions": {
			"include": [],
			"exclude": ["5fb643ddf277b96c8401119b", "5f8dc28407e86603bfe281f8"]
		}
	},
	"usersRoot": "5800d9aaac7bf0f90d3d520e" 
}

server.user.auth_enabled

In enables self-account-creation for users;

    • false | self-account-creation is disabled,
    • true | self-account-creation is enabled.

By default false | self-account-creation is disabled.

server.user.lang_default

User language by default;

    • "en" - English,
    • "it" - Italian,
    • "ru" - Russian.

By default "en" | English.

server.user.
new_user_access

Access rights to objects for a new user;

    • "all" | access to all of the objects,
    • "not" | no access to any object.

By default "all" | access to all of the objects.

server.user.usersRoot

ID of the object used as the root for a newly registered user's new objects.

By default "1".

server.user.template

New user's rights template.

These parameters are applied only for users, who used self-account-creation.

server.user.template.
permissions

A list of permissions given to a newly registered user by default.
server.user.template.
objectPermissions		User rights to access to objects.
server.user.template.
objectPermissions.include		A list of objects' IDs to which a newly registered user is given access by default.
server.user.template.
objectPermissions.exclude		A list of objects' IDs to which a newly registered user is denied access by default.

SNMP 

This section contains settings for processing SNMP traps. 

"snmp": {
	"filter": "/users/admin/tmp/snmp-filter.js"
}
snmp.filter

The path to the file with a filtration function for incoming SNMP traps.

If the function returns false, the message will be discarded.

The function below blocks traps which contain any string from the filters array:

Filtration function example
module.exports = function(message, rawMessage) {
  rawMessage = String(rawMessage);
  // console.log(message, rawMessage);
  let filters = [
    'HLR Call Processing Message',
    'AIR Rejected - No EPS Subscription',
    'GPRS SIBB Processing Exception',
    'AuC Call Processing Message',
    'Received notification from CLIM',
    'AuC Event Log Clean Up',
    'SOFT 0006'
  ];

  return !filters.some((filter) => rawMessage.includes(filter));
}

Next example drops trap with enterpriseOid = '.1.3.6.1.4.1.169.10.1.1' AND genericTrap = 6 AND specificTrap = 5:

Filtration function example
module.exports = function(message, rawMessage) {
  return message.payload.enterpriseOid != '.1.3.6.1.4.1.169.10.1.1' && message.payload.genericTrap != 6 && message.payload.specificTrap != 5 ;
}

Zabbix

The section contains the settings for data import from the Zabbix system.

"zabbix" : [{
    "url" : "http://192.168.1.215/zabbix/api_jsonrpc.php",
    "user" : "saymon",
    "password" : "saymon_user_password",
    "parent_id" : "58b586d5c3a2f96642e25537",
	"debug": true,
 	"polling_period": 30000
}]
zabbix.debug

It enables recording parameters and request results into the log file;

    • false | recording is disabled,
    • true | recording is enabled.

By default false | recording is disabled.

zabbix.parent_id

The ID of the object which is used as the parent for objects imported from Zabbix.

zabbix.password

The password of the user with the access to read the hosts or groups of hosts, the data about which need to be imported.

zabbix.polling_period

Data update period (in milliseconds).

By default 120000 | 2 minutes.

zabbix.url

The address of the api_jsonrpc.php file of the required Zabbix installation.

zabbix.userThe login of the user with the access to read the hosts or groups of hosts, the data about which need to be imported.

zabbix.
request_options

This subsection contains modified options of the requests for hosts, triggers and data.

"request_options": { 
      "hosts": {
            "filter":  {
               ...
            }
      },
      "triggers": { 
            "filter": {
                ...  			
            }
      }, 
      "data": { 
            "filter": {
                ...  			
             }
      }
}
zabbix.request_options.
hosts		Parameters of requests for hosts.
zabbix.request_options.
hosts.filter

Fields of the filter of requests for hosts.

All of the available hosts filters are described in Zabbix API documentation.

zabbix.request_options.
trigers		Parameters of requests for triggers.
zabbix.request_options.
trigers.filter

Fields of the filter of requests for triggers.

All of the available triggers filters are described in Zabbix API documentation.

zabbix.request_options.
data		Parameters of requests for data.
zabbix.request_options.
data.filter

Fields of the filter of requests for data.

All of the available data filters are described in Zabbix API documentation.

  • No labels