Frequently Asked Questions (FAQ)


TABLE OF CONTENTS:

What You Need To Know About Logging.

FortiAnalyzer Ansible has requests and intermediate data stored in a log file /tmp/fortianalyzer.ansible.log to ease troubleshooting.

Logging is only enabled by setting enable_log option for a task.

When to Use Parameter bypass_validation?

You are not encouraged to use bypass_validation except that you are sure something is wrong with the parameter definition and you want to fix them on you own immediately. by setting bypass_validation to True, the content of parameters is not examined, thus enabling you to send any parameters to FortiAnalyzer backend server.

To use this parameter, you are likely to look up the defnition for an API on fortiapi spec page.

How To Monitor FortiAnalyzer Task?

There are lots of FortiAnalyzer APIs which return a task identifier. the task itself is running in the remote FortiAnalyzer server. you must poll the task periodically to see whether the task terminates or goes wrong.

- name: poll the task
  fmgr_fact:
    facts:
      selector: "task_task"
      params:
        task: "{{installing_task.meta.response_data.taskid}}"
  register: taskinfo
  until: taskinfo.meta.response_data.percent == 100
  retries: 30
  delay: 5
  failed_when: taskinfo.meta.response_data.state == 'error'

  • until - the condition to quit polling, this is the condition to quit normally

  • retries - how many times you want to try to check the status of running task.

  • delay - checking frequency: 1/delay.

  • failed_when - failing condition in which you regard the task a failure, this is the condition to quit abnormally

How To Use FortiAnalyzer Ansible without Providing Username and Password?

FortiAnalyzer Ansible collection supports three different ways to login.

  • Providing ansible_user and ansible_password.

  • Using access token.

  • Using the Forticloud access token (only for the FortiAnalyzer managed by Forticloud).

To avoid unexpected behaviour, please only use one login method at a time.

The access token login method is only valid for the latest versions of FortiAnalyzer v7.

If you want to use the access token to login FortiAnalyzer Ansible, please go to the CLI interface of FortiAnalyzer and enter the following command:

config system admin user
  edit api_user_example_name
    set profileid Super_User
    set user_type api
    set rpc-permit read-write
  next
end

Then, use execute api-user generate-key api_user_example_name and you will get an API key.

FAZ-VM64 # execute api-user generate-key api_user_example_name
New API key: XXXXXXXXXXXXXXX

You can use this API key in your playbook, and you don’t need to provide ansible_user and ansible_password anymore.

Here is an example of how to use access token:

- hosts: fortianalyzers
  connection: httpapi
  collections:
    - fortinet.fortianalyzer
  vars:
    ansible_httpapi_use_ssl: yes
    ansible_httpapi_validate_certs: no
    ansible_httpapi_port: 443
  tasks:
    - name: get fact
      fmgr_fact:
        access_token: <your access_token>
        facts:
          selector: "sys_status"
      register: result
    - name: Display response
      debug:
        var: result

How To Use FortiAnalyzer Ansible With FortiAnalyzer Cloud?

FortiAnalyzer can be managed by forticloud. Example of a fortianalyzer cloud host: 1234567.us-west-1.fortianalyzer.forticloud.com.

It’s possible to authenticate Ansible client with forticloud API access token. forticloud_access_token is the module option to enable forticloud access token based authentication.

To obatin access token, it’s required to register an API user in https://support.fortinet.com/iam/#/api-user and download the crendentials which contains needed API user ID and password. it’s strongly recommended that you keep it safe!

below is an example to obtain access token:

- hosts: fortianalyzers
  collections:
    - fortinet.fortianalyzer
  connection: httpapi
  vars:
    ansible_httpapi_use_ssl: True
    ansible_httpapi_validate_certs: False
    ansible_httpapi_port: 443
    FORTICLOUD_APIID: "3EE835AF-F9F8-48........"
    FORTICLOUD_PASSWD: "36b25667c61b2.........."
  tasks:
    - name: Generate Access Token From FortiCloud Auth Server.
      uri:
        url: https://customerapiauth.fortinet.com/api/v1/oauth/token/
        method: POST
        body_format: json
        return_content: true
        headers:
          Content-Type: application/json
        body: '{"username": "{{ FORTICLOUD_APIID }}", "password": "{{ FORTICLOUD_PASSWD }}", "client_id": "FortiAnalyzer", "grant_type": "password"}'
      register: tokeninfo

then in subsequent tasks, we can reference returned token:

- name: get fact
  faz_fact:
    forticloud_access_token: '{{ tokeninfo.json.access_token }}'
    enable_log: true
    facts:
      selector: "sys_status"
  register: result
- name: Display response
  debug:
    var: result

Access token usually expires in hours, you should always renew one in case of failure.