Pebble ACME Test Server

Pebble is a miniature ACME test server designed as a lightweight alternative to Boulder. It is intended strictly for testing ACME clients and protocol features in a self-contained environment.

Warning: Pebble is NOT intended for production use. It is designed to be volatile; it drops all state between invocations and randomizes keys and certificates used for issuance to prevent it from being used as a production Certificate Authority.

Pebble supports a -strict flag to balance testing new protocol features with maintaining backward compatibility.

• Strict Mode Enabled: Pebble may introduce breaking changes to test client readiness.
• Strict Mode Disabled (-strict false): Known breaking changes are disabled to ensure reliable integration tests.

If you prioritize reliability for your integration tests, explicitly run Pebble with -strict false.

pebble -strict false

When using Pebble for testing, be aware of the following functional differences compared to Boulder/Let's Encrypt:

• Missing ACME Features: Does not support pre-authorization or revoking a certificate issued by a different ACME account via domain authorization.
• Validation: Does not perform the same level of input validation as Boulder; some domain names rejected by Let's Encrypt may be accepted by Pebble.
• Rate Limiting: Pebble does not enforce any rate limits. It cannot be used to test how a client handles Let's Encrypt rate limiting.
• Volatility: Pebble does not support non-volatile storage or persistence. It randomizes /directory endpoint URLs to ensure clients do not hardcode them.

Pebble provides a docker-compose setup that includes a pebble-challtestsrv instance for DNS resolution. This automatically maps the necessary ports to your host system.

To start the environment:

1. Run docker-compose up.
2. Access the ACME API at https://localhost:14000/dir.
3. Access the Pebble management interface at https://localhost:15000.
4. Access the pebble-challtestsrv management interface at http://localhost:8055.

To update the DNS data for pebble-challtestsrv (e.g., setting a new default IPv4 for A queries), use the following command:

curl --request POST --data '{"ip":"172.20.0.1"}' http://localhost:8055/set-default-ipv4

To test how clients handle urn:ietf:params:acme:error:badNonce errors, Pebble can be configured to reject a percentage of valid nonces.

Use the PEBBLE_WFE_NONCEREJECT environment variable to set the rejection percentage (0-100):

• Reject 90% of nonces: PEBBLE_WFE_NONCEREJECT=90 pebble
• Never reject nonces: PEBBLE_WFE_NONCEREJECT=0 pebble

You can run Pebble using standalone Docker commands or via a docker-compose file. Images are available on the GitHub Container Registry (ghcr.io/letsencrypt/pebble).

Docker Compose Example:

services:
 pebble:
  image: ghcr.io/letsencrypt/pebble:latest
  command: -config /test/my-pebble-config.json
  ports:
    - 14000:14000  # ACME port
    - 15000:15000  # Management port
  environment:
    - PEBBLE_VA_NOSLEEP=1
  volumes:
    - ./my-pebble-config.json:/test/my-pebble-config.json

Docker Run Example:

docker run -p 14000:14000 -p 15000:15000 -e "PEBBLE_VA_NOSLEEP=1" ghcr.io/letsencrypt/pebble

The pebble-challtestsrv binary is a standalone tool for testing ACME challenges (HTTP-01, HTTPS HTTP-01, DNS-01, and TLS-ALPN-01).

WARNING: This tool is for TEST USAGE ONLY. It is trivially insecure and offers no authentication. Use it only in controlled test environments.

By default, the server enables all challenge types on specific ports. To disable a specific challenge type, set its corresponding flag to an empty string "".

# To run HTTP-01 only:
pebble-challtestsrv -https01 "" -dnsserver "" -tlsalpn01 ""

# To run HTTPS-01 only:
pebble-challtestsrv -http01 "" -dnsserver "" -tlsalpn01 ""

# To run DNS-01 only:
pebble-challtestsrv -http01 "" -https01 "" -tlsalpn01 ""

# To run TLS-ALPN-01 only:
pebble-challtestsrv -http01 "" -https01 "" -dnsserver ""

Pebble normally sleeps for a random duration (0-15s) between challenge validation attempts to force clients to poll. To disable this for faster testing, use the PEBBLE_VA_NOSLEEP environment variable.

• Disable sleeps: Set PEBBLE_VA_NOSLEEP=1.
• Set max sleep time: Set PEBBLE_VA_SLEEPTIME to a positive integer.

PEBBLE_VA_NOSLEEP=1 pebble -config ./test/config/pebble-config.json

If the pebble binary is in your $PATH, you can start the server by providing a configuration file using the -config flag. Once running, the ACME directory is accessible at https://localhost:14000/dir.

pebble -config ./test/config/pebble-config.json

If you want to avoid setting up challenge response servers (HTTP-01, DNS-01, or TLS-ALPN-01), you can run Pebble in a mode where all challenge POST requests automatically succeed.

Set the PEBBLE_VA_ALWAYS_VALID environment variable to 1.

PEBBLE_VA_ALWAYS_VALID=1 pebble

Pebble can simulate ACME server authorization reuse. By default, Pebble reuses valid authorizations 50% of the time.

Control this behavior using the PEBBLE_AUTHZREUSE environment variable:

• Always reuse authorizations: PEBBLE_AUTHZREUSE=100 pebble

To install Pebble, you must have Go installed on your system. Follow these steps to build and install the binary:

1. Set up Go.
2. Ensure ~/go/bin is in your $PATH (e.g., by adding export PATH=$PATH:$HOME/go/bin to your ~/.profile) so the pebble command is available.
3. Clone the repository and install the command using go install.

git clone https://github.com/letsencrypt/pebble/
cd pebble
go install ./cmd/pebble