Installation and configuration of mod_md

Prerequisites

The Sectigo Apache ACME integration has the following requirements:

  • mod_md v2.4.9 and higher

  • Apache v2.4.48 and higher

  • Library dependencies:

    • make

    • openssl

    • libssl-dev

    • libcurl4

    • libcurl4-openssl-dev

    • gcc git

    • libapr1-dev

    • libaprutil1-dev

    • autoconf

    • libtool

    • libtool-bin

    • libpcre3-dev

    • libjansson-dev

    • curl

    • apache2

    • apache2-dev

  • Operating systems:

    • Debian 11

    • Ubuntu 20.04

      Other operating systems have not been tested by Sectigo, however, they may work. Please contact Sectigo support if you encounter issues.
  • Registered Sectigo ACME account

    • An account for the organization, created on SCM (contact Sectigo Sales Team)

    • Organization registered with SCM

    • Domains created, delegated, and pre-validated with Sectigo backend

    • ACME service enabled for the ACME account

    • The ACME account registered for the organization

    • See ACME Integration Guide for Enterprise Customers for instructions on obtaining the artifacts (ACME server URL and External Account Binding (EAB) values) to run the agent. Contact your Sectigo account manager if you need further information.

mod_md supported features

  • Apache domain management

  • External account binding

  • RSA (2048, 4096) and ECDSA (secp256r1) support

  • TLS/SSL certificates (DV/OV/EV) enrollment and renewal

  • Single-domain, multi-domain, and wildcard certificates

  • Multiple certificates with different key types (RSA, ECDSA) for a single host

  • Multiple ACME servers (private/public for DV, OV, EV certificates)

The current version of the module supports only the pre-validated domains in Sectigo Certificate Manager (SCM). The domains for which certificates are requested should go through Domain Control Validation (DCV) in SCM as per the instructions provided in Section 5.7.4 How To Validate Domains of Sectigo Certificate Manager administrator’s guide. For more information on DCV methods, see Domain Control Validation Methods in Sectigo’s Knowledge Base.

Module installation instructions

The following instructions are based on Debian Sid (Debian 11). If you have a different operating system, please use the appropriate installation instructions.

The mod_md v2.4.9 and later requires Apache version 2.4.48 or later installed on the system.
  1. Log in to your Linux system as a root user.

  2. Install the following library dependencies for the module, using the Debian’s apt package manager. The package manager offers the latest Apache httpd version.

    apt install make openssl libssl-dev libcurl4 libcurl4-openssl-dev gcc git libapr1-dev libaprutil1-dev autoconf libtool libtool-bin libpcre3-dev libjansson-dev curl apache2 apache2-dev
  3. Check the version of Apache server to make sure the version is >=2.4.48.

    apache2ctl -V
  4. Create a temporary directory in the present working directory (pwd) to download the mod_md tar file.

    mkdir mod_md_installation
    cd /mod_md_installation
  5. Download the latest mod_md module and save the mod_md-2.4.x.tar.gz file to the mod_md_installation directory.

  6. Untar the file using the tar command.

    tar -xvf mod_md.2.4.x.tar.gz
  7. Execute the following commands one by one.

    cd mod_md-2.4.x
    ./configure --with-apxs=/usr/bin/apxs --enable-werror
    make
    make install
    a2enmod md
    The a2enmod command enables mod_md to work with Apache. Without this command, EAB directives added to the configuration file(s) won’t work.

    After successful installation of mod_md and its dependencies, the module is ready for certificate enrollment using ACME EAB values.

  8. Run the following command to restart the Apache service.

    systemctl restart apache2
  9. Run the following command to check the status of the Apache service.

    systemctl status apache2

    If Apache is not able to start, run systemctl service apache2 for more information.

mod_md configuration requirements

During the creation of an ACME account in SCM, Key ID and HMAC Key are generated. You should copy and save these values for module configuration. This information is required for module registration as an ACME client with the Sectigo ACME server.

The configuration for domain management can be configured as a single file or a separate file for each domain. The path to the configuration files is added to the /etc/apache2/apache2.conf file.

Apache configuration file

The following lines in the /etc/apache2/apache2.conf file contain the path to the domain configuration.

# Include generic snippets of statements:

IncludeOptional conf-enabled/*.conf

# Include the virtual host configurations:

IncludeOptional sites-enabled/*.conf

The following example shows five configuration files for five virtual hosts created under the /var/www folder.

# /etc/apache2/sites-enabled# ls

apachewebserver.conf
example1.apachewebserver.conf
example2.apachewebserver.conf
example3.apachewebserver.conf
slitaz.conf

Sectigo ACME account details

The following ACME account details are required for the module:

  • The URL of the ACME server

  • External account binding (EAB) Key ID

  • EAB HMAC Key

  • Network access from a Linux client machine to connect to the ACME server URL

Configuration details

The following directives must be configured on the Apache server.

Module Directive Description

MDomain

Certificate Common Name

MDCertificateAuthority

The URL of the ACME public or private server

Public ACME URL format:

https://<acme-server-url>/v2/DV

https://<acme-server-url>/v2/OV

https://<acme-server-url>/v2/EV

Private ACME URL fomat:

https://<acme-server-url?>

MDExternalAccountBinding

KeyID and HMAC values

MDPrivateKeys

The type and size of keys. The default value is RSA 2048.

MDCertificateAgreement

Enrollment Agreement should be accepted by default for silent enrollment of certificates

MDContactEmail

The email of the server administrator

MDRenewWindow

When the certificates will be renewed. The default value is 30 days.

ServerName

The domain name of the web server

ServerAlias

Additional names for multi-domain usage. Note that every domain name added to the configuration file should be pre-validated in the SCM before submitted for enrollment/renewal.

LogLevel md:trace4

Enabling log directive will create error log in the /var/log/apache2 directory.

For a complete list of module directives (MD), see Apache Module mod_md.
Sectigo ACME servers (private and public) require the domains to be pre-validated on SCM, except for DV certificates. For publicly trusted DV TLS/SSL certificates, you can send the request directly to the public DV ACME server to enroll a DV SSL/TLS certificate after the successful HTTP-01 challenge validation. See Sectigo Knowledge Base or contact Sectigo Support for more information.

Configuration examples

Example 1: Single domain certificate

<MDomain sitea.ccmqa.com>
    MDCertificateAuthority https://acme-qa.secure.trust-provider.com/v2/DV
    MDExternalAccountBinding avLn8exu9G_zmogLpYjcgw 4YuRDEIAaNtEmnpwSirdISNWXw5YtCbTjz-Wp0ai5zFNYFN-Hm7XKbiRGTO5F3jSi8YiD3cELzQsYs2ae_gARw
    MDRenewWindow 365
    MDContactEmail [email protected]
    LogLevel md:trace4
</MDomain>

<VirtualHost *:443>
    ServerName sitea.ccmqa.com
    DocumentRoot /var/www/sitea.ccmqa.com
    SSLEngine on
</VirtualHost>

Example 2: Multi-domain certificate

<MDomain sitea.ccmqa.com>
    MDCertificateAuthority https://acme-qa.secure.trust-provider.com/v2/DV
    MDExternalAccountBinding avLn8exu9G_zmogLpYjcgw 4YuRDEIAaNtEmnpwSirdISNWXw5YtCbTjz-Wp0ai5zFNYFN-Hm7XKbiRGTO5F3jSi8YiD3cELzQsYs2ae_gARw
    MDRenewWindow 365
    MDContactEmail [email protected]
</MDomain>

<VirtualHost *:443>
    ServerName sitea.ccmqa.com
    ServerAlias siteaa.ccmqa.com
    ServerAlias siteaaa.ccmqa.com
    DocumentRoot /var/www/sitea.ccmqa.com
    SSLEngine on
</VirtualHost>

Example 3: WildCard certificate (private, DV, and OV)

<MDomain ccmqa.com *.ccmqa.com>
    MDCertificateAuthority https://acme-qa.secure.trust-provider.com/v2/DV
    MDExternalAccountBinding avLn8exu9G_zmogLpYjcgw 4YuRDEIAaNtEmnpwSirdISNWXw5YtCbTjz-Wp0ai5zFNYFN-Hm7XKbiRGTO5F3jSi8YiD3cELzQsYs2ae_gARw
    MDRenewWindow 365
    MDContactEmail [email protected]
</MDomain>

<VirtualHost *:443>
    ServerName ccmqa.com
    ServerAlias *.ccmqa.com
    DocumentRoot /var/www/sitea.ccmqa.com
    SSLEngine on
</VirtualHost>

Example 4: One certificate for multiple hosts

<MDomain sitea.ccmqa.com siteb.ccmqa.com>
    MDCertificateAuthority https://acme-qa.secure.trust-provider.com/v2/DV
    MDExternalAccountBinding avLn8exu9G_zmogLpYjcgw 4YuRDEIAaNtEmnpwSirdISNWXw5YtCbTjz-Wp0ai5zFNYFN-Hm7XKbiRGTO5F3jSi8YiD3cELzQsYs2ae_gARw
    MDRenewWindow 365
    MDContactEmail [email protected]
</MDomain>

<VirtualHost *:443>
    ServerName sitea.ccmqa.com
    DocumentRoot /var/www/sitea.ccmqa.com
    SSLEngine on
</VirtualHost>

<VirtualHost *:443>
    ServerName siteb.ccmqa.com
    DocumentRoot /var/www/siteb.ccmqa.com
    SSLEngine on
</VirtualHost>

Example 5: Multiple certificates for a single host

<MDomain sitea.ccmqa.com>
    MDCertificateAuthority https://acme-qa.secure.trust-provider.com/v2/DV
    MDExternalAccountBinding avLn8exu9G_zmogLpYjcgw 4YuRDEIAaNtEmnpwSirdISNWXw5YtCbTjz-Wp0ai5zFNYFN-Hm7XKbiRGTO5F3jSi8YiD3cELzQsYs2ae_gARw
    MDPrivateKeys rsa2048 secp256r1
    MDRenewWindow 365
    MDContactEmail [email protected]
</MDomain>

<VirtualHost *:443>
    ServerName sitec.ccmqa.com
    ServerAlias sited.ccmqa.com
    DocumentRoot /var/www/sitea.ccmqa.com
    SSLEngine on
</VirtualHost>

Example 6: Single configuration file for multiple hosts

<MDomain sitea.ccmqa.com siteb.ccmqa.com sitec.ccmqa.com>
    MDCertificateAuthority https://acme-qa.secure.trust-provider.com/v2/DV
    MDExternalAccountBinding avLn8exu9G_zmogLpYjcgw 4YuRDEIAaNtEmnpwSirdISNWXw5YtCbTjz-Wp0ai5zFNYFN-Hm7XKbiRGTO5F3jSi8YiD3cELzQsYs2ae_gARw
    MDRenewWindow 365
    MDContactEmail [email protected]
</MDomain>

<VirtualHost *:443>
    ServerName sitea.ccmqa.com
    DocumentRoot /var/www/sitea.ccmqa.com
    SSLEngine on
</VirtualHost>

<VirtualHost *:443>
    ServerName siteb.ccmqa.com
    DocumentRoot /var/www/siteb.ccmqa.com
    SSLEngine on
</VirtualHost>

<VirtualHost *:443>
    ServerName sitec.ccmqa.com
    DocumentRoot /var/www/sitec.ccmqa.com
    SSLEngine on
</VirtualHost>
To check whether the configuration files have any syntax errors, run the apachectl configtest command. If there is an error in the configuration file, the command will output the details.