Agent installation and configuration

This section provides details on the following topics:

  • Agent installation

  • Agent configuration

  • Running the agent

Agent installation

The agent needs access to the internet to connect to the Sectigo ACME server, and access to F5 to install the certificates.
All the prerequisites provided in Prerequisites should be satisfied before executing the following steps.
  1. Login as root to the Linux client machine.

  2. Navigate to the /opt directory.

  3. Copy the <Sectigo_ACME_F5_Agent>.tgz to the /opt directory.

  4. Untar the <Sectigo_ACME_F5_Agent>.tgz from the /opt directory:

    tar xvf <Sectigo_ACME_F5_Agent V2.0>.tgz

    This will create a sub-folder called sectigo under /opt.

  5. Navigate to the /opt/sectigo directory.

  6. Run ./install.sh from the /opt/sectigo directory.

Agent configuration

The agent configuration involves setting environment variables and defining the configuration file.

Set environment variables

Update the env file, which is provided with the package, with values for the variables corresponding to your ACME account in SCM (or corresponding to the details received from Sectigo Onboarding Team). The shell script automatically reads the variables.

ACME_URL=<ACME URL VALUE>
ACME_EXTERNAL_ACCOUNT_ID=<KEYID>
ACME_EXTERNAL_ACCOUNT_KEY=<HMAC VALUE>
ACME_NON_INTERACTIVE_EMAIL= <emailID>
ACME_USER_AGENT_COMMENT=sectigo/acme-dockerclient
ACME_DAYS_TO_RENEW=30

The following table describes environment variables on which the agent depends.

Variable Mandatory Description

ACME_NON_INTERACTIVE_EMAIL

Yes

An email address for important account notifications

ACME_EXTERNAL_ACCOUNT_ID

Yes

The identifier for External Account Binding used to select the customer account with Sectigo

ACME_EXTERNAL_ACCOUNT_KEY

Yes

The keyed-hash message authentication (HMAC) key for External Account Binding

ACME_URL

Yes

The URL of the ACME service

ACME_USER_AGENT_COMMENT

No

A comment added to the User-Agent header when communicating with the ACME service

ACME_DAYS_TO_RENEW

No

The certificate renewal period. The default value is 30 days.

Define the configuration file

Configuration files for F5 and certificate configuration are YAML-based. The agent is designed to consider each YAML file as representing one virtual server configuration.

To define a configuration file:

  1. Create a directory called sectigo under the /etc directory (/etc/sectigo) with root privilege.

  2. Create a YAML file (.yaml) and define the configuration parameters in this file, as per your environment.

  3. Copy the f5_demo.yaml file from the package to the /etc/sectigo directory and modify the values. The following are sample values for the file:

    name: demo1
    version: v1
    
    devices:
    - name: device1
      #device domains which will override global domains
      common_name: example.iiswebserver.com
      san_domains:
         - example.slitaz.com
         - example.nginxwebservere.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
    If the virtualservers parameter is not specified, the certificate is not bound to the virtual server, but is still installed on the appliances.
    The YAML file contains a username and password, ensure that only the root users can access it.

The following table describes the parameters of the .yaml file.

Parameter Description

version

Must be set to v1

name

The name of the certificate used by the Certbot command. This value is passed to the <configured_name> parameter in the certbot run command. Must be unique across all configuration files; otherwise, unrelated certificates are overwritten.

common_name

The common name for the device

san_domains

The list of SANs associated with the common_name

devices

Each entry specifies an external device or appliance on which the certificate is to be installed:

  • name: Optional name of the device. The default is host.

  • type: Must be set to F5 or Netscaler

  • protocol: Must be set to http or https

  • username: The username needed to access the end device

  • password: The password needed to access the end device

    If a credentials file is specified, both username and password can be omitted.
  • key_type: rsa or ecdsa

  • key_size:

    • RSA: 2048, 3072, or 4096

    • ECDSA: secp256r1, secp384r1, or secp521r1

  • bigip_partition: The partition name (default/Common)

  • bigip_clientssl_parent: The clientssl parent

  • big_device_group: The name of the HA group (optional)

  • bigip_list: A list of IP addresses separated by commas if the F5 appliances are in a HA group.

  • bigip_unused_profile: Old_Profile_Name (if specified, the old profile will be replaced with the new client SSL profile)

  • virtualservers:

    • name: The name of the server

Running the agent

Run the agent with the following command.

[email protected]<hostname> /opt/sectigo#./start_acme.py

All available options for the command.

start_acme.py [-h] [config -o, -y, -c] [show_version] [-L {critical,error,warning,info,debug} ]

Get more details about the agent

To get more details about the agent, run the command with the -h flag.

start_acme.py -h

Validate the YAML files

To validate the YAML files stored at /etc/sectigo, run the command with the --operation or -o flag.

start_acme.py config --operation check_yaml

Check the version of the agent

To check the version of the agent, run the following command.

start_acme.py show_version

Enable certificate management on specific virtual servers

To enable certificate management on specific virtual servers, run the command with the --yamlfiles or -y flag.

start_acme.py config --yamlfiles demo_config1.yaml,demo_config2.yaml

By default, the .yaml files are resolved relative to the /etc/sectigo folder or the CFG_LOCATION env value (if present) when using the following command.

./start_acme.py config -y config1.yaml

Alternatively, you can specify the full path to yaml files with any of the following commands.

./start_acme.py config -y /path/to/config1.yaml
./start_acme.py config -y /path/to/config1.yaml,/path/to/config2.yaml
./start_acme.py config -y /path/to/config1.yaml /path/to/config2.yaml
./start_acme.py config -y /path/to/*
./start_acme.py config -y /path/to/*.yaml

Specify an external credentials file

To specify an external credentials file, run the command with the --credentials or -c flag.

start_acme.py config -c /path/to/credentials.txt

Credential files must have each set of credentials on a new line and the credentials must be structured as:

<bigip_address1>;<username>;<password>

For example:

24.156.99.202;AverageUser1;notGuest

The plugin automation

Once the YAML files are configured, the agent reads the configuration of external appliances for which certificates are to be enrolled, requests the certificates, and installs them on the configured devices.