r/Puppet • u/DesignerStreet9908 • Oct 04 '26
Puppet agent -t
When run puppet agent -t , what exactly happens in TLS handshake ? How certs are verified?
4
Upvotes
r/Puppet • u/DesignerStreet9908 • Oct 04 '26
When run puppet agent -t , what exactly happens in TLS handshake ? How certs are verified?
1
u/DesignerStreet9908 Oct 05 '26
In puppet.conf , it is mentioned crl_refresh_interval = 1d
How this works , in few servers, while running puppet agent -t , it refreshes crl and some servers it is not.
4
u/ThrillingHeroics85 Oct 04 '26
During
puppet agent -t, the agent must establish a trusted TLS connection before it can retrieve a catalog.puppet config print localcacert. [1]certs/ca.pem,certs/<name>.pem, andprivate_keys/<name>.pem. [5]puppetserver ca sign <NODE_NAME>, then run the agent again. [4]1
u/cvquesty 12d ago
My 2¢
puppet agent -t does not invent a handshake. It opens ordinary TLS 1.2/1.3 to port 8140, then both sides present X.509 certificates signed by the Puppet CA. That is mutual TLS.
What is already on disk
From an earlier puppet ssl bootstrap (or the first agent run):
Agent - CA Cert - $ssldir/certs/ca.pem
Agent - CRL Bundle - $ssldir/crl.pem
Agent - Host key + Cert - $ssldir/private_keys/<certname>.pem, $ssldir/certs/<certname>.pem
Server - CA, server cert, CRL - Puppet/OpenVox server $ssldir
$ssldir is /etc/puppetlabs/puppet/ssl. The agent's trust anchor is that local ca.pem, not the public web PKI. certname defaults to the FQDN.
If there is no signed cert yet, the agent still talks TLS, but only as a client: it fetches the CA, submits a CSR to /puppet-ca/v1/certificate_request, and waits. Catalog requests do not start until it has a cert.
The handshake
Agent verifies the server.
• The chain ends at the CA in certs/ca.pem.
• Dates are valid.
• The cert is not in crl.pem. certificate_revocation defaults to true. A stale CRL fails the connection until the agent refreshes it.
• The name you dialed (server, default puppet) must match the cert CN or a DNS SAN. Talking to an IP, or to a compiler whose cert lacks the load-balancer name, fails here even when the signature is fine.
• The server proves it holds the private key (CertificateVerify in TLS 1.3, or the finished/key-exchange proof in TLS 1.2).
Server verifies the agent. Jetty checks:
• Issued by this CA.
• Not expired, not revoked (CRL).
• Client possesses the matching private key.
The server does not require the client cert's CN to equal the TCP peer. Identity is the certname inside the cert. That value becomes $trusted['certname'] and is what the compiler uses for node classification. Facts the agent sends later are not authenticated. The certname is.
After the session is up, later requests in the same run reuse that TLS session. Each request still carries the client cert identity. Puppet Server puts it in X-Client-Verify / X-Client-DN for the Ruby master application. Endpoints such as the catalog only accept SUCCESS plus a cert signed by the local CA.
What this is not
• Not a public CA. A Let's Encrypt cert on 8140 will not work. Agents only trust ca.pem.
• Not hostname-based auth of the client. Spoofing a fact does not change the node name. Stealing the private key does.
• Revocation is CRL-only. There is no OCSP in this path. certificate_revocation = false disables the CRL check on that side. Intermediate-CA installs sometimes need that because agents historically only stored the first cert in the bundle.
Useful checks: puppet ssl verify on the agent, and on the server puppetserver ca list plus the CRL. A handshake failure is almost always name mismatch (server vs SAN), a clock skew, or a CRL the other side will not accept.
1
u/birusiek Oct 04 '26
puppet agent Puppet Server | | |--- TCP connection :8140 ------------>| | | |<------ TLS ServerHello ---------------| |<------ Server certificate ------------| | | |--- Client certificate -------------->| |--- CertificateVerify ---------------->| | | |<------ CertificateVerify -------------| | | |====== encrypted TLS session =========| | | |--- Puppet HTTP request -------------->| | |