Server installation

Server installation is a two-step process. The first step, as described in the previous section, is to setup a Neo4j DBMS to act as persistence for NOM.

The second step is to download and configure arguments and/or environment variables to the specific environment you want to run NOM in and either install NOM as a service or run it as a console application. Both ways are described below. Running as a service is the recommended way of operating the NOM Server.

Releases of Neo4j enterprise all come bundled with the most current version of NOM at the time of that Neo4j release. Please note that this does not have to be the most current version of NOM. You can find NOM as .zip or .tar.gz inside your Neo4j folder under /products. Alternatively, you can download any version of the NOM Server, including the agent binaries here: Download. In any case, please extract the content from the downloaded .zip or .tar.gz file to whichever directory you want to operate NOM from (in the following referenced as NOM server-folder).

Prerequisites

  • Windows or unix-based operating system

  • Java 17

  • Key pair and certificate (as a PKCS12 file) to be used for TLS protected endpoints (see Self-Signed Certificate Generation for test and demo purposes).

If the certificate is not issued by a public CA, the intermediate certificate or the certificate from CA needs to be added to Java’s trust store using the following command:

keytool -importcert -alias <alias> -file <path/to/cert/file> -cacerts -storepass <trust store password> -trustcacerts -noprompt

In case you have multiple versions of Java installed on the machine you will use for the server, you can set JAVA_HOME environment variable to point to the desired Java home directory.

Pay close attention when entering configuration values that contain special (reserved) characters. Which characters are special (reserved) depends on the operating system and the method of installation.

Running as a service

Linux (systemd)

Setting arguments in service file

Navigate to the NOM server-folder under etc/ where a neo4j-ops-manager-server.service file is located. This file includes a section that needs to be adjusted to your environment (e.g. the Neo4j password you used for setting up the persistence database, the proper path to your ssl key-store file, etc.).

Using environment variables

As an alternative to changing the arguments in the neo4j-ops-manager-server.service file, you can instead use environment variables to achieve the same result. The neo4j-ops-manager-server.service file contains the necessary information for this. The table here contains environment variables and example values.

Installation

Copy neo4j-ops-manager-server.service file into the directory /etc/systemd/system.

Next, execute the following commands to install the NOM Server as a service:

sudo systemctl daemon-reload
sudo systemctl enable neo4j-ops-manager-server

Starting and stopping

Start the NOM Server as a service with the command:

sudo systemctl start neo4j-ops-manager-server

The NOM Server is now ready to use.

To stop the NOM Server, use the command:

sudo systemctl stop neo4j-ops-manager-server

For SELinux

The SELinux context of the server binary must be changed so that it can be executed from the service. To permanently change the SELinux context of the file, run the following commands:

sudo semanage fcontext -a -t bin_t <SERVER_PATH>/bin/server
sudo restorecon -v <SERVER_PATH>/bin/server

<SERVER_PATH> should be replaced with the path to the NOM server-folder.

Windows

Setting arguments in the service file

Navigate to the NOM server-folder under bin\, where a server.xml is located. This file includes an <arguments> section that needs to be adjusted to your environment (e.g. the Neo4j password you used for setting up the persistence database, the proper path to your SSL key-store file, etc.).

Using environment variables

As an alternative to changing the arguments in the server.xml file, you can instead use environment variables to achieve the same result. The server.xml file contains the necessary information for this. The table here contains environment variables and example values.

Installation

You install the server service using server.exe, provided in the NOM server folder under bin\ by running the following command:

server.exe install

Starting and stopping

Once the installation is successfully completed, you can start the NOM Server as a service with the command:

server.exe start

The NOM Server is now ready to use.

To stop the NOM Server, use the command:

server.exe stop

Running as a console application

Although it is possible to run the NOM Server as a console application, it is not recommended. Best practice is to run the NOM Server as a service, as described in the previous section.

Unix

Passing arguments on command line

Navigate to the NOM Server folder and execute the following command:

java -jar ./lib/server.jar
        --spring.neo4j.uri=neo4j://localhost:7687
        --spring.neo4j.authentication.username=neo4j
        --spring.neo4j.authentication.password=password
        --server.port=8080
        --server.ssl.key-store-type=PKCS12
        --server.ssl.key-store=file:./certificates/server.pfx
        --server.ssl.key-store-password=changeit
        --grpc.server.port=9090
        --grpc.server.security.key-store-type=PKCS12
        --grpc.server.security.key-store=file:./certificates/server.pfx
        --grpc.server.security.key-store-password=changeit

Make sure to replace the arguments with values adjusted to your environment (e.g. the Neo4j password you used for setting up the persistence database, the proper path to your ssl key-store file, etc.).

Using environment variables

All the arguments from the command in the last section can also be defined as environment variables as described here.

If you set all the arguments to environment variables, you can shorten the server start command to the following (provided that you have navigated to the NOM Server folder):

java -jar ./lib/server.jar

Windows

Passing arguments on the command line

Navigate to the NOM Server folder and execute the following command:

java -jar .\lib\server.jar
        --spring.neo4j.uri=neo4j://localhost:7687
        --spring.neo4j.authentication.username=neo4j
        --spring.neo4j.authentication.password=password
        --server.port=8080
        --server.ssl.key-store-type=PKCS12
        --server.ssl.key-store=file:.\certificates\server.pfx
        --server.ssl.key-store-password=changeit
        --grpc.server.port=9090
        --grpc.server.security.key-store-type=PKCS12
        --grpc.server.security.key-store=file:.\certificates\server.pfx
        --grpc.server.security.key-store-password=changeit

Make sure to replace the arguments with values adjusted to your environment (e.g. the Neo4j password you used for setting up the persistence database, the proper path to your ssl key-store file, etc.).

Using environment variables

All the arguments from the command in the last section can also be defined as environment variables as described here.

If you set all the arguments to environment variables, you can shorten the server start command to the following (provided that you have navigated to the NOM Server folder):

java -jar .\lib\server.jar

If the NOM Server is required to support self-registered agents, then additional configuration needs to be provided to above commands as mentioned in the configuration reference table. More about agent self-registration here

Server configuration reference

Command line argument Environment variable name Description Example value

spring.neo4j.uri

SPRING_NEO4J_URI

Neo4j URI for NOM persistence DBMS

neo4j://localhost:7687

spring.neo4j.authentication.username

SPRING_NEO4J_AUTHENTICATION_USERNAME

Neo4j user name for NOM persistence DBMS

neo4j

spring.neo4j.authentication.password

SPRING_NEO4J_AUTHENTICATION_PASSWORD

Neo4j password for NOM persistence DBMS

password

server.port

SERVER_PORT

The port that the server will listen on for HTTP traffic

8080

server.ssl.key-store-type

SERVER_SSL_KEY_STORE_TYPE

Type of key store used for HTTP traffic

PKCS12

server.ssl.key-store=file

SERVER_SSL_KEY_STORE

Location of key store used for HTTP traffic

file:./../certificates/server.pfx

server.ssl.key-store-password

SERVER_SSL_KEY_STORE_PASSWORD

Password of key store used for HTTP traffic

changeit

grpc.server.port

GRPC_SERVER_PORT

The port that the server will listen on for GRPC traffic

9090

grpc.server.security.key-store-type

GRPC_SERVER_SECURITY_KEY_STORE_TYPE

Type of key store used for GRPC traffic

PKCS12

grpc.server.security.key-store-file

GRPC_SERVER_SECURITY_KEY_STORE

Location of key store used for GRPC traffic

file:./../certificates/server.pfx

grpc.server.security.key-store-password

GRPC_SERVER_SECURITY_KEY_STORE_PASSWORD

Password of key store used for GRPC traffic

changeit

jwt.secret

JWT_SECRET

Random string used for JWT signing (optional)

please-set-a-random-secret-string-here-for-jwt-signing

optout.crash-analytics

OPTOUT_CRASH_ANALYTICS

Set to true to opt out of product analytics being sent to Neo4j (optional)

false

optout.product-analytics

OPTOUT_PRODUCT_ANALYTICS

Set to true to opt out of crash analytics being sent to Neo4j (optional)

false

grpc.server.security.trustCertCollection

GRPC_SERVER_SECURITY_TRUST_CERT_COLLECTION

File containing list of PEM encoded agent certificates. Required for agent self-registration. (optional)

file:/path/to/agent-certs.pem

grpc.server.security.clientAuth

GRPC_SERVER_SECURITY_CLIENT_AUTH

Option to indicate whether to verify client certificates. Required for agent self-registration. (optional)

OPTIONAL

logging.file.name

LOGGING_FILE_NAME

If set, logs of NOM server will be written to the file designated by this location. If not set, logs will be written to STDOUT. (optional)

/var/log/nom-server.log

logging.level.root

LOGGING_LEVEL_ROOT

Root log level. Default is warn. (optional)

error, warn, info, debug or trace

logging.level.com.neo4j

LOGGING_LEVEL_COM_NEO4J

Log level of the com.neo4j logger (its output corresponds to what NOM server itself logs). Default: info. (optional)

error, warn, info, debug or trace