Back to home

nine-manage-vhosts with Let's Encrypt

  1. Introduction
  2. Registration
  3. Certificate Management
    1. Create Certificate
    2. Remove Certificate
    3. Renewal
    4. Redirect

Introduction

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

Registration

To manage certificates via Let’s Encrypt, you have to register first. This can be done on the command line:

www-data@server:~ $ sudo nine-manage-vhosts certificate register-client ↵
--contact-email=meineemail@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.

Certificate Management

Prerequisite

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

  • All domains contained in the vhost have to be configured in the DNS system and have to point to your server
  • The directory /path/to/website/.well-known/acme-challenge must be readable by apache/nginx

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
    Require 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 beeing 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 send us an email to support@nine.ch 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, it must be ensured 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 cronjob 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

With the apache2 webserver, the redirect of plain HTTP requests to HTTPS requests encrypted with Let’s Encrypt will be automatically enabled.

The nginx webserver must be manually configured for you. Please write us an e-mail to support@nine.ch with the corresponding template name, then we will take enable the redirect for you.

Didn't find what you were looking for?

Contact our support:

+41 44 637 40 40 support@nine.ch