Skip to content

Guide to getting a certificate for example.com and www.example.com

Jump to bottom
Tim Kimber edited this page Apr 1, 2021 · 3 revisions

Background

To enable HTTPS on your website, you need to get a certificate (a type of file) from a Certificate Authority (CA).

getssl is an ACME client which enables you to get a certificate from Let’s Encrypt. In order to get a certificate for your website’s domain from Let’s Encrypt, you have to demonstrate control over the domain.

There are two ways to demonstrate control of a domain:

  1. Create a webpage on the web server (eg nginx/apache) containing the challenge token from the Let's Encrypt ACME server (http-01 verification)
  2. Create a DNS entry for the domain which contains the challenge token from the Let's Encrypt ACME server (dns-01 verification)

wildcard certificates can only be created using dns-01 verification

More details are here: How It Works - Let's Encrypt

Configuration steps

These only need to be done the first time you create a certificate, not for every renewal

1. Create the getssl.cfg file

getssl -c <domain>

e.g.

getssl -c example.com

2. Tell getssl what additional domains you want in the certificate

Additional domains are in the SANS configuration variable. If you just want a certificate for example.com, you can leave this blank. If you want the certificate to be valid for example.com and www.example.com then you need to put www.example.com in the SANS line in getssl.cfg, e.g.

SANS="www.example.com"

3. Tell getssl how put the Let's Encrypt token in the right place

Placing a file on the webserver containing the challenge token (http-01 verification - not wildcard certificates)

To do this you need to specify the ACL line in the getssl.cfg file which tells getssl how and where to put the challenge token. If you are running getssl on the web server, then you just need to specify the directory in getssl.cfg as follows:

USE_SINGLE_ACL="true" # use the same location for the example.com www.example.com challenge tokens
ACL=('/var/www/html/.well-known/acme-challenge')

If you are running getssl on a different machine, and need to copy the challenge token to the correct place, you can use ssh, sftp, ftp, davs or ftpes, so you need to add something like the following to getssl.cfg:

ACL=(
'ssh:user1:pass1@example.com:/var/www/${DOMAIN}/web/.well-known/acme-challenge'
'ssh:user2:pass2@www.example.com:/var/www/${DOMAIN}/web/.well-known/acme-challenge'
)

Creating a DNS record containing the challenge token (dns-01 verification)

To do this you need to tell getssl how to add and remove dns records for your domain. This will depend on where you host your domain (godaddy.com / namecheap.com / AWS / run your own DNS server) and what API is available to update the DNS records.

For example, if your hosting provider uses cpanel, then you would need to add the following to getssl.cfg

VALIDATE_VIA_DNS=true
export CPANEL_USERNAME=''
export CPANEL_URL='https://www.example.com:2083'
export CPANEL_APITOKEN='<apitoken>'
DNS_ADD_COMMAND=/home/root/getssl/dns_scripts/dns_add_cpanel
DNS_DEL_COMMAND=/home/root/getssl/dns_scripts/dns_del_cpanel

You can create an API token from cpanel in the Security -> Manage API Tokens section.

Scripts exist for the following hosting providers

Each script needs a different configuration variable to specify the credentials - check the scripts for details

  • clouddns
  • cloudflare
  • cpanel
  • dnspod
  • duckdns
  • dynu
  • godaddy
  • joker
  • lexicon
  • linode
  • nsupdate
  • ovh
  • pdns-mysql

Or you can specify getssl/dns_scripts/dns_add_manual and the getssl script will pause while you manually update the DNS record. This isn't recommended as the certificates are only valid for 90 days so this will need to be done frequently.

4. Tell getssl where to put the ssl certificate

The certificate will be created in .getssl/example.com/example.com.crt and the private key will be placed in getssl/example.com/example.com.key

If you want getssl to copy the certificates to the correct place on your webserver then you need to specify the DOMAIN_CERT_LOCATION and DOMAIN_KEY_LOCATION variables in getssl.cfg.

If you need to copy the certificate to two or more locations, you can specify more than one location by adding a semi-colon (;) between entries

If you are running getssl on the webserver

In this case you can copy the file to the correct location, for example:

DOMAIN_CERT_LOCATION="/etc/nginx/pki/server.crt"
DOMAIN_KEY_LOCATION="/etc/nginx/pki/private/server.key"

If you are running getssl on a different machine

In this case you can use ssh, sftp, ftp, davs or ftpes to copy the file, e.g.

DOMAIN_CERT_LOCATION="ssh:example.com:/etc/ssl/domain.crt;ssh:www.example.com:/etc/ssl/domain.crt"
DOMAIN_KEY_LOCATION="ssh:server5:/etc/ssl/domain.key;ssh:www.example.com:/etc/ssl/domain.crt"

5. Optionally tell the web server to load the new certificates

You can specify the command used to tell the web server to reload the certificates using the RELOAD_CMD variable. This is optional, but recommended. The exact command depends on which web server you are running and what operating system you are using.

If you are running on the web server

RELOAD_CMD="service apache2 reload"

If you are running on a different machine

RELOAD_CMD="ssh user1@example.com:service nginx reload"

6. Optionally check that the new certificate is being used

As a last check, getssl can check that the certificate being used by the webserver is the certificate that has just been created by specifying the SERVER_TYPE and CHECK_REMOTE configuration variables in getssl.cfg

SERVER_TYPE="https"
CHECK_REMOTE="true"

Request a certificate from Let's Encrypt

This needs to be done for new certificates and renewals and can be automated by adding an entry to cron

getssl example.com
Clone this wiki locally