:source: fmgd_system_fortiguard.py
:orphan:
.. _fmgd_system_fortiguard:
fmgd_system_fortiguard -- Configure FortiGuard services.
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
.. versionadded:: 1.1.0
.. contents::
:local:
:depth: 1
Synopsis
--------
- This module is able to configure a FortiManager device.
- Examples include all parameters and values need to be adjusted to data sources before usage.
- Tested with FortiManager v7.x.
Requirements
------------
The below requirements are needed on the host that executes this module.
- ansible-core>=2.16.0
FortiManager Version Compatibility
----------------------------------
.. raw:: html
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
Parameters
----------
.. raw:: html
- access_token -The token to access FortiManager without using username and password. type: str required: false
- bypass_validation - Only set to True when module schema diffs with FortiManager API structure, module continues to execute without validating parameters. type: bool required: false default: False
- enable_log - Enable/Disable logging for task. type: bool required: false default: False
- forticloud_access_token - Access token of forticloud managed API users, this option is available with FortiManager later than 6.4.0. type: str required: false
- proposed_method - The overridden method for the underlying Json RPC request. type: str required: false choices: set, update, add
- rc_succeeded - The rc codes list with which the conditions to succeed will be overriden. type: list required: false
- rc_failed - The rc codes list with which the conditions to fail will be overriden. type: list required: false
- workspace_locking_adom - Acquire the workspace lock if FortiManager is running in workspace mode. type: str required: false choices: global, custom adom including root
- workspace_locking_timeout - The maximum time in seconds to wait for other users to release workspace lock. type: integer required: false default: 300
- device - The parameter in requested url type: str required: true
- system_fortiguard - Configure FortiGuard services. type: dict
- antispam_cache (Alias name: antispam-cache) Enable/disable fortiguard antispam request caching. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- antispam_cache_mpercent (Alias name: antispam-cache-mpercent) Maximum percentage of fortigate memory the antispam cache is allowed to use (1 - 15). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- antispam_cache_ttl (Alias name: antispam-cache-ttl) Time-to-live for antispam cache entries in seconds (300 - 86400). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- antispam_expiration (Alias name: antispam-expiration) Antispam expiration. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- antispam_force_off (Alias name: antispam-force-off) Enable/disable turning off the fortiguard antispam service. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- antispam_license (Alias name: antispam-license) Antispam license. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- antispam_timeout (Alias name: antispam-timeout) Antispam query time out (1 - 30 sec, default = 7). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- anycast_sdns_server_ip (Alias name: anycast-sdns-server-ip) Ip address of the fortiguard anycast dns rating server. type: str
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- anycast_sdns_server_port (Alias name: anycast-sdns-server-port) Port to connect to on the fortiguard anycast dns rating server. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- auto_firmware_upgrade (Alias name: auto-firmware-upgrade) Enable/disable automatic patch-level firmware upgrade from fortiguard. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- auto_firmware_upgrade_day (Alias name: auto-firmware-upgrade-day) Allowed day(s) of the week to install an automatic patch-level firmware upgrade from fortiguard (default is none). type: list choices: [sunday, monday, tuesday, wednesday, thursday, friday, saturday]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- auto_firmware_upgrade_delay (Alias name: auto-firmware-upgrade-delay) Delay of day(s) before installing an automatic patch-level firmware upgrade from fortiguard (default = 3). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- auto_firmware_upgrade_end_hour (Alias name: auto-firmware-upgrade-end-hour) End time in the designated time window for automatic patch-level firmware upgrade from fortiguard in 24 hour time (0 ~ 23, default = 4). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- auto_firmware_upgrade_start_hour (Alias name: auto-firmware-upgrade-start-hour) Start time in the designated time window for automatic patch-level firmware upgrade from fortiguard in 24 hour time (0 ~ 23, default = 2). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- auto_join_forticloud (Alias name: auto-join-forticloud) Automatically connect to and login to forticloud. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- ddns_server_ip (Alias name: ddns-server-ip) Ip address of the fortiddns server. type: str
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- ddns_server_ip6 (Alias name: ddns-server-ip6) Ipv6 address of the fortiddns server. type: str
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- ddns_server_port (Alias name: ddns-server-port) Port used to communicate with fortiddns servers. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- dlp_expiration (Alias name: dlp-expiration) Dlp expiration. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- dlp_license (Alias name: dlp-license) Dlp license. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- fnbi_expiration (Alias name: fnbi-expiration) Fnbi expiration. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- fnbi_license (Alias name: fnbi-license) Fnbi license. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- fortiguard_anycast (Alias name: fortiguard-anycast) Enable/disable use of fortiguards anycast network. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- fortiguard_anycast_source (Alias name: fortiguard-anycast-source) Configure which of fortinets servers to provide fortiguard services in fortiguards anycast network. type: str choices: [fortinet, aws, debug]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- gui_prompt_auto_upgrade (Alias name: gui-prompt-auto-upgrade) Enable/disable prompting of automatic patch-level firmware upgrade recommendation. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- ia_expiration (Alias name: ia-expiration) Ia expiration. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- ia_license (Alias name: ia-license) Ia license. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- interface Specify outgoing interface to reach server. type: list
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- interface_select_method (Alias name: interface-select-method) Specify how to select outgoing interface to reach server. type: str choices: [auto, sdwan, specify]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- load_balance_servers (Alias name: load-balance-servers) Number of servers to alternate between as first fortiguard option. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- outbreak_prevention_cache (Alias name: outbreak-prevention-cache) Enable/disable fortiguard virus outbreak prevention cache. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- outbreak_prevention_cache_mpercent (Alias name: outbreak-prevention-cache-mpercent) Maximum percent of memory fortiguard virus outbreak prevention cache can use (1 - 15%, default = 2). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- outbreak_prevention_cache_ttl (Alias name: outbreak-prevention-cache-ttl) Time-to-live for fortiguard virus outbreak prevention cache entries (300 - 86400 sec, default = 300). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- outbreak_prevention_expiration (Alias name: outbreak-prevention-expiration) Outbreak prevention expiration. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- outbreak_prevention_force_off (Alias name: outbreak-prevention-force-off) Turn off fortiguard virus outbreak prevention service. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- outbreak_prevention_license (Alias name: outbreak-prevention-license) Outbreak prevention license. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- outbreak_prevention_timeout (Alias name: outbreak-prevention-timeout) Fortiguard virus outbreak prevention time out (1 - 30 sec, default = 7). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- persistent_connection (Alias name: persistent-connection) Enable/disable use of persistent connection to receive update notification from fortiguard. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- port Port used to communicate with the fortiguard servers. type: str choices: [53, 80, 443, 8888]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- protocol Protocol used to communicate with the fortiguard servers. type: str choices: [udp, http, https]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- proxy_password (Alias name: proxy-password) Proxy user password. type: list
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- proxy_server_ip (Alias name: proxy-server-ip) Hostname or ipv4 address of the proxy server. type: str
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- proxy_server_port (Alias name: proxy-server-port) Port used to communicate with the proxy server. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- proxy_username (Alias name: proxy-username) Proxy user name. type: str
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- sandbox_inline_scan (Alias name: sandbox-inline-scan) Enable/disable forticloud sandbox inline-scan. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- sandbox_region (Alias name: sandbox-region) Forticloud sandbox region. type: str
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- sdns_options (Alias name: sdns-options) Customization options for the fortiguard dns service. type: list choices: [include-question-section]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- sdns_server_ip (Alias name: sdns-server-ip) Ip address of the fortiguard dns rating server. type: list
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- sdns_server_port (Alias name: sdns-server-port) Port to connect to on the fortiguard dns rating server. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- service_account_id (Alias name: service-account-id) Service account id. type: str
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- source_ip (Alias name: source-ip) Source ipv4 address used to communicate with fortiguard. type: str
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- source_ip6 (Alias name: source-ip6) Source ipv6 address used to communicate with fortiguard. type: str
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- update_build_proxy (Alias name: update-build-proxy) Enable/disable proxy dictionary rebuild. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- update_dldb (Alias name: update-dldb) Enable/disable dlp signature update. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- update_extdb (Alias name: update-extdb) Enable/disable external resource update. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- update_ffdb (Alias name: update-ffdb) Enable/disable internet service database update. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- update_server_location (Alias name: update-server-location) Location from which to receive fortiguard updates. type: str choices: [usa, automatic, eu, any]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- update_uwdb (Alias name: update-uwdb) Enable/disable allowlist update. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- vdom Fortiguard service virtual domain name. type: list
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- videofilter_expiration (Alias name: videofilter-expiration) Videofilter expiration. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- videofilter_license (Alias name: videofilter-license) Videofilter license. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- webfilter_cache (Alias name: webfilter-cache) Enable/disable fortiguard web filter caching. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- webfilter_cache_ttl (Alias name: webfilter-cache-ttl) Time-to-live for web filter cache entries in seconds (300 - 86400). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- webfilter_expiration (Alias name: webfilter-expiration) Webfilter expiration. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- webfilter_force_off (Alias name: webfilter-force-off) Enable/disable turning off the fortiguard web filtering service. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- webfilter_license (Alias name: webfilter-license) Webfilter license. type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- webfilter_timeout (Alias name: webfilter-timeout) Web filter query time out (1 - 30 sec, default = 15). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- antispam_cache_mpermille (Alias name: antispam-cache-mpermille) Maximum permille of fortigate memory the antispam cache is allowed to use (1 - 150). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- FDS_license_expiring_days (Alias name: FDS-license-expiring-days) Threshold for number of days before fortiguard license expiration to generate license expiring event log (1 - 100 days, default = 15). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- outbreak_prevention_cache_mpermille (Alias name: outbreak-prevention-cache-mpermille) Maximum permille of memory fortiguard virus outbreak prevention cache can use (1 - 150 permille, default = 1). type: int
more...
Supported Version Ranges: v7.4.8 -> v7.4.10, v7.6.4 -> latest
- vrf_select (Alias name: vrf-select) Vrf id used for connection to server. type: int
more...
Supported Version Ranges: v7.6.4 -> latest
- subscribe_update_notification (Alias name: subscribe-update-notification) Enable/disable subscription to receive update notification from fortiguard. type: str choices: [disable, enable]
more...
Supported Version Ranges: v7.6.4 -> latest
Notes
-----
.. note::
- Running in workspace locking mode is supported in this FortiManager module, the top level parameters workspace_locking_adom and workspace_locking_timeout help do the work.
- To create or update an object, use state: present directive.
- To delete an object, use state: absent directive
- Normally, running one module can fail when a non-zero rc is returned. you can also override the conditions to fail or succeed with parameters rc_failed and rc_succeeded
Examples
--------
.. code-block:: yaml+jinja
- name: Example playbook (generated based on argument schema)
hosts: fortimanagers
connection: httpapi
gather_facts: false
vars:
ansible_httpapi_use_ssl: true
ansible_httpapi_validate_certs: false
ansible_httpapi_port: 443
tasks:
- name: Configure FortiGuard services.
fortinet.fmgdevice.fmgd_system_fortiguard:
# bypass_validation: false
# workspace_locking_adom:
# workspace_locking_timeout: 300
# rc_succeeded: [0, -2, -3, ...]
# rc_failed: [-2, -3, ...]
device:
system_fortiguard:
# antispam_cache:
# antispam_cache_mpercent:
# antispam_cache_ttl:
# antispam_expiration:
# antispam_force_off:
# antispam_license:
# antispam_timeout:
# anycast_sdns_server_ip:
# anycast_sdns_server_port:
# auto_firmware_upgrade:
# auto_firmware_upgrade_day:
# - "sunday"
# - "monday"
# - "tuesday"
# - "wednesday"
# - "thursday"
# - "friday"
# - "saturday"
# auto_firmware_upgrade_delay:
# auto_firmware_upgrade_end_hour:
# auto_firmware_upgrade_start_hour:
# auto_join_forticloud:
# ddns_server_ip:
# ddns_server_ip6:
# ddns_server_port:
# dlp_expiration:
# dlp_license:
# fnbi_expiration:
# fnbi_license:
# fortiguard_anycast:
# fortiguard_anycast_source:
# gui_prompt_auto_upgrade:
# ia_expiration:
# ia_license:
# interface:
# interface_select_method:
# load_balance_servers:
# outbreak_prevention_cache:
# outbreak_prevention_cache_mpercent:
# outbreak_prevention_cache_ttl:
# outbreak_prevention_expiration:
# outbreak_prevention_force_off:
# outbreak_prevention_license:
# outbreak_prevention_timeout:
# persistent_connection:
# port:
# protocol:
# proxy_password:
# proxy_server_ip:
# proxy_server_port:
# proxy_username:
# sandbox_inline_scan:
# sandbox_region:
# sdns_options:
# - "include-question-section"
# sdns_server_ip:
# sdns_server_port:
# service_account_id:
# source_ip:
# source_ip6:
# update_build_proxy:
# update_dldb:
# update_extdb:
# update_ffdb:
# update_server_location:
# update_uwdb:
# vdom:
# videofilter_expiration:
# videofilter_license:
# webfilter_cache:
# webfilter_cache_ttl:
# webfilter_expiration:
# webfilter_force_off:
# webfilter_license:
# webfilter_timeout:
# antispam_cache_mpermille:
# FDS_license_expiring_days:
# outbreak_prevention_cache_mpermille:
# vrf_select:
# subscribe_update_notification:
Return Values
-------------
Common return values are documented: https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values, the following are the fields unique to this module:
.. raw:: html
- meta - The result of the request.returned: always type: dict
- request_url - The full url requested. returned: always type: str sample: /sys/login/user
- response_code - The status of api request. returned: always type: int sample: 0
- response_data - The data body of the api response. returned: optional type: list or dict
- response_message - The descriptive message of the api response. returned: always type: str sample: OK
- system_information - The information of the target system. returned: always type: dict
- rc - The status the request. returned: always type: int sample: 0
- version_check_warning - Warning if the parameters used in the playbook are not supported by the current FortiManager version. returned: if at least one parameter not supported by the current FortiManager version type: list
Status
------
- This module is not guaranteed to have a backwards compatible interface.
Authors
-------
- Xinwei Du (@dux-fortinet)
- Xing Li (@lix-fortinet)
- Jie Xue (@JieX19)
- Link Zheng (@chillancezen)
- Frank Shen (@fshen01)
- Hongbin Lu (@fgtdev-hblu)