Run Your First Playbook

This document explains how to run your first FortiOS Ansible playbook.

With FortiOS Galaxy collection, you are always recommended to run FortiOS module in httpapi manner. The first step is to prepare your host inventory with which you can use ansible-vault to encrypt or decrypt your secrets for the sake of confidentiality.

Prepare host inventory

in our case we create a file named hosts:

fortigate01 ansible_host= ansible_user="admin" ansible_password="password"
fortigate02 ansible_host= ansible_user="admin" ansible_password="password"
fortigate03 ansible_host= fortios_access_token=<your access token>


FortiOS supports two ways to authenticate Ansible: ansible_user and ansible_password pair based; fortios_access_token access token based. Access token based way is prefered as it is safer without any password explosure and access token guarantees request source location is wanted.

for how to generate an API token, visit page FortiOS API Spec.

Write the playbook

in the example: test.yml we are going to modify the fortigate device’s hostname:

- hosts: fortigate03
  connection: httpapi
  - fortinet.fortios
   vdom: "root"
   ansible_httpapi_use_ssl: true
   ansible_httpapi_validate_certs: false
   ansible_httpapi_port: 443
   - name: Configure global attributes.
        vdom:  "{{ vdom }}"
        access_token: "{{ fortios_access_token }}" #if you prefer access token based authentication, add this line.
            hostname: 'CustomHostName'

there are several options which might need you special care:

  • connection : httpapi is preferred.

  • collections : The namespace must be fortinet.fortios

  • ansible_httpapi_use_ssl and ansible_httpapi_port: by default when your fortiOS device is licensed, the https is enabled. there is one exception: uploading vmlicence to a newly installed FOS instance, where you should set ansible_httpapi_use_ssl: no and ansible_httpapi_port: 80. Please see Import licence to FOS for more details.

Run the playbook

ansible-playbook -i hosts test.yml

you can also observe the verbose output by adding option at the tail: -vvv.