Ansible Role - Certificate Generator

Ansible Role to create certificates to use on a linux server.

Molecule Integration-Tests:

• Status: |
• Logs: API | Short | Full

Internal CI: Tester Role | Jobs API

Tested:

• Debian 11
• Debian 12

---

Install

# latest
ansible-galaxy role install git+https://github.com/O-X-L/ansible-role-certs

# from galaxy
ansible-galaxy install oxlorg.certs

# or to custom role-path
ansible-galaxy install oxlorg.certs --roles-path ./roles

# install dependencies
ansible-galaxy install -r requirements.yml

---

Usage

Notes

The self-signed and minimal-ca modes will only create a single certificate per run.

Re-runs can save some overhead by using the 'certs' tag.

The LetsEncrypt mode will create/remove multiple certificates as defined.

Config

Example for LetsEncrypt config:

certs:
  mode: 'le_certbot'
  path: '/etc/apache2/ssl'
  letsencrypt:
    certs:
      myNiceSite:
        domains: ['myRandomSite.net', 'oxl.at']
        email: 'certs@template.oxl.at'
    service: 'apache'

Example for Self-Signed config:

certs:
  mode: 'selfsigned'  # or 'snakeoil' (if faster)
  # choose 'ca' instead if you use dns-names
  #   some browsers won't let you connect when using self-signed ones
  path: '/etc/nginx/ssl'
  group_key: 'nginx'
  owner_cert: 'nginx'
  cert:
    cn: 'My great certificate!'
    org: 'AnsibleGuy'
    country: 'AT'
    email: 'certs@template.oxl.at'
    domains: ['mySoGreat.site', 'oxl.at']
    ips: ['192.168.44.2']
    pwd: !vault ...

Example for minimal-CA config:

certs:
  mode: 'ca'
  path: '/etc/ca/certs'
  mode_key: '0400'
  cert:
    name: 'custom_file_name'  # extension will be appended
    cn: 'My great certificate!'
    org: 'AnsibleGuy'
    country: 'AT'
    email: 'certs@template.oxl.at'
    domains: ['mySoGreat.site', 'oxl.at']
  ca:
    path: '/etc/ca'
    cn: 'SUPER CertificateAuthority'
    org: 'AnsibleGuy'
    country: 'AT'
    email: 'certs@template.oxl.at'
    pwd: !vault ...

Using the minimal-CA you can create multiple certificates signed by the CA by re-running the role with changed 'cert' settings.

You might want to use 'ansible-vault' to encrypt your passwords:

ansible-vault encrypt_string

Execution

Run the playbook:

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml --ask-vault-pass

There are also some useful tags available:

• certs => ignore ca tasks; only generate certs
• selfsigned
• config
• certs

To debug errors - you can set the 'debug' variable at runtime:

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml -e debug=yes

---

Functionality

• Package installation

  • Ansible dependencies (minimal)
  • Crypto Dependencies

• Configuration

  • Four Possible Modes:

    • Generate Self-Signed certificate
    • Use a minimal Certificate Authority to create signed certificates
    • Configure LetsEncrypt-Certbot to generate publicly valid certificates
      • Supported for Nginx and Apache
      • Host needs to have a valid public dns record pointed at it
      • Needs to be publicly reachable over port 80/tcp

  • Default config:

    • Mode => Self-Signed

---

Info

• Note: this role currently only supports debian-based systems

• Note: Most of the role's functionality can be opted in or out.

  For all available options - see the default-config located in the main defaults-file!

• Note: If you have the need to mass manage certificates - you might want to check out the oxlorg.pki role that enables you to create and manage a full Public Key Infrastructure.

• Note: The certificate file-name (name variable as defined or else CommonName) will be updated:

  • spaces are transformed into underlines
  • all Characters except "0-9a-zA-Z." are removed
  • the file-extension (crt/chain.crt/key/csr) will be appended

• Warning: Not every setting/variable you provide will be checked for validity. Bad config might break the role!

• Info: For LetsEncrypt renewal to work, you must allow outgoing connections to:

  80/tcp, 443/tcp+udp to acme-v02.api.letsencrypt.org, staging-v02.api.letsencrypt.org (debug mode) and r3.o.lencr.org