acmetool

Acmetool stores all state in a single directory (default /var/lib/acme).

live/ directory

Contains symlinks for hostnames pointing to their respective certificate directories. Use these stable paths in your webserver config: /var/lib/acme/live/example.com/{cert,chain,fullchain,privkey}

desired/ directory

Contains YAML target files. Each file defines what certificates should be obtained.

Target File Structure Example:

satisfy:
  names:
    - example.com
    - www.example.com

request:
  provider:               # ACME Directory URL
  ocsp-must-staple: true
  challenge:
    webroot-paths:
      - /var/www
    http-ports:
      - 123
    env:
      FOO: BAR
  key:
    type: rsa|ecdsa
    rsa-size: 2048
    ecdsa-curve: nistp256

priority: 0

Important Constraints

• Filesystem Boundaries: All files under the state directory must reside on the same filesystem.
• Target Files: An empty target file in desired/ defaults to the filename as the target hostname.

satisfy:
  names:
    - example.com       # The names you want on the certificate.
    - www.example.com

request:
  provider:               # ACME Directory URL. Normally set in conf/target only.
  ocsp-must-staple: true  # Request OCSP Must Staple. Use with care.
  challenge:
    webroot-paths:        # You can specify custom webroot paths.
      - /var/www
    http-ports:           # You can specify different ports for proxying.
      - 123               # Defaults to listening on localhost.
      - 456
      - 0.0.0.0:789       # Global listen.
    http-self-test: false # Defaults to true. If false, will not perform self-test
                          # but will assume challenge can be completed. Rarely needed.
    env:                  # Optionally set environment variables to be passed to hooks.
      FOO: BAR
  key:                    # What sort of key will be used for this certificate?
    type: rsa|ecdsa
    rsa-size: 2048
    ecdsa-curve: nistp256
    id: krzh2akn...       # If specified, the key ID to use to generate new certificates.
                          # If not specified, a new private key will always be generated.
                          # Useful for key pinning.

priority: 0

The reconciliation process is the core operation that builds the State Directory to ensure all targets are satisfied with the best possible certificates.

The Reconciliation Lifecycle:

1. Conform: Validates the directory for consistency, fixes permissions, and ensures symlinks are unbroken and relative.
2. Cache: Ensures all uncached certificates are available.
3. Revoke: If a revoke file exists in a certificate directory, the implementation requests revocation and creates a revoked file upon confirmation.
4. Satisfy Targets: For each target, the system checks if a satisfying certificate exists. If not, it initiates a certificate request process:
   • Create an order and satisfy authorizations.
   • Once the order is ready, create a CSR with the required SANs and finalize the order.
   • Write the order URL to the State Directory.
5. Update Live Symlinks: Updates the live directory so hostnames point to the Most Preferred Certificate.
6. Cleanup: Optionally deletes cullable certificates and keys.

Key Concepts:

• Satisfying a Target: A certificate satisfies a target if its private key is available, it is not revoked, it is not self-signed, it is within its validity period, and it is not 'near expiry'.
• Near Expiry: A certificate is considered near expiry if the time remaining is less than the implementation's threshold (recommended: 30 days or 33% of validity).
• Most Preferred Certificate: The system selects the best certificate for a target based on:
  1. Whether it satisfies the target.
  2. If multiple don't satisfy, it uses a fallback hierarchy (e.g., a certificate with an available private key is better than one without; a self-signed cert is better than a revoked one).
  3. Certificates with later Not After times are preferred.

acmetool supports several ways to perform domain validation:

• Webroot: Places challenge files in a directory that your webserver serves from /.well-known/acme-challenge/.
• Proxy: acmetool listens on port 402. You configure your webserver to proxy requests for /.well-known/acme-challenge/ to http://127.0.0.1:402/.well-known/acme-challenge/.
• Stateless: A method where the webserver responds to challenges without consulting acmetool, requiring a one-time configuration change.
• Redirector: Starts an HTTP server on port 80 that redirects all requests to HTTPS and handles validation responses. This is useful if your webserver is not listening on port 80. Run it as a service: acmetool redirector --service.uid=USERNAME --service.daemon=1
• Listen: If ports 80 or 443 are not in use, acmetool can use them directly (primarily for development).
• Hook: Allows you to write custom shell scripts or binaries to provision challenge files (e.g., rsyncing them to a remote server).

The ACME State Directory is the central storage for all ACME-related data. It follows a specific directory tree to manage accounts, keys, certificates, and symlinks for easy access by applications.

Directory Tree Overview

• accounts/: Contains account-specific information. Each subdirectory is named after an Account ID and contains a privkey file (PEM format).
• keys/: Contains private keys used for certificates. Each subdirectory is named after a Key ID and contains a privkey file (PEM format).
• certs/: Contains information about issued or requested certificates. Each subdirectory is named after a Certificate ID and contains:
  • url: The URL for the finalized order (UTF-8).
  • account: A relative symlink to the account directory used for the request.
  • cert: The PEM-encoded certificate.
  • chain: The PEM-encoded certificate chain (intermediate certificates).
  • fullchain: The concatenation of cert and chain.
  • privkey: A relative symlink to the corresponding key in the keys/ directory.
• live/: Contains relative symlinks to subdirectories in certs/. Symlink names follow the pattern hostname:label (e.g., example.com or example.com:web). This allows applications to point to a stable path like /var/lib/acme/live/example.com/cert regardless of certificate rotations.
• tmp/: Used for atomic file operations and temporary storage.