fmgr_system_fortiguard – Configure FortiGuard services.

New in version 2.0.0.

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 v6.x and v7.x.

Requirements

The below requirements are needed on the host that executes this module.

  • ansible>=2.9.0

FortiManager Version Compatibility


6.0.0
True
6.2.0 6.2.1 6.2.2 6.2.3 6.2.5 6.2.6 6.2.7 6.2.8 6.2.9 6.2.10
True True True True True True True True True True
6.4.0 6.4.1 6.4.2 6.4.3 6.4.4 6.4.5 6.4.6 6.4.7 6.4.8 6.4.9 6.4.10 6.4.11
True True True True True True True True True True True True
7.0.0 7.0.1 7.0.2 7.0.3 7.0.4 7.0.5 7.0.6 7.0.7
True True True True True True True True
7.2.0 7.2.1 7.2.2
True True True
7.4.0
True

Parameters

  • 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
  • adom - The parameter in requested url type: str required: true
  • system_fortiguard - Configure FortiGuard services. type: dict
    • antispam-cache - Enable/disable FortiGuard antispam request caching. type: str choices: [disable, enable] more...
    • antispam-cache-mpercent - Maximum percent of FortiGate memory the antispam cache is allowed to use (1 - 15%). type: int more...
    • antispam-cache-ttl - Time-to-live for antispam cache entries in seconds (300 - 86400). type: int more...
    • antispam-expiration - Antispam-Expiration. type: int more...
    • antispam-force-off - Enable/disable turning off the FortiGuard antispam service. type: str choices: [disable, enable] more...
    • antispam-license - Antispam-License. type: int more...
    • antispam-timeout - Antispam query time out (1 - 30 sec, default = 7). type: int more...
    • auto-join-forticloud - Automatically connect to and login to FortiCloud. type: str choices: [disable, enable] more...
    • ddns-server-ip - IP address of the FortiDDNS server. type: str more...
    • ddns-server-port - Port used to communicate with FortiDDNS servers. type: int more...
    • load-balance-servers - Number of servers to alternate between as first FortiGuard option. type: int more...
    • outbreak-prevention-cache - Enable/disable FortiGuard Virus Outbreak Prevention cache. type: str choices: [disable, enable] more...
    • outbreak-prevention-cache-mpercent - Maximum percent of memory FortiGuard Virus Outbreak Prevention cache can use (1 - 15%, default = 2). type: int more...
    • outbreak-prevention-cache-ttl - Time-to-live for FortiGuard Virus Outbreak Prevention cache entries (300 - 86400 sec, default = 300). type: int more...
    • outbreak-prevention-expiration - Outbreak-Prevention-Expiration. type: int more...
    • outbreak-prevention-force-off - Turn off FortiGuard Virus Outbreak Prevention service. type: str choices: [disable, enable] more...
    • outbreak-prevention-license - Outbreak-Prevention-License. type: int more...
    • outbreak-prevention-timeout - FortiGuard Virus Outbreak Prevention time out (1 - 30 sec, default = 7). type: int more...
    • port - Port used to communicate with the FortiGuard servers. type: str choices: [53, 80, 8888, 443] more...
    • sdns-server-ip - IP address of the FortiDNS server. type: str more...
    • sdns-server-port - Port used to communicate with FortiDNS servers. type: int more...
    • service-account-id - Service account ID. type: str more...
    • source-ip - Source IPv4 address used to communicate with FortiGuard. type: str more...
    • source-ip6 - Source IPv6 address used to communicate with FortiGuard. type: str more...
    • update-server-location - Signature update server location. type: str choices: [any, usa, automatic, eu] more...
    • webfilter-cache - Enable/disable FortiGuard web filter caching. type: str choices: [disable, enable] more...
    • webfilter-cache-ttl - Time-to-live for web filter cache entries in seconds (300 - 86400). type: int more...
    • webfilter-expiration - Webfilter-Expiration. type: int more...
    • webfilter-force-off - Enable/disable turning off the FortiGuard web filtering service. type: str choices: [disable, enable] more...
    • webfilter-license - Webfilter-License. type: int more...
    • webfilter-timeout - Web filter query time out (1 - 30 sec, default = 7). type: int more...
    • protocol - Protocol used to communicate with the FortiGuard servers. type: str choices: [udp, http, https] more...
    • proxy-password - Proxy user password. type: str more...
    • proxy-server-ip - IP address of the proxy server. type: str more...
    • proxy-server-port - Port used to communicate with the proxy server. type: int more...
    • proxy-username - Proxy user name. type: str more...
    • sandbox-region - Cloud sandbox region. type: str more...
    • avquery-force-off - Turn off the FortiGuard antivirus service. type: str choices: [disable, enable] more...
    • avquery-timeout - Antivirus query time out (1 - 30 sec, default = 7). type: int more...
    • avquery-cache-ttl - Time-to-live for antivirus cache entries (300 - 86400 sec, default = 1800). type: int more...
    • avquery-cache-mpercent - Maximum percent of memory the antivirus cache can use (1 - 15%, default = 2). type: int more...
    • avquery-license - Interval of time between license checks for the FortiGuard antivirus contract. type: int more...
    • avquery-cache - Enable/disable the FortiGuard antivirus cache. type: str choices: [disable, enable] more...
    • fortiguard-anycast - Enable/disable use of FortiGuards anycast network. type: str choices: [disable, enable] more...
    • fortiguard-anycast-source - Configure which of Fortinets servers to provide FortiGuard services in FortiGuards anycast network. type: str choices: [fortinet, aws, debug] more...
    • interface - Specify outgoing interface to reach server. type: str more...
    • interface-select-method - Specify how to select outgoing interface to reach server. type: str choices: [auto, sdwan, specify] more...
    • sdns-options - Customization options for the FortiGuard DNS service. type: array choices: [include-question-section] more...
    • anycast-sdns-server-ip - IP address of the FortiGuard anycast DNS rating server. type: str more...
    • anycast-sdns-server-port - Port to connect to on the FortiGuard anycast DNS rating server. type: int more...
    • persistent-connection - Enable/disable use of persistent connection to receive update notification from FortiGuard. type: str choices: [disable, enable] more...
    • update-build-proxy - Enable/disable proxy dictionary rebuild. type: str choices: [disable, enable] more...
    • update-extdb - Enable/disable external resource update. type: str choices: [disable, enable] more...
    • update-ffdb - Enable/disable Internet Service Database update. type: str choices: [disable, enable] more...
    • update-uwdb - Enable/disable allowlist update. type: str choices: [disable, enable] more...
    • videofilter-expiration - Videofilter-Expiration. type: int more...
    • videofilter-license - Videofilter-License. type: int more...
    • ddns-server-ip6 - IPv6 address of the FortiDDNS server. type: str more...
    • vdom - FortiGuard Service virtual domain name. type: str more...
    • auto-firmware-upgrade - Enable/disable automatic patch-level firmware upgrade from FortiGuard. type: str choices: [disable, enable] more...
    • auto-firmware-upgrade-day - No description for the parameter type: array choices: [sunday, monday, tuesday, wednesday, thursday, friday, saturday] more...
    • 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...
    • 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...
    • sandbox-inline-scan - Enable/disable FortiCloud Sandbox inline-scan. type: str choices: [disable, enable] more...
    • 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...
    • antispam-cache-mpermille - Maximum permille of FortiGate memory the antispam cache is allowed to use (1 - 150). type: int more...
    • auto-firmware-upgrade-delay - Delay of day(s) before installing an automatic patch-level firmware upgrade from FortiGuard (default = 3). type: int more...
    • outbreak-prevention-cache-mpermille - Maximum permille of memory FortiGuard Virus Outbreak Prevention cache can use (1 - 150 permille, default = 1). type: int more...
    • update-dldb - Enable/disable DLP signature update. type: str choices: [disable, enable] more...

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

- hosts: fortimanager-inventory
  collections:
    - fortinet.fortimanager
  connection: httpapi
  vars:
     ansible_httpapi_use_ssl: True
     ansible_httpapi_validate_certs: False
     ansible_httpapi_port: 443
  tasks:
   - name: Configure FortiGuard services.
     fmgr_system_fortiguard:
        bypass_validation: False
        workspace_locking_adom: <value in [global, custom adom including root]>
        workspace_locking_timeout: 300
        rc_succeeded: [0, -2, -3, ...]
        rc_failed: [-2, -3, ...]
        adom: <your own value>
        system_fortiguard:
           antispam-cache: <value in [disable, enable]>
           antispam-cache-mpercent: <value of integer>
           antispam-cache-ttl: <value of integer>
           antispam-expiration: <value of integer>
           antispam-force-off: <value in [disable, enable]>
           antispam-license: <value of integer>
           antispam-timeout: <value of integer>
           auto-join-forticloud: <value in [disable, enable]>
           ddns-server-ip: <value of string>
           ddns-server-port: <value of integer>
           load-balance-servers: <value of integer>
           outbreak-prevention-cache: <value in [disable, enable]>
           outbreak-prevention-cache-mpercent: <value of integer>
           outbreak-prevention-cache-ttl: <value of integer>
           outbreak-prevention-expiration: <value of integer>
           outbreak-prevention-force-off: <value in [disable, enable]>
           outbreak-prevention-license: <value of integer>
           outbreak-prevention-timeout: <value of integer>
           port: <value in [53, 80, 8888, ...]>
           sdns-server-ip: <value of string>
           sdns-server-port: <value of integer>
           service-account-id: <value of string>
           source-ip: <value of string>
           source-ip6: <value of string>
           update-server-location: <value in [any, usa, automatic, ...]>
           webfilter-cache: <value in [disable, enable]>
           webfilter-cache-ttl: <value of integer>
           webfilter-expiration: <value of integer>
           webfilter-force-off: <value in [disable, enable]>
           webfilter-license: <value of integer>
           webfilter-timeout: <value of integer>
           protocol: <value in [udp, http, https]>
           proxy-password: <value of string>
           proxy-server-ip: <value of string>
           proxy-server-port: <value of integer>
           proxy-username: <value of string>
           sandbox-region: <value of string>
           avquery-force-off: <value in [disable, enable]>
           avquery-timeout: <value of integer>
           avquery-cache-ttl: <value of integer>
           avquery-cache-mpercent: <value of integer>
           avquery-license: <value of integer>
           avquery-cache: <value in [disable, enable]>
           fortiguard-anycast: <value in [disable, enable]>
           fortiguard-anycast-source: <value in [fortinet, aws, debug]>
           interface: <value of string>
           interface-select-method: <value in [auto, sdwan, specify]>
           sdns-options:
             - include-question-section
           anycast-sdns-server-ip: <value of string>
           anycast-sdns-server-port: <value of integer>
           persistent-connection: <value in [disable, enable]>
           update-build-proxy: <value in [disable, enable]>
           update-extdb: <value in [disable, enable]>
           update-ffdb: <value in [disable, enable]>
           update-uwdb: <value in [disable, enable]>
           videofilter-expiration: <value of integer>
           videofilter-license: <value of integer>
           ddns-server-ip6: <value of string>
           vdom: <value of string>
           auto-firmware-upgrade: <value in [disable, enable]>
           auto-firmware-upgrade-day:
             - sunday
             - monday
             - tuesday
             - wednesday
             - thursday
             - friday
             - saturday
           auto-firmware-upgrade-end-hour: <value of integer>
           auto-firmware-upgrade-start-hour: <value of integer>
           sandbox-inline-scan: <value in [disable, enable]>
           FDS-license-expiring-days: <value of integer>
           antispam-cache-mpermille: <value of integer>
           auto-firmware-upgrade-delay: <value of integer>
           outbreak-prevention-cache-mpermille: <value of integer>
           update-dldb: <value in [disable, enable]>

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:

  • 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 0
  • version_check_warning - Warning if the parameters used in the playbook are not supported by the current FortiManager version. returned: if at least on parameter mpt supported by the current FortiManager version type: list 0

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)

Hint

If you notice any issues in this documentation, you can create a pull request to improve it.