[SOLVED] PMM Server Installation Error – X509: Certificate Signed By Unknown Authority.

If pmm-admin config fails with x509: certificate signed by unknown authority, it means pmm-agent is rejecting the pmm-server's TLS certificate because it isn't signed by a trusted CA. The fastest fix on a private network is --server-insecure-tls. For internet-facing setups, install a real certificate (Let's Encrypt works) into the pmm-server container's nginx directory and restart.

This error can occur when you try to connect pmm-agent to a pmm-server over a secure channel, but your server only has a self-signed certificate.

pmm-admin config --server-url=https://admin:PASSWORD@host:443 XXX.XXX.XXX.XXX generic my_pmm_client
Checking local pmm-agent status...
pmm-agent is running.
Registering pmm-agent on PMM Server...
Failed to register pmm-agent on PMM Server: Post "https://host:443/v1/management/Node/Register": x509: certificate signed by unknown authority.

So first of all you need to understand if it really needs to be secured, if it doesn’t you can just add the –server-insecure-tls key. For example, if the pmm server and pmm clients are on the same isolated network, it is not necessary to build a fully secure connection.

pmm-admin config--server-insecure-tls--server-url=https://admin:PASSWORD@host:443 XXX.XXX.XXX.XXX generic my_pmm_client

In other cases, a secure connection is preferred.

You need to create a DNS entry for the pmm server and make sure the client resolves it correctly.

Then you need to put the certificate, ca-chain and key into the docker container with the pmm server.

docker cp -L /tmp/cert.pem pmm-server:/srv/nginx/certificate.crt
docker cp -L /tmp/cert.ca pmm-server:/srv/nginx/ca-certs.pem
docker cp -L /tmp/cert.key pmm-server:/srv/nginx/certificate.key

After updating the certificate, you need to restart the container

docker restart pmm-server

And now agent should connect to server correctly.

pmm-admin config --server-url=https://admin:PASSWORD@host:443 XXX.XXX.XXX.XXX generic my_pmm_client
Checking local pmm-agent status...
pmm-agent is running.
Registering pmm-agent on PMM Server...
Registered.
Configuration file /usr/local/percona/pmm2/config/pmm-agent.yaml updated.
Reloading pmm-agent configuration...
Configuration reloaded.
Checking local pmm-agent status...
pmm-agent is running.

PS: You can use a Let’s Encrypt certificate for this.

If you still receive this kind of error

We found a bug with official pmm-client image. If certificates at server side is completely correct, but you still receive this error.

pmm-client  | INFO[2022-11-30T08:53:38.245+00:00] Loading configuration file /etc/pmm-agent.yaml.  component=setup
pmm-client  | INFO[2022-11-30T08:53:38.246+00:00] Using /usr/local/percona/pmm2/exporters/node_exporter  component=setup
pmm-client  | INFO[2022-11-30T08:53:38.247+00:00] Using /usr/local/percona/pmm2/exporters/mysqld_exporter  component=setup
pmm-client  | INFO[2022-11-30T08:53:38.247+00:00] Using /usr/local/percona/pmm2/exporters/mongodb_exporter  component=setup
pmm-client  | INFO[2022-11-30T08:53:38.247+00:00] Using /usr/local/percona/pmm2/exporters/postgres_exporter  component=setup
pmm-client  | INFO[2022-11-30T08:53:38.247+00:00] Using /usr/local/percona/pmm2/exporters/proxysql_exporter  component=setup
pmm-client  | INFO[2022-11-30T08:53:38.247+00:00] Using /usr/local/percona/pmm2/exporters/rds_exporter  component=setup
pmm-client  | INFO[2022-11-30T08:53:38.247+00:00] Using /usr/local/percona/pmm2/exporters/azure_exporter  component=setup
pmm-client  | INFO[2022-11-30T08:53:38.248+00:00] Using /usr/local/percona/pmm2/exporters/vmagent  component=setup
pmm-client  | Checking local pmm-agent status...
pmm-client  | pmm-agent is not running.
pmm-client  | Registering pmm-agent on PMM Server...
pmm-client  | Failed to register pmm-agent on PMM Server: Post "https://host:443/v1/management/Node/Register": x509: certificate signed by unknown authority.
pmm-client exited with code 1

Probably it’s related to problem with certificates at pmm-client image . We reported this bug to Percona, so the problem will be resolved when they update official image.

So the workaround at this moment to avoid this issue with docker oriented install instruction is only to enable SEVER_INSECURE_TLS option:

PMM_SERVER=X.X.X.X:443
docker run \
--rm \
--name pmm-client \
-e PMM_AGENT_SERVER_ADDRESS=${PMM_SERVER} \
-e PMM_AGENT_SERVER_USERNAME=admin \
-e PMM_AGENT_SERVER_PASSWORD=admin \
-ePMM_AGENT_SERVER_INSECURE_TLS=1 \
-e PMM_AGENT_SETUP=1 \
-e PMM_AGENT_CONFIG_FILE=config/pmm-agent.yaml \
--volumes-from pmm-client-data \
percona/pmm-client:2

Need help running PMM at scale or troubleshooting database monitoring infrastructure? See our development services.

Frequently Asked Questions

What does "x509: certificate signed by unknown authority" mean in PMM?

It means pmm-agent connected to pmm-server over HTTPS, but the certificate the server presented is not signed by a CA pmm-agent trusts. This usually happens with self-signed certificates or when a private CA isn't installed in the agent's trust store. The agent refuses the connection rather than risk a man-in-the-middle.

Is it safe to use --server-insecure-tls with PMM?

Only on networks you fully control — for example, when pmm-server and pmm-clients are inside the same VPC or private subnet. The flag disables certificate verification, so traffic could be intercepted on an untrusted network. For any path that crosses the public internet, install a real certificate instead.

How do I install a real TLS certificate on PMM Server?

Copy your cert, CA chain, and key into the container using docker cp: target /srv/nginx/certificate.crt, /srv/nginx/ca-certs.pem, and /srv/nginx/certificate.key. Then docker restart pmm-server. Make sure pmm-clients connect using the DNS name on the certificate, not the raw IP address.

Why does pmm-client docker image still fail with x509 even after fixing the server cert?

There's a known bug in the official percona/pmm-client:2 image where the agent inside the container doesn't pick up the host trust store correctly. The workaround is to set PMM_AGENT_SERVER_INSECURE_TLS=1 as an environment variable on the docker run command until Percona ships a fix.

Related Reading

• [SOLVED] PMM Server Installation Error – Connection Check Failed: Error 1130: Host Is Not Allowed To Connect To This Server.
• [SOLVED] PMM Server Installation Error – Connection Check Failed: Pq: |Peer|Ident|Password Authentication Failed For User “Pmm”.
• [SOLVED] PMM Server Installation Error – Failed To Get PMM Server Parameters From Local Pmm-Agent: Pmm-Agent Is Not Connected To PMM Server.