arensb.truenas.certificate module – Manage host certificates.

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.

New in arensb.truenas 1.12.0

Synopsis

  • Allows uploading and revoking host certificates.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

certificate

string

Used instead of src to specify a certificate inline.

name

string / required

Name of the certificate. This serves as an identifier for Ansible.

passphrase

string

Passphrase for the certificate.

private_key

string

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

private_keyfile

path

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

revoked

boolean

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

Perhaps counterintuitively, only specifying name and revoked=yes will cause an error when the cert does not exist. This is because the cert needs to be uploaded before it can be revoked.

Choices:

  • false ← (default)

  • true

src

path

Pathname of the file containing the certificate.

See also certificate.

This file must only contain the certificate, not any signing certificates.

state

string

Whether the certificate should exist or not.

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 certificates.

  • Although TrueNAS supports creating certificates 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 certificates as part of your PKI system, and upload them to TrueNAS devices. Failing that, you can manually generate a cert in the TrueNAS console, and download it to your Ansible server.

Examples

- name: Install an existing cert from a file.
  arensb.truenas.certificate:
    name: my_cert
    src: /etc/pki/truenas-host.cert

- name: Same, but include a private key and passphrase.
  arensb.truenas.certificate:
    name: my_cert
    src: /etc/pki/truenas-host.cert
    private_key: |-
      -----BEGIN PRIVATE KEY-----
      MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC9QCpnXKNXoOdx
      ...
    passphrase: "squeamish ossifrage"

- name: Revoke a cert
  arensb.truenas.certificate:
    name: my_cert
    revoked: true

- name: Remove a cert
  arensb.truenas.certificate:
    name: my_cert
    state: absent

Return Values

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

Key

Description

certificate

dictionary

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

Only returned when a certificate is created.

Returned: success

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