Self-registering agent

Agent self-registration omits manually acquiring token information from NOM UI as described in Manually registering agent. Instead, minimal configuration of the NOM server is provided to allow the agent to connect and register itself. Authorization is granted either through manual approval of the agent in the UI or through mutual authentication.

A self-registering agent is useful in an automated environment such as a Kubernetes cluster of Neo4j instances where instances are dynamically created and managed.

Run agent

To run a self-registering agent, an additional command line option is provided as -s for short and --self-register.

Running as a service

To run an agent in service mode means that the agent process runs in the background and monitors the instance. The agent lifecycle is handled by the operating system service manager. Best practice is to run an agent in service mode.

Linux (systemd)

Service installation

agent service -s install

Setting arguments

Run the following to edit the service:

systemctl edit neo4j-ops-manager-agent.service

Set environment variables by either setting Environment or EnvironmentFile options. For example, using the Environment options, the override file can look like this:

[Service]
Environment="CONFIG_SERVER_GRPC_ADDRESS=<server grpc address>"
Environment="CONFIG_SERVER_HTTP_ADDRESS=<server http address>"
Environment="CONFIG_TLS_TRUSTED_CERTS=</path/to/trusted/certs/pem/file>"
Environment="CONFIG_LOG_FILE=</path/to/nom-agent/log.txt>"
Environment="CONFIG_INSTANCE_1_NAME=<instance name>"
Environment="CONFIG_INSTANCE_1_BOLT_URI=<bolt uri of the local instance>"
Environment="CONFIG_INSTANCE_1_BOLT_USERNAME=<local instance user name>"
Environment="CONFIG_INSTANCE_1_BOLT_PASSWORD=<local instance password>"
Environment="CONFIG_INSTANCE_1_QUERY_LOG_PORT=<an available port>"
Environment="CONFIG_INSTANCE_1_LOG_CONFIG_PATH=<path to server-logs.xml>"

Please refer to the full list of options here.

Starting and stopping

To start the service:

systemctl start neo4j-ops-manager-agent.service

To stop the service:

systemctl stop neo4j-ops-manager-agent.service

Logs are available, using journalctl, via

journalctl -u neo4j-ops-manager-agent

Windows

Service installation

agent service -s install

Setting arguments

  • Open registry editor and navigate to HKLM\SYSTEM\CurrentControlSet\Services\neo4j-ops-manager-agent.

  • Create a key of type REG_MULTI_SZ named Environment and add your environment variables, each on a separate line, for example:

    CONFIG_SERVER_GRPC_ADDRESS=<server grpc address>
CONFIG_SERVER_HTTP_ADDRESS=<server http address>
CONFIG_TLS_TRUSTED_CERTS=</path/to/the/trusted/certs/pem>
CONFIG_LOG_FILE=</path/to/nom-agent/log.txt>
CONFIG_INSTANCE_1_NAME=<instance name>
CONFIG_INSTANCE_1_BOLT_URI=<bolt uri of the local instance>
CONFIG_INSTANCE_1_BOLT_USERNAME=<local instance user name>
CONFIG_INSTANCE_1_BOLT_PASSWORD=<local instance password>
CONFIG_INSTANCE_1_QUERY_LOG_PORT=<an available port>
CONFIG_INSTANCE_1_LOG_CONFIG_PATH=<path to server-logs.xml>

Please refer to the full list of options here.

Starting and stopping

To start the service:

agent service -s start

To uninstall the service:

agent service -s uninstall

Running as a console application

All configuration values for the agent should be set as environment variables before starting the agent.

agent console -s

or

agent console --self-register

Verify agent setup

Ensure agent has contacted NOM server, is online and is reporting DBMS(s) correctly.

  1. Return to Agents listing in global settings.

    agents

  2. Find self-registered agent in list.

    • If the agent is not in the list then go back to where the agent is running and check the logs. It may be that the server address is configured incorrectly or the TLS certificates are not correctly specified.

  3. Approve agent if required.

    • An agent in standby mode shows up in the list of agents in NOM UI with Unauthorized status.

      agent unauthorized

      To enable the agent to continue its normal execution, the agent needs to be approved from the NOM UI as shown below:

      1. Click on …​ agent action icon and click Approve Agent:

        agent action menu

      2. Update agent name or description if desired and click 'Approve':

        agent approve

      3. Upon approval, the agent status changes to Offline until the agent receives token information and re-connects to NOM server.

        agent approved offline

      4. Wait for agent status to change to Online indicating that the agent has successfully re-connected to the NOM server and is in normal execution mode. This can take a few minutes.

        agent approved online

  4. If the agent status is not 'Online' then go to where it is running and check the logs.

  5. Hover over the newly added agent and select "View Configuration" from the menu on the right to show agent configuration. Check configuration is as expected.

  6. Navigate to the home page (if this agent is the first to manage an instance in a DBMS, it may take a few minutes for the DBMS to appear).

  7. Select the Alerts tab and make sure that there are no alerts for any of the DBMSs managed by the new agent.

Agent configuration reference

Registration configuration

Variable Description Example

CONFIG_SERVER_GRPC_ADDRESS

Server GRPC Address

server:9090

CONFIG_SERVER_HTTP_ADDRESS

Server HTTP address ( should include protocol scheme )

https://server:8080

CONFIG_TLS_TRUSTED_CERTS

PEM encoded trusted CA list ()

/path/to/a/pem/file

Since agent-server communication needs to be encrypted, you need to configure the agent so that it trusts the server’s certificates. The file that contains the trusted certificate list (PEM encoded) can be specified through the CONFIG_TLS_TRUSTED_CERTS environment variable. Most operating systems default to the system-wide trusted certificates, but this is not the case on Windows. For this reason, you must set this environment variable on Windows.

The following optional configuration can be used to specify the location for agent config file:

Variable Description Example Default

CONFIG_AGENT_CONFIG_PATH

Persistent path to a file on Neo4j instance host

"file://path/to/"

NEO4J_CONF if set or conf folder under NEO4J_HOME if set, else .nom folder in user home directory.
Agent config location must be of persistent type.

Agent meta-data can be optionally specified using these configuration parameters:

Variable Description Example

CONFIG_AGENT_NAME

Optional name for agent to easily differentiate among self-registered agents

home-db-agent

CONFIG_AGENT_DESCRIPTION

Optional description for agent to easily differentiate among self-registered agents

An agent to monitor home db

It’s recommended to set agent name and description if multiple agents are being self-registered on similar hosts as it would lead to confusion with similarly named agents appearing in UI for approval.

Additional configuration for mutual authentication (optional)

With only the above configuration, the agent will connect to NOM server, register itself and then enter Standby mode.

Standby mode is the runtime state of a self-registering agent which is not authorized yet to monitor instances. In this mode agent keeps checking with NOM server for approval status at every preset time interval (default 30 seconds).

The agent exits Standby mode once it has been manually approved in the UI.

Mutual authentication eliminates the manual approval step. The NOM server immediately authorizes an agent that registers using a trusted certificate.

The following configuration is required to enable mutual authentication:

Variable Description Example

CONFIG_TLS_CLIENT_CERT

PEM encoded Agent certificate for mutual TLS

/path/to/a/pem/file

CONFIG_TLS_CLIENT_KEY

PEM encoded Agent key for mutual TLS

/path/to/a/pem/file

In addition to the above configuration, the NOM server also needs to be configured to trust the agent certificates as described here.

Self-signed certificates for agents in test and demo environments can be generated as documented here.

Agent logging configuration

The following environment variables specify start configuration for the agent:

Variable Description Example

CONFIG_LOG_LEVEL

Log level (debug,info,warn,error)

info

CONFIG_LOG_FILE

Path to the log file

/var/log/nom-agent/log.txt

Monitored instance configuration

For each managed DBMS instance on the host, the following environment variables need to be set to allow the agent to access the instance:

Variable Description Example

CONFIG_INSTANCE_n_NAME

Name of nth instance

my-instance-n

CONFIG_INSTANCE_n_BOLT_URI

Bolt URI for nth instance with bolt or bolt+s protocol

bolt://localhost:7687 or bolt+s://localhost:7687 or bolt+ssc://localhost:7687, depending on the local database setup

CONFIG_INSTANCE_n_BOLT_USERNAME

Bolt user name for nth instance

neo4j

CONFIG_INSTANCE_n_BOLT_PASSWORD

Bolt password for nth instance

password

Query log collection configuration

Variable Description Example

CONFIG_INSTANCE_n_QUERY_LOG_PORT

Port for connecting the agent to the Neo4j log4j appender. If not set, the query log collection feature is treated as disabled.

9500

CONFIG_INSTANCE_n_LOG_CONFIG_PATH

Path to the instance log4j config file. If set, appends the appropriate log appender automatically (including the port specified above).

/var/lib/neo4j/conf/server-logs.xml

CONFIG_INSTANCE_n_QUERY_LOG_MIN_DURATION

Minimum duration in milliseconds for a query to be logged (optional)

100

CONFIG_INSTANCE_n_QUERY_LOG_MIN_DURATION_FILTER_ERRORS

Enable filter for errors under the minimum duration in milliseconds (optional)

true

CONFIG_INSTANCE_n_QUERY_LOG_DISABLE_OBFUSCATION

Disable the string literal obfuscation in queries (optional)

true

CONFIG_INSTANCE_n_QUERY_LOG_INCLUDE_AGENT

Collect and show queries coming from the NOM agent (optional)

true

Environment variable considerations:

  • n in the above environment variables needs to be replaced with 1, 2, etc. for each of the monitored DBMS instances on the same host. For example, for a single monitored DBMS, the environment variables must be named as CONFIG_INSTANCE_1_NAME, CONFIG_INSTANCE_1_BOLT_URI, CONFIG_INSTANCE_1_BOLT_USERNAME and CONFIG_INSTANCE_1_BOLT_PASSWORD.

  • The instance name that you specify for CONFIG_INSTANCE_n_NAME will be used to identify your instance on NOM. For this reason, it is important that you specify unique names across your cluster.

Agents are supposed to monitor only local instances and should not be configured to connect to remote instances.

Refer to Neo4j instance requirements to ensure that all instances meet the requirements to be managed by NOM.