GreenArrow Email Software Documentation

TLS Certificate Configuration

Overview

This page describes how to configure TLS certificates for GreenArrow’s HTTPS, FTP, and incoming SMTP services.

This page also describes GreenArrow’s Let’s Encrypt integration.

We recommend configuring GreenArrow to register TLS certificates automatically with Let’s Encrypt. Automatic registration is the most straightforward approach, and it covers the needs of most GreenArrow installations.

A DNS record for the domain that’s to be registered must point to your GreenArrow server for automatic registration to work.

Let’s Encrypt Integration

Enabling Let’s Encrypt

Let’s Encrypt is a Certificate Authority that provides free TLS certificates and a protocol to automate TLS installation and renewal.

GreenArrow can automatically register TLS certificates, but that functionality is disabled by default. To enable it, you must accept the Let’s Encrypt subscriber agreement by completing the following steps:

  1. Set lets_encrypt_agree_to_terms_of_service to yes and lets_encrypt_registration_email to your email address to signify your acceptance.
  2. Apply changes by running greenarrow_config reload.

Getting a Server-Default TLS certificate through Let’s Encrypt

Once Let’s Encrypt integration is enabled, GreenArrow’s default behavior is to get the Server-Default TLS certificate through Let’s Encrypt for the domain name configured in/var/hvmail/control/me.

This can be overridden with the following methods:

Getting TLS certificates for URL Domains through Let’s Encrypt

Once Let’s Encrypt integration is enabled, GreenArrow’s default behavior is to get a TLS certificate for every URL Domain through Let’s Encrypt.

This can be disabled by setting the url_domains_get_lets_encrypt_certs configuration directive to no.

NOTE: If TLS certificates are configured in the /var/hvmail/control/httpd.ssl.listen file for any URL domains, they take precidence over certificates gotten from Let’s Encrypt for URL Domains.

You can check the status of certificates for each URL domain by either:

After this is enabled and certificates have been retreived for all URL Domains, we recommend also enabling the url_domains_always_use_tls directive to always use HTTPS for all click, open, and unsubscribe links.

Self-Checks

GreenArrow’s automatic TLS certificate registration checks whether it’s able to connect to itself via HTTP (port 80) at the URL domain before it attempts to register a TLS certificate with Let’s Encrypt for that domain.

If the self-check fails, the error message will include “Self-check failed:” to aid in determining the source of the failure.

See lets_encrypt_certs_self_check for more information on the self-check.

greenarrow lets_encrypt_status

The greenarrow lets_encrypt_status command is used to check the status of Let’s Encrypt TLS certificate registrations, including expiration dates. It’s also used to identify the causes of registration issues.

Here’s an example of its output when there are two URL domains:

Domain                                             Cert Exists     Cert Expiration
----------------------------------------------------------------------------------
working.example.com                                 yes             2020-05-26
broken.example.com                                  no
  Error message:     Registration failed: Self-check failed: DNS lookup failed. Check DNS and verify that "broken.example.com" resolves to an IP address on this host.
  Last failure time: 2020-03-06 06:48:04 -0600
  Next retry time:   2020-03-06 07:48:04 -0600

Here’s what the above report means:

  • working.example.com has a certificate that expires on May 26, 2020.
  • broken.example.com does not have a certificate because it failed the Self-Check.

Add the flag --only-errors (i.e. greenarrow lets_encrypt_status --only-errors) to display only certificates that have not yet been attempted or have encountered an error in registration or renewal.

Running greenarrow lets_encrypt_status --json produces JSON formatted output:

{
    "domains": [
        {
            "domain": "working.example.com",
            "has_cert": true,
            "cert_expiration_time": "2020-05-28T20:23:35Z",
            "last_failure_error_message": null,
            "last_failure_time": null,
            "next_retry_time": null
        },
        {
            "domain": "broken.example.com",
            "has_cert": false,
            "cert_expiration_time": null,
            "last_failure_error_message": "Registration failed: Self-check failed: DNS lookup failed. Check DNS and verify that \"broken.example.com\" resolves to an IP address on this host.",
            "last_failure_time": "2020-03-06T12:48:04.740131Z",
            "next_retry_time": "2020-03-06T13:48:04.740128Z"
        }
    ]
}

greenarrow lets_encrypt_retry

The greenarrow lets_encrypt_retry command is used to force GreenArrow to retry registration on one or more specific domains.

greenarrow lets_encrypt_retry domain1.example.com domain2.example.com

GreenArrow immediately retries registration or renewal of the specified domains.

This command does not affect TLS certificates that are currently valid and are outside of their renewal window, so it doesn’t cause early renewals.

Configuring TLS certificates manually

If you prefer to configure TLS certificates manually, then you have a few options:

  1. The Server-Default TLS certificate can be set with the tls_certificate_files configuration directive. This is the recommended alternative for customers who don’t want to use automatic registration.
  2. Use the HTTP Server’s /var/hvmail/control/httpd.ssl.listen file.
  3. Use the deprecated default TLS certificate paths.

Server-Default TLS Certificate

GreenArrow uses the Server-Default TLS certificate in the following areas:

  1. HTTPS requests for hostnames or IPs that do not otherwise have a matching certificate
  2. The FTP server
  3. TLS encryption for incoming SMTP connections
  4. The GreenArrow Sink Service, which is used for speed testing

The Server-Default TLS certificate is the first certificate found in the following list:

  1. The certificate defined by tls_certificate_files
  2. A Let’s Encrypt certificate obtained due to the tls_certificate_auto_generate directive
  3. A Let’s Encrypt certificate obtained for the domain in /var/hvmail/control/me
  4. A self-signed certificate generated for the domain in /var/hvmail/control/me

Acquisition of Let’s Encrypt certificates can fail due to registration errors. If a failure occurs, GreenArrow moves onto the next item in the above list. Failures can be seen with the greenarrow lets_encrypt_status command. The last option (generating a self-signed certificate) always succeeds.

Deprecated Default TLS Certificates

Prior to the introduction of automatic TLS certificate registration and the tls_certificate_files configuration directive, TLS certificates were read from different files for different functions.

If a service’s deprecated default TLS certificate files are present, they take precidence over the (Server-Default TLS certificate)[#server-default-tls-certificate] to ensure backward compatibility. We recommend replacing them with one of the other options described in the Default TLS Certificate section.

  1. HTTPS requests and the GreenArrow Sink Service used:
    • /var/hvmail/control/httpd.ssl.crt
    • /var/hvmail/control/httpd.ssl.key
  2. The FTP server used:
    • /var/hvmail/control/pure-ftpd.pem
  3. TLS encryption for incoming SMTP connections used:
    • /var/hvmail/control/tls.servercert.pem

Copyright © 2012–2020 GreenArrow Email