zerossl/client

By zerossl

Updated almost 2 years ago

Crypt::LE SSL Certificates client for Let's Encrypt, Buypass, other ACME-compatible CAs and servers.

Image
67

10K+

Lightweight client for Let's Encrypt, Buypass, other ACME-compatible CAs and servers - Docker version, Alpine Linux based.

Note: This repository is superseded by https://hub.docker.com/repository/docker/doknow/crypt-le.

Current base version:0.39, runs as 'ssl' user in the container, not as 'root'.

APIv2 is now default, unless a custom server is used or the API version is specified explicitly.

The client supports both ACME v1 and ACME v2 (default) protocols, as well as wildcard certificates issuance. IDN (internationalized domain names) are supported as well.

Please consider removing --api 2 option from the command line if you used it before. Even though the client will still work with that option, not having it explicitly set should ensure a better future compatibility if and when APIv3 comes out.

Previous version can be pulled using "previous" tag ("docker pull zerossl/client:previous").

For additional details and documentation visit GitHub repo.

Questions or issues - contact via GitHub or Do-Know.com.

How to use:

To make it possible to write certificate-related files on the host file system, map /data appropriately or as shown below in the alias example.

  • Pull the image (Note: you may need to be in docker group to use it)

    $ docker pull zerossl/client

  • Decide which host directory you will be keeping certificate files and keys in and which host directory is your 'acme-challenge' one (the latter is usually created as /webroot/.well-known/acme-challenge, where 'webroot' is the main directory with your web-server pages, often public_html). Let's say you keep files in /home/my_user/keys_and_certs and you are using /home/my_user/public_html/.well-known/acme-challenge. Those directories should be writable by your current user.

  • Run the container directly or create an alias similar to the one shown below

    $ alias le.pl='docker run -it -v /home/my_user/keys_and_certs:/data -v /home/my_user/public_html/.well-known/acme-challenge:/webroot -u $(id -u) --rm zerossl/client'

  • If you have created an alias (you can add it into your .bashrc for convenience), you can then run le.pl as normal. Without parameters you will be presented with a help screen listing the available options. To see the extended help screen, including usage examples, use --help option.

    $ le.pl

    $ le.pl --help

  • If you are using --path option (with or without --unlink) to create verification files automatically, use the mapped path, not the real one, so in the example above it will be /webroot

    $ le.pl --key account.key --csr domain.csr --csr-key domain.key --crt domain.crt --domains "my.domain1.com,my.domain2.com" --generate-missing --path /webroot --unlink

If you want to include domains with different webroots on the same certificate, you should define the mappings first (as demonstrated above, using -v option in an alias command example) and then list webroots for each domain in the --path option (comma separated, in the same order as you list domains themselves).

  • If you want to issue a wildcard certificate for your domain, use DNS verification and specify the domain in the following format: *.some.domain. You will also need to use --handle-as dns parameter:

    $ le.pl --key account.key --csr domain.csr --csr-key domain.key --crt domain.crt --domains "*.domain.com" --generate-missing --handle-as dns

Important - if you are issuing a wildcard certificate and also want a so-called "naked domain" ("some.domain") to be covered, list both of those names in the domains parameter. You will then need to create two TXT records with identical names but different values - this is normal and this is how you should create them.

$ le.pl ... --domains "*.some.domain, some.domain" --generate-missing --handle-as dns


Don't forget that by default the test certificate is generated, so you will need to use --live option to generate a 'real' trusted one.


By default RSA encryption is used, if you want to use ECC, specify a curve name with --curve option. You can use --curve default to use prime256v1.

To update your contact details at Let's Encrypt (to receive expiration notifications), you can use --update-contacts option as shown below:

$ le.pl --key account.key --update-contacts "one@email.address, another@email.address" --live

To remove your contact details use "none" as a value:

$ le.pl --key account.key --update-contacts "none" --live

You can also use --quiet option to suppress all messages but errors (useful when run from crontab).

Docker Pull Command

docker pull zerossl/client