Once you have configured the Leader for encrypted TLS communication, you can implement client certificate exchange to enable mutual authentication (mTLS). This allows Cribl Edge to permit only explicitly authorized clients, which hold valid certificates, to connect to the Leader.

When a client certificate is presented to a Leader, two things happen:

1. The Leader validates the client certificate presented to Cribl Edge. The Validate Client Certs setting is optional, but highly recommended. When enabled, the Leader checks the certificate against the trust store, to see if it has been signed by a valid certificate authority (CA).

The Leader checks the list of certificates in the CA Certificates Path box first (if populated), then against the list of built-in system certificates.

2. The Leader checks whether the Common Name (CN) matches the regular expression in the configuration. Cribl Edge’s default is to accept any value in the Common Name field. You can customize this as needed.

Within the Common Name, we validate against the value after the CN=string. If your Common Name is CN=logstream.worker, you would enter logstream\.worker in the Common Name field - including the backslash, because the value entered is a regular expression.

The Cribl.Cloud Leader connections on port 4200/tcp do not currently support mutual TLS (mTLS).

Certificate Requirements for mTLS

​

mTLS provides a significantly higher security posture by requiring both the server and the client to prove their identities. For this handshake to succeed, Cribl Edge relies on the underlying TLS stack to validate the integrity and purpose of each certificate.

Before enabling mTLS, verify that your certificate infrastructure meets the standards outlined below. If a certificate is expired, uses a legacy algorithm, or cannot be traced back to a trusted root, the TLS connection will be rejected immediately to prevent unauthorized access.

General Certificate Standards

​

Regardless of their role in the handshake, all certificates used by the Leader, Worker/Edge Nodes, and Sources/Destinations must adhere to these baseline criteria:

• Validity Period: Certificates must be current. TLS handshakes will fail if the system time is outside the NotBefore or NotAfter window.
• Modern Cryptography: Use certificates signed with modern algorithms (such as RSA or ECDSA). Avoid legacy or deprecated hash functions like MD4, MD5, or SHA-1, which are often blocked by TLS.
• Chain of Trust: The peer validating the certificate must be able to build a complete path from the end-entity certificate through any Intermediate CAs to a trusted root. In Cribl Edge, this trust is established via the CA Certificates Path configuration or the host system trust store.

Server-Specific Requirements

​

Server certificates are presented by components that terminate TLS (such as the Leader on its management port). These certificates must prove they are authorized to act as a “server” to the connecting client:

• Key usage: The certificate Extended Key Usage (EKU) must include serverAuth.
• Hostname Verification: To prevent man-in-the-middle attacks, the Common Name (CN) or Subject Alternative Name (SAN) must exactly match the hostname or IP address that clients use to connect (for example, leader.cribl.com).

Client-Specific Requirements

​

Client certificates are presented by the component initiating the connection (such as a Worker/Edge Node connecting to a Leader). These are subject to stricter identity checks:

• Client Authentication: The certificate EKU must explicitly include clientAuth. Public CAs (such as Let’s Encrypt) have increasingly disallowed this attribute in their standard issuance policies to comply with stricter industry root program requirements. For mTLS, you will likely need to use an internal PKI or a specialized certificate product that permits client-side usage.
• Identity Constraints: Client certificates must be leaf certificates (where Basic Constraints are set to CA=false). Root or Intermediate CA certificates should never be used as client identifiers.
• CN Regex Matching: Cribl Edge provides an additional layer of security by checking the certificate CN against a user-defined regular expression to ensure only specific named clients are permitted.

Limitations on mTLS Authentication

​

When configuring mTLS authentication on Edge Nodes, make sure you place your certificates into a separate directory outside of $CRIBL_HOME. If you place the certificates inside $CRIBL_HOME, they’ll be removed when the next config bundle is deployed from the Leader.

Similarly, you can’t bootstrap Edge Nodes with mutual authentication already populated. To bootstrap Edge Nodes, you supply only the shared authentication token. Certificates should be viewed as two-factor authentication; so placing the certificates in the config bundle defeats the purpose of two-factor authentication.

Configure via the UI

​

mTLS authentication in Cribl.Cloud is configured separately for each Source.

Below is a sample configuration on the Leader:

In the above configuration, note:

• You can set both the Minimum TLS version and Maximum TLS version.

• The Common Name regex contains an additional check for \d+. This allows checking for the format: logstream1.worker, logstream2.worker, logstream3.worker, etc.

Using YAML Config File

​

To set up mTLS authentication via the Edge Node’s instance.yml config file, you need to change some values and also add a few keys, as shown in this example:

distributed:
  mode: managed-edge
  master:
    host: <hostname>
    port: 4200
    authToken: <token>
    tls:
      disabled: false
      rejectUnauthorized: true # false if ignoring untrusted certs
      requestCert: true
      privKeyPath: /path/to/certs/worker.key
      certPath: /path/to/certs/worker.pem
      caPath: /path/to/certs/root.pem
    resiliency: none
  group: default_fleet     

Using Environment Variables

​

You can set up mTLS authentication by configuring this environment variable, using the format shown in this example:

CRIBL_DIST_LEADER_URL="tls://<authToken>@leader.cribl:4200?tls.privKeyPath=/path/to/certs/worker.key&tls.certPath=/path/to/certs/workers.pem&tls.caPath=/path/to/certs/root.pem&tls.requestCert=true&tls.rejectUnauthorized=true"

Once you’ve set this variable, restart the Edge Node. You should see the Edge Node successfully reconnect to the Leader.

If the Edge Node doesn’t connect, check cribl.log on both the Edge Node and Leader for more context about the problem. You should see errors related to dist leader communications.

To build your own Certificate Authority (a self-signed CA), see our blog post on How to Secure Cribl Stream Worker-to-Leader Communications.