engine - Operations on single or cluster layer 3 firewalls¶

New in version 2.5.

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
Notes
- Author
- Status

Synopsis ¶

Create or delete a Stonesoft Layer 3 Firewall on the Stonesoft Management Center.

Requirements (on host that executes module)¶

smc-python

Options ¶

parameter required default choices comments

antispoofing_network

no

network
group
host

Antispoofing networks are automatically added to the route antispoofing configuration. The dict should have a key specifying the element type from SMC. The dict key value should be a list of the element types by name.

antivirus

no

yes
no

Enable Anti-Virus engine on the FW

backup_heartbeat

no

Specify an interface by ID that will be the backup heartbeat. If the interface is a VLAN, specify in '2.4' format. If the interface cannot be used as this management type, operation is skipped.

backup_mgt

no

Specify an interface by ID that will be the backup management. If the interface is a VLAN, specify in '2.4' format (interface 2, vlan 4). If the interface cannot be used as this management type, operation is skipped.

bgp

no

If enabling BGP on the engine, provide BGP related settings

**Dictionary object bgp**
parameter	required	choices	comments
router_id	no		Optional router ID to identify this BGP peer
bgp_peering	no		BGP Peerings to add to specified interfaces.
enabled	no	yes no	Set to true or false to specify whether to configure BGP
autonomous_system	no		The autonomous system for this engine. Provide additional arguments to allow for get or create logic
announced_network	no	network group host	Announced networks identify the network and optional route map for internal networks announced over BGP. The list should be a dict with the key identifying the announced network type from SMC. The key should have a dict with name and route_map (optional) if the element should have an associated route_map.

cluster_mode

no

standby

balancing
standby

How to perform clustering, either balancing or standby

comment

no

Optional comment tag for the engine

default_nat

no

yes
no

Whether to enable default NAT on the FW. Default NAT will identify internal networks and use the external interface IP for outgoing traffic

delete_undefined_interfaces

no

yes
no

Delete interfaces from engine cluster that are not defined in the YAML file. This can be used as a strategy to remove interfaces. One option is to retrieve the full engine json using engine_facts as yaml, then remove the interfaces from the yaml and set this to True.

domain_server_address

no

A list of IP addresses to use as DNS resolvers for the FW. Required to enable Antivirus, GTI and URL Filtering on the NGFW.

**Dictionary object domain_server_address**
parameter	required	default	choices	comments
type	no			Type of element. Valid entries are ipaddress, host, dns_server or dynamic_interface_alias. If using an element that is not ipaddress, it must pre-exist in the SMC
name	no			Name of the element, can be IP address or element

enable_vpn

no

Provide a list of IP addresses for which to enable VPN endpoints on. This should be a list of string IP address identifiers. If enabling on a DHCP address, use the value specified in the SMC under VPN endpoints, i.e. First DHCP Interface ip.

file_reputation

no

yes
no

Enable file reputation

interfaces

yes

Define the interface settings for this cluster interface, such as address, network and node id.

**Dictionary object interfaces**
parameter	required	comments
comment	no	Optional comment for this interface. If you want to unset the interface comment, set to an empty string or define with no value
macaddress	no	The mac address to assign to the cluster virtual IP interface. This is required if cluster_virtual
zone_ref	no	Optional zone name for this interface
cluster_virtual	no	The cluster virtual (shared) IP address for all cluster members. Not required if only creating NDI's
interface_id	yes	The cluster nic ID for this interface. Required.
network_value	no	The cluster netmask for the cluster_vip. Required if cluster_virtual
nodes	yes	List of the nodes for this interface
type	no	The type of interface. Default is physical_interface. This is only required if the interface type is tunnel_interface or switch_physical_interface

location

no

Location identifier for the engine. Used when engine is behind NAT. If a location is set on the engine and you want to reset to unspecified, then use the keyword None.

log_server

no

Name of the log server to assign. If not provided, the default (primary) log server will be used

name

yes

The name of the firewall cluster to add or delete

netlinks

no

Netlinks are a list of dicts defining where to place netlinks and any destinations on a given routing interface. Suboptions define the dict structure for each list dict

**Dictionary object netlinks**
parameter	required	comments
destination	no	Destination elements specifying the networks, hosts, groups behind this netlink. Suboptions define the dict format for each list member
name	yes
interface_id	yes	The interface ID which to bind the netlink to. For VLAN, should be in dot syntax, i.e. 1.2, indicating interface 1, VLAN 2

policy_vpn

no

Defines any policy based VPN membership for thie engine. You can specify multiple and whether the engine should be a central gateway or satellite gateway and whether it should be enabled for mobile gateway. Updating policy VPN on the engine directly requires SMC version >= 6.3.x

**Dictionary object policy_vpn**
parameter	required	choices	comments
central_gateway	no	yes no	Whether this engine should be a central gateway. Mutually exclusive with satellite_gateway
name	yes		The name of the policy VPN.
mobile_gateway	no	yes no	Whether this engine should be enabled for remote VPN for mobile gateways (client VPN)
satellite_gateway	no	yes no	Whether this engine should be a satellite gateway. Mutually exclusive with central_gateway

primary_heartbeat

no

Specify an interface for the primary heartbeat interface. This will default to the same interface as primary_mgt if not specified. If the interface cannot be used as this management type, operation is skipped.

primary_mgt

yes

Identify the interface to be specified as management. When creating a new cluster, the primary mgt must be a non-VLAN interface. You can move it to a VLAN interface after creation. If the interface cannot be used as this management type, operation is skipped.

skip_interfaces

no

yes
no

Optionally skip the analysis of interface changes. This is only relevant when running the playbook against an already created engine. This must be false if attempting to add interfaces.

smc_address

no

FQDN with port of SMC. The default value is the environment variable SMC_ADDRESS

smc_alt_filepath

no

Provide an alternate path location to read the credentials from. File is expected to be stored in ~.smcrc. If provided, url and api_key settings are not required and will be ignored.

smc_api_key

no

API key for api client. The default value is the environment variable SMC_API_KEY Required if url

smc_api_version

no

Optional API version to connect to. If none is provided, the latest SMC version API will be used based on the Management Center version. Can be set though the environment variable SMC_API_VERSION

smc_domain

no

Optional domain to log in to. If no domain is provided, 'Shared Domain' is used. Can be set throuh the environment variable SMC_DOMAIN

smc_extra_args

no

Extra arguments to pass to login constructor. These are generally only used if specifically requested by support personnel.

**Dictionary object smc_extra_args**
parameter	required	default	choices	comments
verify	no	True	yes no	Is the connection to SMC is HTTPS, you can set this to True, or provide a path to a client certificate to verify the SMC SSL certificate. You can also explicitly set this to False.

smc_logging

no

Optionally enable SMC API logging to a file

**Dictionary object smc_logging**
parameter	required	default	choices	comments
path	yes			Full path to the log file
level	no			Log level as specified by the standard python logging library, in int format. Default setting is logging.DEBUG.

smc_timeout

no

Optional timeout for connections to the SMC. Can be set through environment SMC_TIMEOUT

snmp

no

SNMP settings for the engine

**Dictionary object snmp**
parameter	required	choices	comments
snmp_agent	yes		The name of the SNMP agent from within the SMC
enabled	no	yes no	Set this to False if enabled on the engine and wanting to remove the configuration.
snmp_interface	no		A list of interface IDs to enable SNMP. If enabling on a VLAN, use '2.3' syntax. If omitted, snmp is enabled on all interfaces
snmp_location	no		Optional SNMP location string to add the SNMP configuration

state

no

present

present
absent

Create or delete a firewall cluster

Examples ¶

- name: Firewall Template
  hosts: localhost
  gather_facts: no
  tasks:
  - name: Layer 3 FW template
    engine:
      smc_logging:
        level: 10
        path: ansible-smc.log
      antispoofing_network:
        group:
        - group1
        host:
        - 2.2.2.23
        network:
        - network-5.5.5.0/24
        - network-50.50.50.0/24
      antivirus: true
      bgp:
        announced_network:
        - network:
            name: network-1.1.1.0/24
            route_map: myroutemap
        autonomous_system:
          as_number: 200
          comment: null
          name: as-200
        bgp_peering:
        - external_bgp_peer: bgppeer
          interface_id: '1000'
          name: bgppeering
        bgp_profile: Default BGP Profile
        enabled: true
        router_id: 2.3.4.5
      default_nat: true
      domain_server_address:
      - name: 8.8.8.8
        type: ipaddress
      - name: Localhost
        type: host
      file_reputation: true
      interfaces:
      - interface_id: '1000'
        interfaces:
        - nodes:
          - address: 10.10.10.1
            network_value: 10.10.10.1/32
            nodeid: 1
        type: tunnel_interface
      - interface_id: '2'
        interfaces:
        - nodes:
          - address: 21.21.21.21
            network_value: 21.21.21.0/24
            nodeid: 1
          vlan_id: '1'
      - interface_id: '1'
        interfaces:
        - nodes:
          - address: 2.2.2.1
            network_value: 2.2.2.0/24
            nodeid: 1
      - interface_id: '0'
        interfaces:
        - nodes:
          - address: 1.1.1.1
            network_value: 1.1.1.0/24
            nodeid: 1
      - interface_id: SWP_0
        appliance_switch_module: 110
        type: switch_physical_interface
        port_group_interface:
        - interface_id: SWP_0.4
          switch_physical_interface_port:
          - switch_physical_interface_port_comment: port 2
            switch_physical_interface_port_number: 2
          - switch_physical_interface_port_comment: ''
            switch_physical_interface_port_number: 4
          - switch_physical_interface_port_comment: ''
            switch_physical_interface_port_number: 5
          - switch_physical_interface_port_comment: ''
            switch_physical_interface_port_number: 6
      name: myfw3
      log_server: my_custom_log_server
      netlinks:
      - destination:
        - name: host-3.3.3.3
          type: host
        interface_id: '2.1'
        name: netlink-21.21.21.0
      ospf:
        enabled: true
        ospf_areas:
        - interface_id: '2.1'
          name: myarea
          network: 21.21.21.0/24
        ospf_profile: Default OSPFv2 Profile
        router_id: 1.1.1.1
      policy_vpn:
      - central_gateway: true
        mobile_gateway: false
        name: new_policy_vpn
        satellite_gateway: false
      primary_mgt: '0'
      snmp:
        snmp_agent: fooagent
        snmp_interface:
        - '1'
        snmp_location: test
      type: single_fw


# Delete a layer 3 firewall, using environment variables for credentials
- name: delete firewall by name
  engine:
    name: myfirewall
    state: 'absent'

Return Values ¶

Common return values are documented Return Values, the following are the fields unique to this module:

name	description	returned	type	sample
state	The current state of the element		dict
changed	Whether or not the change succeeded	always	bool

Notes ¶

Note

Login credential information is either obtained by providing them directly to the task/play, specifying an alt_filepath to read the credentials from to the play, or from environment variables (in that order). See http://smc-python.readthedocs.io/en/latest/pages/session.html for more information.

Author ¶

David LePage (@gabstopper)

Status ¶

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.