Skip to content

Commit

Permalink
Document how to use different Pebble domain (#160)
Browse files Browse the repository at this point in the history
  • Loading branch information
shred committed Aug 22, 2024
1 parent e589b16 commit afa60ae
Showing 1 changed file with 19 additions and 0 deletions.
19 changes: 19 additions & 0 deletions src/doc/docs/ca/pebble.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,22 @@ This ACME provider can be used to connect to a local Pebble server instance, mai
* `acme://pebble/pebble.example.com:12345` - Connect to a Pebble server at `pebble.example.com` and port 12345.

Pebble uses a self-signed certificate for HTTPS connections. The Pebble provider accepts this certificate.

## Different Host Name

The Pebble server provides an end-entity certificate for the `localhost` and `pebble` domain.

If your Pebble server can be reached at a different domain (like `pebble.example.com` above), you need to create a correct end-entity certificate on your Pebble server. [See here](https://github.com/letsencrypt/pebble/tree/main/test/certs) for how to use `minica` to create a matching certificate.

Otherwise you will get an `AcmeNetworkException: Network error` that is caused by a `java.io.IOException: No subject alternative DNS name matching [...] found` when trying to access the Pebble server.

If you cannot create a correct end-entity certificate on your Pebble server, you could also disable host name verification on Java side: `-Djdk.internal.httpclient.disableHostnameVerification`

!!! warning
**Disable hostname verification for testing purposes only, never in a production environment!** Create a correct end-entity certificate whenever possible.

## Custom CA Certificate

Pebble provides a default CA certificate, which can be found at `test/certs/pebble.minica.pem` of the Pebble server. This default CA is integrated into _acme4j_'s Pebble provider, and is automatically accepted.

If you run a Pebble instance with a custom `pebble.minica.pem`, copy your PEM file as a resource to your project (either in the `src/test/resources` or `src/test/resources/META-INF` folder).

0 comments on commit afa60ae

Please sign in to comment.