Download the PHP package kelunik/acme-client without Composer

kelunik/acme-client is a command-line ACME client implemented in PHP, enabling the issuance and renewal of certificates via the ACME protocol used by Let's Encrypt. It supports PHP 8.1+ with OpenSSL and runs on Unix-like systems and Windows.

Installation

Requirements

• PHP 8.1+ with OpenSSL
• Unix-like system or Windows

Installation using PHAR

This is the preferred installation method for usage on a production system. You can download acme-client.phar in the release section.

Instructions

If you want to update, just replace the old .phar with a new one.

All commands require a --storage argument when using the PHAR. That's the path where your keys and certificates will be stored. On Unix you could use something like --storage /etc/acme.

You can add a file named acme-client.yml next to the .phar with the two keys storage and server. These values will be used as default if you don't specify them, but you can still use another server by explicitly adding it as argument.

Installation using Composer

If you plan to actively develop this client, you don't want the PHAR but install the dependencies using Composer.

Instructions

You can use ./bin/acme as script instead of the PHAR. Please note, that all data will be stored in ./data as long as you don't provide the --storage argument.

Usage

The client stores your account keys, domain keys and certificates in a single directory. If you're using the PHAR, you usually configure the storage in the configuration file. If you're using it with Composer, all data is stored in ./data.

Be sure to backup that directory regularly.

Before you can issue certificates, you have to register an account. You have to read and understand the terms of service of the certificate authority you're using. For the Let's Encrypt certificate authority, there's a subscriber agreement you have to accept.

By using this client you agree to any agreement and any further updates by continued usage. You're responsible to react to updates and stop the automation if you no longer agree with the terms of service.

These usage instructions assume you have installed the client globally as a PHAR. If you are using the PHAR, but don't have it globally, replace acme-client with the location to your PHAR or add that path to your $PATH variable.

Configuration

The client can be configured using a (global) configuration file. The client takes the first available of ./acme-client.yml (if running as PHAR), $HOME/.acme-client.yml, /etc/acme-client.yml (if not on Windows).

The configuration file has the following format:

All configuration keys are optional and can be passed as arguments directly (except for certificates when using acme-client auto).

Before you can issue certificates, you must create an account using acme-client setup --agree-terms.

Certificate Issuance

You can use acme-client auto to issue certificates and renew them if necessary. It uses the configuration file to determine the certificates to request. It will store certificates in the configured storage in a sub directory called ./certs.

If everything has been successful, you'll see a message for each issued certificate. If nothing has to be renewed, the script will be quiet to be cron friendly. If an error occurs, the script will dump all available information.

You should execute acme-client auto as a daily cron. It's recommended to setup e-mail notifications for all output of that script.

Create a new script, e.g. in /usr/local/bin/acme-renew. The PATH might need to be modified to suit your system.

Exit codes 4 and 5 usually need a server reload, to reload the new certificates. It's already handled in the recommended cron setup.

If you want a more fine grained control or revoke certificates, you can have a look at the advanced usage document. The client allows to handle setup / issuance / revocation and other commands separately from acme-client auto.

Advanced Usage

Most users should use the auto command described above.

Register an Account

After a successful registration you're able to issue certificates. This client assumes you have a HTTP server setup and running. You must have a document root setup in order to use this client.

Issue a Certificate

You can separate multiple domains (-d) with ,, : or ;. You can separate multiple document roots (-p) with your system's path separator:

• Colon (:) for Unix
• Semicolon (;) for Windows

If you specify less paths than domains, the last one will be used for the remaining domains.

Please note that Let's Encrypt has rate limits. Currently it's five certificates per domain per seven days. If you combine multiple subdomains in a single certificate, they count as just one certificate. If you just want to test things out, you can use their staging server, which has way higher rate limits by appending --server letsencrypt:staging.

Revoke a Certificate

To revoke a certificate, you need a valid account key, just like for issuance.

--name is the common name of the certificate that you want to revoke.

Renew a Certificate

For renewal, there's the acme-client check subcommand. It exists with a non-zero exit code, if the certificate is going to expire soon. Default check time is 30 days, but you can use --ttl to customize it.

You may use this as daily cron:

You can also use a more advanced script to automatically reload the server as well. For this example we assume you're using Nginx. Something similar should work for Apache. But usually you shouldn't need any script, see basic usage.