Skip to main content

nine-manage-vhosts with Let's Encrypt

nine-manage-vhosts supports managing certificates using Let's Encrypt.

Account administration​

Register​

To manage certificates via Let's Encrypt, you have to register an email address first. This can be done using the following command:

www-data@server:~ $ sudo nine-manage-vhosts certificate register-client \
--contact-email=myemail@domain.ch

Your e-mail address is used by Let's Encrypt to inform you about expiring certificates. As nine-manage-vhosts is configured to do this automatically, you normally shouldn't receive any e-mails.

Show​

You can view the current email address, on which you will be informed about expiring certificates. This can be done using the following command:

www-data@server:~ $ sudo nine-manage-vhosts certificate show-contact-email

Update​

You can update the email address, on which you will be informed about expiring certificates. This can be done using the following command:

www-data@server:~ $ sudo nine-manage-vhosts certificate update-client \
--contact-email=myemail@domain.ch

Certificate Management​

Please make sure the following requirements are met before trying to create certificates:

  • All domains and DNS aliases registered in the vhost have to be configured in the DNS system and need to point to your server
  • The directory /path/to/website/.well-known/acme-challenge must be readable by apache/nginx. To ensure the directory exists it is created (even if deleted again) and permissions are reset.
  • The directory needs to be readable from the internet without any redirects (or a redirect to HTTPS at max).

To ensure the availability of the directory /path/to/website/.well-known/acme-challenge for validation, the appropriate configuration can be set in the .htaccess file:

  • For virtual hosts with "BasicAuth":
AuthType Basic
AuthName "Password Protected Area"
AuthUserFile /path/to/.htpasswd
Require expr %{REQUEST_URI} =~ m#^/.well-known/acme-challenge/#
Require valid-user
  • For virtual hosts with "RewriteRules": (To be placed at the beginning of the .htaccess-File)
RewriteEngine On
RewriteCond %{REQUEST_URI} ^/\.well\-known/acme\-challenge/
RewriteRule (.*) - [L]
  • For virtual hosts with "Allow From":
SetEnvIf Request_URI "^/.well-known/acme-challenge/" allowles
Allow from env=allowles

The configuration can be tested as follows:

  • In the directory /path/to/website/.well-known/acme-challenge create a text file with content. If the directory does not exist, you can create it manually.
  • Execute the following command, based on your domain and text file:
curl http://your-domain.tld/.well-known/acme-challenge/test.txt
  • If the content of the file is being displayed, in this case "test.txt", the access is working.

Create Certificate​

To create a certificate for an existing VirtualHost, the following command can be used:

www-data@server:~ $ sudo nine-manage-vhosts certificate create \
--virtual-host=example.org

The domain and all aliases need to have a working A record or CNAME (pointing to the server) configured. If the certificate was successfully created, you should see the following output:

Certificate created: example.org (valid until: 2016-07-12)

Now the newly created certificate can be enabled with updating the corresponding VirtualHost with a Let's Encrypt enabled template:

www-data@server:~ $ sudo nine-manage-vhosts virtual-host update example.org \
--template=default_letsencrypt_https

The certificate should be active now. It will be renewed automatically. If you're using a custom template, we have to enable it for Let's Encrypt use first. Please email us to with the name of the template, and we'll set it up for you.

Remove certificate​

To remove a certificate, you can issue the following command:

www-data@server:~ $ sudo nine-manage-vhosts certificate remove \
--virtual-host=example.org

Prior to removing, ensure that the certificate isn't used by a VirtualHost anymore. To do that, you can simply update the VirtualHost with a non-Let's Encrypt template:

www-data@server:~ $ sudo nine-manage-vhosts virtual-host update example.org \
--template=default

Renewal​

Let's Encrypt certificates are valid 90 days. To renew the certificates, a cron job is automatically configured. It will run every night and renew expiring certificates.

Renewing certificates only works if the configuration is still working (see "Create Certificate"). Therefore, renewal can fail if this is not the case. Let's Encrypt will then inform you about expiring certificates using the e-mail you defined when registering.

Renewing expiring certificates is always possible issuing the following command:

www-data@server:~ $ sudo nine-manage-vhosts certificate renew-expiring

Redirect​

The redirect of plain HTTP requests to HTTPS encrypted environment with Let's Encrypt will be automatically enabled.