Usage

Getting the certificates

First-time run and regular use

If you have just installed the client (or asked your system administrator to install it for you), you can start creating your certificates. First make sure that you are accepting Let's Encrypt TOS (pdf). Then write down the domain name you want your certificate for. If it is a second-level domain, like mydomain.com, then you would probably want your certificate to contain both names: mydomain.com and www.mydomain.com. If it is a sub-domain like myserver.somedomain.com, then use just that name alone. In the examples below we will use both names.

Note: In all the examples of the commands below the name of the file to run is given as "le.pl". If you are running Windows binaries, then it would be either le32.exe (for older systems such as Windows XP) or le64.exe (for newer systems).

Before we begin, a few words about the keys. Even though le.pl can create your keys for you, it is recommended to create them in advance, using the following commands:

  • To generate an account key - openssl genrsa -out account.key 4096
  • To generate a domain key - openssl genrsa -out mydomain.key 2048

You only need to generate your account key once. Domain key is best to be created for every separate set of names you are creating certificates for. Note the difference in key length - in the example given, it is 2048 bits for the domain key. You can use 4096 bits too, but you need to keep in mind that Amazon Web Services (such as CloudFront), some Cisco IOS versions and some Control Panels cannot use the keys longer than 2048 bits. Andditionally, longer keys produce slightly more overhead on connection "handshake" (even though it is still pretty fast). On the other hand, longer keys are considered a bit more "future-proof" and SSL Labs "Key Exchange" test will give 100% score only if 4096 bits key is in use. If you don't want to create the keys by yourself, le.pl will create them for you by generating 4096 bits keys using openssl via Net::SSLeay library.

If you are generating your certificate for those cases mentioned above where shorter keys are required, you can use --legacy option of the client. That will result in using 2048 bits domain key and placing the issuer's certificate ceparately in its own .ca file rather than bundled with the domain certificate.

Additionally, if you want to use ECC keys instead of RSA, you can specify the curve name with --curve parameter. To use default prime256v1 curve, use:

le.pl ... -curve default

To have your certificate issued, the certificate authority must verify that you are the owner of the domains in question. The easiest way to do that is to have verification file(s) temporarily placed into certain directory in the 'webroot' of your website. Webroot basically means the directory where your website pages are. For example, if your pages are located in '/var/www/html/', then you need to create a directory for challenge files as "mkdir -p /var/www/html/.well-known/acme-challenge/" (the dot before "well" is important). Note: Windows might not be allowing you to create appropriate directories with leading dot directly from the Explorer - in that case you need to open the command line (run cmd.exe) and use "mkdir" command.

Now you are ready to start getting your free certificates! Run the following command:

le.pl --key account.key --csr mydomain.csr --csr-key mydomain.key --crt mydomain.crt --domains "www.mydomain.com,domain.com" --path /var/www/html/.well-known/acme-challenge/ --generate-missing --unlink --live

Note: It is advised before issuing an actual certificate to test the process first. To do so, just remove --live from the command line. The testing process is pretty much the same as the process of getting an actual certificate, but the retrieved test certificate will not be 'trusted' by browsers.

With the command above, the client will generate an account key for you (keep the 'account.key' file safe) and, assuming that verification process has been finished successfully, it will produce the domain key ('mydomain.key') and the domain certificate ('mydomain.crt'). You can then install the certificate on your web server(*) or ask your system administrator to install it for you. You will need your 'account.key' to get more certificates, to renew the existing certificates and to revoke previously issued certificates if needed.

Once your account key has been generated and registered during the first-time run, you just need to have that key available on any subsequent run of the client. Everything else can be generated again if needed, though there is no harm in re-using previously generated files. You will also need your domain certificate file available if you are going to revoke it.

Please keep in mind that if you are using --path on Windows with IIS as your web-server, you need to ensure that IIS is configured to serve files without an extension (as those verification files) correctly. You can see an example of such configuration here.

DNS verification

If you prefer not to use http verification or maybe you cannot (for some reason) put verification files into the proper directory on your server, you can try using DNS verification instead. That requires having access to your DNS settings, which is normally available through your registrar or some DNS hosting service you might be using. All you have to do is to create a TXT record, wait a few minutes until it propagates and then proceed with validation. The value for the record will be given you by the client.

DNS verification is supported out of the box through the provided plugin. To use it, the command might look like this:

le.pl --key account.key --csr mydomain.csr --csr-key mydomain.key --crt mydomain.crt --domains "www.mydomain.com,domain.com" --generate-missing --handle-as dns --live

Certificate renewal

The certificates are issued for 90 days, so it makes sense to renew them sometime before they expire. It is as easy as to issue ones, you will just need one more option added to the command line - "--renew XX", where XX is the amount of days before expiration for the renew process to proceed. Let's say you want renew to happen 10 or fewer days before the certificate expiration date. The command line will be the same as earlier, except for the added option:

le.pl --key account.key --csr mydomain.csr --csr-key mydomain.key --crt mydomain.crt --domains "www.mydomain.com,domain.com" --path /var/www/html/.well-known/acme-challenge/ --generate-missing --unlink --renew 10 --live

If you run this command for example 20 days before expiration, it will inform you that it is too early for renewal. If you run it when it is 10 or fewer days are left before the expiration date, then your new certificate will be retrieved. Please note that if your old mydomain.key and mydomain.csr files from previous runs are not available during renewal, then your domain key ('mydomain.key') will also be updated, not only the domain certificate ('mydomain.crt').

Certificate renewal - automation

The renewal command mentioned above can be run automatically and it is safe to put it into cron on Linux or Task Scheduler on Windows to be run daily.

If you want to run some specific actions once the certificate has been issued/renewed, you can create a bash script in Linux or batch/command file in Windows and specify the commands to run based on "exit code" of the client. The exit code you can specify by using --issue-code parameter. For example, to set the code to 100, you can run:

le.pl --key account.key --csr mydomain.csr --csr-key mydomain.key --crt mydomain.crt --domains "www.mydomain.com,domain.com" --path /var/www/html/.well-known/acme-challenge/ --generate-missing --unlink --renew 10 --issue-code 100 --live

If there was a renewal, then on Linux the exit code will be available in $? and on Windows in %errorlevel% variable.

# Linux example
le.pl ... --issue-code 100
if [ $? -eq 100 ]; then
    echo "Time to update the certificate file and reload the server"
fi                                        

REM Windows example
le64.exe ... --issue-code 100
if errorlevel 100 (
    echo Time to update the certificate file and reload the server
)

On Windows you may need to convert the certificate to a PKCS#12 form (.pfx or .p12 file). You can do that with pvk2pfx tool from Microsoft for example, which is shipped with Windows SDK. The command would be similar to the one below:

pvk2pfx /pvk domain.key /spc domain.crt /pfx your.pfx /po YourPfxPassword

Alternatively, if you have OpenSSL installed, you can use it instead of pvk2pfx. The command would look like this:

openssl pkcs12 -inkey domain.key -in domain.crt -export -out your.pfx

Finally, you can create it without any third-party tools at all, by importing the certificate in your Certificate Store and then exporting it, as described here.

Once created, that pfx can be imported by double-clicking on it.

Certificate revocation

In the rare case when you need some of your certificates revoked, you can do it with the following command:

le.pl --key account.key --crt mydomain.crt --revoke --live

Just make sure that the certificate file ('mydomain.crt') is available.

IDN (internationalized domain name) support

If you are getting your certificate for the internationalized domain name, you can use it with the client just fine - it will make the necessary conversion for you. Please note that for the conversion to work properly you need to have correct locale settings on your system. For Linux-based systems you can check that with the "locale" command, for Windows make sure that "System locale" in the Control Panel is set correctly.

Integration options

If you decide to implement some specific automation or add specific triggers (for example to run something or send an email when you get or renew your sertificate), then it can be easily done by using external modules. Please see the "integration options" document for details.

Installing certificates on the web server

While getting the certificate does not require any specific technical knowledge, installing the certificate might require a bit of it. Normally you would need to locate where your web server configuration files are and make a few small changes to them. Usually configuration files contain commented out examples of configurations, which you can use as a template. Two most common web servers are Apache and Nginx.

Apache

Assuming that you are using a more or less recent version of Apache (2.4.8 or better), your key and the certificate are ready to be used. Below is the example of a minimal configuration:

Listen 443
<VirtualHost *:443>
        ServerName www.mydomain.com
        ServerAlias mydomain.com
        SSLEngine on
        SSLCertificateFile "/path/to/mydomain.crt"
        SSLCertificateKeyFile "/path/to/mydomain.key"
        SSLCipherSuite HIGH:!aNULL:!MD5
        SSLProtocol All -SSLv2 -SSLv3
        SSLHonorCipherOrder on
</VirtualHost>

For the advanced options see the documentation or use Mozilla SSL Configuration Generator.

Nginx

server {
        listen       443 ssl;
        server_name  www.mydomain.com mydomain.com;
        ssl          on;
        ssl_certificate      /path/to/mydomain.crt;
        ssl_certificate_key  /path/to/mydomain.key;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers 'HIGH:!aNULL:!MD5:!kEDH';
}

For the advanced options see the documentation or use Mozilla SSL Configuration Generator.

Prev: Installation Next: Integration