Self-registering agent
Register 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.
Install agent
The following steps are required to install an agent:
-
Standalone binaries (only linux and windows platform binaries are available)
-
Download: Download
-
If downloading agents is not an option in some environments, NOM agents are also bundled into Neo4j packages which can be used for the installation as described here |
-
Extract the archive:
-
Add the
bin
folder in the extracted directory toPATH
-
To verify the installation, run the following command:
agent version
Which should output:
<agent name> <agent version> <agent revision>
-
Make sure the agent version is equal to that of the NOM server.
-
Configure agent
Registration configuration
Variable | Description | Example |
---|---|---|
|
Server GRPC Address |
server:9090 |
|
Server HTTP address ( Http address should include protocol scheme ) |
https://server:8080 |
The following optional configuration can be used to specify the location for agent config file:
Variable | Description | Example | Default |
---|---|---|---|
|
Peristent path to a file on Neo4j instance host |
"file://path/to/" |
|
Agent config location must be of persistent type. |
Agent meta-data can be optionally specified using these configuration parameters:
Variable | Description | Example |
---|---|---|
|
Optional name for agent to easily differentiate among self-registered agents |
home-db-agent |
|
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. |
Start configuration
The following environment variables specify start configuration for the agent:
Variable | Description | Example |
---|---|---|
|
PEM encoded trusted CA list () |
|
|
Log level (debug,info,warn,error) |
info |
|
Path to the log 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 |
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 |
---|---|---|
|
Name of nth instance |
my-instance-n |
|
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 |
|
Bolt user name for nth instance |
neo4j |
|
Bolt password for nth instance |
password |
To enable the query log collection functionality, there are a few additional environment variables.
If CONFIG_INSTANCE_n_QUERY_LOG_PORT
is not set, the feature is treated as disabled.
The rest of NOM still works.
Variable | Description | Example |
---|---|---|
|
Port for connecting the agent to the Neo4j log4j appender |
9500 |
|
Path to the instance log4j config. If set, appends the appropriate log appender automatically (including the port specified above). |
/var/lib/neo4j/conf/server-logs.xml |
|
Minimum duration in milliseconds for a query to be logged (optional) |
100 |
|
Enable filter for errors under the minimum duration in milliseconds (optional) |
true |
|
Disable the string literal obfuscation in queries (optional) |
true |
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.
Additional configuration for mutual authentication (optional)
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 |
---|---|---|
|
PEM encoded Agent certificate for mutual TLS |
|
|
PEM encoded Agent key for mutual TLS |
|
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. |
Run agent
To run a self-registering agent, an additional command line option is provided as -s
for short and --self-register
.
-
Run an agent in console mode:
All configuration values for the agent should be set as environment variables before starting the agent
-
Command:
agent console -s or agent console --self-register
-
-
Run an agent in service mode:
To run an agent in service means that the agent process runs in the background and monitors the instance and this is the recommended way. The agent lifecycle is handled by the operating system service manager.
-
Install the service for linux (systemd):
-
Run
agent service -s install
-
Execute
systemctl edit neo4j-ops-manager-agent.service
and 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.
-
Start your service
systemctl start neo4j-ops-manager-agent.service
or
systemctl stop neo4j-ops-manager-agent.service
-
Logs are available, using journalctl, via
journalctl -u neo4j-ops-manager-agent
-
-
Install the service for Windows:
-
Run
agent service -s install
-
Open registry editor and navigate to
HKLM\SYSTEM\CurrentControlSet\Services\neo4j-ops-manager-agent
. -
Create a key of type
REG_MULTI_SZ
namedEnvironment
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.
-
Start your service
agent service -s start
-
-
To uninstall the service
agent service -s uninstall
-
Verify agent setup
Ensure agent has contacted NOM server, is online and is reporting DBMS(s) correctly.
-
Return to Agents listing in global settings.
-
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.
-
-
Approve agent if required.
-
An agent in standby mode shows up in the list of agents in NOM UI with
Unauthorized
status.To enable the agent to continue its normal execution, the agent needs to be approved from the NOM UI as shown below:
-
Click on
…
agent action icon and clickApprove Agent
: -
Update agent name or description if desired and click 'Approve':
-
Upon approval, the agent status changes to
Offline
until the agent receives token information and re-connects to NOM server. image::agent-approved-offline.png[width=800] -
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.
-
-
-
If the agent status is not 'Online' then go to where it is running and check the logs.
-
Hover over the newly added agent and click the cog icon to show agent configuration. Check configuration is as expected.
-
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).
-
Select the Alerts tab and make sure that there are no alerts for any of the DBMSs managed by the new agent.
Was this page helpful?