From 882a45498ddefdfc83ff5b19da723fd0be3acdec Mon Sep 17 00:00:00 2001 From: Thore Bödecker Date: Tue, 3 Sep 2019 11:56:58 +0200 Subject: 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 --- REFERENCE.md | 139 ++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 115 insertions(+), 24 deletions(-) (limited to 'REFERENCE.md') 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']` + -- cgit v1.2.3