diff --git a/README.md b/README.md index 2ca19926..348220a7 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,18 @@ [![Puppet Forge - endorsement](https://img.shields.io/puppetforge/e/puppet/firewalld.svg)](https://forge.puppetlabs.com/puppet/firewalld) [![Puppet Forge - scores](https://img.shields.io/puppetforge/f/puppet/firewalld.svg)](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, ports, and rich rules. +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, ports, and rich rules. ## Compatibility -Latest versions of this module (3.0+) are only supported on Puppet 4.0+. 2.2.0 is the latest version to run on Puppet 3.x, important patches (security bugs..etc) will be accepted in the 2.x until Puppet 3.x is offically end-of-life, but new features will only be accepted in 3.x. +Latest versions of this module (3.0+) are only supported on Puppet 4.0+. 2.2.0 +is the latest version to run on Puppet 3.x, important patches (security +bugs..etc) will be accepted in the 2.x until Puppet 3.x is offically +end-of-life, but new features will only be accepted in 3.x. ## Usage @@ -23,37 +27,50 @@ Latest versions of this module (3.0+) are only supported on Puppet 4.0+. 2.2.0 class { 'firewalld': } ``` -#### Parameters +### Parameters + * `package`: Name of the package to install (default firewalld) -* `package_ensure`: Default 'installed', can be any supported ensure type for the package resource +* `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) +* `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) +* `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 * `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. - +* `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 @@ -66,9 +83,15 @@ This module supports a number of resource types * [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. +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 Firewalld zones can be managed with the `firewalld_zone` resource type. @@ -96,23 +119,34 @@ firewalld::zones: purge_ports: true ``` -#### Parameters +#### 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 * `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 rich rules +* `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 Rich Rules Firewalld rich rules are managed using the `firewalld_rich_rule` resource type -firewalld_rich_rules will `autorequire` the firewalld_zone specified in the `zone` parameter so there is no need to add dependencies for this +firewalld_rich_rules will `autorequire` the firewalld_zone specified in the +`zone` parameter so there is no need to add dependencies for this _Example in Class_: @@ -138,13 +172,15 @@ firewalld::rich_rules: action: 'accept' ``` -#### Parameters +#### Parameters (Firewalld Rich Rules) * `zone`: Name of the zone 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 +* `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', @@ -153,7 +189,10 @@ firewalld::rich_rules: 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 +* `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', @@ -162,28 +201,33 @@ firewalld::rich_rules: dest => { 'ipset' => 'blacklist' } ``` -* `log`: When set to `true` will enable logging, optionally this can be hash with `prefix`, `level` and `limit` +* `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` +* `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` +* `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 @@ -191,6 +235,7 @@ The following paramters are the element of the rich rule, only _one_ may be used * `protocol`: Protocol of the rich rule * `port`: A hash containing `port` and `protocol` values + ```puppet port => { 'port' => 80, @@ -203,6 +248,7 @@ The following paramters are the element of the rich rule, only _one_ may be used * `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', @@ -212,9 +258,11 @@ The following paramters are the element of the rich rule, only _one_ may be used }, ``` -## Firewalld Custom Service +### 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. +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. --- @@ -268,6 +316,7 @@ firewalld::custom_services: ``` This resource will create the following XML service definition in /etc/firewalld/services/XZY.xml + ``` @@ -279,22 +328,32 @@ This resource will create the following XML service definition in /etc/firewalld ``` -and you will also see 'puppet' in the service list when you issue ```firewall-cmd --permanent --get-services``` -#### Parameters +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) +* `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 -* `port`: (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 +* `port`: (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 port => [{'port' => '1234', 'protocol' => 'tcp'}], port => [{'port' => '4321', 'protocol' => 'udp'}, {'protocol' => 'rdp'}], ``` -The `port` parameter can also take a range of ports separated by a colon or a dash (colons are replaced by dashes), for example: +The `port` parameter can also take a range of ports separated by a colon or a +dash (colons are replaced by dashes), for example: ```puppet port => [ {'port' => '8000:8002', 'protocol' => 'tcp']} ] @@ -306,23 +365,33 @@ will produce: ``` -* `module`: (Optional) An array of strings specifying netfilter kernel helper modules associated with this service +* `module`: (Optional) An array of strings specifying netfilter kernel helper + modules associated with this service + +* `destination`: (Optional) A hash specifying the destination network as a + network IP address (optional with /mask), or a plain IP address. Valid hash + keys are 'ipv4' and 'ipv6', with values corresponding to the IP / mask + associated with each of those protocols. The use of hostnames is possible but + not recommended, because these will only be resolved at service activation and + transmitted to the kernel. -* `destination`: (Optional) A hash specifying the destination network as a network IP address (optional with /mask), or a plain IP address. Valid hash keys are 'ipv4' and 'ipv6', with values corresponding to the IP / mask associated with each of those protocols. The use of hostnames is possible but not recommended, because these will only be resolved at service activation and transmitted to the kernel. ```puppet destination => {'ipv4' => '127.0.0.1', 'ipv6' => '::1'}, destination => {'ipv4' => '192.168.0.0/24'}, ``` -* `config_dir`: The location where the service definition XML files will be stored. Defaults to /etc/firewalld/services +* `config_dir`: The location where the service definition XML files will be + stored. Defaults to /etc/firewalld/services -## Firewalld Service +### Firewalld Service -The `firewalld_service` type is used to add or remove both built in and custom services from zones. +The `firewalld_service` type is used to add or remove both built in and custom +services from zones. -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 +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_: @@ -352,20 +421,23 @@ firewalld::services: zone: public ``` -#### Parameters +#### 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. - -* `ensure`: Whether to add (`present`) or remove the service (`absent`), defaults to `present`. +* `zone`: Name of the zone in which you want to manage the service, defaults to + parameter `default_service_zone` of class `firewalld` if specified. +* `ensure`: Whether to add (`present`) or remove the service (`absent`), + defaults to `present`. -## Firewalld Ipsets +### Firewalld IPsets -Firewalld IPsets (on supported versions of firewalld) can be managed using the `firewalld_ipset` resource type +Firewalld IPsets (on supported versions of firewalld) can be managed using the +`firewalld_ipset` resource type _Example_: + ```puppet firewalld_ipset { 'whitelist': ensure => present, @@ -383,20 +455,22 @@ firewalld::ipsets: - 192.168.0.2 ``` -#### Parameters +#### 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. - +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 Firewalld ports can be managed with the `firewalld_port` resource type. -firewalld_port will `autorequire` the firewalld_zone specified in the `zone` parameter so there is no need to add dependencies for this +firewalld_port will `autorequire` the firewalld_zone specified in the `zone` +parameter so there is no need to add dependencies for this _Example_: @@ -420,21 +494,24 @@ firewalld::ports: protocol: 'tcp' ``` -#### Parameters +#### Parameters (Firewalld Ports) -* `zone`: Name of the zone this port belongs to, defaults to parameter `default_port_zone` of class `firewalld` if specified. +* `zone`: Name of the zone this port belongs to, defaults to parameter + `default_port_zone` of class `firewalld` if specified. * `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. +* `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`. +* `ensure`: Whether to add (`present`) or remove the service (`absent`), + defaults to `present`. -## Firewalld Direct Chains +### Firewalld Direct Chains Direct chains can be managed with the `firewalld_direct_chain` type -_Example_: +#### Example ```puppet firewalld_direct_chain {'Add custom chain LOG_DROPS': @@ -445,7 +522,8 @@ 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 +The title can also be mapped to the types namevars using a colon delimited +string, so the above can also be represented as ```puppet firewall_direct_chain { 'ipv4:filter:LOG_DROPS': @@ -453,7 +531,8 @@ firewall_direct_chain { 'ipv4:filter:LOG_DROPS': } ``` -_Example in hiera_ +#### Example in hiera + ``` firewalld::direct_chains: 'Add custom chain LOG_DROPS': @@ -463,17 +542,17 @@ firewalld::direct_chains: table: filter ``` -#### Parameters +#### Parameters (Firewalld Direct Chains) + * `name`: name of the chain, eg `LOG_DROPS` (namevar) * `inet_protocol`: ipv4 or ipv6, defaults to ipv4 (namevar) * `table`: The table (eg: filter) to apply the chain (namevar) - -## Firewalld Direct Rules +### Firewalld Direct Rules Direct rules can be applied using the `firewalld_direct_rule` type -_Example_: +#### Example (Firewalld Direct Rules) ```puppet @@ -487,7 +566,7 @@ _Example_: } ``` -_Example in hiera_ +#### Example in hiera (Firewalld Direct Rules) ```yaml firewalld::direct_rules: @@ -500,7 +579,7 @@ firewalld::direct_rules: args: '-p tcp --dport=22 -j ACCEPT' ``` -#### Parameters +#### Parameters (Firewalld Direct Rules) * `name`: Resource name in Puppet * `ensure`: present or absent @@ -510,11 +589,11 @@ firewalld::direct_rules: * `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 +### Firewalld Direct Passthroughs Direct passthroughs can be applied using the `firewalld_direct_passthrough` type -_Example_: +#### Example (Firewalld Direct Passthroughs) ```puppet @@ -525,7 +604,7 @@ _Example_: } ``` -_Example in hiera_ +#### Example in hiera (Firewalld Direct Passthroughs) ```yaml firewalld::direct_passthroughs: @@ -535,38 +614,44 @@ firewalld::direct_passthroughs: args: '-A OUTPUT -j OUTPUT_filter' ``` -#### Parameters +#### Parameters (Firewalld Direct Passthroushs) * `name`: Resource name in Puppet * `ensure`: present or absent * `inet_protocol`: ipv4 or ipv6, 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` + +* `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. +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. +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` + +* `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 +* `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)