add ability to define rules in tables != filter

Previously it was neither possible to properly define custom chains nor
to define rules in tables other than the default filter table.
For various legitimate reasons it can be required to define rules in the
raw, nat or mangle tables, e.g. to use NOTRACK or to configure
DNAT/SNAT/MASQUERADE.
Additionally it might come in handy to define custom chains to group
certain rules and allow a more efficient evaluation for incoming packets
by not cramming all rules into the filter/INPUT chain so that
(worst-case) all packets need to traverse and evaluate all rules.

I have tried to maintain backwards compatibility and to not change
default filenames/paths so that it won't result in leftover obsolete unmaged
files from previous versions of this module.

In order to improve the naming schema the rule $policy has been renamed
to $action, however both parameters are available and optional now, with
some sanity checks that require at most one of them and issueing a
warning() for users of the now deprecated $policy parameter.

All previous tests have been adapted to the changes, a long with an
additional set of tests for the new feature.

Fixes #61

1 files changed, 115 insertions, 24 deletions

diff --git a/REFERENCE.md b/REFERENCE.md
index 39ba310..19ffae0 100644
--- a/REFERENCE.md
+++ b/REFERENCE.md
@@ -17,13 +17,15 @@ _Private Classes_
 
 **Defined types**
 
-* [`ferm::chain`](#fermchain): defined resource which creates all rules for one chain
-* [`ferm::rule`](#fermrule): defined resource which creates a single rule in a specific chain
+* [`ferm::chain`](#fermchain): This defined resource manages ferm/iptables chains
+* [`ferm::rule`](#fermrule): This defined resource manages a single rule in a specific chain
 
 **Data types**
 
-* [`Ferm::Policies`](#fermpolicies): a list of allowed default policies for a chain
+* [`Ferm::Actions`](#fermactions): a list of allowed actions for a rule
+* [`Ferm::Policies`](#fermpolicies): a list of allowed policies for a chain
 * [`Ferm::Protocols`](#fermprotocols): a list of allowed protocolls to match
+* [`Ferm::Tables`](#fermtables): a list of available tables
 
 ## Classes
 
@@ -123,7 +125,7 @@ Data type: `Ferm::Policies`
 
 Default policy for the FORWARD chain
 Default value: DROP
-Allowed values: (ACCEPT|DROP|REJECT)
+Allowed values: (ACCEPT|DROP)
 
 ##### `output_policy`
 
@@ -131,7 +133,7 @@ Data type: `Ferm::Policies`
 
 Default policy for the OUTPUT chain
 Default value: ACCEPT
-Allowed values: (ACCEPT|DROP|REJECT)
+Allowed values: (ACCEPT|DROP)
 
 ##### `input_policy`
 
@@ -139,7 +141,7 @@ Data type: `Ferm::Policies`
 
 Default policy for the INPUT chain
 Default value: DROP
-Allowed values: (ACCEPT|DROP|REJECT)
+Allowed values: (ACCEPT|DROP)
 
 ##### `rules`
 
@@ -193,17 +195,23 @@ Example: {'nat' => ['PREROUTING', 'POSTROUTING']}
 
 ### ferm::chain
 
-defined resource which creates all rules for one chain
+This defined resource manages ferm/iptables chains
 
-#### Parameters
+#### Examples
 
-The following parameters are available in the `ferm::chain` defined type.
+##### create a custom chain, e.g. for all incoming SSH connections
 
-##### `policy`
+```puppet
+ferm::chain{'check-ssh':
+  chain               => 'SSH',
+  disable_conntrack   => true,
+  log_dropped_packets => true,
+}
+```
 
-Data type: `Ferm::Policies`
+#### Parameters
 
-Set the default policy for a CHAIN
+The following parameters are available in the `ferm::chain` defined type.
 
 ##### `disable_conntrack`
 
@@ -211,23 +219,70 @@ Data type: `Boolean`
 
 Disable/Enable usage of conntrack
 
+##### `log_dropped_packets`
+
+Data type: `Boolean`
+
+Enable/Disable logging of packets to the kernel log, if no explicit chain matched
+
+##### `policy`
+
+Data type: `Optional[Ferm::Policies]`
+
+Set the default policy for CHAIN (works only for builtin chains)
+Default value: undef
+Allowed values: (ACCEPT|DROP) (see Ferm::Policies type)
+
+Default value: `undef`
+
 ##### `chain`
 
 Data type: `String[1]`
 
 Name of the chain that should be managed
+Default value: $name (resource name)
+Allowed values: String[1]
 
 Default value: $name
 
-##### `log_dropped_packets`
+##### `table`
 
-Data type: `Boolean`
+Data type: `Ferm::Tables`
 
-Enable/Disable logging of packets to the kernel log, if no explicit chain matched
+Select the target table (filter/raw/mangle/nat)
+Default value: 'filter'
+Allowed values: (filter|raw|mangle|nat) (see Ferm::Tables type)
+
+Default value: 'filter'
 
 ### ferm::rule
 
-defined resource which creates a single rule in a specific chain
+This defined resource manages a single rule in a specific chain
+
+#### Examples
+
+##### Jump to the 'SSH' chain for all incoming SSH traffic (see chain.pp examples on how to create the chain)
+
+```puppet
+ferm::rule{'incoming-ssh':
+  chain  => 'INPUT',
+  action => 'SSH',
+  proto  => 'tcp',
+  dport  => '22',
+}
+```
+
+##### Create a rule in the 'SSH' chain to allow connections from localhost
+
+```puppet
+ferm::rule{'allow-ssh-localhost':
+  chain  => 'SSH',
+  action => 'ACCEPT',
+  proto  => 'tcp',
+  dport  => '22',
+  saddr  => '127.0.0.1',
+}
+```
 
 #### Parameters
 
@@ -239,12 +294,6 @@ Data type: `String[1]`
 
 Configure the chain where we want to add the rule
 
-##### `policy`
-
-Data type: `Ferm::Policies`
-
-Configure what we want to do with the packet (drop, accept, log...)
-
 ##### `proto`
 
 Data type: `Ferm::Protocols`
@@ -259,6 +308,26 @@ A comment that will be added to the ferm config and to ip{,6}tables
 
 Default value: $name
 
+##### `action`
+
+Data type: `Optional[Ferm::Actions]`
+
+Configure what we want to do with the packet (drop/accept/reject, can also be a target chain name)
+Default value: undef
+Allowed values: (RETURN|ACCEPT|DROP|REJECT|NOTRACK|LOG|MARK|DNAT|SNAT|MASQUERADE|REDIRECT|String[1])
+
+Default value: `undef`
+
+##### `policy`
+
+Data type: `Optional[Ferm::Policies]`
+
+Configure what we want to do with the packet (drop/accept/reject, can also be a target chain name) [DEPRECATED]
+Default value: undef
+Allowed values: (RETURN|ACCEPT|DROP|REJECT|NOTRACK|LOG|MARK|DNAT|SNAT|MASQUERADE|REDIRECT|String[1])
+
+Default value: `undef`
+
 ##### `dport`
 
 Data type: `Optional[Variant[Stdlib::Port,String[1]]]`
@@ -315,13 +384,29 @@ Set the rule to present or absent
 
 Default value: 'present'
 
+##### `table`
+
+Data type: `Ferm::Tables`
+
+Select the target table (filter/raw/mangle/nat)
+Default value: filter
+Allowed values: (filter|raw|mangle|nat) (see Ferm::Tables type)
+
+Default value: 'filter'
+
 ## Data types
 
+### Ferm::Actions
+
+As you can also *jump* to other chains, each chain-name is also a valid action/target
+
+Alias of `Variant[Enum['RETURN', 'ACCEPT', 'DROP', 'REJECT', 'NOTRACK', 'LOG', 'MARK', 'DNAT', 'SNAT', 'MASQUERADE', 'REDIRECT'], String[1]]`
+
 ### Ferm::Policies
 
-a list of allowed default policies for a chain
+a list of allowed policies for a chain
 
-Alias of `Enum['ACCEPT', 'DROP', 'REJECT']`
+Alias of `Enum['ACCEPT', 'DROP']`
 
 ### Ferm::Protocols
 
@@ -329,3 +414,9 @@ a list of allowed protocolls to match
 
 Alias of `Enum['icmp', 'tcp', 'udp', 'udplite', 'icmpv6', 'esp', 'ah', 'sctp', 'mh', 'all']`
 
+### Ferm::Tables
+
+a list of available tables
+
+Alias of `Enum['raw', 'mangle', 'nat', 'filter']`
+