Agent management
Introduction
NetXMS agent is daemon or service that runs on a node to provide additional monitoring options. This is optional for installation, but it’s installation gives following advantages:
Centralized configuration - you can change configuration of agent from management client; if needed, you can even store agent configs on NetXMS server
More secure: communications between NetXMS server and agent can be encrypted, additional authentication on agent can be configured
TCP instead of UDP is used for communications with agent - this can help in case of slow and poor quality links
Remote command execution - agents can be used to execute commands on managed systems as a reaction to certain events
Proxy functionality: agent can be used as a proxy to reach agents on hosts not directly accessible by NetXMS server
SNMP proxy: agent can be used as a proxy to reach remote SNMP devices
SNMP Trap proxy: agent can be used as a proxy to get messages from remote SNMP device
Extensible: you can add new metrics very easy using configuration option like
ExternalMetric
or by writing your own subagentsEasy upgrade - you can upgrade all agents at once from management client
Provides file management possibilities on agent.
Provides log file monitoring functionality.
Agent configuration files
Agent have 3 types of configuration files: master configuration file, additional configuration files and Agent Policy configuration files. Master configuration file is the only mandatory file. Minimal configuration for master configuration file is server address. Address should be set as MasterServers to be able to apply other configuration settings from the server.
After configuration file change agent should be restarted to apply new changes.
Two formats are supported for configuration files and configuration file policies: XML and ‘key = value’ format.
In ‘key = value’ format configuration file can contain one or more parameters in Parameter = Value form, each parameter should be on its own line. Parameters are grouped into sections. Beginning of a section is denoted by section name in square brackets (example: “[sectionName]”). Section named “[Core]” contains parameters for agent itself. It’s the default section, if a configuration file starts from parameter and not from section name, parameters are treated as belonging to “Core” section. Subagents’ parameters should be placed in separate sections named by subagent name. Same section name can be present several times in the configuration file. Comments can be inserted after “#” sign
In XML format general tag should be <config>, second level tags contain section names and third level tags are agent or subagent configuration parameters.
‘key = value’ format example:
[Core]
MasterServers = 10.0.0.4
SubAgent = winperf.nsm
# Below is a configuration for winperf subagent, in separate section
[WinPerf]
EnableDefaultCounters = yes
Same example in XML format:
<config>
<Core>
<MasterServers>10.0.0.4</MasterServers>
<SubAgent>winperf.nsm</Subagent>
</Core>
<!-- Below is a configuration for winperf subagent, in separate section -->
<WinPerf>
<EnableDefaultCounters>yes</EnableDefaultCounters>
</WinPerf>
</config>
Example of configuration sections:
Detailed list of parameters can be found here: Agent configuration file (nxagentd.conf).
The following parameters can be specified in master configuration
file only (and will be ignored if found in other configuration files):
DataDirectory
and ConfigIncludeDir
.
Master configuration file
File nxagentd.conf is a master configuration file for NetXMS agent. Depending on OS there are different locations, where agent tries to find master configuration file.
UNIX-like systems
On UNIX systems master configuration file is searched in the following order:
If
$NETXMS_HOME
environment variable is set:$NETXMS_HOME/etc/nxagentd.conf
'prefix'/etc/nxagentd.conf
. ‘prefix’ is set during build configuration with--prefix='prefix'
parameter. If that parameter was not specified during build,/usr/local
is used.
/Database/etc/nxagentd.conf
/usr/etc/nxagentd.conf
/etc/nxagentd.conf
If configuration file is placed in a different location or named in a different way,
then it’s location and file name can be given to agent with -c
parameter or by
specifying $NXAGENTD_CONFIG
environment variable. In this cause
search in the locations mentioned above is not performed.
Windows
On Windows location of NetXMS config is stored in the registry. Alternatively,
location of configuration file can be provided to agent with -c
command line parameter.
If there is no record in the registry and -c
parameter is not specified, then
agent tries to find configuration files in the following locations:
'installation directory'\etc\nxagentd.conf
C:\nxagentd.conf
Additional configuration files
To increase maintainability, configuration can be stored in multiple additional configuration files located in a specific folder. Additional configuration files override (if a parameter supports only one value) or supplement (if parameter supports multiple values, e.g. list of servers or root folders for filemgr subagent) configuration parameters from master file. Depending on OS there are different locations, where agent tries to find master configuration file.
UNIX-like systems
On UNIX systems it is searched in the following order (search is performed until first existing folder is found):
If
$NETXMS_HOME
environment variable is set:$NETXMS_HOME/etc/nxagentd.conf.d
'prefix'/etc/nxagentd.conf.d
. ‘prefix’ is set during build configuration with--prefix='prefix'
parameter. If that parameter was not specified during build,/usr/local
is used.
/Database/etc/nxagentd.conf.d
/etc/nxagentd.conf.d
/usr/etc/nxagentd.conf.d
A different configuration file folder name can be given by specifying $NXAGENTD_CONFIG_D environment variable. In this cause search in the locations mentioned above is not performed.
Windows
On Windows location of configuration file folder is stored in the registry. If there is no record in the registry, then agent tries to find configuration file folder in the following locations (search is performed until first existing folder is found):
'installation directory'\etc\nxagentd.conf.d
C:\nxagentd.conf.d
Agent policy configuration files
Agent policies allow to store agent configuration on server and deliver it to the agents. More information about Policies can be read there: Agent Policies.
On agent configuration policy files are stored in a separate folder named config_ap under DataDirectory folder. Every policy is saved into a separate file named by policy GUID.
Agent configuration options from server
Edit configuration file remotely
Right click on node, select Edit agent’s configuration file from menu. When closing the editor, a dialog will be presented. New configuration apply is performed on agent restart. So to immediately apply new configuration select Save and Apply. This option will save configuration file and automatically restart the agent. If just Save is selected, then agent should be manually restarted to apply new configuration.
Agent configuration files on server
Agent master configuration files can be stored on server side and requested by agent, if it is launched with -M <serverAddress> command line parameter. Each configuration file on server is stored along with filter script. When server receives configuration request from agent, it goes through available configs and executes filter scripts to find an appropriate configuration.
If appropriate configuration file is found, it is sent to agent and old
nxagentd.conf
file is overwritten (or a new nxagentd.conf
file is created, if
it did not exist). When agent can’t connect to server or server hasn’t found right configuration,
the agent is started with old configuration file. In case if agent configuration file does not
exist and it is not possible to get new one from the server - agent fails to start.
Doesn’t work with tunnel agent connection
Configuration
Each configuration has a name, filter script and the configuration file text.
Name just identifies the configuration.
Filter script is executed on configuration request to define which configuration file to send to the agent. Filter is defined with help of NXSL scripting language. The following parameters are available in the filter script:
$1 - IP address
$2 - platform
$3 - major version number
$4 - minor version number
$5 - release number
Configuration file is the text of returned configuration file.
Agent configuration policy
Another option to store and distribute agent configuration are agent policies. In this case agent configuration is stored on the server side as a policy belonging to template and deployed to the agent when corresponding template is applied to a node. More information about policies and their types can be found in Agent Policies chapter.
Agent Configuration Policies vs. Agent Configuration Files on Server
A short lists of main points to compare both options:
- Agent Configuration Files on Server:
Assignment is based on rules described in filter scripts
When configuration is changed, agent restart is needed to activate new configuration
Config download from server is each time the agent starts (if option ‘-M servername’)
When config is found on server, local Master config is overwritten, if not - existing Master config is used
Works with master configuration file
Does not required initial config (agent can be started without config), but in this case agent would fail if nothing was returned from server
Server provides configuration file without authorization which can be a security issue, if sensitive information is present in configuration file.
Doesn’t work via proxy
Doesn’t work via tunnel agent connection
- Agent Policies:
Not possible for bootstrap agent
After policy is deployed to agent, the agent should be restarted to activate new configuration.
At minimum the server connection parameters must be in master config to be able to start agent
Each policy is saved in a separate configuration file
If policy and master config have same parameter that can be set only once (e.g. LogFile), then policy will overwrite master config configuration
If policy and master config have same parameter that can be set multiple times (e.g. Target for PING subagent or Query for DBQUERY), then policy will merge lists of configs
Can work via proxy
Can work with tunnel agent connection
Agent Policies
Agent policies are additional configuration created by user (agent configuration or files) that are uploaded and updated on agent when template is manually or automatically applied on the node. Agent policies belong to templates, so they are applied to nodes to which a corresponding template is applied.
To create policy, right click a template and select OK. Existing policy can be modified by right-clicking it and selecting from the menu or by double clicking on it.
. Click plus icon to create a new policy, give it a name, choose correct policy type and click- The following policy types are available:
Agent configuration policy
File delivery policy
Log parser policy
User support application policy
Policies are automatically deployed to nodes after creation/modification or when a template is applied to a node. When configuration policy is deleted or template is removed from a node, the policy is automatically undeployed from node.
- Policies get deployed / undeployed:
On node configuration poll.
When list of Agent Policies is closed in the management client. If a node is down at that moment, next attempt will happen on configuration poll.
When template is applied or removed from a node. If a node is down at that moment, next attempt will happen on configuration poll.
Installed policy configurations are stored as additional files under agent DataDirectory. List of applied policies is stored in agent local database.
If agent discovers for a record in local database, that policy file is missing, it will delete the record from database.
When performing deployment, server checks information in agent’s database with it’s database and issues necessary commands.
Agent configuration policy
Agent configuration policy provides option to populate agent configuration with additional parts. Main agent configuration is merged with additional rules from policy. Using policy for configuration file maintenance has advantages that configuration is edited in centralized way and gives granular control on the configuration that each node gets. More information about different agent configuration options can be found in above chapters.
It is possible to use the same parameters and format as in any NetXMS agent configuration file (key=value format or XML format).
Example:
MasterServer=127.0.0.1
SubAgent=netsvc.nsm
SubAgent=dbquery.nsm
SubAgent=filemgr.nsm
[DBQUERY]
Database=id=myDB;driver=mysql.ddr;server=127.0.0.1;login=netxms;password=xxxxx;dbname=netxms
Query=dbquery1:myDB:60:SELECT name FROM images
ConfigurableQuery=dbquery2:myDB:Comment in param :SELECT name FROM images WHERE name like ?
ConfigurableQuery=byID:myDB:Comment in param :SELECT name FROM users WHERE id=?
[filemgr]
RootFolder=/
<config>
<core>
<!-- there can be added comment -->
<MasterServers>127.0.0.1</MasterServers>
<SubAgent>netsvc.nsm</SubAgent>
<SubAgent>dbquery.nsm</SubAgent>
<SubAgent>filemgr.nsm</SubAgent>
</core>
<DBQUERY>
<Database>id=myDB;driver=mysql.ddr;server=127.0.0.1;login=netxms;password=xxxxx;dbname=netxms</Database>
<Query>dbquery1:myDB:60:SELECT name FROM images</Query>
<ConfigurableQuery>dbquery2:myDB:Comment in param :SELECT name FROM images WHERE name like ?</ConfigurableQuery>
<ConfigurableQuery>byID:myDB:Comment in param :SELECT name FROM users WHERE id=?</ConfigurableQuery>
</DBQUERY>
<filemgr>
<RootFolder>/</RootFolder>
</filemgr>
</config>
Example:
Agent should be manually restarted to apply the configuration after the configuration policy is deployed or undeployed to node.
Log parser policy
Information about log parser format and usage available in Log monitoring chapter.
Log parser configuration is applied right after log parser policy is deployed or undeployed to node - no agent restart is required.
File delivery policy
File delivery policy is created to automatically upload files form server to agents.
First root folder or folders should be created - folders with the full path to place where uploaded file and folder structure should be placed. After folder structure is created files can be added to this structure. On policy apply folders will be created if possible and files will be uploaded.
In file and folder names the following macros can be used:
Environment variables as %{ENV_VAR_NAME}
strftime(3C) macros
Text inside ` braces will be executed as a command and first line of output will be taken
Example:
Note
File delivery policy uses File manager to upload files so filemgr subagent should be loaded and root folders should be defined to provide write access to folders.
User support application policy
Agent registration
Two ways of agent-server communication are available. Standard one is when server initializes connection to agent, the second one is when tunnel is used and agent initialize connection to server.
Server to agent connection
- There are few ways to register agent:
To enter it manually by creating a node
Run the network discovery and enter the range of IP addresses.
Register agent on management server
nxagentd -r <addr>
, where <addr> is the IP address of server. To register agents using this optionEnableAgentRegistration
server configuration parameter should be set to 1.
Agent to server connection
This connection requires certificate configuration on server side. More about required actions can be found in Server configuration for Agent to Server connection / Tunnel connection. Server address to which the agent should connect is specified in agent configuration file. There are two options:
ServerConnection parameter
ServerConnection
parameter set in agentd.conf file to server
DNS or server IP address. It’s also possible to specify port number
separated by colon, e.g.:
ServerConnection=monitoring.example.com
ServerConnection=192.168.77.77:1234
ServerConnection section
[ServerConnection]
section is set in agentd.conf. This allows to
specify additional parameters, e.g.:
[ServerConnection]
Hostname=192.168.77.77
Port=4703
CertificateFile=/etc/cert/agent_certificate.crt
ServerCertificateFingerprint=E6:5A:5D:37:22......FC:EF:EA:4B:22
The following parameters are supported in ServerConnection section:
Parameter |
Description |
---|---|
Hostname |
Server DNS or server IP address |
Port |
Port number |
CertificateId |
Id of Certificate in Certificate Store (Windows only). E.g.:
|
CertificateFile |
Agent certificate file. |
Password |
Certificate password |
ServerCertificateFingerprint |
Fingerprint to verify server certificate. Setting this parameter forces verification of server certificate. |
Using CertificateId
or CertificateFile
allows to provide
agent certificate manually, not by auto-generation by NetXMS server.
It is possible to have several ServerConnection
parameters or
sections in the config, in this case agent will establish tunnel connection to
multiple servers.
In addition to ServerConnection
it’s necessary to set
MasterServers
, ControlServers
or Servers
parameter to configure what access rights server has to this agent.
Agent can validate certificate chain, when connecting to server. This is configured in agent configuration file, e.g.:
TrustedRootCertificate=/etc/cert/root_cert.crt
TrustedRootCertificate=/etc/cert/root_certs
VerifyServerCertificate=yes
TrustedRootCertificate
can point to either certificate file or a
folder with certificates. Several TrustedRootCertificate
parameters
can be specified. For Windows system agent loads certificates from Certificate Store.
For non-Windows systems a number of default certificate locations are automatically
loaded by agent:
Path |
OS where this path is used |
---|---|
/etc/ssl/certs |
Ubuntu, Debian, and many other Linux distros |
/usr/local/share/certs |
FreeBSD |
/etc/pki/tls/certs |
Fedora/RHEL |
/etc/openssl/certs |
NetBSD |
/var/ssl/certs |
AIX |
If ServerCertificateFingerprint
is specified for a server, server
certificate is always verified, disregarding the
VerifyServerCertificate
value.
Agent registration on server
Right after agent start it will try to connect to the server. On first connect node will be shown in Agent Tunnels.
- There are few ways to register agent:
To enter it manually by creating a node and then binding tunnel to already created node.
Create node from Agent Tunnels view by selecting one or more tunnels and selecting Create node and bind… menu item.
Debugging
In case of errors enable server debug for “agent.tunnel” and “crypto.cert” to level 4 and agent log debug for “tunnel” and “crypto.cert” to level 4. Check for “SYS_TUNNEL_SETUP_ERROR” events on management node.
Security
Message encryption in server to agent communication
Server encryption policy is configured in Server Configuration view by selecting one of 4 options for DefaultEncryptionPolicy parameter. Default Policy is 2.
Policy types:
0 - Forbid encryption. Will communicate with agents only using unencrypted messages. If agent force encryption (RequireEncryption agent configuration parameter is set to yes), server will not accept connection with this agent.
1 - Allow encryption. Will communicate with agents using unencrypted messages if encryption is not enforced by setting RequireEncryption agent configuration parameter to yes or by selecting Force encryption option in Communication properties of node object.
2 - Encryption preferred. Will communicate with agents using encryption. In case if agent does not support encryption will use unencrypted communication.
3 - Encryption required. Will communicate with agent using encryption. In case if agent does not support encryption will not establish connection.
Security in agent to server connection
Agent to server connection uses TLS protocol to ensure communication security. Server has root certificate, that is used to issue public certificate for agent. Server issues certificate to node when user manually binds tunnel to a node in Agent Tunnels, or node is bind automatically (when AgentTunnels.UnboundTunnelTimeoutAction server configuration parameter is set to Bind tunnel to existing node or Bind tunnel to existing node or create a new node). If required, this process can also be automated by NXShell. More information: NXShell examples, Latest Javadoc.
Server access levels
Depending on how server’s IP address (or domain name) is added to in nxagentd.conf, it will have different access level. It is preferred to use MasterServers. There are 3 levels of access for an agent:
MasterServers - full access.
ControlServers - can read data and execute predefined actions and make screenshots
Servers - read only access. (Is default for tunneled agent connection if other server level is not defined)
In case if server IP is not listed in one of this parameters agent will not enable connection with server in server to agent connection or will set access level to Servers if tunnel connection is used.
Detailed list of functionality available to above mentioned access levels is the following:
Functionality |
MasterServers |
ControlServers |
Servers |
---|---|---|---|
Read metrics, lists and table metrics |
X |
X |
X |
Web service, modbus, SNMP trap, syslog, tftp proxy operation (also requires enabling specific proxy type in agent configuration file) |
X |
X |
X |
Execute actions defined in agent configuration files or configuration policies |
X |
X |
|
Take screenshots |
X |
X |
|
Edit agent main configuration file |
X |
||
Remote agent upgrade |
X |
||
Install software packages |
X |
||
Deploy/undeploy agent policies |
X |
||
File manager – all write operations, e.g. file or folder creation, deletion, etc. (also requires enabling file manager and specifying root folder in agent configuration file) |
X |
||
Sending notifications via user support application |
X |
||
Running commands inside ` braces for File.* metrics and in log file monitoring |
X |
||
Use of File.Content() metric |
X |
||
SNMP.ScanAddressRange() and TCP.ScanAddressRange() lists (also requires EnableProxy = yes in agent configuration file) |
X |
||
Agent, SNMP and TCP proxy operation (also requires enabling specific proxy type in agent configuration file) |
X |
Password encryption
When it is required to write password or Shared Secret in agent configuration file, there is possibility to encrypt it. All passwords can be encrypted with help of nxencpasswd command line tool and added in configuration file in encrypted way.
Subagents
Subagents are used to extend agent functionality. NetXMS subagent are libraries that are loaded by agent. By default all subagents are included in agent build. Subagent may be not included in build only if on time of the build there were no required libraries for subagent build. To enable subagent is require just to add line in main agent configuration file (example: “Subagent=dbquery.nsm”). More about configuration and usage of subagents will be described in monitoring chapters.
Below is list of available NetXMS subagents:
Database Query
File Manager
Ping
Windows Performance
WMI
XEN
Java subagent
This is a special type of subagent, that allows to load Java plugins(subagents written using Java language). Java subagent does not provide any functionality by itself.
There are several configuration parameters that are supported by Java subagent. None of them is mandatory.
Parameter |
Description |
---|---|
Jvm |
Path to JVM. System default is used if not set. |
Classpath |
This parameter is added to java CLASSPATH. |
Plugin |
This parameter defines plugin that should be loaded. Can be used multiple times. |
Configuration example:
MasterServers = netxms.demo
SubAgent=java.nsm
[JAVA]
Jvm = /path/to/jvm
Classpath = /path/to/user/classes
Plugin = bind9.jar
Java plugins
List of available java plugins:
JMX
Bind9
Load of subagent as separate process
Load of subagent as separate process can be used in case it is necessary to load agent and subagent
under different users. It can be done by adding ExternalSubagent
parameter with unique ID that
will represent connection name between agent and subagent. Create second configuration file for this
subagent and add there ExternalMasterAgent
parameter with same ID and run instance of nxagentd
with
this config. Now external subagent will communicate with master agent using Named Pipe. Only master agent will
communicate with server.
Agent Proxy node configuration
In case it is required to monitor nodes behind firewall, it can be configured access to one of subnet nodes and used this node as a proxy node for others.
Proxy node can be set during node creation or in Communications tab of node properties. To configure proxy node select node in object selector NetXMS Agent Proxy.
Agent configuration
To enable NetXMS Agent proxy “EnableProxy” agent configuration parameter should be set to yes.
Agent External Metrics
Other option to define new metric that can be collected from node is to use
ExternalMetric
/ExternalMetricShellExec
, or ExternalList
, or
ExternalMetricProvider
configuration parameters to define a command that
will be executed on a node and it’s output will be provided as a metric. This
functionality provides flexibility to create your own metrics, lists or table
metrics.
New metrics will be visible in the Available metrics list only after agent restart (agent reads its configuration files only once on start) and subsequent configuration poll, so to force it’s appearance run Configuration poll manually after agent restart.
Note
On Windows platforms UTF-8 encoding should be returned in External Metrics.
ExternalMetric/ExternalMetricShellExec
ExternalMetric
defines name of the metric and command that is executed
synchronously when this metric is requested by the server. Parameters from DCI
configuration can be provided, these will be available as $1, $2, $3…, $9
variables. To accept parameters metric name should contain “(*)” symbols after
name. Only first line of command output will be given as a result of execution
(metric’s value).
ExternalMetricShellExec
has same meaning as ExternalMetric
and
behaves identically on non-Windows systems. On Windows systems
ExternalMetric
executes specified command using system process execution
API’s CreateProcess() function. It will search in PATH, but the command should
be with file extension, e.g. command.exe
. ExternalMetricShellExec
will use shell to execute specified command on Windows.
To add multiple metrics, you should use multiple
ExternalMetric
/ExternalMetricShellExec
entries.
As these commands are executed synchronously, long-executing commands may cause
timeout. There are two timeouts - one on the agent side (controlled by
ExternalMetricTimeout
in agent’s configuration file) and generic timeout for
all requests to agent (controlled by AgentCommandTimeout in server’s
configuration file). It’s strongly not recommended to increase server timeout to
more then a few seconds because this may lead to performance issues due to
poller threads spending too much time on timeouts.
ExternalMetricProvider
can be used to handle long-executing commands.
# Example
# Without DCI parameters
ExternalMetric=Name:command
ExternalMetricShellExec=Name:command
# With DCI parameters
ExternalMetric=Name(*):command $1 $2
ExternalMetricShellExec=Name(*):command $1 $2
For each metric configured two agent metrics are provided - one is Name
as
specified in ExternalMetric
/ExternalMetricShellExec
which provides
output of the command (first line only), the other is Name.ExitCode
that
provides exit code of the executed command.
# Real example
ExternalMetric = Test:echo test
ExternalMetric = LineCount(*):cat $1 | wc -l
> nxget localhost Test
test
> nxget localhost 'LineCount(somefile.txt)'
42
> nxget localhost 'LineCount(somefile.txt).ExitCode'
0
ExternalList
ExternalList
defines name of the list metric and command that is executed
synchronously when this metric is requested by server. Parameters from DCI
configuration can be provided, these will be available as $1, $2, $3…, $9
variables. To accept parameters metric name should contain “(*)” symbols after
name. Lines of the list are separated by new line character.
# Example
# Without DCI parameters
ExternalList=Name:command
# With DCI parameters
ExternalList=Name(*):command $1 $2
ExternalMetricProvider
ExternalMetricProvider
defines command (script) and execution interval in
seconds. Defined script will be executed regularly and agent will cache list of
metrics along with their values. When server will request one of provided
metrics, it’s value will be read from the agent cache. Main purpose is to
provide data from long-running processes, or retrieve multiple values by running
a command only once.
Timeout in milliseconds for command execution is defined by ExternalMetricProviderTimeout parameter in agent configuration file.
Script should print one or more “Metric=Value” pairs to standard output. Multiple pairs should be separated by new line. If metric takes a parameter, it should be included in “Metric(…)”.
Example of the script:
#!/bin/sh
echo 'Metric1=Value1'
echo 'Metric2=Value2'
echo 'MetricWithParams(parameter)=Value3'
echo 'MetricWithParams(another_parameter)=Value4'
Example of agent configuration:
#Example
ExternalMetricProvider=PATH_TO_PROVIDER_SCRIPT:EXECUTION_INTERVAL_IN_SECONDS
#Example (run /tmp/test.sh every 5 seconds)
ExternalMetricProvider=/tmp/test.sh:5
ExternalTable
ExternalTable
defines table that is provided by agent and how it can be
obtained. Table can be collected synchronously when requested by the server or
regularly in the background (in this case server gets cached data). Second
option is useful when command for table creation is taking a long time to avoid
timeout. To collect table in the background “PollingInterval” configuration
option is required.
Timeout in milliseconds for background operation is defined by ExternalMetricProviderTimeout parameter in agent configuration file.
Each table line is separated with new line symbol. First line in returned text
should contain name of columns, subsequent lines contain table data. Parameters
from DCI configuration can be provided, these will be available like $1, $2,
$3…, $9 variables. To accept parameters metric name should contain (*)
symbols after name.
Name |
Required |
Description |
---|---|---|
Command |
Yes |
Result of this command execution will be used as a value for table DCI. First row is used as column names. |
Separator |
No |
Symbol that will be used as a separator for columns. If separator is not
specified, default value of
|
InstanceColumns |
No |
Comma separated instance column list.
|
Description |
No |
Table DCI description that will be shown in table DCI selector. |
PollingInterval |
No |
Interval that is used to poll table in the background. Table will be collected synchronously (per request) if this parameter is omitted. |
ColumnType |
No |
Data type of the column. Is set in format columnName:dataTypeName. If column does not have type int32 is used by default.
|
# Example
# Simple example
[ExternalTable/test]
Command = echo 'col1;col2;col3\na;b;c'
Separator = ;
# Without DCI parameters
[ExternalTable/dciName]
Command = command
Separator = ;
InstanceColumns = columnName,columnName2
Description = description
PollingInterval = 60
ColumnType = columnName:string
ColumnType = columnName3:string
# With DCI parameters
[ExternalTable/dciName(*)]
Command = cat /folder/with/my/files/$1
# Old configuration format
ExternalTable=dciName::command
ExternalTable=dciName:instanceColumns=columnName;description=description;separator=|:command
ExternalTable=dciName(*):instanceColumns=columnName;description=description;separator=|:command $1 $2
#Old configuration format with background polling
ExternalTable=dciName:instanceColumns=columnName;description=description;separator=|:command;backgroundPolling=yes;pollingInterval=60
Note
backgroundPolling
configuration should be set to true
or yes
in order to use polling interval with old configuration format.
Agent Actions
For security reasons actions that can be executed on agent first are defined in agent configuration file and only then can be used by users. This excludes that an unauthorized user can access system data through an arbitrary entered command. Only users with access to the agent configuration file editing can define executed commands.
There are 2 options to define action:
Action - usual action definition. On Windows platform system process execution API’s CreateProcess() is used to run the command, it will search in PATH, but the command should be with file extension, e.g.
command.exe
.ActionShellExec - Same as Action, but on the Windows platform agent will use shell to execute command instead of normal process creation. There is no difference between Action and ActionShellExec on UNIX platforms.
Both versions accept parameters that will be available like $1
, $2
, $3
…, $9
variables.
After action is defined it can be used in the object tools - agent action or in actions - action execution on remote node. Action should be defined in main section of agent configuration file.
# Example
Action=Name:command
Action=Name:command $1 $2
Action=cleanLogs:rm /opt/netxms/log/*
Action=ping:ping $1
ActionShellExec=listFiles:dir $1