From beb7c4247272569918aa0ed85ee5a95653f2b46f Mon Sep 17 00:00:00 2001 From: Tim Meusel Date: Fri, 13 Sep 2019 10:36:20 +0200 Subject: enhance puppet-strings documentation --- README.md | 122 ++++-------------------------------------------------- REFERENCE.md | 22 ++++++++++ manifests/rule.pp | 17 ++++++++ 3 files changed, 47 insertions(+), 114 deletions(-) diff --git a/README.md b/README.md index 2668e95..7ccc141 100644 --- a/README.md +++ b/README.md @@ -95,119 +95,9 @@ with the FQDN of a box. ## Reference -### Main class - -The main class has the following parameters: - -#### `manage_service` - -[Boolean] disable/enable the management of the ferm daemon - -#### `manage_configfile` - -[Boolean] disable/enable the management of the ferm default config - -#### `manage_initfile` - -[Boolean] disable/enable the management of the ferm init script for RedHat-based OS - -#### `configfile` - -[Stdlib::Absolutepath] path to the config file - -#### `forward_policy` - -[Ferm::Policies] default policy for the FORWARD chain - -#### `output_policy` - -[Ferm::Policies] default policy for the OUTPUT chain - -#### `input_policy` - -[Ferm::Policies] default policy for the INPUT chain - -#### `rules` - -A hash that holds all data for ferm::rule - -### rule defined resource - -This creates an entry in the correct chain file for ferm. - -#### `chain` - -The chain where we place this rule - -#### `policy` - -The desired policy. Allowed values are Enum['ACCEPT','DROP', 'REJECT'] - -#### `protocol` - -the protocol we would like to filter. Allowed values are Enum['icmp', 'tcp', 'udp'] - -### `proto_options` - -The protocol options we would like to add. -The following example will suppress the hostname in programs like `traceroute`: - -```yaml ---- -ferm::rules: - 'drop_output_traceroute': - chain: 'OUTPUT' - policy: 'DROP' - proto: 'icmp' - proto_options: 'icmp-type time-exceeded' -``` - -#### `comment` - -A comment that will be written into the file and into ip(6)tables - -#### `dport` - -The destination port we want to filter for. Can be any string from -/etc/services or an integer - -#### `sport` - -Like the destination port above, just for the source port - -#### `saddr` - -Source IPv4/IPv6 address. Can be one or many of them. Multiple addresses are -always encapsulated in braces: -'(127.0.0.1 2003::)' - -IPv4 and IPv6 addresses can be mixed. CIDR notation is possible if you want to -block networks, otherwise /32 or /128 is assumed by ferm/ip(6)tables - -#### `daddr` - -Same as above, just for the destination IP address - -#### `ensure` - -Add or remove it from the ruleset - -#### `interface` - -If set, this rule only applies to this specific interface - -### chain defined resource - -The module defines the three default chains for you, INPUT, FORWARD and OUTPUT. -You're able to define own chains if you want to - -#### `policy` - -The desired default policy for the chain - -#### `chain` - -The name of the chain +All parameters are documented within the classes. We generate markdown +documentation. It's available in the [REFERENCE.md](REFERENCE.md). It also +contains many examples. ## Development @@ -220,6 +110,10 @@ bundle install --path .vendor/ --without system_tests --without development --wi bundle exec rake test ``` +For more details about the development workflow and on how to contribute, +please check the [CONTRIBUTING.md](.github/CONTRIBUTING.md). + ## Authors -puppet-ferm is maintained by [Vox Pupuli](https://voxpupuli.org), it was written by [Tim 'bastelfreak' Meusel](https://github.com/bastelfreak). +puppet-ferm is maintained by [Vox Pupuli](https://voxpupuli.org), it was written +by [Tim 'bastelfreak' Meusel](https://github.com/bastelfreak). diff --git a/REFERENCE.md b/REFERENCE.md index 62a5d3b..3225969 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -292,6 +292,28 @@ ferm::rule{'allow-ssh-localhost': } ``` +##### Confuse people that do a traceroute/mtr/ping to your system + +```puppet +ferm::rule{'drop-icmp-time-exceeded': + chain => 'OUTPUT', + policy => 'DROP', + proto => 'icmp', + proto_options => 'icmp-type time-exceeded', +} +``` + +##### allow multiple protocols + +```puppet +ferm::rule{'allow_consul': + chain => 'INPUT', + policy => 'ACCEPT', + proto => ['udp', 'tcp'], + dport => 8301, +} +``` + #### Parameters The following parameters are available in the `ferm::rule` defined type. diff --git a/manifests/rule.pp b/manifests/rule.pp index a973601..1acbfd1 100644 --- a/manifests/rule.pp +++ b/manifests/rule.pp @@ -17,6 +17,23 @@ # saddr => '127.0.0.1', # } # +# +# @example Confuse people that do a traceroute/mtr/ping to your system +# ferm::rule{'drop-icmp-time-exceeded': +# chain => 'OUTPUT', +# policy => 'DROP', +# proto => 'icmp', +# proto_options => 'icmp-type time-exceeded', +# } +# +# @example allow multiple protocols +# ferm::rule{'allow_consul': +# chain => 'INPUT', +# policy => 'ACCEPT', +# proto => ['udp', 'tcp'], +# dport => 8301, +# } +# # @param chain Configure the chain where we want to add the rule # @param proto Which protocol do we want to match, typically UDP or TCP # @param comment A comment that will be added to the ferm config and to ip{,6}tables -- cgit v1.2.3