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