This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Node Management Agent

The Node Management Agent (NMA) lets you perform operations of your nodes with a REST API. The NMA listens on port 5554 and runs on all nodes.

1: API Docs
2: Custom certificates
3: Endpoints

The Node Management Agent (NMA) lets you administer your cluster with a REST API. The NMA listens on port 5554 and runs on all nodes.

Start the NMA

To start the NMA, run the following on any Vertica node. In addition, if you want to use the recommended vcluster utility to interact with NMA and the HTTPS service, you must run it on all nodes:

$ /opt/vertica/bin/manage_node_agent.sh start node_management_agent

To verify that the NMA is running, you can send a GET request to /v1/health, which returns {"healthy":"true"} if the NMA is running.

When you first start the NMA, Vertica recommends that you perform this verification from inside the cluster. While you can and should still verify that the NMA is reachable from outside the cluster, doing it first from inside the cluster removes possible network and environmental interference:

$ curl https://localhost:5554/v1/health -k

{"healthy":"true"}

To send this and other requests from outside the cluster, see Endpoints.

If the request to /v1/health hangs or otherwise fails, perform the following troubleshooting steps:

Verify that port 5554 is not being used by any other process on the target node.
Verify that the host and port 5554 are accessible by the client.
Open /opt/vertica/log/node_management_agent.log and verify that the endpoint can reach the NMA service.

Stop the NMA

To stop the NMA, send a PUT request to /v1/nma/shutdown:

For simplicity, the following command is run from a Vertica node and specifies paths for certificates generated by the install_vertica script. To send this and other requests from outside the cluster, see Endpoints:

$ curl -X PUT https://localhost:5554/v1/nma/shutdown -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

{"shutdown_error":"Null","shutdown_message":"NMA server stopped","shutdown_scheduled":"NMA server shutdown scheduled"}

1 - API Docs

2 - Custom certificates

The Node Management Agent (NMA) starts with the following certificates by default.

The Node Management Agent (NMA) starts with the following certificates by default. These certificates are automatically generated by the install_vertica script in the /opt/vertica/config/https_certs directory. The certificate authority (CA) certificate is a self-signed certificate, but is safe to use with the NMA in production environments:

vertica_https.key (private key)
vertica_https.pem (certificate)
rootca.pem (CA certificate)

If you want to use custom certificates or cannot run install_vertica, you can specify custom certificates with environment variables. Invalid values for these parameters prevent the NMA from starting, and the failure is logged in /opt/vertica/log/node_management_agent.log.

Each category of environment variable (literal certificate or path) must either be set together with valid parameters or not at all. For example, setting only NMA_ROOTCA and NMA_CERT causes an error. Similarly, setting NMA_ROOTCA_PATH, NMA_CERT_PATH, and NMA_KEY_PATH would also cause an error if NMA_KEY_PATH references an invalid path.

Certificate literals

NMA_ROOTCA: A PEM-encoded root CA certificate or concatenated CA certificates.
NMA_CERT: A PEM-encoded server certificate.
NMA_KEY: A PEM-encoded private key.

Certificate paths

Note

In general, you should use absolute paths for the _PATH environment variables. Relative paths must be relative to the current working directory of the process.

NMA_ROOTCA_PATH: The path to a file containing either a PEM-encoded root CA certificate or concatenated CA certificates.
NMA_CERT_PATH: The path to a PEM-encoded server certificate.
NMA_KEY_PATH: The path to a PEM-encoded private key.

Configuration precedence

The NMA attempts to use the specified certificates in the following order. If all parameters at a given level are unset, the NMA falls through and attempts to use the parameters, if any, at the next level. However, if the parameters at a given level are only partially set or invalid, the NMA does not fall through and instead produces an error:

Environment specifying a literal certificate (NMA_ROOTCA, NMA_CERT, NMA_KEY).
Environment variables specifying the path to a certificate (NMA_ROOTCA_PATH, NMA_CERT_PATH, NMA_KEY_PATH).
/opt/vertica/config/https_certs/tls_path_cache.yaml, which caches the values of the certificate path environment variables. In general, you should not edit this file, but you can delete it to return to Vertica defaults.
The default certificates at the default path: /opt/vertica/config/https_certs.

3 - Endpoints

The Node Management Agent exposes several endpoints for performing various database operations.

The Node Management Agent exposes several endpoints on port 5554 for performing various node operations.

For a static, publicly accessible copy of the documentation for all NMA endpoints, see NMA API Docs. This can be used as a general reference if you don't have access to a local instance of the NMA and its /api-docs/ endpoint.

Prerequisites

For all endpoints other than /api-docs/ and /v1/health, the Node Management Agent (NMA) authenticates users of its API with mutual TLS. The client and Vertica server must each provide the following so that the other party can verify their identity:

Private key
Certificate
Certificate authority (CA) certificate

Server configuration

If you installed Vertica with the install_vertica script, Vertica should already be configured for mutual TLS for NMA. The install_vertica script automatically creates the necessary keys and certificates in /opt/vertica/config/https_certs. These certificates are also used by the HTTPS service.

Note

The CA certificate, rootca.pem, is a self-signed certificate and is safe to use in production with the NMA. If you want to use custom certificates, see Custom certificates.

If you do not have files in /opt/vertica/config/https_certs, run install_vertica --generate-https-certs-only, specifying the hosts of every Vertica node with the --hosts option. This generates the keys and certificates in the /opt/vertica/config/https_certs directory on each of the specified hosts.

For example, for a Vertica cluster with nodes on hosts 192.0.2.100, 192.0.2.101, 192.0.2.102:

$ /opt/vertica/sbin/install_vertica --dba-user dbadmin \
    --dba-group verticadba \
    --hosts '192.0.2.100, 192.0.2.101, 192.0.2.102' \
    --ssh-identity '/home/dbadmin/.ssh/id_rsa' \
    --generate-https-certs-only

Client configuration

Copy the following files from /opt/vertica/config/https_certs to client machines that send requests to NMA:

dbadmin.key (private key)
dbadmin.pem (certificate)
rootca.pem (CA certificate)

You can then use these files when sending requests to the NMA. For example, to send a GET request to the /v1/health endpoint with curl:

$ curl https://localhost:5554/v1/health -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

If you want to use your browser to send requests to NMA, copy the PKCS #12 file dbadmin.p12 to your client machine and import it into your browser. This file packages the private key, certificate, and CA certificate together as one file. The steps for importing PKCS #12 files vary between browsers, so consult your browser's documentation for instructions.

Endpoints

The following are basic, general-purpose endpoints for interacting with your database, as opposed to the advanced endpoints exclusively documented by /api-docs/.

/v1/health (GET)

Send a GET request to /v1/health to verify the status of the NMA. This endpoint does not require authentication. If the NMA is running, /v1/health responds with {"healthy":"true"}:

$ curl https://localhost:5554/v1/health -k

{"healthy":"true"}

In general, /v1/health cannot return {"healthy":"false"}. In cases where NMA is not functioning properly, /v1/health will either hang or clients will fail to connect entirely:

$ curl https://localhost:5554/v1/health -k

curl: (7) Failed connect to localhost:5554; Connection refused

/v1/vertica/version (GET)

Send a GET request to /v1/vertica/version to retrieve the version of Vertica:

$ curl https://localhost:5554/v1/vertica/version -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

{"vertica_version":"Vertica Analytic Database v23.3.0-20230613"}

/v1/nma/shutdown (PUT)

Send a PUT request to /v1/shutdown to shut down the NMA:

$ curl -X PUT https://localhost:5554/v1/nma/shutdown -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

{"shutdown_error":"Null","shutdown_message":"NMA server stopped","shutdown_scheduled":"NMA server shutdown scheduled"}

/v1/vertica-processes/signal-vertica (POST)

Send a POST request to the /v1/vertica-processes/signal-vertica endpoint to send a KILL or TERM signal to the Vertica process. This endpoint takes the following query parameters:

signal_type: Either kill or term (default), the signal to send to the Vertica process.
catalog_path: The path of the catalog for the instance of Vertica to signal. Specify the catalog path when there is more than one database running on a single host, or if the NMA must distinguish between Vertica processes. For example, if there are old or stale Vertica processes on the target node.

To terminate the Vertica process:

$ curl -X POST https://localhost:5554/v1/vertica-processes/signal-vertica -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

{"status": "Signal has been sent to the Vertica process"}

To kill the Vertica process:

$ curl -X POST https://localhost:5554/v1/vertica-processes/signal-vertica?signal_type=kill -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

{"status": "Signal has been sent to the Vertica process"}

To kill the Vertica process with the catalog path /home/dbadmin/VMart/v_vmart_node0001_catalog/:

$ curl -X POST https://localhost:5554/v1/vertica-processes/signal-vertica?signal_type=kill&catalog_path=/home/dbadmin/VMart/v_vmart_node0001_catalog/ -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

{"status": "Signal has been sent to the Vertica process"}

/api-docs/ (GET)

Send a GET request to the /api-docs/ endpoint to get the Swagger UI documentation for all NMA endpoints. This endpoint does not require authentication and serves the documentation in .json, .yaml, and .html formats.

The /api-docs/ endpoint contains documentation for additional endpoints not listed on this page. These extra endpoints should only be used by advanced users and developers to manage and integrate their Vertica database with applications and scripts.

To retrieve the .json-formatted documentation, send a GET request to /api-docs/nma_swagger.json:

$ curl https://localhost:5554/api-docs/nma_swagger.json -k

To retrieve the .yaml-formatted documentation, send a GET request to /api-docs/nma_swagger.yaml:

$ curl https://localhost:5554/api-docs/nma_swagger.yaml -k

To retrieve the .html-formatted documentation, go to https://my_vertica_node:5554/api-docs/ with your web browser.