diff --git a/README.md b/README.md index b321070aa..47df87dbf 100644 --- a/README.md +++ b/README.md @@ -170,15 +170,7 @@ resources { 'firewallchain': Internal chains can not be deleted. In order to avoid all the confusing Warning/Notice messages when using `purge => true`, like these ones: - Notice: Compiled catalog for blonde-height.delivery.puppetlabs.net in environment production in 0.05 seconds - Warning: Firewallchain[INPUT:mangle:IPv4](provider=iptables_chain): Attempting to destroy internal chain INPUT:mangle:IPv4 - Notice: /Stage[main]/Main/Firewallchain[INPUT:mangle:IPv4]/ensure: removed - Warning: Firewallchain[FORWARD:mangle:IPv4](provider=iptables_chain): Attempting to destroy internal chain FORWARD:mangle:IPv4 - Notice: /Stage[main]/Main/Firewallchain[FORWARD:mangle:IPv4]/ensure: removed - Warning: Firewallchain[OUTPUT:mangle:IPv4](provider=iptables_chain): Attempting to destroy internal chain OUTPUT:mangle:IPv4 - Notice: /Stage[main]/Main/Firewallchain[OUTPUT:mangle:IPv4]/ensure: removed - Warning: Firewallchain[POSTROUTING:mangle:IPv4](provider=iptables_chain): Attempting to destroy internal chain POSTROUTING:mangle:IPv4 - Notice: /Stage[main]/Main/Firewallchain[POSTROUTING:mangle:IPv4]/ensure: removed + Warning: Inbuilt Chains may not be deleted. Chain `POSTROUTING:mangle:IPv6` will be flushed and have it's policy reverted to default. Please create firewallchains for every internal chain. Here is an example: @@ -248,7 +240,7 @@ firewall { '006 Allow inbound SSH (v6)': dport => 22, proto => 'tcp', action => 'accept', - provider => 'ip6tables', + protocol => 'ip6tables', } ``` @@ -280,10 +272,13 @@ class profile::apache { ### Rule inversion -Firewall rules may be inverted by prefixing the value of a parameter by "! ". If the value is an array, then every item in the array must be prefixed as iptables does not understand inverting a single value. +Firewall rules may be inverted by prefixing the value of a parameter by "! ". Parameters that understand inversion are: connmark, ctstate, destination, dport, dst\_range, dst\_type, iniface, outiface, port, proto, source, sport, src\_range and src\_type. +If the value is an array, then either the first value of the array, or all of its values must be prefixed in order to invert them all. +For most array attributes it is not possible to invert only one passed value. + Examples: ```puppet @@ -297,12 +292,23 @@ firewall { '002 drop NEW external website packets with FIN/RST/ACK set and SYN u state => 'NEW', action => 'drop', proto => 'tcp', - sport => ['! http', '! 443'], + sport => ['! http', '443'], source => '! 10.0.0.0/8', tcp_flags => '! FIN,SYN,RST,ACK SYN', } ``` +There are exceptions to this however, with attributes such as src\_type, dst\_type and ipset allowing the user to negate each passed values seperately. + +Examples: + +```puppet +firewall { '001 allow local disallow anycast': + action => 'accept', + src_type => ['LOCAL', '! ANYCAST'], +} +``` + ### Additional uses for the firewall module You can apply firewall rules to specific nodes. Usually, you should put the firewall rule in another class and apply that class to a node. Apply a rule to a node as follows: @@ -542,3 +548,60 @@ And run the tests from the root of the source code: ```text bundle exec rake parallel_spec ``` + +See also `.travis.yml` for information on running the acceptance and other tests. + +### Migration path to v7.0.0 + +As of `v7.0.0` of this module a major rework has been done to adopt the [puppet-resource_api](https://github.com/puppetlabs/puppet-resource_api) into the module and use it style of code in place of the original form of Puppet Type and Providers. As part of this several breaking changes where made to the code that will need to be accounted for whenever you update to this new version of the module. +These changes include: + +* The `provider` attibute within the `firewall` type has been renamed to `protocol`, both to bring it in line with the matching attribute within the `firewallchain` type and due to the resource_api forbidding the use of `provider` as a attribute name. As part of this the attribute has also been updated to accept `IPv4` and `IPv6` in place of `iptables` or `ip6tables`, though they are still valid as input. +* The `action` attribute within the `firewall` type has been removed as it was merely a restricted version of the `jump` attribute, both of them managing the same function, this being reasoned as a way to enforce the use of generic parameters. From this point the parameters formerly unique to `action` should now be passed to `jump`. +* Strict types have now been implemented for all attributes, while this should not require changes on the user end in most cases, there may be some instances where manifests will require updated to match the new expected form of input. +* Attributes that allow both arrays and negated values have now been updated. + * For attributes that require that all passed values be negated as one, you now merely have to negate the first value within the array, rather than all of them, though negating all is still accepted. + * For attributes that allow passed values to be negated seperately this is not the case. All attributes in this situation are noted within their description. +* The `sport` and `dport` attributes have been updated so that they will now accept with `:` or `-` as a separator when passing ranges, with `:` being preferred as it matchs what is passed to iptables. + +Two pairs of manifest tkane from the tests can be seen below, illustrating the changes that may be required, the fist applying a hoplimit on `ip6tables`: + +```Puppet +firewall { '571 - hop_limit': + ensure => present, + proto => 'tcp', + dport => '571', + action => 'accept', + hop_limit => '5', + provider => 'ip6tables', +} +``` + +```Puppet +firewall { '571 - hop_limit': + ensure => present, + proto => 'tcp', + dport => '571', + jump => 'accept', + hop_limit => '5', + protocol => 'IPv6', +} +``` + +And the second negating access to a range of ports on `iptables`: + +```puppet +firewall { '560 - negated ports': + proto => `tcp`, + sport => ['! 560-570','! 580'], + action => `accept`, +} +``` + +```puppet +firewall { '560 - negated ports': + proto => `tcp`, + sport => '! 560:570','580', + jump => `accept`, +} +``` diff --git a/REFERENCE.md b/REFERENCE.md index 004605396..2af1f988b 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -21,8 +21,8 @@ ### Resource types -* [`firewall`](#firewall): This type provides the capability to manage firewall rules within puppet. -* [`firewallchain`](#firewallchain): This type provides the capability to manage rule chains for firewalls. +* [`firewall`](#firewall): This type provides the capability to manage firewall rules within puppet via iptables. **Autorequires:** If Puppet is managing the iptables +* [`firewallchain`](#firewallchain): This type provides the capability to manage rule chains for firewalls. Currently this supports only iptables, ip6tables and ebtables on Linu ## Classes @@ -115,32 +115,19 @@ Default value: `false` ### `firewall` +This type provides the capability to manage firewall rules within puppet via iptables. + **Autorequires:** -If Puppet is managing the iptables or ip6tables chains specified in the +If Puppet is managing the iptables chains specified in the `chain` or `jump` parameters, the firewall resource will autorequire those firewallchain resources. If Puppet is managing the iptables, iptables-persistent, or iptables-services packages, -and the provider is iptables or ip6tables, the firewall resource will -autorequire those packages to ensure that any required binaries are +the firewall resource will autorequire those packages to ensure that any required binaries are installed. #### Providers - Note: Not all features are available with all providers. - - * ip6tables: Ip6tables type provider - - * Required binaries: ip6tables-save, ip6tables. - * Supported features: address_type, connection_limiting, conntrack, dnat, hop_limiting, icmp_match, - interface_match, iprange, ipsec_dir, ipsec_policy, ipset, iptables, isfirstfrag, - ishasmorefrags, islastfrag, length, log_level, log_prefix, log_uid, - log_tcp_sequence, log_tcp_options, log_ip_options, mask, mss, - owner, pkttype, queue_bypass, queue_num, rate_limiting, recent_limiting, reject_type, - snat, socket, state_match, string_matching, tcp_flags, hashlimit, bpf. - - * iptables: Iptables type provider - * Required binaries: iptables-save, iptables. * Default for kernel == linux. * Supported features: address_type, clusterip, connection_limiting, conntrack, dnat, icmp_match, @@ -249,1176 +236,1479 @@ installed. The following properties are available in the `firewall` type. -##### `action` - -Valid values: `accept`, `reject`, `drop` - -This is the action to perform on a match. Can be one of: - -* accept - the packet is accepted -* reject - the packet is rejected with a suitable ICMP response -* drop - the packet is dropped - -If you specify no value it will simply match the rule but perform no -action unless you provide a provider specific parameter (such as *jump*). - ##### `burst` -Valid values: `%r{^\d+$}` +Data type: `Optional[Integer[1]]` -Rate limiting burst value (per second) before limit checks apply. + Rate limiting burst value (per second) before limit checks apply. ##### `bytecode` -Match using Linux Socket Filter. Expects a BPF program in decimal format. -This is the format generated by the nfbpf_compile utility. +Data type: `Optional[String[1]]` + + Match using Linux Socket Filter. Expects a BPF program in decimal format. + This is the format generated by the nfbpf_compile utility. ##### `cgroup` -Matches against the net_cls cgroup ID of the packet. +Data type: `Optional[String[1]]` + + Matches against the net_cls cgroup ID of the packet. + + To negate add a space seperate `!` to the beginning of the string ##### `chain` -Valid values: `%r{^[a-zA-Z0-9\-_]+$}` +Data type: `String[1]` -Name of the chain to use. Can be one of the built-ins: + Name of the chain the rule will be a part of, ensure the chain you choose exists within your set table. + Can be one of the built-in chains: -* INPUT -* FORWARD -* OUTPUT -* PREROUTING -* POSTROUTING + * INPUT + * FORWARD + * OUTPUT + * PREROUTING + * POSTROUTING -Or you can provide a user-based chain. + Or you can provide a user-based chain. + Defaults to 'INPUT' Default value: `INPUT` ##### `checksum_fill` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Compute and fill missing packet checksums. + Compute and fill missing packet checksums. ##### `clamp_mss_to_pmtu` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Sets the clamp mss to pmtu flag. + Sets the clamp mss to pmtu flag. ##### `clusterip_clustermac` -Valid values: `%r{^([0-9a-f]{2}[:]){5}([0-9a-f]{2})$}i` +Data type: `Optional[Pattern[/^([0-9a-fA-F]{2}[:]){5}([0-9a-fA-F]{2})$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -Used with the CLUSTERIP jump target. -Specify the ClusterIP MAC address. Has to be a link-layer multicast address. + Used with the CLUSTERIP jump target. + Specify the ClusterIP MAC address. Has to be a link-layer multicast address. + This is IPv4 specific. ##### `clusterip_hash_init` -Used with the CLUSTERIP jump target. -Specify the random seed used for hash initialization. +Data type: `Optional[String[1]]` + + Used with the CLUSTERIP jump target. + Specify the random seed used for hash initialization. + This is IPv4 specific. ##### `clusterip_hashmode` -Valid values: `sourceip`, `sourceip-sourceport`, `sourceip-sourceport-destport` +Data type: `Optional[Enum['sourceip', 'sourceip-sourceport', 'sourceip-sourceport-destport']]` -Used with the CLUSTERIP jump target. -Specify the hashing mode. + Used with the CLUSTERIP jump target. + Specify the hashing mode. + This is IPv4 specific. ##### `clusterip_local_node` -Valid values: `%r{\d+}` +Data type: `Optional[Integer[1]]` -Used with the CLUSTERIP jump target. -Specify the random seed used for hash initialization. + Used with the CLUSTERIP jump target. + Specify the random seed used for hash initialization. + This is IPv4 specific. ##### `clusterip_new` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Used with the CLUSTERIP jump target. -Create a new ClusterIP. You always have to set this on the first rule for a given ClusterIP. + Used with the CLUSTERIP jump target. + Create a new ClusterIP. You always have to set this on the first rule for a given ClusterIP. + This is IPv4 specific. ##### `clusterip_total_nodes` -Valid values: `%r{\d+}` +Data type: `Optional[Integer[1]]` -Used with the CLUSTERIP jump target. -Number of total nodes within this cluster. + Used with the CLUSTERIP jump target. + Number of total nodes within this cluster. + This is IPv4 specific. ##### `condition` -Match on boolean value (0/1) stored in /proc/net/nf_condition/name. +Data type: `Optional[String[1]]` + + Match on boolean value (0/1) stored in /proc/net/nf_condition/name. ##### `connlimit_above` -Valid values: `%r{^\d+$}` +Data type: `Optional[Integer]` -Connection limiting value for matched connections above n. + Connection limiting value for matched connections above n. ##### `connlimit_mask` -Valid values: `%r{^\d+$}` +Data type: `Optional[Integer[0,128]]` + + Connection limiting by subnet mask for matched connections. + IPv4: 0-32 + IPv6: 0-128 + +##### `connlimit_upto` -Connection limiting by subnet mask for matched connections. -IPv4: 0-32 -IPv6: 0-128 +Data type: `Optional[Integer]` + + Connection limiting value for matched connections below or equal to n. ##### `connmark` -Match the Netfilter mark value associated with the packet. Accepts either of: -mark/mask or mark. These will be converted to hex if they are not already. +Data type: `Optional[Pattern[/^(?:!\s)?[a-fA-F0-9x]+$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Match the Netfilter mark value associated with the packet, accepts a mark. + This value will be converted to hex if it is not already. + This value can be negated by adding a space seperated `!` to the beginning. ##### `ctdir` -Valid values: `REPLY`, `ORIGINAL` +Data type: `Optional[Enum['REPLY', 'ORIGINAL']]` -Matches a packet that is flowing in the specified direction using the -conntrack module. If this flag is not specified at all, matches packets -in both directions. Values can be: + Matches a packet that is flowing in the specified direction using the + conntrack module. If this flag is not specified at all, matches packets + in both directions. Values can be: -* REPLY -* ORIGINAL + * REPLY + * ORIGINAL ##### `ctexpire` -Valid values: `%r{^!?\s?\d+$|^!?\s?\d+\:\d+$}` +Data type: `Optional[Pattern[/^(?:!\s)?\d+(?:\:\d+)?$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -Matches a packet based on lifetime remaining in seconds or range of values -using the conntrack module. For example: + Matches a packet based on lifetime remaining in seconds or range of seconds + using the conntrack module. For example: - ctexpire => '100:150' + ctexpire => '100' + ctexpire => '100:150' ##### `ctorigdst` -The original destination address using the conntrack module. For example: +Data type: `Optional[String[1]]` - ctorigdst => '192.168.2.0/24' + The original destination address using the conntrack module. For example: -You can also negate a mask by putting ! in front. For example: + ctorigdst => '192.168.2.0/24' - ctorigdst => '! 192.168.2.0/24' + You can also negate a mask by putting ! in front. For example: -The ctorigdst can also be an IPv6 address if your provider supports it. + ctorigdst => '! 192.168.2.0/24' + + The ctorigdst can also be an IPv6 address if your provider supports it. ##### `ctorigdstport` -Valid values: `%r{^!?\s?\d+$|^!?\s?\d+\:\d+$}` +Data type: `Optional[Pattern[/^(?:!\s)?\d+(?:\:\d+)?$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -The original destination port to match for this filter using the conntrack module. -For example: + The original destination port to match for this filter using the conntrack module. + For example: - ctorigdstport => '80' + ctorigdstport => '80' -You can also specify a port range: For example: + You can also specify a port range: For example: - ctorigdstport => '80:81' + ctorigdstport => '80:81' -You can also negate a port by putting ! in front. For example: + You can also negate a port by putting ! in front. For example: - ctorigdstport => '! 80' + ctorigdstport => '! 80' ##### `ctorigsrc` -The original source address using the conntrack module. For example: +Data type: `Optional[String[1]]` + + The original source address using the conntrack module. For example: - ctorigsrc => '192.168.2.0/24' + ctorigsrc => '192.168.2.0/24' -You can also negate a mask by putting ! in front. For example: + You can also negate a mask by putting ! in front. For example: - ctorigsrc => '! 192.168.2.0/24' + ctorigsrc => '! 192.168.2.0/24' -The ctorigsrc can also be an IPv6 address if your provider supports it. + The ctorigsrc can also be an IPv6 address if your provider supports it. ##### `ctorigsrcport` -Valid values: `%r{^!?\s?\d+$|^!?\s?\d+\:\d+$}` +Data type: `Optional[Pattern[/^(?:!\s)?\d+(?:\:\d+)?$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -The original source port to match for this filter using the conntrack module. -For example: + The original source port to match for this filter using the conntrack module. + For example: - ctorigsrcport => '80' + ctorigsrcport => '80' -You can also specify a port range: For example: + You can also specify a port range: For example: - ctorigsrcport => '80:81' + ctorigsrcport => '80:81' -You can also negate a port by putting ! in front. For example: + You can also negate a port by putting ! in front. For example: - ctorigsrcport => '! 80' + ctorigsrcport => '! 80' ##### `ctproto` -Valid values: `%r{^!?\s?\d+$}` +Data type: `Optional[Variant[Pattern[/^(?:!\s)?\d+$/],Integer]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -The specific layer-4 protocol number to match for this rule using the -conntrack module. + The specific layer-4 protocol number to match for this rule using the + conntrack module. ##### `ctrepldst` -The reply destination address using the conntrack module. For example: +Data type: `Optional[String[1]]` + + The reply destination address using the conntrack module. For example: - ctrepldst => '192.168.2.0/24' + ctrepldst => '192.168.2.0/24' -You can also negate a mask by putting ! in front. For example: + You can also negate a mask by putting ! in front. For example: - ctrepldst => '! 192.168.2.0/24' + ctrepldst => '! 192.168.2.0/24' -The ctrepldst can also be an IPv6 address if your provider supports it. + The ctrepldst can also be an IPv6 address if your provider supports it. ##### `ctrepldstport` -Valid values: `%r{^!?\s?\d+$|^!?\s?\d+\:\d+$}` +Data type: `Optional[Pattern[/^(?:!\s)?\d+(?:\:\d+)?$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -The reply destination port to match for this filter using the conntrack module. -For example: + The reply destination port to match for this filter using the conntrack module. + For example: - ctrepldstport => '80' + ctrepldstport => '80' -You can also specify a port range: For example: + You can also specify a port range: For example: - ctrepldstport => '80:81' + ctrepldstport => '80:81' -You can also negate a port by putting ! in front. For example: + You can also negate a port by putting ! in front. For example: - ctrepldstport => '! 80' + ctrepldstport => '! 80' ##### `ctreplsrc` -The reply source address using the conntrack module. For example: +Data type: `Optional[String[1]]` + + The reply source address using the conntrack module. For example: - ctreplsrc => '192.168.2.0/24' + ctreplsrc => '192.168.2.0/24' -You can also negate a mask by putting ! in front. For example: + You can also negate a mask by putting ! in front. For example: - ctreplsrc => '! 192.168.2.0/24' + ctreplsrc => '! 192.168.2.0/24' -The ctreplsrc can also be an IPv6 address if your provider supports it. + The ctreplsrc can also be an IPv6 address if your provider supports it. ##### `ctreplsrcport` -Valid values: `%r{^!?\s?\d+$|^!?\s?\d+\:\d+$}` +Data type: `Optional[Pattern[/^(?:!\s)?\d+(?:\:\d+)?$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -The reply source port to match for this filter using the conntrack module. -For example: + The reply source port to match for this filter using the conntrack module. + For example: - ctreplsrcport => '80' + ctreplsrcport => '80' -You can also specify a port range: For example: + You can also specify a port range: For example: - ctreplsrcport => '80:81' + ctreplsrcport => '80:81' -You can also negate a port by putting ! in front. For example: + You can also negate a port by putting ! in front. For example: - ctreplsrcport => '! 80' + ctreplsrcport => '! 80' ##### `ctstate` -Valid values: `INVALID`, `ESTABLISHED`, `NEW`, `RELATED`, `UNTRACKED`, `SNAT`, `DNAT` +Data type: `Optional[Variant[Pattern[/^(?:!\s)?(?:INVALID|ESTABLISHED|NEW|RELATED|UNTRACKED|SNAT|DNAT)$/], Array[Pattern[/^(?:!\s)?(?:INVALID|ESTABLISHED|NEW|RELATED|UNTRACKED|SNAT|DNAT)$/]]]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Matches a packet based on its state in the firewall stateful inspection + table, using the conntrack module. Values can be: + + * INVALID + * ESTABLISHED + * NEW + * RELATED + * UNTRACKED + * SNAT + * DNAT + + Can be passed either as a single String or as an Array, if passed as an array values should be passed in order: + + ctstate => 'INVALID' + ctstate => ['INVALID', 'ESTABLISHED'] + + Values can be negated by adding a '!'. + If you wish to negate multiple states at once, then place a ! at the start of the first array + variable. For example: -Matches a packet based on its state in the firewall stateful inspection -table, using the conntrack module. Values can be: + ctstate => ['! INVALID', 'ESTABLISHED'] -* INVALID -* ESTABLISHED -* NEW -* RELATED -* UNTRACKED -* SNAT -* DNAT + Note: this will negate all passed states, it is not possible to negate a single one of the array. ##### `ctstatus` -Valid values: `NONE`, `EXPECTED`, `SEEN_REPLY`, `ASSURED`, `CONFIRMED` +Data type: `Optional[Variant[Pattern[/^(?:!\s)?(?:EXPECTED|SEEN_REPLY|ASSURED|CONFIRMED|NONE)$/], Array[Pattern[/^(?:!\s)?(?:EXPECTED|SEEN_REPLY|ASSURED|CONFIRMED|NONE)$/]]]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -Matches a packet based on its status using the conntrack module. Values can be: + Matches a packet based on its status using the conntrack module. Values can be: -* EXPECTED -* SEEN_REPLY -* ASSURED -* CONFIRMED + * EXPECTED + * SEEN_REPLY + * ASSURED + * CONFIRMED + * NONE + + Can be passed either as a single String or as an Array: + + ctstatus => 'EXPECTED' + ctstatus => ['EXPECTED', 'CONFIRMED'] + + Values can be negated by adding a '!'. + If you wish to negate multiple states at once, then place a ! at the start of the first array + variable. For example: + + ctstatus => ['! EXPECTED', 'CONFIRMED'] + + Note: this will negate all passed states, it is not possible to negate a single one of the array. ##### `date_start` -Only match during the given time, which must be in ISO 8601 "T" notation. -The possible time range is 1970-01-01T00:00:00 to 2038-01-19T04:17:07 +Data type: `Optional[Pattern[/^[0-9]{4}\-(?:0[0-9]|1[0-2])\-(?:[0-2][0-9]|3[0-1])T(?:[0-1][0-9]|2[0-3])\:[0-5][0-9]\:[0-5][0-9]$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Only match during the given time, which must be in ISO 8601 "T" notation. + The possible time range is 1970-01-01T00:00:00 to 2038-01-19T04:17:07 ##### `date_stop` -Only match during the given time, which must be in ISO 8601 "T" notation. -The possible time range is 1970-01-01T00:00:00 to 2038-01-19T04:17:07 +Data type: `Optional[Pattern[/^[0-9]{4}\-(?:0[0-9]|1[0-2])\-(?:[0-2][0-9]|3[0-1])T(?:[0-1][0-9]|2[0-3])\:[0-5][0-9]\:[0-5][0-9]$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Only match during the given time, which must be in ISO 8601 "T" notation. + The possible time range is 1970-01-01T00:00:00 to 2038-01-19T04:17:07 ##### `destination` -The destination address to match. For example: +Data type: `Optional[String[1]]` + + The destination address to match. For example: - destination => '192.168.1.0/24' + destination => '192.168.1.0/24' -You can also negate a mask by putting ! in front. For example: + You can also negate a mask by putting ! in front. For example: - destination => '! 192.168.2.0/24' + destination => '! 192.168.2.0/24' -The destination can also be an IPv6 address if your provider supports it. + The destination can also be an IPv6 address if your provider supports it. ##### `dport` -The destination port to match for this filter (if the protocol supports -ports). Will accept a single element or an array. +Data type: `Optional[Variant[Array[Variant[Pattern[/^(?:!\s)?\d+(?:(?:\:|-)\d+)?$/],Integer]],Pattern[/^(?:!\s)?\d+(?:(?:\:|-)\d+)?$/],Integer]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + The source port to match for this filter (if the protocol supports + ports). Will accept a single element or an array. + + For some firewall providers you can pass a range of ports in the format: -For some firewall providers you can pass a range of ports in the format: + dport => '1:1024' - - + This would cover ports 1 to 1024. -For example: + You can also negate a port by putting ! in front. For example: - 1-1024 + dport => '! 54' -This would cover ports 1 to 1024. + If you wish to negate multiple ports at once, then place a ! at the start of the first array + variable. For example: + + dport => ['! 54','23'] + + Note: this will negate all passed ports, it is not possible to negate a single one of the array. ##### `dst_cc` -Valid values: `%r{^[A-Z]{2}(,[A-Z]{2})*$}` +Data type: `Optional[Pattern[/^[A-Z]{2}(,[A-Z]{2})*$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -dst attribute for the module geoip + dst attribute for the module geoip ##### `dst_range` -The destination IP range. For example: +Data type: `Optional[String[1]]` + + The destination IP range. For example: + + dst_range => '192.168.1.1-192.168.1.10' + + You can also negate the range by putting ! in front. For example: - dst_range => '192.168.1.1-192.168.1.10' + dst_range => '! 192.168.1.1-192.168.1.10' -The destination IP range must be in 'IP1-IP2' format. + The destination IP range must be in 'IP1-IP2' format. ##### `dst_type` -Valid values: `[:UNSPEC, :UNICAST, :LOCAL, :BROADCAST, :ANYCAST, :MULTICAST, - :BLACKHOLE, :UNREACHABLE, :PROHIBIT, :THROW, :NAT, :XRESOLVE].map { |address_type| - [ - address_type, - "! #{address_type}".to_sym, - "#{address_type} --limit-iface-in".to_sym, - "#{address_type} --limit-iface-out".to_sym, - "! #{address_type} --limit-iface-in".to_sym, - "! #{address_type} --limit-iface-out".to_sym, - ] - }.flatten` +Data type: `Optional[Variant[ + Array[Pattern[/^(?:!\s)?(?:UNSPEC|UNICAST|LOCAL|BROADCAST|ANYCAST|MULTICAST|BLACKHOLE|UNREACHABLE|UNREACHABLE|PROHIBIT|THROW|NAT|XRESOLVE)(?:\s--limit-iface-(?:in|out))?$/]], + Pattern[/^(?:!\s)?(?:UNSPEC|UNICAST|LOCAL|BROADCAST|ANYCAST|MULTICAST|BLACKHOLE|UNREACHABLE|UNREACHABLE|PROHIBIT|THROW|NAT|XRESOLVE)(?:\s--limit-iface-(?:in|out))?$/]]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -The destination address type. For example: + The destination address type. For example: - dst_type => ['LOCAL'] + dst_type => ['LOCAL'] -Can be one of: + Can be one of: -* UNSPEC - an unspecified address -* UNICAST - a unicast address -* LOCAL - a local address -* BROADCAST - a broadcast address -* ANYCAST - an anycast packet -* MULTICAST - a multicast address -* BLACKHOLE - a blackhole address -* UNREACHABLE - an unreachable address -* PROHIBIT - a prohibited address -* THROW - undocumented -* NAT - undocumented -* XRESOLVE - undocumented + * UNSPEC - an unspecified address + * UNICAST - a unicast address + * LOCAL - a local address + * BROADCAST - a broadcast address + * ANYCAST - an anycast packet + * MULTICAST - a multicast address + * BLACKHOLE - a blackhole address + * UNREACHABLE - an unreachable address + * PROHIBIT - a prohibited address + * THROW - undocumented + * NAT - undocumented + * XRESOLVE - undocumented -In addition, it accepts '--limit-iface-in' and '--limit-iface-out' flags, specified as: + In addition, it accepts '--limit-iface-in' and '--limit-iface-out' flags, specified as: - dst_type => ['LOCAL --limit-iface-in'] + dst_type => ['LOCAL --limit-iface-in'] -It can also be negated using '!': + Each value can be negated seperately using '!': - dst_type => ['! LOCAL'] + dst_type => ['! UNICAST', '! LOCAL'] -Will accept a single element or an array. + Will accept a single element or an array. ##### `ensure` -Valid values: `present`, `absent` +Data type: `Enum[present, absent, 'present', 'absent']` -Manage the state of this rule. + Whether this rule should be present or absent on the target system. Default value: `present` ##### `gateway` -The TEE target will clone a packet and redirect this clone to another -machine on the local network segment. gateway is the target host's IP. +Data type: `Optional[Pattern[/^(\d+.\d+.\d+.\d+|\w+:\w+::\w+)$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + The TEE target will clone a packet and redirect this clone to another + machine on the local network segment. + Gateway is the target host's IP. ##### `gid` -GID or Group owner matching rule. Accepts a string argument -only, as iptables does not accept multiple gid in a single -statement. +Data type: `Optional[Variant[String[1], Integer]]` + + GID or Group owner matching rule. Accepts a single argument + only, as iptables does not accept multiple gid in a single + statement. + To negate add a space seperated '!' in front of the value. ##### `goto` -The value for the iptables --goto parameter. Normal values are: +Data type: `Optional[Pattern[/^[a-zA-Z0-9_]+$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + The value for the iptables --goto parameter. Normal values are: -* QUEUE -* RETURN -* DNAT -* SNAT -* LOG -* MASQUERADE -* REDIRECT -* MARK + * QUEUE + * RETURN + * DNAT + * SNAT + * LOG + * MASQUERADE + * REDIRECT + * MARK -But any valid chain name is allowed. + But any valid chain name is allowed. ##### `hashlimit_above` -Match if the rate is above amount/quantum. -This parameter or hashlimit_upto is required. -Allowed forms are '40','40/second','40/minute','40/hour','40/day'. +Data type: `Optional[Pattern[/^\d+(?:\/(?:sec|min|hour|day))?$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Match if the rate is above amount/quantum. + This parameter or `hashlimit_upto` and `hashlimit_name` are required when setting any other hashlimit values. + Allowed forms are '40','40/sec','40/min','40/hour','40/day'. ##### `hashlimit_burst` -Valid values: `%r{^\d+$}` +Data type: `Optional[Integer[1]]` -Maximum initial number of packets to match: this number gets recharged by one every time the limit specified above is not reached, up to this number; the default is 5. When byte-based rate matching is requested, this option specifies the amount of bytes that can exceed the given rate. This option should be used with caution -- if the entry expires, the burst value is reset too. + Maximum initial number of packets to match: this number gets recharged by one every time the limit specified above is not reached, up to this number; the default is 5. + When byte-based rate matching is requested, this option specifies the amount of bytes that can exceed the given rate. + This option should be used with caution -- if the entry expires, the burst value is reset too. ##### `hashlimit_dstmask` -Like --hashlimit-srcmask, but for destination addresses. +Data type: `Optional[Integer[0,32]]` + + When --hashlimit-mode srcip is used, all destination addresses encountered will be grouped according to the given prefix length + and the so-created subnet will be subject to hashlimit. + Prefix must be between (inclusive) 0 and 32. + Note that --hashlimit-dstmask 0 is basically doing the same thing as not specifying srcip for --hashlimit-mode, but is technically more expensive. ##### `hashlimit_htable_expire` -After how many milliseconds do hash entries expire. +Data type: `Optional[Integer]` + + After how many milliseconds do hash entries expire. ##### `hashlimit_htable_gcinterval` -How many milliseconds between garbage collection intervals. +Data type: `Optional[Integer]` + + How many milliseconds between garbage collection intervals. ##### `hashlimit_htable_max` -Maximum entries in the hash. +Data type: `Optional[Integer]` + + Maximum entries in the hash. ##### `hashlimit_htable_size` -The number of buckets of the hash table +Data type: `Optional[Integer]` + + The number of buckets of the hash table ##### `hashlimit_mode` -A comma-separated list of objects to take into consideration. If no --hashlimit-mode option is given, hashlimit acts like limit, but at the expensive of doing the hash housekeeping. -Allowed values are: srcip, srcport, dstip, dstport +Data type: `Optional[Pattern[/^(?:srcip|srcport|dstip|dstport)(?:\,(?:srcip|srcport|dstip|dstport))*$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + A comma-separated list of objects to take into consideration. + If no --hashlimit-mode option is given, hashlimit acts like limit, but at the expensive of doing the hash housekeeping. + Allowed values are: srcip, srcport, dstip, dstport ##### `hashlimit_name` -The name for the /proc/net/ipt_hashlimit/foo entry. -This parameter is required. +Data type: `Optional[String[1]]` + + The name for the /proc/net/ipt_hashlimit/foo entry. + This parameter and either `hashlimit_upto` or `hashlimit_above` are required when setting any other hashlimit values. ##### `hashlimit_srcmask` -When --hashlimit-mode srcip is used, all source addresses encountered will be grouped according to the given prefix length and the so-created subnet will be subject to hashlimit. prefix must be between (inclusive) 0 and 32. Note that --hashlimit-srcmask 0 is basically doing the same thing as not specifying srcip for --hashlimit-mode, but is technically more expensive. +Data type: `Optional[Integer[0,32]]` + + When --hashlimit-mode srcip is used, all source addresses encountered will be grouped according to the given prefix length + and the so-created subnet will be subject to hashlimit. + Prefix must be between (inclusive) 0 and 32. + Note that --hashlimit-srcmask 0 is basically doing the same thing as not specifying srcip for --hashlimit-mode, but is technically more expensive. ##### `hashlimit_upto` -Match if the rate is below or equal to amount/quantum. It is specified either as a number, with an optional time quantum suffix (the default is 3/hour), or as amountb/second (number of bytes per second). -This parameter or hashlimit_above is required. -Allowed forms are '40','40/second','40/minute','40/hour','40/day'. +Data type: `Optional[Pattern[/^\d+(?:\/(?:sec|min|hour|day))?$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Match if the rate is below or equal to amount/quantum. It is specified either as a number, with an optional time quantum suffix (the default is 3/hour), or as amountb/second (number of bytes per second). + This parameter or `hashlimit_above` and `hashlimit_name` are required when setting any other hashlimit values. + Allowed forms are '40','40/sec','40/min','40/hour','40/day'. ##### `helper` -Invoke the nf_conntrack_xxx helper module for this packet. +Data type: `Optional[String[1]]` + + Invoke the nf_conntrack_xxx helper module for this packet. ##### `hop_limit` -Valid values: `%r{^\d+$}` +Data type: `Optional[Variant[Pattern[/^(?:!\s)?\d+$/],Integer]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -Hop limiting value for matched packets. + Hop limiting value for matched packets. + To negate add a space seperated `!` the the beginning of the value + This is IPv6 specific. ##### `icmp` -When matching ICMP packets, this is the type of ICMP packet to match. +Data type: `Optional[Variant[String[1],Integer]]` + + When matching ICMP packets, this is the type of ICMP packet to match. -A value of "any" is not supported. To achieve this behaviour the -parameter should simply be omitted or undefined. -An array of values is also not supported. To match against multiple ICMP -types, please use separate rules for each ICMP type. + A value of "any" is not supported. To achieve this behaviour the + parameter should simply be omitted or undefined. + An array of values is also not supported. To match against multiple ICMP + types, please use separate rules for each ICMP type. ##### `iniface` -Valid values: `%r{^!?\s?[a-zA-Z0-9\-\._\+\:@]+$}` +Data type: `Optional[Pattern[/^(?:!\s)?[a-zA-Z0-9\-\._\+\:@]+$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -Input interface to filter on. Supports interface alias like eth0:0. -To negate the match try this: + Input interface to filter on. Supports interface alias like eth0:0. + To negate the match try this: - iniface => '! lo', + iniface => '! lo', ##### `ipsec_dir` -Valid values: `in`, `out` +Data type: `Optional[Enum['in', 'out']]` -Sets the ipsec policy direction + Sets the ipsec policy direction ##### `ipsec_policy` -Valid values: `none`, `ipsec` +Data type: `Optional[Enum['none', 'ipsec']]` -Sets the ipsec policy type. May take a combination of arguments for any flags that can be passed to `--pol ipsec` such as: `--strict`, `--reqid 100`, `--next`, `--proto esp`, etc. + Sets the ipsec policy type. May take a combination of arguments for any flags that can be passed to `--pol ipsec` such as: `--strict`, `--reqid 100`, `--next`, `--proto esp`, etc. ##### `ipset` -Matches against the specified ipset list. -Requires ipset kernel module. Will accept a single element or an array. -The value is the name of the blacklist, followed by a space, and then -'src' and/or 'dst' separated by a comma. -For example: 'blacklist src,dst' +Data type: `Optional[Variant[Pattern[/^(?:!\s)?\w+\s(?:src|dst)(?:,src|,dst)?$/], Array[Pattern[/^(?:!\s)?\w+\s(?:src|dst)(?:,src|,dst)?$/]]]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Matches against the specified ipset list. + Requires ipset kernel module. Will accept a single element or an array. + The value is the name of the denylist, followed by a space, and then + 'src' and/or 'dst' separated by a comma. + For example: 'denylist src,dst' + To negate simply place a space seperated `!` at the beginning of a value. + Values can de negated independently. ##### `ipvs` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Indicates that the current packet belongs to an IPVS connection. + Match using Linux Socket Filter. Expects a BPF program in decimal format. + This is the format generated by the nfbpf_compile utility. ##### `isfirstfrag` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -If true, matches if the packet is the first fragment. -Sadly cannot be negated. ipv6. + Matches if the packet is the first fragment. + Specific to IPv6. ##### `isfragment` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Set to true to match tcp fragments (requires type to be set to tcp) + Set to true to match tcp fragments (requires proto to be set to tcp) ##### `ishasmorefrags` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -If true, matches if the packet has it's 'more fragments' bit set. ipv6. + Matches if the packet has it's 'more fragments' bit set. + Specific to IPv6. ##### `islastfrag` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -If true, matches if the packet is the last fragment. ipv6. + Matches if the packet is the last fragment. + Specific to IPv6. ##### `jump` -The value for the iptables --jump parameter. Normal values are: +Data type: `Optional[Pattern[/^[a-zA-Z0-9_]+$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -* QUEUE -* RETURN -* DNAT -* SNAT -* LOG -* NFLOG -* MASQUERADE -* REDIRECT -* MARK -* CT + This value for the iptables --jump parameter and the action to perform on a match. Common values are: -But any valid chain name is allowed. + * ACCEPT - the packet is accepted + * REJECT - the packet is rejected with a suitable ICMP response + * DROP - the packet is dropped -For the values ACCEPT, DROP, and REJECT, you must use the generic -'action' parameter. This is to enfore the use of generic parameters where -possible for maximum cross-platform modelling. + But can also be on of the following: -If you set both 'accept' and 'jump' parameters, you will get an error as -only one of the options should be set. + * QUEUE + * RETURN + * DNAT + * SNAT + * LOG + * NFLOG + * NETMAP + * MASQUERADE + * REDIRECT + * MARK + * CT + + And any valid chain name is also allowed. + + If you specify no value it will simply match the rule but perform no action. ##### `kernel_timezone` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Use the kernel timezone instead of UTC to determine whether a packet meets the time regulations. + Use the kernel timezone instead of UTC to determine whether a packet meets the time regulations. ##### `length` -Sets the length of layer-3 payload to match. +Data type: `Optional[Pattern[/^([0-9]+)(:)?([0-9]+)?$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Sets the length of layer-3 payload to match. + + Example values are: '500', '5:400' ##### `limit` -Rate limiting value for matched packets. The format is: -rate/[/second/|/minute|/hour|/day]. +Data type: `Optional[Pattern[/^\d+\/(?:sec(?:ond)?|min(?:ute)?|hour|day)$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Rate limiting value for matched packets. The format is: + rate/[/second/|/minute|/hour|/day] + + Example values are: '50/sec', '40/min', '30/hour', '10/day'." -Example values are: '50/sec', '40/min', '30/hour', '10/day'." +##### `line` + +Data type: `Optional[String[1]]` + + A read only attribute containing the full rule, used when deleting and when applying firewallchain purge attributes. ##### `log_ip_options` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -When combined with jump => "LOG" logging of the TCP IP/IPv6 -packet header. + When combined with jump => "LOG" logging of the TCP IP/IPv6 packet header. ##### `log_level` -When combined with jump => "LOG" specifies the system log level to log -to. +Data type: `Optional[Variant[Integer[0,7],String[1]]]` + + When combined with jump => "LOG" specifies the system log level to log to. + + Note: log level 4/warn is the default setting and as such it is not returned by iptables-save. + As a result, explicitly setting `log_level` to this can result in idempotency errors. ##### `log_prefix` -When combined with jump => "LOG" specifies the log prefix to use when -logging. +Data type: `Optional[String[1]]` + + When combined with jump => "LOG" specifies the log prefix to use when logging. ##### `log_tcp_options` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -When combined with jump => "LOG" logging of the TCP packet -header. + When combined with jump => "LOG" logging of the TCP packet header. ##### `log_tcp_sequence` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -When combined with jump => "LOG" enables logging of the TCP sequence -numbers. + When combined with jump => "LOG" enables logging of the TCP sequence numbers. ##### `log_uid` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -When combined with jump => "LOG" specifies the uid of the process making -the connection. + When combined with jump => "LOG" specifies the uid of the process making the connection. ##### `mac_source` -Valid values: `%r{^([0-9a-f]{2}[:]){5}([0-9a-f]{2})$}i` +Data type: `Optional[Pattern[/^(?:!\s)?([0-9a-fA-F]{2}[:]){5}([0-9a-fA-F]{2})$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -MAC Source + MAC Source ##### `mask` -Sets the mask to use when `recent` is enabled. +Data type: `Optional[Pattern[/^\d+\.\d+\.\d+\.\d+$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Recent module; sets the mask to use when `recent` is enabled. + The recent module defaults this to `255.255.255.255` when recent is set ##### `match_mark` -Match the Netfilter mark value associated with the packet. Accepts either of: -mark/mask or mark. These will be converted to hex if they are not already. +Data type: `Optional[Pattern[/^(?:!\s)?[a-fA-F0-9x]+$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Match the Netfilter mark value associated with the packet, accepts a mark. + This value will be converted to hex if it is not already. + This value can be negated by adding a space seperated `!` to the beginning. ##### `month_days` -Only match on the given days of the month. Possible values are 1 to 31. -Note that specifying 31 will of course not match on months which do not have a 31st day; -the same goes for 28- or 29-day February. +Data type: `Optional[Variant[Integer[0,31], Array[Integer[0,31]]]]` + + Only match on the given days of the month. Possible values are 1 to 31. + Note that specifying 31 will of course not match on months which do not have a 31st day; + the same goes for 28-day or 29-day February. + + Can be passed either as a single value or an array of values: + month_days => 5, + month_days => [5, 9, 23], ##### `mss` -Match a given TCP MSS value or range. +Data type: `Optional[Pattern[/^(?:!\s)?\d+(?:\:\d+)?$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Match a given TCP MSS value or range. + This value can be negated by adding a space seperated `!` to the beginning. ##### `nflog_group` -Used with the jump target NFLOG. -The netlink group (0 - 2^16-1) to which packets are (only applicable -for nfnetlink_log). Defaults to 0. +Data type: `Optional[Integer[1, 65535]]` + + Used with the jump target NFLOG. + The netlink group (0 - 2^16-1) to which packets are (only applicable + for nfnetlink_log). Defaults to 0. ##### `nflog_prefix` -Used with the jump target NFLOG. -A prefix string to include in the log message, up to 64 characters long, -useful for distinguishing messages in the logs. +Data type: `Optional[String]` + + Used with the jump target NFLOG. + A prefix string to include in the log message, up to 64 characters long, + useful for distinguishing messages in the logs. ##### `nflog_range` -Used with the jump target NFLOG. -This has never worked, use nflog_size instead. +Data type: `Optional[Integer[1]]` + + Used with the jump target NFLOG. + This has never worked, use nflog_size instead. ##### `nflog_size` -Used with the jump target NFLOG. -The number of bytes to be copied to userspace (only applicable for nfnetlink_log). -nfnetlink_log instances may specify their own size, this option overrides it. +Data type: `Optional[Integer[1]]` + + Used with the jump target NFLOG. + The number of bytes to be copied to userspace (only applicable for nfnetlink_log). + nfnetlink_log instances may specify their own size, this option overrides it. ##### `nflog_threshold` -Used with the jump target NFLOG. -Number of packets to queue inside the kernel before sending them to userspace -(only applicable for nfnetlink_log). Higher values result in less overhead -per packet, but increase delay until the packets reach userspace. Defaults to 1. +Data type: `Optional[Integer[1]]` + + Used with the jump target NFLOG. + Number of packets to queue inside the kernel before sending them to userspace + (only applicable for nfnetlink_log). Higher values result in less overhead + per packet, but increase delay until the packets reach userspace. Defaults to 1. ##### `notrack` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Invoke the disable connection tracking for this packet. -This parameter can be used with iptables version >= 1.8.3 + Invoke the disable connection tracking for this packet. + This parameter can be used with iptables version >= 1.8.3 ##### `outiface` -Valid values: `%r{^!?\s?[a-zA-Z0-9\-\._\+\:@]+$}` +Data type: `Optional[Pattern[/^(?:!\s)?[a-zA-Z0-9\-\._\+\:@]+$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ - Output interface to filter on. Supports interface alias like eth0:0. -To negate the match try this: + Output interface to filter on. Supports interface alias like eth0:0. + To negate the match try this: - outiface => '! lo', + outiface => '! lo', ##### `physdev_in` -Valid values: `%r{^[a-zA-Z0-9\-\._\+]+$}` +Data type: `Optional[Pattern[/^(?:!\s)?[a-zA-Z0-9\-\._\+]+$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -Match if the packet is entering a bridge from the given interface. + Match if the packet is entering a bridge from the given interface. + To negate the match try this: + + physdev_in => '! lo', ##### `physdev_is_bridged` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Match if the packet is transversing a bridge. + Match if the packet is transversing a bridge. ##### `physdev_is_in` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Matches if the packet has entered through a bridge interface. + Matches if the packet has entered through a bridge interface. ##### `physdev_is_out` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Matches if the packet will leave through a bridge interface. + Matches if the packet will leave through a bridge interface. ##### `physdev_out` -Valid values: `%r{^[a-zA-Z0-9\-\._\+]+$}` - -Match if the packet is leaving a bridge via the given interface. - -##### `pkttype` +Data type: `Optional[Pattern[/^(?:!\s)?[a-zA-Z0-9\-\._\+]+$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -Valid values: `unicast`, `broadcast`, `multicast` + Match if the packet is leaving a bridge via the given interface. + To negate the match try this: -Sets the packet type to match. + physdev_out => '! lo', -##### `port` +##### `pkttype` -*note* This property has been DEPRECATED +Data type: `Optional[Enum['unicast', 'broadcast', 'multicast']]` -The destination or source port to match for this filter (if the protocol -supports ports). Will accept a single element or an array. + Sets the packet type to match. -For some firewall providers you can pass a range of ports in the format: +##### `proto` - - +Data type: `Optional[Pattern[/^(?:!\s)?(?:ip(?:encap)?|tcp|udp|icmp|esp|ah|vrrp|carp|igmp|ipv4|ospf|gre|cbt|sctp|pim|all)/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -For example: + The specific protocol to match for this rule. - 1-1024 +Default value: `tcp` -This would cover ports 1 to 1024. +##### `protocol` -##### `proto` +Data type: `Enum['iptables', 'ip6tables', 'IPv4', 'IPv6']` -Valid values: `[:ip, :tcp, :udp, :icmp, :"ipv6-icmp", :esp, :ah, :vrrp, :carp, :igmp, :ipencap, :ipv4, :ipv6, :ospf, :gre, :cbt, :sctp, :pim, :all].map { |proto| - [proto, "! #{proto}".to_sym] - }.flatten` + The protocol used to set the rule, it's allowed values have been expanded to bring it closer to its `firewallchain` counterpart. + Defaults to `IPv4` -The specific protocol to match for this rule. + Noted: this was previously defined as `provider`, however the resource_api does not allow this to be used as an attribute title. -Default value: `tcp` +Default value: `IPv4` ##### `queue_bypass` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Used with NFQUEUE jump target -Allow packets to bypass :queue_num if userspace process is not listening + Allow packets to bypass :queue_num if userspace process is not listening ##### `queue_num` -Used with NFQUEUE jump target. -What queue number to send packets to +Data type: `Optional[Integer[1]]` + + Used with NFQUEUE jump target. + What queue number to send packets to ##### `random` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -When using a jump value of "MASQUERADE", "DNAT", "REDIRECT", or "SNAT" -this boolean will enable randomized port mapping. + When using a jump value of "MASQUERADE", "DNAT", "REDIRECT", or "SNAT" this boolean will enable randomized port mapping. ##### `random_fully` -Valid values: `true`, `false` - -When using a jump value of "MASQUERADE", "DNAT", "REDIRECT", or "SNAT" -this boolean will enable fully randomized port mapping. +Data type: `Optional[Boolean]` -**NOTE** Requires Kernel >= 3.13 and iptables >= 1.6.2 + When using a jump value of "MASQUERADE", "DNAT", "REDIRECT", or "SNAT" this boolean will enable fully randomized port mapping. ##### `rdest` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Recent module; add the destination IP address to the list. -Must be boolean true. + Recent module; add the destination IP address to the list. + Mutually exclusive with `rsource` + Must be boolean true. ##### `reap` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Recent module; can only be used in conjunction with the `rseconds` -attribute. When used, this will cause entries older than 'seconds' to be -purged. Must be boolean true. + Recent module; can only be used in conjunction with the `rseconds` + attribute. When used, this will cause entries older than 'seconds' to be + purged. Must be boolean true. ##### `recent` -Valid values: `set`, `update`, `rcheck`, `remove` - -Enable the recent module. Takes as an argument one of set, update, -rcheck or remove. For example: - - ``` - # If anyone's appeared on the 'badguy' blacklist within - # the last 60 seconds, drop their traffic, and update the timestamp. - firewall { '100 Drop badguy traffic': - recent => 'update', - rseconds => 60, - rsource => true, - rname => 'badguy', - action => 'DROP', - chain => 'FORWARD', - } - ``` - - - ``` - # No-one should be sending us traffic on eth0 from the - # localhost, Blacklist them - firewall { '101 blacklist strange traffic': - recent => 'set', - rsource => true, - rname => 'badguy', - destination => '127.0.0.0/8', - iniface => 'eth0', - action => 'DROP', - chain => 'FORWARD', - } - ``` +Data type: `Optional[Enum['set', 'update', 'rcheck', 'remove', '! set', '! update', '! rcheck', '! remove']]` + + Enable the recent module. Takes as an argument one of set, update, + rcheck or remove. For example: + + ``` + # If anyone's appeared on the 'badguy' blacklist within + # the last 60 seconds, drop their traffic, and update the timestamp. + firewall { '100 Drop badguy traffic': + recent => 'update', + rseconds => 60, + rsource => true, + rname => 'badguy', + jump => 'DROP', + chain => 'FORWARD', + } + ``` + + + ``` + # No-one should be sending us traffic on eth0 from the + # localhost, Blacklist them + firewall { '101 blacklist strange traffic': + recent => 'set', + rsource => true, + rname => 'badguy', + destination => '127.0.0.0/8', + iniface => 'eth0', + jump => 'DROP', + chain => 'FORWARD', + } + ``` ##### `reject` -When combined with action => "REJECT" you can specify a different icmp -response to be sent back to the packet sender. +Data type: `Optional[Enum['icmp-net-unreachable', 'icmp-host-unreachable', 'icmp-port-unreachable', 'icmp-proto-unreachable', + 'icmp-net-prohibited', 'icmp-host-prohibited', 'icmp-admin-prohibited', 'icmp6-no-route', 'no-route', + 'icmp6-adm-prohibited', 'adm-prohibited', 'icmp6-addr-unreachable', 'addr-unreach', 'icmp6-port-unreachable']]` + + When combined with jump => "REJECT" you can specify a different icmp response to be sent back to the packet sender. + Valid values differ depending on if the protocol is `IPv4` or `IPv6`. + IPv4 allows: icmp-net-unreachable, icmp-host-unreachable, icmp-port-unreachable, icmp-proto-unreachable, icmp-net-prohibited, + icmp-host-prohibited, or icmp-admin-prohibited. + IPv6 allows: icmp6-no-route, no-route, icmp6-adm-prohibited, adm-prohibited, icmp6-addr-unreachable, addr-unreach, or icmp6-port-unreachable. ##### `rhitcount` -Recent module; used in conjunction with `recent => 'update'` or `recent -=> 'rcheck'. When used, this will narrow the match to only happen when -the address is in the list and packets had been received greater than or -equal to the given value. +Data type: `Optional[Integer[1]]` + + Recent module; used in conjunction with `recent => 'update'` or `recent + => 'rcheck'. When used, this will narrow the match to only happen when + the address is in the list and packets had been received greater than or + equal to the given value. ##### `rname` -Recent module; The name of the list. Takes a string argument. +Data type: `Optional[String[1]]` + + Recent module; The name of the list. + The recent module defaults this to `DEFAULT` when recent is set ##### `rpfilter` -Valid values: `loose`, `validmark`, `accept-local`, `invert` +Data type: `Optional[Variant[Enum['loose', 'validmark', 'accept-local', 'invert'], Array[Enum['loose', 'validmark', 'accept-local', 'invert']]]]` -Enable the rpfilter module. + Enable the rpfilter module. ##### `rseconds` -Recent module; used in conjunction with one of `recent => 'rcheck'` or -`recent => 'update'`. When used, this will narrow the match to only -happen when the address is in the list and was seen within the last given -number of seconds. +Data type: `Optional[Integer[1]]` + + Recent module; used in conjunction with one of `recent => 'rcheck'` or + `recent => 'update'`. When used, this will narrow the match to only + happen when the address is in the list and was seen within the last given + number of seconds. ##### `rsource` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Recent module; add the source IP address to the list. -Must be boolean true. + Recent module; add the source IP address to the list. + Mutually exclusive with `rdest` + The recent module defaults this behaviour to true when recent is set. ##### `rttl` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -Recent module; may only be used in conjunction with one of `recent => -'rcheck'` or `recent => 'update'`. When used, this will narrow the match -to only happen when the address is in the list and the TTL of the current -packet matches that of the packet which hit the `recent => 'set'` rule. -This may be useful if you have problems with people faking their source -address in order to DoS you via this module by disallowing others access -to your site by sending bogus packets to you. Must be boolean true. + Recent module; may only be used in conjunction with one of `recent => + 'rcheck'` or `recent => 'update'`. When used, this will narrow the match + to only happen when the address is in the list and the TTL of the current + packet matches that of the packet which hit the `recent => 'set'` rule. + This may be useful if you have problems with people faking their source + address in order to DoS you via this module by disallowing others access + to your site by sending bogus packets to you. Must be boolean true. ##### `set_dscp` -Set DSCP Markings. +Data type: `Optional[String[1]]` + + Set DSCP Markings. ##### `set_dscp_class` -This sets the DSCP field according to a predefined DiffServ class. +Data type: `Optional[Enum['af11', 'af12', 'af13', 'af21', 'af22', 'af23', 'af31', 'af32', 'af33', 'af41', 'af42', 'af43', 'cs1', 'cs2', 'cs3', 'cs4', 'cs5', 'cs6', 'cs7', 'ef']]` + + This sets the DSCP field according to a predefined DiffServ class. ##### `set_mark` -Set the Netfilter mark value associated with the packet. Accepts either of: -mark/mask or mark. These will be converted to hex if they are not already. +Data type: `Optional[Pattern[/^[a-fA-F0-9x]+(?:\/[a-fA-F0-9x]+)?$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Set the Netfilter mark value associated with the packet. Accepts either of mark/mask or mark. + These will be converted to hex if they are not already. ##### `set_mss` -Sets the TCP MSS value for packets. +Data type: `Optional[Integer[1]]` + + Sets the TCP MSS value for packets. ##### `socket` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -If true, matches if an open socket can be found by doing a coket lookup -on the packet. + If true, matches if an open socket can be found by doing a coket lookup + on the packet. ##### `source` -The source address. For example: +Data type: `Optional[String[1]]` + + The source address. For example: - source => '192.168.2.0/24' + source => '192.168.2.0/24' -You can also negate a mask by putting ! in front. For example: + You can also negate a mask by putting ! in front. For example: - source => '! 192.168.2.0/24' + source => '! 192.168.2.0/24' -The source can also be an IPv6 address if your provider supports it. + The source can also be an IPv6 address if your provider supports it. ##### `sport` -The source port to match for this filter (if the protocol supports -ports). Will accept a single element or an array. +Data type: `Optional[Variant[Array[Variant[Pattern[/^(?:!\s)?\d+(?:(?:\:|-)\d+)?$/],Integer]],Pattern[/^(?:!\s)?\d+(?:(?:\:|-)\d+)?$/],Integer]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + The source port to match for this filter (if the protocol supports + ports). Will accept a single element or an array. -For some firewall providers you can pass a range of ports in the format: + For some firewall providers you can pass a range of ports in the format: - - + sport => '1:1024' -For example: + This would cover ports 1 to 1024. - 1-1024 + You can also negate a port by putting ! in front. For example: -This would cover ports 1 to 1024. + sport => '! 54' + + If you wish to negate multiple ports at once, then place a ! at the start of the first array + variable. For example: + + sport => ['! 54','23'] + + Note: this will negate all passed ports, it is not possible to negate a single one of the array. ##### `src_cc` -Valid values: `%r{^[A-Z]{2}(,[A-Z]{2})*$}` +Data type: `Optional[Pattern[/^[A-Z]{2}(,[A-Z]{2})*$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -src attribute for the module geoip + src attribute for the module geoip ##### `src_range` -The source IP range. For example: +Data type: `Optional[String[1]]` + + The source IP range. For example: + + src_range => '192.168.1.1-192.168.1.10' - src_range => '192.168.1.1-192.168.1.10' + You can also negate the range by apending a `!`` to the front. For example: -The source IP range must be in 'IP1-IP2' format. + src_range => '! 192.168.1.1-192.168.1.10' + + The source IP range must be in 'IP1-IP2' format. ##### `src_type` -Valid values: `[:UNSPEC, :UNICAST, :LOCAL, :BROADCAST, :ANYCAST, :MULTICAST, - :BLACKHOLE, :UNREACHABLE, :PROHIBIT, :THROW, :NAT, :XRESOLVE].map { |address_type| - [ - address_type, - "! #{address_type}".to_sym, - "#{address_type} --limit-iface-in".to_sym, - "#{address_type} --limit-iface-out".to_sym, - "! #{address_type} --limit-iface-in".to_sym, - "! #{address_type} --limit-iface-out".to_sym, - ] - }.flatten` +Data type: `Optional[Variant[ + Array[Pattern[/^(?:!\s)?(?:UNSPEC|UNICAST|LOCAL|BROADCAST|ANYCAST|MULTICAST|BLACKHOLE|UNREACHABLE|UNREACHABLE|PROHIBIT|THROW|NAT|XRESOLVE)(?:\s--limit-iface-(?:in|out))?$/]], + Pattern[/^(?:!\s)?(?:UNSPEC|UNICAST|LOCAL|BROADCAST|ANYCAST|MULTICAST|BLACKHOLE|UNREACHABLE|UNREACHABLE|PROHIBIT|THROW|NAT|XRESOLVE)(?:\s--limit-iface-(?:in|out))?$/]]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -The source address type. For example: + The source address type. For example: - src_type => ['LOCAL'] + src_type => 'LOCAL' -Can be one of: + Can be one of: -* UNSPEC - an unspecified address -* UNICAST - a unicast address -* LOCAL - a local address -* BROADCAST - a broadcast address -* ANYCAST - an anycast packet -* MULTICAST - a multicast address -* BLACKHOLE - a blackhole address -* UNREACHABLE - an unreachable address -* PROHIBIT - a prohibited address -* THROW - undocumented -* NAT - undocumented -* XRESOLVE - undocumented + * UNSPEC - an unspecified address + * UNICAST - a unicast address + * LOCAL - a local address + * BROADCAST - a broadcast address + * ANYCAST - an anycast packet + * MULTICAST - a multicast address + * BLACKHOLE - a blackhole address + * UNREACHABLE - an unreachable address + * PROHIBIT - a prohibited address + * THROW - undocumented + * NAT - undocumented + * XRESOLVE - undocumented -In addition, it accepts '--limit-iface-in' and '--limit-iface-out' flags, specified as: + In addition, it accepts '--limit-iface-in' and '--limit-iface-out' flags, specified as: - src_type => ['LOCAL --limit-iface-in'] + src_type => ['LOCAL --limit-iface-in'] -It can also be negated using '!': + It can also be negated using '!': - src_type => ['! LOCAL'] + src_type => ['! LOCAL'] -Will accept a single element or an array. + Will accept a single element or an array. Each element of the array should be negated seperately. ##### `stat_every` -Match one packet every nth packet. Requires `stat_mode => 'nth'` +Data type: `Optional[Integer[1]]` + + Match one packet every nth packet. Requires `stat_mode => 'nth'` ##### `stat_mode` -Valid values: `nth`, `random` +Data type: `Optional[Enum[nth, random]]` -Set the matching mode for statistic matching. + Set the matching mode for statistic matching. ##### `stat_packet` -Valid values: `%r{^\d+$}` +Data type: `Optional[Integer]` -Set the initial counter value for the nth mode. Must be between 0 and the value of `stat_every`. Defaults to 0. Requires `stat_mode => 'nth'` + Set the initial counter value for the nth mode. Must be between 0 and the value of `stat_every`. + Defaults to 0. Requires `stat_mode => 'nth'` ##### `stat_probability` -Set the probability from 0 to 1 for a packet to be randomly matched. It works only with `stat_mode => 'random'`. +Data type: `Optional[Variant[Integer[0,1], Float[0.0,1.0]]]` + + Set the probability from 0 to 1 for a packet to be randomly matched. It works only with `stat_mode => 'random'`. ##### `state` -Valid values: `INVALID`, `ESTABLISHED`, `NEW`, `RELATED`, `UNTRACKED` +Data type: `Optional[Variant[Pattern[/^(?:!\s)?(?:INVALID|ESTABLISHED|NEW|RELATED|UNTRACKED)$/], Array[Pattern[/^(?:!\s)?(?:INVALID|ESTABLISHED|NEW|RELATED|UNTRACKED)$/]]]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Matches a packet based on its state in the firewall stateful inspection + table. Values can be: + + * INVALID + * ESTABLISHED + * NEW + * RELATED + * UNTRACKED + * SNAT + * DNAT + + Can be passed either as a single String or as an Array: -Matches a packet based on its state in the firewall stateful inspection -table. Values can be: + state => 'INVALID' + state => ['INVALID', 'ESTABLISHED'] -* INVALID -* ESTABLISHED -* NEW -* RELATED -* UNTRACKED + Values can be negated by adding a '!'. + If you wish to negate multiple states at once, then place a ! at the start of the first array + variable. For example: + + state => ['! INVALID', 'ESTABLISHED'] + + Note: this will negate all passed states, it is not possible to negate a single one of the array. ##### `string` -String matching feature. Matches the packet against the pattern -given as an argument. +Data type: `Optional[String[1]]` + + String matching feature. Matches the packet against the pattern + given as an argument. + To negate, add a space seperated `!` to the beginning of the string. ##### `string_algo` -Valid values: `bm`, `kmp` +Data type: `Optional[Enum['bm', 'kmp']]` -String matching feature, pattern matching strategy. + String matching feature, pattern matching strategy. ##### `string_from` -String matching feature, offset from which we start looking for any matching. +Data type: `Optional[Integer[1]]` + + String matching feature, offset from which we start looking for any matching. ##### `string_hex` -String matching feature. Matches the package against the hex pattern -given as an argument. +Data type: `Optional[Pattern[/^(?:!\s)?\|[a-zA-Z0-9\s]+\|$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + String matching feature. Matches the packet against the pattern + given as an argument. + To negate, add a space seperated `!` to the beginning of the string. ##### `string_to` -String matching feature, offset up to which we should scan. +Data type: `Optional[Integer[1]]` + + String matching feature, offset up to which we should scan. ##### `table` -Valid values: `nat`, `mangle`, `filter`, `raw`, `rawpost` +Data type: `Enum['nat', 'mangle', 'filter', 'raw', 'rawpost', 'broute', 'security']` + + The table the rule will exist in. + Valid options are: -Table to use. Can be one of: + * nat + * mangle + * filter + * raw + * rawpost -* nat -* mangle -* filter -* raw -* rawpost + Defaults to 'filter' Default value: `filter` ##### `tcp_flags` -Match when the TCP flags are as specified. -Is a string with a list of comma-separated flag names for the mask, -then a space, then a comma-separated list of flags that should be set. -The flags are: SYN ACK FIN RST URG PSH ALL NONE -Note that you specify them in the order that iptables --list-rules -would list them to avoid having puppet think you changed the flags. -Example: FIN,SYN,RST,ACK SYN matches packets with the SYN bit set and the -ACK,RST and FIN bits cleared. Such packets are used to request -TCP connection initiation. +Data type: `Optional[Pattern[/^(?:!\s)?((FIN|SYN|RST|PSH|ACK|URG|ALL|NONE),?)+\s((FIN|SYN|RST|PSH|ACK|URG|ALL|NONE),?)+$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Match when the TCP flags are as specified. + Is a string with a list of comma-separated flag names for the mask, + then a space, then a comma-separated list of flags that should be set. + The flags are: FIN SYN RST PSH ACK URG ALL NONE + Note that you specify them in the order that iptables --list-rules + would list them to avoid having puppet think you changed the flags. + + Example: FIN,SYN,RST,ACK SYN matches packets with the SYN bit set and the + ACK,RST and FIN bits cleared. Such packets are used to request + TCP connection initiation. + Can be negated by placing ! in front, i.e. + ! FIN,SYN,RST,ACK SYN + +##### `tcp_option` + +Data type: `Optional[Variant[Pattern[/^(?:!\s)?(?:[0-1][0-9]{0,2}|2[0-4][0-9]|25[0-5])$/], Integer[0,255]]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Match when the TCP option is present or absent. + Given as a single TCP option, optionally prefixed with '! ' to match + on absence instead. Only one TCP option can be matched in a given rule. + TCP option numbers are an eight-bit field, so valid option numbers range + from 0-255. ##### `time_contiguous` -Valid values: `true`, `false` +Data type: `Optional[Boolean]` -When time_stop is smaller than time_start value, match this as a single time period instead distinct intervals. + When time_stop is smaller than time_start value, match this as a single time period instead distinct intervals. ##### `time_start` -Only match during the given daytime. The possible time range is 00:00:00 to 23:59:59. -Leading zeroes are allowed (e.g. "06:03") and correctly interpreted as base-10. +Data type: `Optional[Pattern[/^([0-9]|[0-1][0-9]|2[0-3])\:[0-5][0-9](?:\:[0-5][0-9])?/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Only match during the given daytime. The possible time range is 00:00:00 to 23:59:59. + Leading zeroes are allowed (e.g. "06:03") and correctly interpreted as base-10. ##### `time_stop` -Only match during the given daytime. The possible time range is 00:00:00 to 23:59:59. -Leading zeroes are allowed (e.g. "06:03") and correctly interpreted as base-10. +Data type: `Optional[Pattern[/^([0-9]|[0-1][0-9]|2[0-3])\:[0-5][0-9](?:\:[0-5][0-9])?/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Only match during the given daytime. The possible time range is 00:00:00 to 23:59:59. + Leading zeroes are allowed (e.g. "06:03") and correctly interpreted as base-10. ##### `to` -For NETMAP this will replace the destination IP +Data type: `Optional[String[1]]` + + For NETMAP this will replace the destination IP ##### `todest` -When using jump => "DNAT" you can specify the new destination address -using this paramter. +Data type: `Optional[String[1]]` + + When using jump => "DNAT" you can specify the new destination address using this paramter. + Can specify a single new destination IP address or an inclusive range of IP addresses. + Optionally a port or a port range with a possible follow up baseport can be provided. + Input structure: [ipaddr[-ipaddr]][:port[-port[/baseport]]] ##### `toports` -For DNAT this is the port that will replace the destination port. +Data type: `Optional[Pattern[/^\d+(?:-\d+)?$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + For REDIRECT/MASQUERADE this is the port that will replace the destination/source port. + Can specify a single new port or an inclusive range of ports. ##### `tosource` -When using jump => "SNAT" you can specify the new source address using -this parameter. +Data type: `Optional[String[1]]` + + When using jump => "SNAT" you can specify the new source address using this paramter. + Can specify a single new destination IP address or an inclusive range of IP addresses. + Input structure: [ipaddr[-ipaddr]][:port[-port]] + +##### `u32` + +Data type: `Optional[Pattern[/^0x[0-9a-fA-F]+&0x[0-9a-fA-F]+=0x[0-9a-fA-F]+(?::0x[0-9a-fA-F]+)?(?:&&0x[0-9a-fA-F]+&0x[0-9a-fA-F]+=0x[0-9a-fA-F]+(?::0x[0-9a-fA-F]+)?)*$/]]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ + + Enable the u32 module. Takes as an argument one of set, update, + rcheck or remove. For example: + firewall { '032 u32 test': + ensure => present, + table => 'mangle', + chain => 'PREROUTING', + u32 => '0x4&0x1fff=0x0&&0x0&0xf000000=0x5000000', + jump => 'DROP', + } ##### `uid` -UID or Username owner matching rule. Accepts a string argument -only, as iptables does not accept multiple uid in a single -statement. +Data type: `Optional[Variant[String[1], Integer]]` + + UID or Username owner matching rule. Accepts a single argument + only, as iptables does not accept multiple uid in a single + statement. + To negate add a space seperated '!' in front of the value. ##### `week_days` -Valid values: `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, `Sun` +Data type: `Optional[Variant[Enum['Mon','Tue','Wed','Thu','Fri','Sat','Sun'], Array[Enum['Mon','Tue','Wed','Thu','Fri','Sat','Sun']]]]` -Only match on the given weekdays. + Only match on the given weekdays. + + Can be passed either as a single value or an array of values: + week_days => 'Mon', + week_days => ['Mon', 'Tue', 'Wed'], ##### `zone` -Assign this packet to zone id and only have lookups done in that zone. +Data type: `Optional[Integer]` + + Assign this packet to zone id and only have lookups done in that zone. #### Parameters The following parameters are available in the `firewall` type. -* [`line`](#-firewall--line) * [`name`](#-firewall--name) -* [`provider`](#-firewall--provider) - -##### `line` - -Read-only property for caching the rule line. ##### `name` -Valid values: `%r{^\d+[[:graph:][:space:]]+$}` - namevar -The canonical name of the rule. This name is also used for ordering -so make sure you prefix the rule with a number: - - 000 this runs first - 999 this runs last +Data type: `Pattern[/(^\d+(?:[ \t-]\S+)+$)/]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -Depending on the provider, the name of the rule can be stored using -the comment feature of the underlying firewall subsystem. + The canonical name of the rule. This name is also used for ordering + so make sure you prefix the rule with a number: -##### `provider` + 000 this runs first + 999 this runs last -The specific backend to use for this `firewall` resource. You will seldom need to specify this --- Puppet will usually -discover the appropriate provider for your platform. + Depending on the provider, the name of the rule can be stored using + the comment feature of the underlying firewall subsystem. ### `firewallchain` +This type provides the capability to manage rule chains for firewalls. + Currently this supports only iptables, ip6tables and ebtables on Linux. And provides support for setting the default policy on chains and tables that allow it. -**Autorequires:** -If Puppet is managing the iptables, iptables-persistent, or iptables-services packages, -and the provider is iptables_chain, the firewall resource will autorequire -those packages to ensure that any required binaries are installed. - #### Providers * iptables_chain is the only provider that supports firewallchain. @@ -1432,89 +1722,78 @@ The following properties are available in the `firewallchain` type. ##### `ensure` -Valid values: `present`, `absent` +Data type: `Enum[present, absent]` -The basic property that the resource should be in. + Whether this chain should be present or absent on the target system. + Setting this to absent will first remove all rules associated with this chain and then delete the chain itself. + Inbuilt chains however will merely remove any added rules and, if it has been changed, return their policy to the default. Default value: `present` -##### `policy` +##### `ignore` -Valid values: `accept`, `drop`, `queue`, `return` +Data type: `Optional[Variant[String[1], Array[String[1]]]]` -This is the action to when the end of the chain is reached. -It can only be set on inbuilt chains (INPUT, FORWARD, OUTPUT, -PREROUTING, POSTROUTING) and can be one of: + Regex to perform on firewall rules to exempt unmanaged rules from purging. + This is matched against the output of `iptables-save`. + + This can be a single regex, or an array of them. + To support flags, use the ruby inline flag mechanism. + Meaning a regex such as + /foo/i + can be written as + '(?i)foo' or '(?i:foo)' + + Full example: + ``` + firewallchain { 'INPUT:filter:IPv4': + purge => true, + ignore => [ + '-j fail2ban-ssh', # ignore the fail2ban jump rule + '--comment "[^"]*(?i:ignore)[^"]*"', # ignore any rules with "ignore" (case insensitive) in the comment in the rule + ], + } + ``` + +##### `ignore_foreign` -* accept - the packet is accepted -* drop - the packet is dropped -* queue - the packet is passed userspace -* return - the packet is returned to calling (jump) queue - or the default of inbuilt chains +Data type: `Boolean` -#### Parameters + Ignore rules that do not match the puppet title pattern "^\d+[[:graph:][:space:]]" when purging unmanaged firewall rules in this chain. + This can be used to ignore rules that were not put in by puppet. Beware that nothing keeps other systems from configuring firewall rules with a comment that starts with digits, and is indistinguishable from puppet-configured rules. -The following parameters are available in the `firewallchain` type. +##### `policy` -* [`ignore`](#-firewallchain--ignore) -* [`ignore_foreign`](#-firewallchain--ignore_foreign) -* [`name`](#-firewallchain--name) -* [`provider`](#-firewallchain--provider) -* [`purge`](#-firewallchain--purge) +Data type: `Optional[Enum['accept', 'drop', 'queue', 'return']]` -##### `ignore` + This action to take when the end of the chain is reached. + This can only be set on inbuilt chains (i.e. INPUT, FORWARD, OUTPUT, + PREROUTING, POSTROUTING) and can be one of: -Regex to perform on firewall rules to exempt unmanaged rules from purging (when enabled). -This is matched against the output of `iptables-save`. + * accept - the packet is accepted + * drop - the packet is dropped + * queue - the packet is passed userspace + * return - the packet is returned to calling (jump) queue + or the default of inbuilt chains -This can be a single regex, or an array of them. -To support flags, use the ruby inline flag mechanism. -Meaning a regex such as - /foo/i -can be written as - '(?i)foo' or '(?i:foo)' +##### `purge` -Full example: -``` -firewallchain { 'INPUT:filter:IPv4': - purge => true, - ignore => [ - '-j fail2ban-ssh', # ignore the fail2ban jump rule - '--comment "[^"]*(?i:ignore)[^"]*"', # ignore any rules with "ignore" (case insensitive) in the comment in the rule - ], -} -``` +Data type: `Boolean` -##### `ignore_foreign` +Whether or not to purge unmanaged rules in this chain -Valid values: `false`, `true` +#### Parameters -Ignore rules that do not match the puppet title pattern "^\d+[[:graph:][:space:]]" when purging unmanaged firewall rules -in this chain. -This can be used to ignore rules that were not put in by puppet. Beware that nothing keeps other systems from -configuring firewall rules with a comment that starts with digits, and is indistinguishable from puppet-configured -rules. +The following parameters are available in the `firewallchain` type. -Default value: `false` +* [`name`](#-firewallchain--name) ##### `name` namevar -The canonical name of the chain. - -For iptables the format must be {chain}:{table}:{protocol}. - -##### `provider` +Data type: `Pattern[/^(?:\S+):(?:nat|mangle|filter|raw|rawpost|broute|security):(?:IP(?:v[46])?|ethernet)$/]` +_*this data type contains a regex that may not be accurately reflected in generated documentation_ -The specific backend to use for this `firewallchain` resource. You will seldom need to specify this --- Puppet will -usually discover the appropriate provider for your platform. - -##### `purge` - -Valid values: `false`, `true` - -Purge unmanaged firewall rules in this chain - -Default value: `false` +The canonical name of the chain with the required format being `{chain}:{table}:{protocol}`.