opamp-core

Self-Signed TLS Certificate Setup

This guide shows how to use the developer CLI certificate helper to:

1. install required Python dependency (cryptography), and
2. generate a self-signed TLS certificate and private key for local provider HTTPS testing.

CLI Location

• Command: python dev-tools/main.py certificate generate
• Help: python dev-tools/main.py certificate generate --help

The command --help output points to this document.

What The Script Generates

By default, the script writes:

• certificate: certs/provider-server.pem
• private key: certs/provider-server-key.pem

Default SAN values:

• DNS: localhost
• IP: 127.0.0.1

Usage

Linux/macOS:

python3 dev-tools/main.py certificate generate

Windows (cmd or PowerShell):

python dev-tools/main.py certificate generate

Common Options

python3 dev-tools/main.py certificate generate \
  --cert-file certs/provider-server.pem \
  --key-file certs/provider-server-key.pem \
  --common-name localhost \
  --dns-name localhost \
  --dns-name provider.local \
  --ip-address 127.0.0.1 \
  --days 365 \
  --force

If dependency auto-install is not desired:

python3 dev-tools/main.py certificate generate --skip-dependency-install

Configuration Updates Required

Apply the following values where relevant.

1) Provider Config (config/opamp.json)

Add/update provider.tls:

{
  "provider": {
    "tls": {
      "enabled": true,
      "cert_file": "certs/provider-server.pem",
      "key_file": "certs/provider-server-key.pem",
      "trust_anchor_mode": "none"
    }
  }
}

Behavior notes:

• If the provider.tls section is missing, provider runs HTTP-only.
• If provider.tls is present and enabled is omitted, TLS defaults to enabled.
• Set provider.tls.enabled to false to keep the section but force HTTP-only mode.

If you start provider with scripts/run_opamp_server.sh --https or scripts\\run_opamp_server.cmd --https, the TLS cert/key/trust values are generated/updated automatically. provider.tls.enabled can be set explicitly, but defaults to enabled when omitted.

Also ensure the consumer URL in the same file uses HTTPS:

{
  "consumer": {
    "server_url": "https://localhost:8080"
  }
}

You can also apply the provider.tls block with the developer CLI:

python3 dev-tools/main.py certificate ensure-provider-config \
  --config-file config/opamp.json \
  --cert-file certs/provider-server.pem \
  --key-file certs/provider-server-key.pem \
  --trust-anchor-mode none

2) Fluentd Consumer Config (consumer/opamp-fluentd.json)

Set:

{
  "consumer": {
    "server_url": "https://localhost:8080"
  }
}

Self-Signed Certificate Impact: CA Validation

A self-signed server certificate is not chained to a public CA. If the consumer is doing strict CA validation, HTTPS validation will fail unless you disable verification or trust that cert/CA explicitly.

For the TLS model documented in docs/tls_https_mtls_revision.md, the impacted client setting is:

{
  "consumer": {
    "tls": {
      "verify_server": false
    }
  }
}

Use verify_server=false for local development only.

Recommended Development-Only Pattern

1. Generate the self-signed certificate/key with the developer CLI.
2. Enable provider TLS using the generated files.
3. Point consumer server_url to https://....
4. Disable client CA verification for local self-signed usage (consumer.tls.verify_server=false).

Troubleshooting

• Missing dependency: cryptography
  • Re-run without --skip-dependency-install, or install manually:
    • python -m pip install --upgrade cryptography
• Certificate hostname mismatch
  • Ensure the host in server_url is included in SAN entries (--dns-name, --ip-address).
• Existing output files
  • Use --force to overwrite existing cert/key files.

This site is open source. Improve this page.