Configure the module

This page describes how to set up the virtual host file to enroll a certificate and manage its lifecycle.

Set up the virtual host file

Navigate to /etc/apache2/sites-available.
Create a new virtual host file.

Apache comes with a default virtual host file called 000-default.conf. You can copy this file to create virtual host files for each of your domains.
Open the virtual host file in your preferred editor and add the mod_md module directives. See Configuration examples for sample configurations and Module directives for a list of directives that must be configured on the Apache server.
Enable the mod_md module.
```
sudo a2enmod mod_md
```
Enable the virtual host configuration file.
```
sudo a2enmod <domain_name>.conf
```

Reload the Apache server twice for the SSL configuration to take effect.

sudo systemctl reload apache2

The second reload of the Apache service is mandatory for new configurations. The first reload activates your configuration changes and enrolls a certificate. After the second reload of the Apache service, the path to the server certificate and private key are provided to the SSL module to enable SSL on the virtual hosts. The second reload is not required for renewal.

To verify the installation, open a browser and visit your website using the HTTPS protocol—the domain should be enabled with a locked padlock which means the website is SSL enabled.

To view the contents of the enrolled certificate, navigate to /etc/apache2/md/domains/<domain_name> and run the following command.

openssl x509 -in pubcert.pem -noout -text

Module directives

The following directives must be configured on the Apache server.

For a complete list of module directives (MD), see Apache module mod_md.

Directive Description

Directive	Description
`MDomain`	The Common Name of the certificate
`MDCertificateAuthority`	The URL of the ACME server
`MDExternalAccountBinding`	The key ID and HMAC key
`MDPrivateKeys`	The type and size of keys. The default value is `rsa2048`.
`MDCertificateAgreement`	By default, the value of this directive is `accepted` for silent enrollment of certificates—you are confirming that you accepted the terms of service of the certificate authority.
`MDContactEmail`	The email address of the server administrator
`MDRenewWindow`	The number of days prior to expiration that a certificate renewal process is initiated. The default expiry window is 30 days.
`ServerName`	The domain name of the web server
`ServerAlias`	Subject alternative names (SAN) for multi-domain usage. Note that every domain name added to the configuration file should be validated in SCM before being submitted for enrollment/renewal.
`LogLevel md:trace4`	Enables logging. The logs are stored in the `/var/log/apache2` directory.

MDomain

The Common Name of the certificate

MDCertificateAuthority

The URL of the ACME server

MDExternalAccountBinding

The key ID and HMAC key

MDPrivateKeys

The type and size of keys. The default value is rsa2048.

MDCertificateAgreement

By default, the value of this directive is accepted for silent enrollment of certificates—you are confirming that you accepted the terms of service of the certificate authority.

MDContactEmail

The email address of the server administrator

MDRenewWindow

The number of days prior to expiration that a certificate renewal process is initiated. The default expiry window is 30 days.

ServerName

The domain name of the web server

ServerAlias

Subject alternative names (SAN) for multi-domain usage. Note that every domain name added to the configuration file should be validated in SCM before being submitted for enrollment/renewal.

LogLevel md:trace4

Enables logging. The logs are stored in the /var/log/apache2 directory.

Configuration examples

To check whether the configuration files have any syntax errors, run the apachectl configtest command.

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>

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>

Wildcard certificate

<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>

Single certificate for multiple domains

<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>

Multiple certificates for a single domain

<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>

Single configuration file for multiple domains

<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>

Enable auto-renewal

You can create a cronjob that will invoke the Apache service reload on a schedule (see crontab for cron schedule expressions) to check whether the certificate is eligible for renewal.

The following example will trigger the Apache service reload every week.

0 0 * * 7 "system reload apache2" > /dev/null 2>&1

You can check whether a cronjob is running by looking at the contents of the error.log file. Run the following command to view the logs.

tail -f /var/log/apache2/error.log

Renew a certificate on demand

Modify the MDRenewalPeriod directive in the configuration file.
```
MDRenewalPeriods 365
```
Reload the Apache service for the configuration to take effect and enroll a new certificate from the Sectigo CA.
```
systemctl reload apache2
```

Enable logging

To enable logging for troubleshooting purposes, add the LogLevel directive to the virtual host file. The supported log levels are trace1, trace2, trace3, trace5, and trace5.

<MDomain>
    LogLevel md:trace4
</MDomain>

The log files are stored by default in the /var/log/apache2 directory.

If you create a support ticket, include the /var/log/apache2/error.log file.

Revoke a certificate

The current version of mod_md doesn’t support checking the revocation status of a certificate. If you need to re-issue the certificate after it is revoked by the administrator in SCM, make the following change to the virtual host file of the certificate and reload the Apache service to trigger re-issuance:

Modify the MDRenewalPeriod directive in the virtual host file.
```
MDRenewalPeriods 365
```
Reload the Apache service for the configuration to take effect and enroll a new certificate from the Sectigo CA.
```
systemctl reload apache2
```

Decommission a certificate

If you need to revoke and decommission a certificate from further use:

Log in to SCM, find the certificate by its Common Name, and revoke it.
Log in to your Apache server machine, navigate to the /etc/apache2/sites-available directory, and remove the corresponding virtual host file that was created for the certificate.
Reload the Apache service.

This will prevent new certificate creation for the decommissioned virtual host.