Additional features

Multi-domain support

The agent can create certificates with multiple SAN values by adding the following configuration in the YAML file.

san_domains:
  -example.domain1.com
  -example.domain2.com

By default, the domain name provided as the common name (CN) is also included to the SAN values to satisfy the browsers requirement.

Certificate key update

To replace the key type (rsa, ecdsa) and key size of a previously provisioned certificate, update the key type and key size fields in the configuration YAML file for the certificate that you want to modify.

When the cronjob is running the start_acme.py automation script, the agent checks for the certificate attribute change in the YAML file. If yes, then it initiates a call to F5, creates a new key pair using the new key type, and connects to the Sectigo ACME server for issuance of a new certificate with the new public key algorithm.

Certificate revocation

If the certificate is revoked in SCM, then during the next cronjob check, the renewal of the certificate is triggered to receive a new certificate from the Sectigo CA server. The agent will install the new certificate and key on the F5 appliances.

Certificate renewal on demand

To get a new certificate before the next cronjob cycle, change the YAML file with new attributes for the certificate (if required) and execute start_acme.py as root to trigger manual certificate renewal.

Wildcard certificate support

The agent supports wildcard certificate issuance and installation on the F5 devices. Wildcards use dns-01 DCV, so the domain should be capable of handling the dns-01 DCV validation for public certificates. The following is the configuration for a wildcard certificate in the YAML file.

name: demo1
version: v1

devices:
- name: device1
  #device domains which will override global domains
  common_name: "*.example.com"
  san_domains:
    - "*.test.com"
    - example.f5test.com

  #device key-type which will override global key-type
  #key_type: ecdsa
  key_type: rsa

  #device key-size which will override global key-type
  #key_size: secp256r1
  key_size: 4096

  bigip_list:
    - 192.168.23.155
  type: F5
  protocol: https
  host: netscalerqa.ca #<<< not used for F5
  username: <REMOVED>
  password: <REMOVED>
  bigip_partition: Common
  bigip_clientssl_parent: /Common/clientssl
  #bigip_device_group: fail-synch
  #bigip_iapp: /internal/example.com.app/example.com_vs

 #profile which will be deleted before associating new profile:
  bigip_unused_profile: xoxoprofile

  virtualservers: #<<<<bigip_vs_list for F5
    - name: VSAB   #VS name
      snicert: no #<<< not used for F5
      host: 1.1.1.1  #<<< ignore by F5 as it is retrieved via REST API at runtime
      port: 8443  #<<< F5 specific. default is 443
Double quotes around the domain name are required for successful parsing of the YAML file.

Configuration of a specific YAML file

The agent supports certificate management with specific YAML file(s) or all YAML files in the /etc/sectigo directory. The following is an example of using a specific file.

start_acme.py config -y F5_ VS1.yaml

Logging levels

You can use the -L option to change the log level.

-L <log_level>

The supported log levels are critical, error, warning, info, and debug. To log messages with level warning or higher (including critical, error, and warning), run the command.

start_acme.py -L warning

To log error and higher (to reduce debug messages displayed on the console), run the command.

start_acme.py -L error

By default, Certbot commands are not printed out. For Certbot commands, set the -L debug log level (useful for manual testing).

These log levels only apply to the log messages generated by the agent. The option has no impact on the log messages generated by Certbot or Certbot BIG-IP.
If you create a support ticket, please include the error.log file.

Certificate decommissioning

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

  1. Log in to SCM, find the certificate by its Common Name, and revoke it.

  2. Log in to the agent machine, navigate to the /etc/sectigo directory, and remove the corresponding YAML file that was created for the certificate.

This will prevent a new certificate creation for the decommissioned virtual server.

The status file

Each configured certificate has a JSON status file associated with it. This file is created when the configured certificate is deployed for the first time, and is overwritten every time the certificate is deployed. The file name matches the certificate’s configuration file name, and has the .status extension. It is created in the /etc/sectigo/status directory.

The following example shows the contents of a status file.

{
    "sslcertkey_cert": "C2nJh8Mb_uey69r0wEeHed",
    "serial_chain": "121329157697969687949425293107064835722",
    "sslcertkey_chain": "BbRyVSvb22qRWKfC1iGY7K",
    "devices": {
        "172.16.1.10": [
            {
                "testdomain.com": "BOUND"
            }
        ]
    },
    "serial_cert": "241403358233721746922372291490280404893"
}

The following table describes the .status file parameters.

Parameter Description

serial_cert

The serial number of the generated certificate

sslcertkey_cert

An encoded string generated from the serial number of the generated certificate

serial_chain

The serial number of the generated certificate’s chain certificate

sslcertkey_chain

An encoded string generated from the serial number of the generated certificate’s chain certificate

devices

A list of devices on which the certificate is being deployed, and their virtual servers to which the certificate needs to be bound. For each virtual server, the status of the binding, either BINDED or FAILURE, is shown. In addition, there is an error message if the status is FAILURE.