https://github.com/voxpupuli/puppet-firewalld
Puppet module for managing firewalld
https://github.com/voxpupuli/puppet-firewalld
centos-puppet-module firewalld hacktoberfest linux-puppet-module oraclelinux-puppet-module puppet puppet-module redhat-puppet-module ruby
Last synced: 7 months ago
JSON representation
Puppet module for managing firewalld
- Host: GitHub
- URL: https://github.com/voxpupuli/puppet-firewalld
- Owner: voxpupuli
- License: apache-2.0
- Created: 2015-03-03T13:07:02.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2024-09-16T18:43:14.000Z (about 1 year ago)
- Last Synced: 2024-10-29T14:22:35.626Z (about 1 year ago)
- Topics: centos-puppet-module, firewalld, hacktoberfest, linux-puppet-module, oraclelinux-puppet-module, puppet, puppet-module, redhat-puppet-module, ruby
- Language: Ruby
- Size: 711 KB
- Stars: 40
- Watchers: 42
- Forks: 77
- Open Issues: 56
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Module: firewalld
[](https://github.com/voxpupuli/puppet-firewalld/blob/master/LICENSE)
[](https://travis-ci.org/voxpupuli/puppet-firewalld)
[](https://coveralls.io/github/voxpupuli/puppet-firewalld)
[](https://forge.puppetlabs.com/puppet/firewalld)
[](https://forge.puppetlabs.com/puppet/firewalld)
[](https://forge.puppetlabs.com/puppet/firewalld)
[](https://forge.puppetlabs.com/puppet/firewalld)
## Description
This module manages firewalld, the userland interface that replaces
iptables and ships with RHEL7+. The module manages firewalld itself as
well as providing types and providers for managing firewalld zones,
policies, ports, and rich rules.
## Compatibility
Latest versions of this module are only supported on Puppet
7.0+.
## Usage
```puppet
class { 'firewalld': }
```
### Parameters
* `package`: Name of the package to install (default firewalld)
* `package_ensure`: Default 'installed', can be any supported ensure type for
the package resource
* `config_package`: Name of the GUI package, default firewall-config
* `install_gui`: Whether or not to install the config_package (default: false)
* `service_ensure`: Whether the service should be running or not (default: running)
* `service_enable`: Whether to enable the service
* `default_zone`: Optional, set the default zone for interfaces (default: undef)
* `firewall_backend`: Optional, set the firewall backend for firewalld (default:
undef)
* `default_service_zone`: Optional, set the default zone for services (default: undef)
* `default_port_zone`: Optional, set the default zone for ports (default: undef)
* `default_port_protocol`: Optional, set the default protocol for ports
(default: undef)
* `log_denied`: Optional, (firewalld-0.4.3.2-8+) Log denied packets, can be one
of `off`, `all`, `multicast`, `unicast`, `broadcast` (default: undef)
* `zones`: A hash of [firewalld zones](#firewalld-zones) to configure
* `policies`: A hash of [firewalld policies](#firewalld-policies) to configure
* `ports`: A hash of [firewalld ports](#firewalld-ports) to configure
* `services`: A hash of [firewalld services](#firewalld-service) to configure
* `rich_rules`: A hash of [firewalld rich rules](#firewalld-rich-rules) to configure
* `custom_services`: A hash of [firewalld custom
services](#firewalld-custom-service) to configure
* `direct_rules`: A hash of [firewalld direct rules](#firewalld-direct-rules) to
configure
* `direct_chains`: A hash of [firewalld direct chains](#firewalld-direct-chains)
to configure
* `direct_passthroughs`: A hash of [firewalld direct
passthroughs](#firewalld-direct-passthroughs) to configure
* `purge_direct_rules`: True or false, whether to purge [firewalld direct
rules](#firewalld-direct-rules)
* `purge_direct_chains`: True or false, whether to purge [firewalld direct
chains](#firewalld-direct-chains)
* `purge_direct_passthroughs`: True or false, whether to purge [firewalld direct
passthroughs](#firewalld-direct-passthroughs)
## Resource Types
The firewalld module contains types and providers to manage zones,
services, ports, and rich rules by interfacing with the `firewall-cmd`
command. The following types are currently supported. Note that all
zone, service, port, and rule management is done in `--permanent`
mode, and a complete reload will be triggered anytime something
changes.
This module supports a number of resource types
* [firewalld_zone](#firewalld-zones)
* [firewalld_policy](#firewalld-policies)
* [firewalld_port](#firewalld-ports)
* [firewalld_service](#firewalld-service)
* [firewalld_ipset](#firewalld-ipsets)
* [firewalld_rich_rule](#firewalld-rich-rules)
* [firewalld_direct_chain](#firewalld-direct-chains)
* [firewalld_direct_rule](#firewalld-direct-rules)
* [firewalld_direct_passthrough](#firewalld-direct-passthroughs)
Note, it is always recommended to include the `::firewalld` class if
you are going to use any of these resources from another Puppet class
(eg: a profile) as it sets up the relationships between the
`firewalld` service resource and the exec resource to reload the
firewall upon change. Without the `firewalld` class included then the
firewall will not be reloaded upon change. The recommended pattern is
to put all resources into hiera and let the `firewalld` class set them
up. Examples of both forms are presented for the resource types below.
### Firewalld Zones
Firewalld zones can be managed with the `firewalld_zone` resource type.
_Example in Class_:
```puppet
firewalld_zone { 'restricted':
ensure => present,
target => '%%REJECT%%',
purge_rich_rules => true,
purge_services => true,
purge_ports => true,
}
```
_Example in Hiera_:
```yaml
firewalld::zones:
restricted:
ensure: present
target: '%%REJECT%%'
purge_rich_rules: true
purge_services: true
purge_ports: true
```
#### Parameters (Firewalld Zones)
* `target`: Specify the target of the zone.
* `interfaces`: An array of interfaces for this zone
* `sources`: An array of sources for the zone
* `protocols`: An array of protocols for the zone
* `icmp_blocks`: An array of ICMP blocks for the zone
* `masquerade`: If set to `true` or `false` specifies whether or not
to add masquerading to the zone
* `purge_rich_rules`: Optional, and defaulted to false. When true any
configured rich rules found in the zone that do not match what is in
the Puppet catalog will be purged.
* `purge_services`: Optional, and defaulted to false. When true any
configured services found in the zone that do not match what is in
the Puppet catalog will be purged. *Warning:* This includes the
default ssh service, if you need SSH to access the box, make sure
you add the service through either a rich firewall rule, port, or
service (see below) or you will lock yourself out!
* `purge_ports`: Optional, and defaulted to false. When true any
configured ports found in the zone that do not match what is in the
Puppet catalog will be purged. *Warning:* As with services, this
includes the default ssh port. If you fail to specify the
appropriate port, rich rule, or service, you will lock yourself out.
### Firewalld policies
Firewalld policies can be managed with the `firewalld_policy` resource type.
_Example in Class_:
```puppet
firewalld_policy { 'anytorestricted':
ensure => present,
target => '%%REJECT%%',
ingress_zones => ['ANY'],
egress_zones => ['restricted'],
purge_rich_rules => true,
purge_services => true,
purge_ports => true,
}
```
_Example in Hiera_:
```yaml
firewalld::policies:
anytorestricted:
ensure: present
target: '%%REJECT%%'
ingress_zones:
- 'ANY'
egress_zones:
- 'restricted'
purge_rich_rules: true
purge_services: true
purge_ports: true
```
#### Parameters (Firewalld policies)
* `target`: Specify the target of the policy.
* `ingress_zones`: An array of ingress zones for this policy.
* `egress_zones`: An array of egress zones for this policy.
* `priority`: A non zero integer specifying the priority of this
policy, policies with negative priorities apply before rules in
zones, policies with positive priorities, after. Defaults to -1.
* `icmp_blocks`: An array of ICMP blocks for the policy
* `masquerade`: If set to `true` or `false` specifies whether or not
to add masquerading to the policy
* `purge_rich_rules`: Optional, and defaulted to false. When true any
configured rich rules found in the policy that do not match what is in
the Puppet catalog will be purged.
* `purge_services`: Optional, and defaulted to false. When true any
configured services found in the policy that do not match what is in
the Puppet catalog will be purged.
* `purge_ports`: Optional, and defaulted to false. When true any
configured ports found in the policy that do not match what is in the
Puppet catalog will be purged.
### Firewalld Rich Rules
Firewalld rich rules are managed using the `firewalld_rich_rule`
resource type
Exactly one of the `zone` or `policy` parameters must be given
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 in Class_:
```puppet
firewalld_rich_rule { 'Accept SSH from barny':
ensure => present,
zone => 'restricted',
source => '192.168.1.2/32',
service => 'ssh',
action => 'accept',
}
```
_Example in Hiera_:
```yaml
firewalld::rich_rules:
'Accept SSH from barny':
ensure: present
zone: restricted
source: '192.168.1.2/32'
service: 'ssh'
action: 'accept'
```
#### Parameters (Firewalld Rich Rules)
* `zone`: (Optional) Name of the zone this rich rule belongs to
* `policy`: (Optional) Name of the policy this rich rule belongs to
* `family`: Protocol family, defaults to `ipv4`
* `source`: Source address information. This can be a hash containing
the keys `address or ipset` and `invert`, or a string containing
just the IP address
```puppet
source => '192.168.2.1',
source => { 'address' => '192.168.1.1', 'invert' => true }
source => { 'ipset' => 'whitelist', 'invert' => true }
source => { 'ipset' => 'blacklist' }
```
* `dest`: Destination address information. This can be a hash
containing the keys `address or ipset` and `invert`, or a string
containing just the IP address
```puppet
dest => '192.168.2.1',
dest => { 'address' => '192.168.1.1', 'invert' => true }
dest => { 'ipset' => 'whitelist', 'invert' => true }
dest => { 'ipset' => 'blacklist' }
```
* `log`: When set to `true` will enable logging, optionally this can
be hash with `prefix`, `level` and `limit`
```puppet
log => { 'level' => 'debug', 'prefix' => 'foo' },
log => true,
```
* `audit`: When set to `true` will enable auditing, optionally this
can be hash with `limit`
```puppet
audit => { 'limit' => '3/s' },
audit => true,
```
* `action`: A string containing the action `accept`, `reject` or
`drop`. For `reject` it can be optionally supplied as a hash
containing `type`
```puppet
action => 'accept'
action => { 'action' => 'reject', 'type' => 'bad' }
```
The following paramters are the element of the rich rule, only _one_
may be used.
* `service`: Name of the service
* `protocol`: Protocol of the rich rule
* `port`: A hash containing `port` and `protocol` values
```puppet
port => {
'port' => 80,
'protocol' => 'tcp',
},
```
* `icmp_block`: Specify an `icmp-block` for the rule
* `masquerade`: Set to `true` or `false` to enable masquerading
* `forward_port`: Set forward-port, this should be a hash containing
`port`,`protocol`,`to_port`,`to_addr`
```puppet
forward_port => {
'port' => '8080',
'protocol' => 'tcp',
'to_addr' => '10.2.1.1',
'to_port' => '8993'
},
```
### Firewalld Custom Service
The `firewalld_custom_service` defined type creates and manages
custom services. It makes the service usable by firewalld, but does
not add it to any zones. To do that, use the firewalld::service type.
_Example in Class_:
```puppet
firewalld_custom_service{'puppet':
short => 'puppet',
description => 'Puppet Client access Puppet Server',
ports => [
{
'port' => '8140',
'protocol' => 'tcp',
},
{
'port' => '8140',
'protocol' => 'udp',
},
],
module => ['nf_conntrack_netbios_ns'],
'ipv4_destination' => '127.0.0.1',
'ipv6_destination' => '::1'
}
```
_Example in Hiera_:
```yaml
firewalld::custom_services:
puppet:
short: 'puppet'
description: 'Puppet Client access Puppet Server'
ports:
- port: 8140
protocol: 'tcp'
module: 'nf_conntrack_netbios_ns'
ipv4_destination: '127.0.0.1'
ipv6_destination: '::1'
```
This resource will create the following XML service definition in
/etc/firewalld/services/XZY.xml
```
puppet
Puppet Client access Puppet Server
```
and you will also see 'puppet' in the service list when you issue
`firewall-cmd --permanent --get-services`
#### Parameters (Firewalld Custom Service)
* `short`: (namevar) The short name of the service (what you see in
the firewalld command line output)
* `description`: (Optional) A short description of the service
* `ports`: (Optional) The protocol / port definitions for this service.
Specified as an array of hashes, where each hash defines a protocol
and/or port associated with this service. Each hash requires both
port and protocol keys, even if the value is an empty string.
Specifying a port only works for TCP & UDP, otherwise leave it empty
and the entire protocol will be allowed. Valid protocols are tcp,
udp, or any protocol defined in /etc/protocols
```puppet
ports => [{'port' => '1234', 'protocol' => 'tcp'}],
ports => [{'port' => '4321', 'protocol' => 'udp'}, {'protocol' => 'rdp'}],
```
The `ports` parameter can also take a range of ports separated by a
colon or a dash (colons are replaced by dashes), for example:
```puppet
ports => [ {'port' => '8000:8002', 'protocol' => 'tcp']} ]
```
will produce:
```xml
```
* `protocols`: (Optional) An array of protocols allowed by the service
as defined in /etc/protocols.
```puppet
protocols => ['ospf'],
```
* `module`: (Optional) An array of strings specifying netfilter kernel
helper modules associated with this service
* `ipv4_destination`: (Optional) A string specifying the destination
network as a network IP address (optional with /mask), or a plain IP
address.
The use of hostnames is possible but not recommended,
because these will only be resolved at service activation and
transmitted to the kernel.
```puppet
ipv4_destination => '192.0.2.0/24',
```
* `ipv6_destination`: (Optional) A string specifying the destination
network as a network IP address (optional with /mask), or a plain IP
address.
The use of hostnames is possible but not recommended,
because these will only be resolved at service activation and
transmitted to the kernel.
```puppet
ipv4_destination => '2001:db8::/32',
```
* `config_dir`: The location where the service definition XML files
will be stored. Defaults to /etc/firewalld/services
### Firewalld Service
The `firewalld_service` type is used to add or remove both built in
and custom services from zones.
Exactly one of the `zone` or `policy` parameters must be given.
firewalld_service will `autorequire` the firewalld_zone specified in
the `zone` parameter and the firewalld_custom_service specified in
the `service` parameter, so there is no need to add dependencies for
this
_Example in Class_:
```puppet
firewalld_service { 'Allow SSH from the external zone':
ensure => 'present',
service => 'ssh',
zone => 'external',
}
```
_Example in Hiera_:
```yaml
firewalld::services:
'Allow SSH from the external zone':
ensure: present
service: ssh
zone: external
dhcp:
ensure: absent
service: dhcp
zone: public
dhcpv6-client:
ensure: present
service: dhcpv6-client
zone: public
```
#### Parameters (Firewalld Service)
* `service`: Name of the service to manage, defaults to the resource
name.
* `zone`: Name of the zone in which you want to manage the service,
defaults to parameter `default_service_zone` of class `firewalld` if
specified.
* `policy`: Name of the policy in which you want to manage the
service. Make sure to set `zone` to `unset` if you use this and have
specified `default_service_zone` for class `firewalld`.
* `ensure`: Whether to add (`present`) or remove the service
(`absent`), defaults to `present`.
### Firewalld IPsets
Firewalld IPsets (on supported versions of firewalld) can be managed
using the `firewalld_ipset` resource type
_Example_:
```puppet
firewalld_ipset { 'whitelist':
ensure => present,
entries => [ '192.168.0.1', '192.168.0.2' ]
}
```
_Example in Hiera_:
```yaml
firewalld::ipsets:
whitelist:
entries:
- 192.168.0.1
- 192.168.0.2
```
#### Parameters (Firewalld IPsets)
* `entries`: An array of entries for the IPset
* `type`: Type of ipset (default: `hash:ip`)
* `options`: A hash of options for the IPset (eg:
`{ "family" => "inet6"}`)
Note that `type` and `options` are parameters used when creating the
IPset and are not managed after creation - to change the type or
options of an ipset you must delete the existing ipset first.
### Firewalld Ports
Firewalld ports can be managed with the `firewalld_port` resource
type.
Exactly one of the `zone` or `policy` parameters must be given.
firewalld_port will `autorequire` the firewalld_zone specified in the
`zone` parameter so there is no need to add dependencies for this
_Example_:
```puppet
firewalld_port { 'Open port 8080 in the public zone':
ensure => present,
zone => 'public',
port => 8080,
protocol => 'tcp',
}
```
_Example in Hiera_:
```yaml
firewalld::ports:
'Open port 8080 in the public zone':
ensure: present
zone: public
port: 8080
protocol: 'tcp'
```
#### Parameters (Firewalld Ports)
* `zone`: Name of the zone this port belongs to, defaults to parameter
`default_port_zone` of class `firewalld` if specified.
* `policy`: Name of the policy this port belongs to. Make sure to set
`zone` to `unset` if you use this and have specified
`default_port_zone` for class `firewalld`.
* `port`: The port to manage, defaults to the resource name.
* `protocol`: The protocol this port uses, e.g. `tcp` or `udp`,
defaults to parameter `default_port_protocol` of class `firewalld`
if specified.
* `ensure`: Whether to add (`present`) or remove the service
(`absent`), defaults to `present`.
### Firewalld Direct Chains
Direct chains can be managed with the `firewalld_direct_chain` type
#### Example
```puppet
firewalld_direct_chain {'Add custom chain LOG_DROPS':
name => 'LOG_DROPS',
ensure => present,
inet_protocol => 'ipv4',
table => 'filter',
}
```
The title can also be mapped to the types namevars using a colon
delimited string, so the above can also be represented as
```puppet
firewalld_direct_chain { 'ipv4:filter:LOG_DROPS':
ensure => present,
}
```
#### Example in hiera
```
firewalld::direct_chains:
'Add custom chain LOG_DROPS':
name: LOG_DROPS
ensure: present
inet_protocol: ipv4
table: filter
```
#### Parameters (Firewalld Direct Chains)
* `name`: name of the chain, eg `LOG_DROPS` (namevar)
* `inet_protocol`: ipv4, ipv6 or eb, defaults to ipv4 (namevar)
* `table`: The table (eg: filter) to apply the chain (namevar)
### Firewalld Direct Rules
Direct rules can be applied using the `firewalld_direct_rule` type
#### Example (Firewalld Direct Rules)
```puppet
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',
}
```
#### Example in hiera (Firewalld Direct Rules)
```yaml
firewalld::direct_rules:
'Allow outgoing SSH connection':
ensure: present
inet_protocol: ipv4
table: filter
chain: OUTPUT
priority: 1
args: '-p tcp --dport=22 -j ACCEPT'
```
#### Parameters (Firewalld Direct Rules)
* `name`: Resource name in Puppet
* `ensure`: present or absent
* `inet_protocol`: ipv4, ipv6 or eb, defaults to ipv4
* `table`: Table (eg: filter) which to apply the rule
* `chain`: Chain (eg: OUTPUT) which to apply the rule
* `priority`: The priority number of the rule (e.g: 0, 1, 2, ... 99)
* `args`: Any iptables, ip6tables and ebtables command line arguments
### Firewalld Direct Passthroughs
Direct passthroughs can be applied using the `firewalld_direct_passthrough` type
#### Example (Firewalld Direct Passthroughs)
```puppet
firewalld_direct_passthrough {'Forward traffic from OUTPUT to OUTPUT_filter':
ensure => 'present',
inet_protocol => 'ipv4',
args => '-A OUTPUT -j OUTPUT_filter'
}
```
#### Example in hiera (Firewalld Direct Passthroughs)
```yaml
firewalld::direct_passthroughs:
'Forward traffic from OUTPUT to OUTPUT_filter':
ensure: present
inet_protocol: ipv4
args: '-A OUTPUT -j OUTPUT_filter'
```
#### Parameters (Firewalld Direct Passthroushs)
* `name`: Resource name in Puppet
* `ensure`: present or absent
* `inet_protocol`: ipv4, ipv6 or eb, defaults to ipv4
* `args`: Name of the passthroughhrough to add (e.g:
-A OUTPUT -j OUTPUT_filter)
## Testing
### Unit Testing
Unit tests can be executed by running the following commands:
* `bundle install`
* `bundle exec rake spec`
### Acceptance Testing
Acceptance tests are performed using
[Beaker](https://github.com/puppetlabs/beaker) and require
[Vagrant](https://vagrantup.com) and
[VirtualBox](https://www.virtualbox.org) to run successfully.
It is **HIGHLY RECOMMENDED** that you use the upstream Vagrant package
and not one from your OS provider.
To run the acceptance tests:
* `bundle install`
* `bundle exec rake beaker`
To leave the Vagrant hosts running on failure for debugging:
* `BEAKER_destroy=onpass bundle exec rake beaker`
* `cd .vagrant/beaker_vagrant_files/default.yml`
* `vagrant ssh `
## Author
* Written Initially by Craig Dunn @crayfishx
* This module is now maintained by [VoxPupuli](https://voxpupuli.org)
* Thanks and acknowlegements to [Baloise
Group](http://baloise.github.io)