Certificate Management

NetXMS uses TLS certificates to secure agent tunnel connections, to authenticate agents, and optionally to authenticate management client users. Server certificates are configured in the server configuration file (netxmsd.conf); there is no certificate management view in the management client.

For the full list of certificate-related configuration file parameters, see Configuration File Reference. For agent tunnel setup, see Agent Tunnels.

Server Certificates

The server uses certificates in two roles:

  • Tunnel certificate — the TLS identity presented to agents connecting via agent tunnels

  • Internal CA certificate — used to sign certificates issued to agents

Both roles can be (and usually are) served by a single certificate.

Automatic Self-Signed Certificates

If no certificate is configured, the server generates a self-signed CA certificate and a server certificate on startup and stores them in the cert subdirectory of the server data directory (ca_cert.pem, ca_key.pem, server_cert.pem, server_key.pem). The generated certificates are valid for 10 years; expiry is checked at server startup, and a certificate with less than 30 days of validity remaining is regenerated at that point (there is no runtime renewal). They are reused on subsequent starts, and agent tunnels work without any manual certificate configuration.

Automatic certificate generation is available starting with version 6.1. On older versions, the tunnel listener does not start until server certificates are configured manually in netxmsd.conf.

Agents do not verify the server certificate by default. To enable verification against an auto-generated certificate, distribute server_cert.pem to agents (TrustedRootCertificate in agent configuration) — the auto-generated server certificate is independently self-signed, not issued by the auto-generated CA, so ca_cert.pem will not validate it. The ServerCertificateFingerprint parameter in the agent’s ServerConnection section additionally pins the expected fingerprint; setting it also turns on full certificate verification, so it complements TrustedRootCertificate rather than replacing it.

Using Your Own Certificates

To use certificates from your own CA, configure the certificate paths in netxmsd.conf:

TrustedCertificate = /opt/netxms/key/rootCA.crt
ServerCertificate = /opt/netxms/key/server.crt
ServerCertificateKey = /opt/netxms/key/server.key
Parameter Description Required

TrustedCertificate

CA certificate or self-signed root certificate. Multiple entries can be added for certificate chains. Used to validate externally issued agent certificates and user login certificates.

Yes

ServerCertificate

Certificate used as tunnel TLS identity and to issue agent certificates. Must allow certificate signing.

Yes

ServerCertificateKey

Private key for the server certificate.

Can be omitted if included in the certificate file

ServerCertificatePassword

Password for the server certificate key.

Only if the key is password-protected

The two certificate roles can be separated using dedicated parameters:

  • Tunnel TLS identity: TunnelCertificate, TunnelCertificateKey, TunnelCertificatePassword

  • Issuing CA: InternalCACertificate, InternalCACertificateKey, InternalCACertificatePassword

ServerCertificate serves as the fallback for both roles: if TunnelCertificate or InternalCACertificate is not set, ServerCertificate is used in its place.

Creating a Self-Signed Certificate Manually

  1. Create private root key: openssl genrsa -out rootCA.key 2048

  2. Create self-signed root certificate: openssl req -x509 -new -key rootCA.key -days 10000 -out rootCA.crt

  3. Create server key: openssl genrsa -out server.key 2048

  4. Create server certificate request: openssl req -new -key server.key -out server.csr -config openssl.conf

  5. Sign server certificate: openssl x509 -req -in server.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out server.crt -days 5000 -extfile openssl.conf -extensions v3_ca

The openssl.conf file must include basicConstraints = CA:TRUE in the extensions to allow certificate signing.

Reissuing Server Certificates

When the server certificate approaches expiration, it can be reissued. To ensure a smooth transition, add the old certificate as a TrustedCertificate entry in netxmsd.conf. Agents with certificates issued by the old server certificate will still be able to connect, while new agent certificates are issued using the new server certificate.

After all agents receive new certificates, the old certificate entries can be removed.

Agent Certificate Authentication

Agents connecting through agent tunnels authenticate with certificates issued by the server. Certificate issuance and renewal are automatic; the only manual step is binding a new tunnel to a node.

Certificate Issuance on Tunnel Bind

  1. The agent connects to the server (TCP port 4703) and appears in Configuration > Agent tunnels as an unbound tunnel

  2. An administrator right-clicks the tunnel and selects Bind to…​ (or Create node and bind…​)

  3. The agent generates a key pair and a certificate signing request

  4. The server signs the request with its internal CA certificate and sends the certificate back; the certificate identifies the node and the tunnel

  5. The tunnel is reset, and the agent reconnects using the issued certificate — from now on, the tunnel is bound to the node automatically

Instead of manual binding, unbound tunnels can be processed automatically — controlled by the AgentTunnels.UnboundTunnelTimeoutAction server configuration variable (reset tunnel, generate event, bind to existing node, or bind and create node), applied after AgentTunnels.UnboundTunnelTimeout seconds. Nodes created automatically are placed into the container named by AgentTunnels.NewNodesContainer. Tunnels can also be bound by source IP address if AgentTunnels.BindByIPAddress is enabled.

Certificate Renewal

Issued certificates are renewed automatically — on tunnel connection and by a daily server task (12:00) — when the certificate is close to expiration or older than the reissue interval.

Server Configuration Variable Default Description

AgentTunnels.Certificates.ValidityPeriod

90

Validity period (days) of certificates issued to agents

AgentTunnels.Certificates.ReissueInterval

30

Age (days) after which an agent certificate is reissued

Certificate expiration for each tunnel is visible in the Certificate expiration column of the Agent Tunnels view.

Manually Provisioned Agent Certificates

Agents can also use certificates issued by an external CA instead of server-issued ones. In this case, certificate renewal is the administrator’s responsibility — the server does not renew externally provisioned certificates.

  1. Issue a certificate for the agent from your CA

  2. Configure the certificate in the agent’s ServerConnection section:

    [ServerConnection/primary]
Hostname = netxms.example.com
Port = 4703
CertificateFile = /etc/nxagentd-cert.pem
Password = keypassword

    On Windows, CertificateId can be used instead of CertificateFile to select a certificate from the system certificate store; the value uses a prefixed selector such as subject:, cn:, name:, email:, org:, template:, or deviceSerial: followed by the value to match.

  3. Add the issuing CA to the server’s trusted certificates (TrustedCertificate in netxmsd.conf)

  4. Configure certificate mapping on the node, so the server knows which node the certificate belongs to: open the node properties, go to Communication > Agent, and set the Certificate mapping method and data

Available mapping methods: Subject, Public key, Common name, and Template ID. The tunnel is matched to the node only when the presented certificate matches by the configured method.

Certificate Files on the Server

There is no certificate store view in the management client. Certificates used by the server live in the file system:

  • Certificates configured in netxmsd.conf (ServerCertificate, TunnelCertificate, InternalCACertificate, TrustedCertificate)

  • Auto-generated certificates in the cert subdirectory of the server data directory

  • Certificate revocation lists configured with the CRL parameter — a local file or an HTTP(S) URL; CRLs are reloaded every 4 hours

To revoke an issued agent certificate, revoke it in your CA and publish the CRL referenced by the CRL parameter, or simply unbind the tunnel and reissue. Runtime certificate-related settings (the AgentTunnels.* variables) are managed in Configuration > Server configuration like any other server configuration variable.

Web Interface HTTPS

The web management console runs on a Java application server (typically Jetty or Tomcat). HTTPS configuration is done at the application server level, not in NetXMS itself.

Using a Reverse Proxy

The recommended approach for production deployments is to use a reverse proxy (nginx, Apache, HAProxy) for TLS termination:

nginx example
server {
    listen 443 ssl;
    server_name netxms.example.com;

    ssl_certificate /etc/ssl/certs/netxms.pem;
    ssl_certificate_key /etc/ssl/private/netxms.key;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Certificate-Based User Authentication

NetXMS supports certificate-based authentication for desktop management client users as an alternative to passwords.

To configure it for a user:

  1. Add the CA that issues user certificates to the server’s trusted certificates (TrustedCertificate in netxmsd.conf)

  2. In Configuration > Users and groups, open the user’s properties

  3. Set the authentication method to Certificate, Certificate or local password, or Certificate or RADIUS password

  4. Select the certificate mapping method — Subject, Public key, Common name, or Template ID — and enter the mapping data

There is no option to import a user’s certificate into the server; the server identifies the user purely by the configured mapping. If the mapping method is Common name and the mapping data is empty, the user’s login name is matched against the certificate common name.

On the login screen, the user selects Certificate authentication and picks a certificate — on Windows from the system certificate store, on other platforms from a PKCS#12 (.p12) file. See User Management for details.

Troubleshooting Certificate Issues

Symptom What to check

Agent tunnels do not work at all; log says tunnel listener cannot start

No server certificate is loaded. On versions before 6.1, configure ServerCertificate/ServerCertificateKey manually. On 6.1 and later, check the server log for certificate auto-generation errors and verify the cert subdirectory of the data directory is writable.

Certificate is not issued on tunnel bind

The internal CA certificate is not usable for signing: verify InternalCACertificate (or the ServerCertificate fallback) includes the private key and allows certificate signing (CA:TRUE).

Manually provisioned agent does not bind to its node

Verify the issuing CA is listed in TrustedCertificate, and that the node’s certificate mapping (Communication > Agent in node properties) matches the certificate by the configured method.

Agent rejects connection when VerifyServerCertificate is enabled

The agent does not trust the server certificate. Add the server’s certificate (for auto-generated setups, server_cert.pem) or its issuing CA to TrustedRootCertificate on the agent. ServerCertificateFingerprint is not a substitute — setting it also requires successful certificate verification.

Issued certificate expired while agent was offline

Renewal happens on tunnel connection and daily; an agent offline longer than the certificate validity must be re-bound manually.

To debug certificate and tunnel problems, raise the crypto.* and agent.tunnel debug tags (see Enabling Debug Logging); certificate handling logs under crypto.cert, which a bare debug crypto does not cover:

debug crypto.* 7
debug agent.tunnel 7