Skip to content

Latest commit

 

History

History
1432 lines (840 loc) · 35.7 KB

REFERENCE.md

File metadata and controls

1432 lines (840 loc) · 35.7 KB

Reference

Table of Contents

Classes

Resource types

  • firewalld_custom_service: Creates a custom firewalld service.
  • firewalld_direct_chain: Allow to create a custom chain in iptables/ip6tables/ebtables using firewalld direct interface. Example: firewalld_direct_chain {'Add c
  • firewalld_direct_passthrough: Allow to create a custom passthroughhrough traffic in iptables/ip6tables/ebtables using firewalld direct interface. Example: firewalld_
  • firewalld_direct_purge: Allow to purge direct rules in iptables/ip6tables/ebtables using firewalld direct interface. Example: firewalld_direct_purge {'chain':
  • firewalld_direct_rule: Allow to pass rules directly to iptables/ip6tables/ebtables using firewalld direct interface. Example: firewalld_direct_rule {'Allow ou
  • firewalld_ipset: Configure IPsets in Firewalld Example: firewalld_ipset {'internal net': ensure => 'present', type => 'hash:net',
  • firewalld_policy: Creates and manages firewalld policies.
  • firewalld_port: Assigns a port to a specific firewalld zone. firewalld_port will autorequire the firewalld_zone specified in the zone parameter or the firew
  • firewalld_rich_rule: Manages firewalld rich rules. firewalld_rich_rules will autorequire the firewalld_zone specified in the zone parameter or the firewalld_poli
  • firewalld_service: Assigns a service to a specific firewalld zone.
  • firewalld_zone: Creates and manages firewalld zones.

Functions

Classes

firewalld

See the README.md for usage instructions for the firewalld_zone and firewalld_rich_rule types

=== Examples

Standard: include firewalld

Command line only, no GUI components: class{'firewalld': }

With GUI components class{'firewalld': install_gui => true, }

=== Documentation

=== Authors

Craig Dunn craig@craigdunn.org

=== Copyright

Copyright 2015 Craig Dunn

Parameters

The following parameters are available in the firewalld class:

package_ensure

Data type: Enum['present','absent','latest','installed']

Define if firewalld-package should be handled Defaults to installed but can be set to absent or latest

Default value: 'installed'

package

Data type: String

The name of the firewalld-package

Default value: 'firewalld'

service_enable

Data type: Boolean

If the firewalld-service should be enabled

Default value: true

service_ensure

Data type: Stdlib::Ensure::Service

The state that the firewalld-service should be in

Default value: 'running'

install_gui

Data type: Boolean

Set to true to install the firewall-config-package

Default value: false

config_package

Data type: String

The name of package that is installed if install_gui is true

Default value: 'firewall-config'

zones

Data type: Hash

A hash of firewalld_zone-definitions

Default value: {}

policies

Data type: Hash

A hash of firewalld_policy-definitions

Default value: {}

ports

Data type: Hash

A hash of firewalld_port-definitions

Default value: {}

services

Data type: Hash

A hash of firewalld_service-definitions

Default value: {}

rich_rules

Data type: Hash

A hash of firewalld_rich_rule-definitions

Default value: {}

custom_services

Data type: Hash

A hash of firewalld_custom_service-definitions

Default value: {}

ipsets

Data type: Hash

A hash of firewalld_ipset-definitions

Default value: {}

direct_rules

Data type: Hash

A hash of firewalld_direct_rule-definitions

Default value: {}

direct_chains

Data type: Hash

A hash of firewalld_direct_chain-definitions

Default value: {}

direct_passthroughs

Data type: Hash

A hash of firewalld_direct_passthrough-definitions

Default value: {}

purge_direct_rules

Data type: Boolean

If direct_rules not maintained by puppet should be removed

Default value: false

purge_direct_chains

Data type: Boolean

If direct_chains not maintained by puppet should be removed

Default value: false

purge_direct_passthroughs

Data type: Boolean

If direct_passthroughs not maintained by puppet should be removed

Default value: false

purge_unknown_ipsets

Data type: Boolean

If ipsets not maintained by puppet should be removed

Default value: false

default_zone

Data type: Optional[String]

Optional string to set the default zone

Default value: undef

log_denied

Data type: Optional[Enum['off','all','unicast','broadcast','multicast']]

Sets the mode for which denied packets should be logged

Default value: undef

cleanup_on_exit

Data type: Optional[Enum['yes', 'no']]

Controls the CleanupOnExit setting of firewalld

Default value: undef

zone_drifting

Data type: Optional[Enum['yes', 'no']]

Controls the AllowZoneDrifting setting of firewalld should be no because zone-drifting is deprecated

Default value: undef

minimal_mark

Data type: Optional[Integer]

Controls the MinimalMark setting of firewalld

Default value: undef

lockdown

Data type: Optional[Enum['yes', 'no']]

Controls the Lockdown setting of firewalld

Default value: undef

individual_calls

Data type: Optional[Enum['yes', 'no']]

Controls the IndividualCalls setting of firewalld

Default value: undef

ipv6_rpfilter

Data type: Optional[Enum['yes', 'no']]

Controls the IPv6_rpfilter setting of firewalld

Default value: undef

firewall_backend

Data type: Optional[Enum['iptables', 'nftables']]

Chooses the backend between iptables (deprecated) or nftables

Default value: undef

default_service_zone

Data type: Optional[String]

Sets the default zone for firewalld_service

Default value: undef

default_port_zone

Data type: Optional[String]

Sets the default zone for firewalld_port

Default value: undef

default_port_protocol

Data type: Optional[String]

Sets the default protocol for firewalld_port

Default value: undef

firewalld::reload

A common point for triggering an intermediary firewalld reload using firewall-cmd

firewalld::reload::complete

A common point for triggering an intermediary firewalld full reload using firewall-cmd

Resource types

firewalld_custom_service

You will still need to create a firewalld_service resource to bind your new service to a zone.

Examples

Creating a custom 'test' service
firewalld_custom_service {'test':
    ensure  => present,
    ports   => [{'port' => '1234', 'protocol' => 'tcp'}]
}

Properties

The following properties are available in the firewalld_custom_service type.

description

Valid values: %r{.+}

The long description of the service

ensure

Valid values: present, absent

Manage the state of this type.

Default value: present

ipv4_destination

The IPv4 destination network of the service

Default value: unset

ipv6_destination

The IPv6 destination network of the service

Default value: unset

modules

Valid values: %r{^[\w-]+$}

The list of netfilter modules to add to the service

Default value: unset

ports

An Array of allowed port/protocol Hashes or Strings of the form port/protocol

Default value: unset

protocols

Valid values: %r{^[^\s#]+$}

Protocols allowed by the service as defined in /etc/protocols

Default value: unset

short

Valid values: %r{.+}

The short description of the service

Parameters

The following parameters are available in the firewalld_custom_service type.

name

Valid values: %r{.+}

namevar

The target filename of the resource (without the .xml suffix)

provider

The specific backend to use for this firewalld_custom_service resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

firewalld_direct_chain

Allow to create a custom chain in iptables/ip6tables/ebtables using firewalld direct interface.

Example:

firewalld_direct_chain {'Add custom chain LOG_DROPS':
    name           => 'LOG_DROPS',
    ensure         => 'present',
    inet_protocol  => 'ipv4',
    table          => 'filter'
}

Properties

The following properties are available in the firewalld_direct_chain type.

ensure

Valid values: present, absent

Manage the state of this type.

Default value: present

Parameters

The following parameters are available in the firewalld_direct_chain type.

inet_protocol

Valid values: ipv4, ipv6, eb

namevar

Name of the TCP/IP protocol to use (e.g: ipv4, ipv6, eb)

Default value: ipv4

name

Name of the chain eg: LOG_DROPS

provider

The specific backend to use for this firewalld_direct_chain resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

table

namevar

Name of the table type to add (e.g: filter, nat, mangle, raw)

firewalld_direct_passthrough

Allow to create a custom passthroughhrough traffic in iptables/ip6tables/ebtables using firewalld direct interface.

Example:

firewalld_direct_passthrough {'Forward traffic from OUTPUT to OUTPUT_filter':
    ensure        => 'present',
    inet_protocol => 'ipv4',
    args          => '-A OUTPUT -j OUTPUT_filter',
}

Or using namevar

firewalld_direct_passthrough {'-A OUTPUT -j OUTPUT_filter':
    ensure        => 'present',
}

Properties

The following properties are available in the firewalld_direct_passthrough type.

ensure

Valid values: present, absent

Manage the state of this type.

Default value: present

Parameters

The following parameters are available in the firewalld_direct_passthrough type.

args

namevar

Name of the passthroughhrough to add (e.g: -A OUTPUT -j OUTPUT_filter)

inet_protocol

Valid values: ipv4, ipv6, eb

Name of the TCP/IP protocol to use (e.g: ipv4, ipv6, eb)

Default value: ipv4

provider

The specific backend to use for this firewalld_direct_passthrough resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

firewalld_direct_purge

Allow to purge direct rules in iptables/ip6tables/ebtables using firewalld direct interface.

Example:

firewalld_direct_purge {'chain': }
firewalld_direct_purge {'passthrough': }
firewalld_direct_purge {'rule': }

Properties

The following properties are available in the firewalld_direct_purge type.

ensure

Valid values: purgable, purged

Manage the state of this type.

Default value: purged

Parameters

The following parameters are available in the firewalld_direct_purge type.

name

Valid values: chain, passthrough, rule

namevar

Type of resource to purge, valid values are 'chain', 'passthrough' and 'rule'

provider

The specific backend to use for this firewalld_direct_purge resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

purge

Valid values: true, false

If unmaintained definitions should be purged

Default value: true

firewalld_direct_rule

Allow to pass rules directly to iptables/ip6tables/ebtables using firewalld direct interface.

Example:

firewalld_direct_rule {'Allow outgoing SSH connection':
    ensure         => 'present',
    inet_protocol  => 'ipv4',
    table          => 'filter',
    chain          => 'OUTPUT',
    priority       => 1,
    args           => '-p tcp --dport=22 -j ACCEPT',
}

Properties

The following properties are available in the firewalld_direct_rule type.

ensure

Valid values: present, absent

Manage the state of this type.

Default value: present

Parameters

The following parameters are available in the firewalld_direct_rule type.

args

can be all iptables, ip6tables and ebtables command line arguments

chain

Name of the chain type to add (e.g: INPUT, OUTPUT, FORWARD)

inet_protocol

Valid values: ipv4, ipv6, eb

Name of the TCP/IP protocol to use (e.g: ipv4, ipv6, eb)

Default value: ipv4

name

namevar

Name of the rule resource in Puppet

priority

The priority number of the rule (e.g: 0, 1, 2, ... 99)

provider

The specific backend to use for this firewalld_direct_rule resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

table

Name of the table type to add (e.g: filter, nat, mangle, raw)

firewalld_ipset

Configure IPsets in Firewalld

Example: firewalld_ipset {'internal net': ensure => 'present', type => 'hash:net', family => 'inet', entries => ['192.168.0.0/24'] }

Properties

The following properties are available in the firewalld_ipset type.

ensure

Valid values: present, absent

Manage the state of this type.

Default value: present

entries

Array of ipset entries

family

Valid values: inet6, inet

Protocol family of the IPSet

hashsize

Initial hash size of the IPSet

maxelem

Valid values: %r{^[1-9]\d*$}

Maximal number of elements that can be stored in the set

timeout

Valid values: %r{^\d+$}

Timeout in seconds before entries expiry. 0 means entry is permanent

Parameters

The following parameters are available in the firewalld_ipset type.

manage_entries

Valid values: true, false, yes, no

Should we manage entries in this ipset or leave another process manage those entries

Default value: true

name

namevar

Name of the IPset

options

Hash of options for the IPset, eg { 'family' => 'inet6' }

provider

The specific backend to use for this firewalld_ipset resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

type

Valid values: bitmap:ip, bitmap:ip,mac, bitmap:port, hash:ip, hash:ip,mark, hash:ip,port, hash:ip,port,ip, hash:ip,port,net, hash:mac, hash:net, hash:net,iface, hash:net,net, hash:net,port, hash:net,port,net, list:set

Type of the ipset (default: hash:ip)

Default value: hash:ip

firewalld_policy

Creates and manages firewalld policies.

Note that setting ensure => 'absent' to the built in firewalld policies will not work, and will generate an error. This is a limitation of firewalld itself, not the module.

Examples

Create a policy called anytorestricted
firewalld_policy { 'anytorestricted':
  ensure           => present,
  target           => '%%REJECT%%',
  ingress_zones    => ['ANY'],
  egress_zones     => ['restricted'],
  purge_rich_rules => true,
  purge_services   => true,
  purge_ports      => true,
  icmp_blocks      => 'router-advertisement'
}

Properties

The following properties are available in the firewalld_policy type.

egress_zones

Specify the egress zones for the policy as an array of strings

ensure

Valid values: present, absent

Manage the state of this type.

Default value: present

icmp_blocks

Specify the icmp-blocks for the policy. Can be a single string specifying one icmp type, or an array of strings specifying multiple icmp types. Any blocks not specified here will be removed

ingress_zones

Specify the ingress zones for the policy as an array of strings

masquerade

Valid values: true, false

Can be set to true or false, specifies whether to add or remove masquerading from the policy

priority

The priority of the policy as an integer (default -1)

Default value: -1

purge_ports

Valid values: false, true

When set to true any ports associated with this policy that are not managed by Puppet will be removed.

purge_rich_rules

Valid values: false, true

When set to true any rich_rules associated with this policy that are not managed by Puppet will be removed.

purge_services

Valid values: false, true

When set to true any services associated with this policy that are not managed by Puppet will be removed.

target

Specify the target for the policy

Parameters

The following parameters are available in the firewalld_policy type.

description

Description of the policy to add

name

namevar

Name of the rule resource in Puppet

policy

Name of the policy

provider

The specific backend to use for this firewalld_policy resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

short

Short description of the policy to add

firewalld_port

Assigns a port to a specific firewalld zone.

firewalld_port will autorequire the firewalld_zone specified in the zone parameter or the firewalld_policy specified in the policy parameter so there is no need to add dependencies for this

Example:

firewalld_port {'Open port 8080 in the public Zone':
    ensure   => 'present',
    zone     => 'public',
    port     => 8080,
    protocol => 'tcp',
}

Properties

The following properties are available in the firewalld_port type.

ensure

Valid values: present, absent

Manage the state of this type.

Default value: present

Parameters

The following parameters are available in the firewalld_port type.

name

namevar

Name of the port resource in Puppet

policy

Name of the policy to which you want to add the port, exactly one of zone and policy must be supplied

Default value: unset

port

Specify the element as a port

protocol

Specify the element as a protocol

provider

The specific backend to use for this firewalld_port resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

zone

Name of the zone to which you want to add the port, exactly one of zone and policy must be supplied

Default value: unset

firewalld_rich_rule

Manages firewalld rich rules.

firewalld_rich_rules will autorequire the firewalld_zone specified in the zone parameter or the firewalld_policy specified in the policy parameter so there is no need to add dependencies for this

Example:

firewalld_rich_rule { 'Accept SSH from barny': ensure => present, zone => 'restricted', source => '192.168.1.2/32', service => 'ssh', action => 'accept', }

Properties

The following properties are available in the firewalld_rich_rule type.

ensure

Valid values: present, absent

Manage the state of this type.

Default value: present

Parameters

The following parameters are available in the firewalld_rich_rule type.

action

Specify the action fo this rule

audit

doc

dest

Specify destination address, this can be a string of the IP address or a hash containing other options

family

Valid values: ipv4, ipv6, eb

IP family, one of ipv4, ipv6 or eb, defauts to ipv4

Default value: ipv4

forward_port

Specify the element as forward-port

icmp_block

Specify the element as an icmp-block

icmp_type

Specify the element as an icmp-type

log

doc

masquerade

Specify the element as masquerade

name

namevar

Name of the rule resource in Puppet

policy

Name of the policy to attach the rich rule to, exactly one of zone and policy must be supplied

Default value: unset

port

Specify the element as a port

priority

Rule priority, it can be in the range of -32768 to 32767

protocol

Specify the element as a protocol

provider

The specific backend to use for this firewalld_rich_rule resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

raw_rule

Manage the entire rule as one string - this is used internally by firwalld_zone and firewalld_policy to handle pruning of rules

service

Specify the element as a service

source

Specify source address, this can be a string of the IP address or a hash containing other options

zone

Name of the zone to attach the rich rule to, exactly one of zone and policy must be supplied

Default value: unset

firewalld_service

Assigns a service to a specific firewalld zone.

firewalld_service will autorequire the firewalld_zone specified in the zone parameter or the firewalld_policy specified in the policy parameter and the firewalld::custom_service specified in the service parameter. There is no need to manually add dependencies for this.

Examples

Allowing SSH
firewalld_service {'Allow SSH in the public Zone':
    ensure  => present,
    zone    => 'public',
    service => 'ssh',
}

Properties

The following properties are available in the firewalld_service type.

ensure

Valid values: present, absent

Manage the state of this type.

Default value: present

Parameters

The following parameters are available in the firewalld_service type.

name

namevar

Name of the service resource in Puppet

policy

Name of the policy to which you want to add the service, exactly one of zone and policy must be supplied

Default value: unset

provider

The specific backend to use for this firewalld_service resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

service

Name of the service to add

zone

Name of the zone to which you want to add the service, exactly one of zone and policy must be supplied

Default value: unset

firewalld_zone

Creates and manages firewalld zones.

Note that setting ensure => 'absent' to the built in firewalld zones will not work, and will generate an error. This is a limitation of firewalld itself, not the module.

Examples

Create a zone called restricted allowing only echo-request icmp types
firewalld_zone { 'restricted':
  ensure               => present,
  target               => '%%REJECT%%',
  interfaces           => [],
  sources              => [],
  purge_rich_rules     => true,
  purge_services       => true,
  purge_ports          => true,
  icmp_blocks          => 'echo-request',
  icmp_block_inversion => true,
}

Properties

The following properties are available in the firewalld_zone type.

ensure

Valid values: present, absent

Manage the state of this type.

Default value: present

icmp_block_inversion

Valid values: true, false

Can be set to true or false, specifies whether to set icmp_block_inversion from the zone

Default value: false

icmp_blocks

Specify the icmp-blocks for the zone. Can be a single string specifying one icmp type, or an array of strings specifying multiple icmp types. Any blocks not specified here will be removed

interfaces

Specify the interfaces for the zone

masquerade

Valid values: true, false

Can be set to true or false, specifies whether to add or remove masquerading from the zone

protocols

Specify the protocols for the zone

purge_ports

Valid values: false, true

When set to true any ports associated with this zone that are not managed by Puppet will be removed.

purge_rich_rules

Valid values: false, true

When set to true any rich_rules associated with this zone that are not managed by Puppet will be removed.

purge_services

Valid values: false, true

When set to true any services associated with this zone that are not managed by Puppet will be removed.

sources

Specify the sources for the zone

target

Specify the target for the zone

Parameters

The following parameters are available in the firewalld_zone type.

description

Description of the zone to add

name

namevar

Name of the rule resource in Puppet

provider

The specific backend to use for this firewalld_zone resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

short

Short description of the zone to add

zone

Name of the zone

Functions

firewalld::safe_filename

Type: Puppet Language

Returns a string that is safe for firewalld filenames

Examples

Regular Filename
$filename = 'B@d Characters!'
firewalld::safe_filename($orig_string)

Result => 'B_d_Characters_'
Filename with Options
$filename = 'B@d Characters!.txt'
firewalld::safe_filename(
  $filename,
  {
    'replacement_string' => '--',
    'file_extension'     => '.txt'
  }
)

Result => 'B--d--Characters--.txt'

`firewalld::safe_filename(String[1] $filename, Struct[

{
  'replacement_string' => Pattern[/^[\w-]+$/],
  'file_extension'     => Optional[String[1]]
}

] $options = { 'replacement_string' => '_' })`

The firewalld::safe_filename function.

Returns: String Processed string

Examples
Regular Filename
$filename = 'B@d Characters!'
firewalld::safe_filename($orig_string)

Result => 'B_d_Characters_'
Filename with Options
$filename = 'B@d Characters!.txt'
firewalld::safe_filename(
  $filename,
  {
    'replacement_string' => '--',
    'file_extension'     => '.txt'
  }
)

Result => 'B--d--Characters--.txt'
filename

Data type: String[1]

The String to process

options

Data type:

Struct[
    {
      'replacement_string' => Pattern[/^[\w-]+$/],
      'file_extension'     => Optional[String[1]]
    }
  ]

Various processing options

Options:

  • file_extension String[1]: This will be stripped from the end of the string prior to processing and re-added afterwards
options

Data type: String[1]

replacement_string The String to use when replacing invalid characters

Options:

  • file_extension String[1]: This will be stripped from the end of the string prior to processing and re-added afterwards