certbot-deployer-bigip 2.0.1

Certbot Deployer plugin for deploying certificates to F5 BIG-IP devices

certbot_deployer_bigip

Certbot Deployer plugin for deploying certificates to F5 BIG-IP devices

BIG-IP is a collection of hardware platforms and software solutions providing services focused on security, reliability, and performance. - What is BIG-IP?

This tool runs as a Certbot "deploy hook", and uploads and installs Certbot certificates to BIG-IP and optionally associates them with a profile.

Requires

• Python 3.9+

• A local user on the target BIG-IP device with Terminal Access set to Advanced shell (see Users and SSH and shells)

• SSH configured to connect as the local BIG-IP user (see Users and SSH and shells)

• Compatible BIG-IP software version

  These are the minimum supported versions of BIG-IP devices according to K15462: Managing SSL certificates for BIG-IP systems using tmsh. Check the article for the full list of supported versions.

  • BIG-IP AAM
    • 12.X.X
  • BIG-IP AFM
    • 11.X.X
  • BIG-IP Analytics
    • 11.X.X
  • BIG-IP APM
    • 11.X.X
  • BIG-IP ASM
    • 11.X.X
  • BIG-IP LTM
    • 11.X.X
  • BIG-IP Edge Gateway
    • 11.X.X
  • BIG-IP WebAccelerator
    • 11.X.X
  • BIG-IP WOM
    • 11.X.X

Installation

You can install with pipx:

pipx certbot_deployer_bigip

You can install with pip:

python3 -m pip install certbot_deployer_bigip

Or install from source:

git clone <url>
pip install certbot_deployer_bigip

Usage

Examples

All examples assume the tool is being run as a Certbot deploy hook, and the environment variable RENEWED_LINEAGE points to the live certificate directory just updated by Certbot.

Install certificate on the BIG-IP device named with its expiry timestamp as host.domain.tld.YYY-MM-DDTHH:MM:SS (the default)

certbot-deployer bigip --host bigip.domain.tld

Install certificate on the BIG-IP device and then synchronize device changes to a device group

certbot-deployer bigip --host bigip.domain.tld --sync-group yoursyncgroup

Install certificate on the BIG-IP device and then associate it with a client-ssl profile. If the profile does not exist, it will be created.

certbot-deployer bigip --host bigip.domain.tld --profile-name yourprofile --profile-type client-ssl

Print out the deployment tasks that would be taken, but do not run them

certbot-deployer bigip --host bigip.domain.tld --dry-run

Users and SSH and shells

This tool runs all of its tasks on the target devices via SSH.

It expects:

• the local user on the BIG-IP to have Terminal Access set to Advanced shell and with appropriate permissions
• a working SSH configuration to connect to the target devices

Note: this tool used to require Terminal Access set to tmsh (lower privilege), but as of BIG-IP software version 15.1.5.1 Advanced shell is now required to transfer certificate files. For more, see K49856182: SCP path not allowed after upgrade to software version 15.1.5.1

BIG-IP user permissions

The local user on the target BIG-IP device must be granted at least the Certificate Manager role in order to deploy certificates.

In order to also create/update the associated profiles on the BIG-IP, the user will require the Administrator role.

SSH

Configuration for the SSH connection can be done via the configuration of the user running the tool.

E.g.:

# /home/user/.ssh/config
Host bigip-device.domain.tld
    User certbot_deploy
    Identityfile /home/user/.ssh/id_rsa
    Port 2022

Reference

usage: certbot-deployer bigip [-h] [--host HOST]
                              [--dest-temp-dir DEST_TEMP_DIR]
                              [--cert-name CERT_NAME]
                              [--profile-name PROFILE_NAME]
                              [--profile-type PROFILE_TYPE]
                              [--sync-group SYNC_GROUP] [--dry-run]

BIG-IP subcommand
        Certbot Deployer plugin for deploying certificates to F5 BIG-IP devices


options:
  -h, --help            show this help message and exit
  --host HOST, -H HOST  BIG-IP host to target with changes.
  --dest-temp-dir DEST_TEMP_DIR, -t DEST_TEMP_DIR
                        The temp path on the BIG-IP to use when uploading the
                        certificates for installation. This tool will try to
                        zero out the certificates at the end of the run once
                        they are ingested into the BIG-IP config, but you
                        should probably try to put them in a "safe" place.
                        Default: `/var/tmp`
  --cert-name CERT_NAME, -c CERT_NAME
                        The name to give the certificate objects on the BIG-
                        IP. If not given, this tool will use the Common Name
                        from the certificate with the ISO8601-formatted `Not
                        After` value appended, e.g. `host.domain.tld.YYY-MM-
                        DDTHH:MM:SS`
  --profile-name PROFILE_NAME, -p PROFILE_NAME
                        The name of the profile to modify/create to use the
                        deployed certificateIf given, the corresponding
                        `--profile-type` is also required. If neither are
                        given, this tool will not create/modify any profiles.
  --profile-type PROFILE_TYPE, -r PROFILE_TYPE
                        The type of profile to create if necessary e.g.
                        `client-ssl`. See BIG-IP docs for details on all
                        profile types. If given, the corresponding `--profile-
                        name` is also required. If neither are given, this
                        tool will not create/modify any profiles.
  --sync-group SYNC_GROUP, -s SYNC_GROUP
                        The sync-group to synchronize to after the
                        certificates are deployed. This tool will not try to
                        sync the BIG-IP node if this argument is not given
  --dry-run, -d         Report the workflow steps that would run without
                        actually running them

Workflow

An outline of the steps that this tool will take:

1. (optionally) abort if sync status is not In Sync
2. Upload the key
3. Install the key
4. Verify key installation
5. Upload the certificate
6. Install the certificate
7. Verify certificate installation
8. Zero out the uploaded key file now that it is installed
9. Zero out the uploaded certificate file now that it is installed
10. Save the running config
11. (optionally) Create/modify a BIG-IP profile to use the new certificate and key
12. (optionally) synchronize to BIG-IP sync-group

Try the --dry-run option to have it list the steps that it would run for your specific configuration.

Limitations

• "Rollbacks" are not yet implemented (and may not be) in the case of failure during deployment.
  • This should not be able to go more "wrong" than failing to synchronize after modifying a profile (if one is even configured), as no other operations should be touching any existing BIG-IP resources.

Contributing

Merge requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

To run the test suite:

# Dependent targets create venv and install dependencies
make

Please make sure to update tests along with any changes.

License

License :: OSI Approved :: MIT License