Ansible playbook task

An ansible playbook task will execute an ansible playbook targeting several nodes.

When to use an ansible playbook task

Here are the main benefits of using this type of task:

  • CTFreak nodes & SSH credentials will be used as the ansible inventory to run your playbook (in other words, you delegate to CTFreak the generation of the ansible inventory that will be used to run your playbook).

  • Playbook content can be defined either in a local file or within the task itself (allowing editing via the API or web interface).

  • A dedicated log file will be generated for each node for which the playbook is executed.

  • If required, a playbook can be re-executed only on nodes that failed during a previous execution.

If you’re not in this use case, you can always create a local command task to directly run the ansible-playbook executable with the parameters of your choice.

Prerequisites

  • Ansible >= 2.17 and sshpass must be installed on the same server running your CTFreak instance (we therefore advise you to install CTFreak manually, or via a homemade docker image to embed the ansible release of your choice).

  • Your CTFreak instance must be running on a Linux or FreeBSD host.

  • ansible-playbook executable must be accessible from the PATH of the user account running your CTFreak instance.

Restrictions

  • Connection to windows nodes will only be via SSH, as the WinRM protocol is not supported.

  • Given that ansible playbook tasks have write access to CTFreak configuration files, only an administrator can create or edit this type of task.

Task characteristics

In addition to the common task characteristics, here are those specific to ansible playbook tasks.

Base folder

The folder from which the ansible-playbook executable will be launched.

If left empty, the working directory of the CTFreak instance will be used by default.

To be used, for example, if:

  • You want to use a specific ansible.cfg file
  • Your playbook or other resources necessary for their execution are stored locally (in a git repo cloned on the server, …)

Playbook source

Choose where the playbook content is defined:

  • Inline → in the task itself
  • File → in a local YAML file

Playbook file

If you have selected a file playbook source, you must specify the path of the file (relative to the base folder) in yaml format.

NB: Since CTFreak dynamically generates the ansible inventory based on selected nodes, playbook content must not contain any restrictions on target hosts, and must therefore contain hosts: all.

Playbook content

If you have selected an inline playbook source, you must define its content in YAML format.

NB: Since CTFreak dynamically generates the ansible inventory based on selected nodes, playbook content must not contain any restrictions on target hosts, and must therefore contain hosts: all.

Check mode

When enabled, the playbook will run in check/simulation mode, ideal for validating playbook content.

Node Set filter

Filter (by names and tags) the nodes on which the playbook will operate.

Max. number of concurrent playbook executions

When a playbook is to run on several nodes, you can specify the maximum number of nodes to be processed concurrently.

Using project constants

Project constants can be used in ansible playbook content as external variables prefixed with CPC_ (for CTFreak Project Constant).

Here’s an example using a project constant named NUMBER_OF_RETENTION_DAYS:

- hosts: all
  tasks:
    - name: Show number of retention days
      ansible.builtin.debug:
        msg: "Message: {{CPC_NUMBER_OF_RETENTION_DAYS}}"

If you later decide to increase the retention period, you’ll only need to modify the constant value to affect all ansible playbooks referring to it.

Using task parameters

Like project constants, task parameters can be used in ansible playbook content as external variables prefixed with CTP_ (for CTFreak Task Parameter).

Here’s an example using a text task parameter named FIRST_NAME:

- hosts: all
  tasks:
    - name: Show first name
      ansible.builtin.debug:
        msg: "Message: {{CTP_FIRST_NAME}}"

Task parameters values are converted to text format when assigned to an environment variable.

The following conversion rules are applied according to parameter type:

  • Checkbox → Checked: true, Unchecked: false
  • Date → Formatting with the YYYY-MM-DD pattern
  • Selector, Integer and Text → No specific formatting