arensb.truenas.certificate_authority module – Manage Certificate Authorities.

Note

This module is part of the arensb.truenas collection (version 1.12.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install arensb.truenas.

To use it in a playbook, specify: arensb.truenas.certificate_authority.

New in arensb.truenas 1.12.0

Synopsis

  • Allows uploading and revoking CA certs. These CA certs are used as part of a key infrastructure to sign host certificates.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

certificate

aliases: ca, cert, ca_cert

string

Used instead of src to specify a certificate inline.

name

string / required

Name of the CA.

passphrase

string

Passphrase for the CA cert.

When uploading a CA certificate, the passphrase for the private key must be supplied, if there is one.

private_key

string

Used instead of private_keyfile to specify a CA private key inline.

When uploading a CA certificate, the private key must be supplied, if there is one.

private_keyfile

path

Pathname of the file containing the CA’s private key.

revoked

boolean

Set to true to revoke a CA. It is possible to upload a CA and immediately revoke it, though it is not clear why this might be useful.

Only CAs with a private key can be revoked.

Note that once revoked, a CA cannot be restored. This module can try to un-revoke a CA, but it will fail.

Choices:

  • false ← (default)

  • true

src

path

Pathname of the file containing the certificate.

See also certificate.

state

string

‘present’: Ensure that the CA cert is installed.

‘absent’: Ensure that the CA cert is absent. Revoke it if necessary.

Choices:

  • "absent"

  • "present" ← (default)

Notes

Note

  • There appears to be a bug in TrueNAS 25.04.0 that prevents installing certificates with keys greater than 2048 bits long. In fact, 2048 seems to be the only usable key size for CAs.

  • Although TrueNAS supports creating CAs in the console, this module does not. It is not immediately clear how this should work in an idempotent Ansible module. At least for now, it is recommended that you generate CAs as part of your PKI system, and upload them to TrueNAS devices. Failing that, you can manually generate a CA in the TrueNAS console, and download it to your Ansible server.

Examples

- name: Install a CA cert from a file
  arensb.truenas.certificate_authority:
    name: my_ca_cert
    src: /etc/pki/my-ca.cert

- name: Install a CA cert and its key
  arensb.truenas.certificate_authority:
    name: my_ca_cert
    src: /etc/pki/my-ca.cert
    private_keyfile: /etc/pki/my-ca.key
    passphrase: "Open, sesame!"

- name: Install a CA cert from a string
  arensb.truenas.certificate_authority:
    name: my_ca_cert
    certificate: |-
      -----BEGIN CERTIFICATE-----
      MIIFdTCCA12gAwIBAgIUQZLjifloJRGBwalKcoODV20BmhUwDQYJKoZIhvcNAQEL
      ...
      B5A/Sn7DTfQz
      -----END CERTIFICATE-----

- name: Remove and revoke a CA cert
  arensb.truenas.certificate_authority:
    name: my_ca_cert
    state: absent

- name: Remove a CA cert, even if it can't be revoked
  arensb.truenas.certificate_authority:
    name: my_ca_cert
    state: absent
    force: yes

- name: Revoke a CA cert, but keep it in the list.
  arensb.truenas.certificate_authority:
    name: my_ca_cert
    state: present
    revoked: yes

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

ca_cert

dictionary

A data structure describing a newly-created or -installed CA certificate.

Only returned when a certificate is created.

Returned: success

Sample: {"id": "6841f242-840a-11e6-a437-00e04d680384", "method": "certificateauthority.create", "msg": "method", "params": [{"certificate": "Certificate string", "create_type": "CA_CREATE_IMPORTED", "name": "imported_ca", "privatekey": "Private key string"}]}