Configuring the connector

This page describes how to configure the connector and related services to automate the certificate lifecycle management on HAProxy load balancers.

Extract the contents

Extract the contents of the sectigo-haproxy-connector-<version>.zip archive to the current path.
Navigate to the root directory containing the solution files.
Give execute permission to the sectigo-haproxy-connector file.
```
chmod +x ./sectigo-haproxy-connector
```

Set up the certificate profile file

Configure the certificates.yml file in the configs directory.

Sample certificate profile file

sectigo:
  commonParams:
    country: US
    province: Texas
    locality: Texas
    organization: Sectigo
  certificates:
    - frontendName: www-https
      commonName: john-doe.com
      comments: frontend www-https
      subjAltNames: ["john-doe.com","www.john-doe.com"]
      externalRequester: "[email protected]"
      renewBeforeDays: 30
      keyType: RSA
      keySize: 2048
      forceRenew: no
    - frontendName: jane-https
      commonName: jane-doe.com
    ...

The following table describes the parameters in the file.

Parameter Description

Parameter	Description
`country`	The country name included in the certificate Country (C) field
`province`	The state or province name included in the certificate State (ST) field
`locality`	The location name included in the certificate Locality (L) field
`organization`	The organization name included in the certificate Organization (O) field
`frontendName`	The name of the HAProxy frontend section. For more information, see Frontend.
`commonName`	The domain name included in the certificate Common Name (CN) field
`comments`	(Optional) Comments for certificate enrollment
`subjAltNames`	A comma-separated list of subject alternative names (SAN) included in the certificate subjectAltName field
`externalRequester`	The email or a comma-separated list of emails of the certificate requester
`renewBeforeDays`	The number of days prior to expiration that a certificate renewal process is initiated. The default expiry window is `30` days.
`keyType`	The key algorithm to use for certificate enrollment. The possible values are `RSA` and `ECDSA`.
`keySize`	The key size to use for certificate enrollment. The possible values: RSA: `2048`, `3072`, `4096`, and `8192` ECDSA: `256` and `384`.
`forceRenew`	Specifies whether to force the renewal of a certificate. For example, you can use this parameter to renew a certificate issued by a Microsoft CA which doesn’t provide the required OSCP URL. The possible values are `yes` and `no.` The default value is `no`.

country

The country name included in the certificate Country (C) field

province

The state or province name included in the certificate State (ST) field

locality

The location name included in the certificate Locality (L) field

organization

The organization name included in the certificate Organization (O) field

frontendName

The name of the HAProxy frontend section. For more information, see Frontend.

commonName

The domain name included in the certificate Common Name (CN) field

comments

(Optional) Comments for certificate enrollment

subjAltNames

A comma-separated list of subject alternative names (SAN) included in the certificate subjectAltName field

externalRequester

The email or a comma-separated list of emails of the certificate requester

renewBeforeDays

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

keyType

The key algorithm to use for certificate enrollment. The possible values are RSA and ECDSA.

keySize

The key size to use for certificate enrollment. The possible values:

RSA: 2048, 3072, 4096, and 8192
ECDSA: 256 and 384.

forceRenew

Specifies whether to force the renewal of a certificate. For example, you can use this parameter to renew a certificate issued by a Microsoft CA which doesn’t provide the required OSCP URL. The possible values are yes and no. The default value is no.

Configure the connector

The connector can work with plaintext or encrypted ACME credentials. To reduce the amount of manual, error-prone configuration, particularly for encryption, it offers a prompt where you can type answers on the command line to specify the HAProxy Data Plane API credentials, ACME credentials, whether to encrypt the ACME credentials, and other configuration details. The solution creates an scm.yml file in the configs directory and populates it with configuration data.

To view all available options, run ./sectigo-haproxy-connector --help.

Run the connector with the --configure or -c option in the terminal and follow the prompt to provide the ACME credentials, logging level, and certificate directory. If you choose to encrypt your credentials, this command also creates a key pair in the current directory and encrypts your HMAC key using the public key.

sudo ./sectigo-haproxy-connector --configure

At each prompt, provide the parameters that will define your configuration file. The square brackets indicate an existing or default value, if any. If you want to keep the default setting at a specific prompt, hit Enter.

If you type yes when asked whether to enable force restart of HAProxy, the HAProxy service will be automatically restarted once the certificates have been provisioned and attached to the load balancers.

If you keep the default value no, you will need to manually restart HAProxy after provisioning the certificates to enable SSL termination.

sudo service haproxy restart

Specify your Sectigo ACME credentials for the SCM configuration file.
Sectigo ACME URL [None]: https://acme-qa.secure.trust-provider.com/v2/DV
Sectigo ACME Key ID [None]: 2a82af7331a11fc8b9ec2793d924b0aa
Sectigo ACME HMAC Key [None]: AqlqlXB9mQoQzrGHmFzLSdbhENiea9RibwyCZoNfXrp7o7A1Yb9pvPwCPFpl7ZBMztc752le8VhCDXyTg5ms68U6
Encrypt ACME HMAC Key (yes / no) [yes]: yes
Log level (panic, fatal, error, warning, info, debug, trace) [info]: info
Configuration file successfully created!

Specify your Data Plane API credentials for the HAProxy configuration file.
HAProxy Data Plane API Username [None]: admin
HAProxy Data Plane Password [None]: adminpwd
Enable HAProxy force restart (yes / no) [no]: yes
Encrypt HAProxy Data Plane API password (yes / no) [yes]: yes
HAProxy configuration file successfully created!
Run the connector with the following command.
./sectigo-haproxy-connector

Resulting SCM configuration file (scm.yaml)

sectigo:
  acme:
    apiUrl: "https://acme-qa.secure.trust-provider.com/v2/DV"
    kid: "2a82af7331a11fc8b9ec2793d924b0aa"
    hmacKey: "4Of1p44zWexJ1lUQcQmozXyisMHEBAGwKOm7V6hqOon+CcpZfudSSXl58shivtyM/GcR1KTm8tjeqPXYcmhcRs0yFjcJSdNtvs7MCso2EotOneAwDLFf7LzshNtMm+vDUP8di1JntaLevRjRiG4m2exUTvxwVQI8NYksizHAp7NdkpsyxOC01Tp2tdZ0Pny4/hI1PL9a2i/9I/l5i7GYm3QOjsARoBSAuCfaN7ntHTN2yrLQEdSBHGeoOTBMUNJBpTcnOv2MGnvFeTivFIRISNO3jJmMwOPrFqdNrM7xux3+lLnAvQn2aECPw4SA5zWj0vwKXRy913LajcVH4NJ06Q=="
    timeout: 30
  logger:
    level: info
  encrypted: rsa_key_scm.pri

The following table describes the parameters in the scm.yaml file.

Parameter Description

Parameter	Description
`apiURL`	The URL of the ACME service
`kid`	The key ID for external account binding
`hmacKey`	The HMAC key for external account binding
`timeout`	The timespan to wait before the request times out. If you’re getting a timeout error during an enrollment attempt, increase the value of timeout. The default value is 30 seconds.
`level`	The log level to use. The possible values are `panic`, `fatal`, `error`, `warning`, `info`, `debug`, and `trace`. The default value is `info`. For more information, see Level logging.
`encrypted`	Specifies whether to encrypt the HMAC key

apiURL

The URL of the ACME service

kid

The key ID for external account binding

hmacKey

The HMAC key for external account binding

timeout

The timespan to wait before the request times out. If you’re getting a timeout error during an enrollment attempt, increase the value of timeout. The default value is 30 seconds.

level

The log level to use. The possible values are panic, fatal, error, warning, info, debug, and trace. The default value is info. For more information, see Level logging.

encrypted

Specifies whether to encrypt the HMAC key

Resulting HAProxy configuration file (haproxy.yaml)

haproxy:
    configuration-file: /etc/haproxy/haproxy.cfg
    bin: /usr/sbin/haproxy
    backups: 4
    transaction-dir: /tmp/haproxy
    data-plane-api:
        credentials:
            username: admin
            password: warw6LgCa0nPxA6iiYl8txmCSbYEh9dX2Lt7TlmkzIEqWIcesM56CSWOkDkXf6RpQbEhHW0JFHOOCg7bZHajajF1b0eBa5BPxRKVJ62jbSSrL9azPro7e5q4i1IgugXTgX3U84O/ACXPlIUyc2d7kLT/8OzqThxpQMTN8A82iH8nziwC4MW98TZ6unMmIoncCyoruzMPPwW4a/wF3uOGNa+MxnLjdoys6k1L8IoR6reA+nBwyl5AwY6PV2nniDuCOA4jv1L6rhygJJVt0p/I9unLaK197yJkALPKRavCuk0weY1OejfE0xvqUxIWohupiOgbQTCNgmhMEPtUuQgi9A==
        force-reload-enabled: "true"
        root:
            url: http://localhost:5555/v2
        storage:
            url: /services/haproxy/storage/ssl_certificates
        health:
            url: /health
    encrypted: rsa_key_haproxy.pri

Sample HAProxy config file

The following is a sample haproxy.cfg file from the /etc/haproxy/ directory of HAProxy Community.

global
master-worker

defaults unnamed_defaults_1
mode http
timeout http-request 10s
timeout connect 5s
timeout client 10s
timeout server 10s

frontend myfrontend from unnamed_defaults_1
  bind :80
  # the following line redirects HTTP to HTTPS
  http-request redirect scheme https unless { ssl_fc }
  default_backend web_servers

backend web_servers from unnamed_defaults_1
server myserver 127.0.0.1:8000

program api
command dataplaneapi -f /etc/haproxy/dataplaneapi.hcl
no option start-on-reload

Sample Data Plane API config file

The following is a sample dataplaneapi.hcl file from the /etc/haproxy/ directory of HAProxy Community.

dataplaneapi {
  host = "0.0.0.0"
  port = 5555

  user "admin" {
    insecure = true
    password = "adminpwd"
  }

  transaction {
    transaction_dir = "/tmp/haproxy"
  }
}

haproxy {
  config_file = "/etc/haproxy/haproxy.cfg"
  haproxy_bin = "/usr/sbin/haproxy"

  reload {
    reload_cmd  = "service haproxy reload"
    restart_cmd = "service haproxy restart"
    reload_delay = "5"
  }
}