Mercurial > repos > other > Puppet

comparison modules/firewall/README.md @ 398:66c406eec60d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update and fix firewall for Ubuntu * Use later version of module (not latest because our Puppet isn't supported) * Change how we define "ensure" because Ubuntu doesn't use IPv6 methods
author IBBoard <dev@ibboard.co.uk>
date Wed, 20 Apr 2022 19:04:13 +0100
parents 11d940c9014e
children
comparison
equal deleted inserted replaced
397:e22eee1d79ef 398:66c406eec60d
1 # firewall 1 # firewall
2 2
3 [![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-firewall.png?branch=master)](https://travis-ci.org/puppetlabs/puppetlabs-firewall) 3 [![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-firewall.png?branch=main)](https://travis-ci.org/puppetlabs/puppetlabs-firewall)
4 4
5 #### Table of Contents 5 #### Table of Contents
6 6
7 1. [Overview - What is the firewall module?](#overview) 7 1. [Overview - What is the firewall module?](#overview)
8 2. [Module description - What does the module do?](#module-description) 8 2. [Module description - What does the module do?](#module-description)
47 47
48 ### Beginning with firewall 48 ### Beginning with firewall
49 49
50 In the following two sections, you create new classes and then create firewall rules related to those classes. These steps are optional but provide a framework for firewall rules, which is helpful if you’re just starting to create them. 50 In the following two sections, you create new classes and then create firewall rules related to those classes. These steps are optional but provide a framework for firewall rules, which is helpful if you’re just starting to create them.
51 51
52 If you already have rules in place, then you don’t need to do these two sections. However, be aware of the ordering of your firewall rules. The module will dynamically apply rules in the order they appear in the catalog, meaning a deny rule could be applied before the allow rules. This might mean the module hasn’t established some of the important connections, such as the connection to the Puppet master. 52 If you already have rules in place, then you don’t need to do these two sections. However, be aware of the ordering of your firewall rules. The module will dynamically apply rules in the order they appear in the catalog, meaning a deny rule could be applied before the allow rules. This might mean the module hasn’t established some of the important connections, such as the connection to the Puppet server.
53 53
54 The following steps are designed to ensure that you keep your SSH and other connections, primarily your connection to your Puppet master. If you create the `pre` and `post` classes described in the first section, then you also need to create the rules described in the second section. 54 The following steps are designed to ensure that you keep your SSH and other connections, primarily your connection to your Puppet server. If you create the `pre` and `post` classes described in the first section, then you also need to create the rules described in the second section.
55 55
56 #### Create the `my_fw::pre` and `my_fw::post` Classes 56 #### Create the `my_fw::pre` and `my_fw::post` Classes
57 57
58 This approach employs a whitelist setup, so you can define what rules you want and everything else is ignored rather than removed. 58 This approach employs a whitelist setup, so you can define what rules you want and everything else is ignored rather than removed.
59 59
125 125
126 The rules you create here are helpful if you don’t have any existing rules; they help you order your firewall configurations so you don’t lock yourself out of your box. 126 The rules you create here are helpful if you don’t have any existing rules; they help you order your firewall configurations so you don’t lock yourself out of your box.
127 127
128 Rules are persisted automatically between reboots, although there are known issues with ip6tables on older Debian/Ubuntu distributions. There are also known issues with ebtables. 128 Rules are persisted automatically between reboots, although there are known issues with ip6tables on older Debian/Ubuntu distributions. There are also known issues with ebtables.
129 129
130 1. In site.pp or another top-scope file, add the following code to set up a metatype to purge unmanaged firewall resources. This will clear any existing rules and make sure that only rules defined in Puppet exist on the machine. 130 1. Use the following code to set up the default parameters for all of the firewall rules that you will establish later. These defaults will ensure that the `pre` and `post` classes are run in the correct order and avoid locking you out of your box during the first Puppet run.
131
132 ```puppet
133 Firewall {
134 before => Class['my_fw::post'],
135 require => Class['my_fw::pre'],
136 }
137 ```
138
139 2. Declare the `my_fw::pre` and `my_fw::post` classes to satisfy dependencies. You can declare these classes using an external node classifier or the following code:
140
141 ```puppet
142 class { ['my_fw::pre', 'my_fw::post']: }
143 ```
144
145 3. Include the `firewall` class to ensure the correct packages are installed:
146
147 ```puppet
148 class { 'firewall': }
149 ```
150
151 4. If you want to remove unmanaged firewall rules, add the following code to set up a metatype to purge unmanaged firewall resources in your site.pp or another top-scope file. This will clear any existing rules and make sure that only rules defined in Puppet exist on the machine.
131 152
132 ```puppet 153 ```puppet
133 resources { 'firewall': 154 resources { 'firewall':
134 purge => true, 155 purge => true,
135 } 156 }
166 resources { 'firewallchain': 187 resources { 'firewallchain':
167 purge => true, 188 purge => true,
168 } 189 }
169 ``` 190 ```
170 191
171 **Note** - If there are unmanaged rules in unmanaged chains, it will take two Puppet runs for the firewall chain to be purged. This is different than the `purge` parameter available in `firewallchain`. 192 > **Note:** If there are unmanaged rules in unmanaged chains, it will take a second Puppet run for the firewall chain to be purged.
172 193
173 2. Use the following code to set up the default parameters for all of the firewall rules that you will establish later. These defaults will ensure that the `pre` and `post` classes are run in the correct order and avoid locking you out of your box during the first Puppet run. 194 > **Note:** If you need more fine-grained control about which unmananged rules get removed, investigate the `purge` and `ignore_foreign` parameters available in `firewallchain`.
174
175 ```puppet
176 Firewall {
177 before => Class['my_fw::post'],
178 require => Class['my_fw::pre'],
179 }
180 ```
181
182 3. Declare the `my_fw::pre` and `my_fw::post` classes to satisfy dependencies. You can declare these classes using an external node classifier or the following code:
183
184 ```puppet
185 class { ['my_fw::pre', 'my_fw::post']: }
186 ```
187
188 4. Include the `firewall` class to ensure the correct packages are installed:
189
190 ```puppet
191 class { 'firewall': }
192 ```
193 195
194 ### Upgrading 196 ### Upgrading
195 197
196 Use these steps if you already have a version of the firewall module installed. 198 Use these steps if you already have a version of the firewall module installed.
197 199
396 puppet doc -r type 398 puppet doc -r type
397 (and search for firewall) 399 (and search for firewall)
398 400
399 ## Reference 401 ## Reference
400 402
401 For information on the classes and types, see the [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-firewall/blob/master/REFERENCE.md). For information on the facts, see below. 403 For information on the classes and types, see the [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-firewall/blob//REFERENCE.md). For information on the facts, see below.
402 404
403 Facts: 405 Facts:
404 406
405 * [ip6tables_version](#fact-ip6tablesversion) 407 * [ip6tables_version](#fact-ip6tablesversion)
406 * [iptables_version](#fact-iptablesversion) 408 * [iptables_version](#fact-iptablesversion)
418 420
419 Retrieves the version of iptables-persistent from your OS. This is a Debian/Ubuntu specific fact. 421 Retrieves the version of iptables-persistent from your OS. This is a Debian/Ubuntu specific fact.
420 422
421 ## Limitations 423 ## Limitations
422 424
423 For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-firewall/blob/master/metadata.json) 425 For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-firewall/blob/main/metadata.json)
424 426
425 ### SLES 427 ### SLES
426 428
427 The `socket` parameter is not supported on SLES. In this release it will cause 429 The `socket` parameter is not supported on SLES. In this release it will cause
428 the catalog to fail with iptables failures, rather than correctly warn you that 430 the catalog to fail with iptables failures, rather than correctly warn you that
472 474
473 * Run `puppet agent -t` on the command line. 475 * Run `puppet agent -t` on the command line.
474 * Use a cron job. 476 * Use a cron job.
475 * Click [Run Puppet](https://docs.puppet.com/pe/2016.1/console_classes_groups_running_puppet.html#run-puppet-on-an-individual-node) in the console. 477 * Click [Run Puppet](https://docs.puppet.com/pe/2016.1/console_classes_groups_running_puppet.html#run-puppet-on-an-individual-node) in the console.
476 478
479 ### condition parameter
480
481 The `condition` parameter requires `xtables-addons` to be installed locally.
482 For ubuntu distributions `xtables-addons-common` package can be installed by running command: `apt-get install xtables-addons-common` or
483 running a manifest:
484
485 ```puppet
486 package { 'xtables-addons-common':
487 ensure => 'latest',
488 }
489 ```
490
491 For other distributions (RedHat, Debian, Centos etc) manual installation of the `xtables-addons` package is required.
492
477 #### Reporting Issues 493 #### Reporting Issues
478 494
479 Please report any bugs in the Puppetlabs JIRA issue tracker: 495 Please report any bugs in the Puppetlabs JIRA issue tracker:
480 496
481 <https://tickets.puppetlabs.com/projects/MODULES/issues> 497 <https://tickets.puppetlabs.com/projects/MODULES/issues>