ReleaseEngineering/PuppetAgain/Modules/fw: Difference between revisions

ReleaseEngineering/PuppetAgain/Modules/fw (view source)

Revision as of 18:31, 8 August 2017

3,784 bytes added , 8 August 2017

Initial pass at fw module documentation

Dividehex

Confirmed users

120

edits

@@ Line 1: / Line 1: @@
-This is a light wrapper around the `firewall` module (which is https://github.com/puppetlabs/puppetlabs-firewall).
+= Firewall Wrapper Module =
+This is a wrapper around the `firewall` and 'pf' module.  It provides transparency for writing firewall rules that may be interchangeable between both OSX and Linux<br />
+The fw module uses a 'Roles & Profiles' framework for managing and applying firewall rules in a simple and easy way.  A role is made up of individual rules grouped together on a source/application basis.  Profiles are a collection of roles.<br /><br />
-In particular, when a firewall is activated, this module includes some basic flows:
+=== Defining ports and protocols for applications ===
-* SSH
+Each application must be defined in the '''$app_proto_port''' hash within the [https://hg.mozilla.org/build/puppet/file/tip/modules/fw/manifests/apps.pp apps.pp manifest].
-* established connections
+For example:
-* ICMP
+  'http'   => { proto => 'tcp', port  => '80' },
-* Nagios
+  'https'  => { proto => 'tcp', port  => '443' },
-and denies all others not specifically added.
+  'puppet' => { proto => 'tcp', port  => '8140' },
+=== Defining hosts and networks ===
+All sources should be defined within the networks.pp manifest.  All variables defined here are arrays even if it is a single element array.
+Valid sources are:
+* CIDR blocks
+* Single IP CIDR blocks
+=== Roles ===
+For example, this role allows all sources to the puppet master listening ports:
+  class fw::roles::puppetmaster_from_all_releng {
+      include fw::networks
+      fw::rules { 'allow_puppetmaster_http':
+          sources =>  $::fw::networks::all_releng,
+          app     => 'http'
+      }
+      fw::rules { 'allow_puppetmaster_https':
+          sources =>  $::fw::networks::all_releng,
+          app     => 'https'
+      }
+      fw::rules { 'allow_puppetmaster_puppet':
+          sources =>  $::fw::networks::all_releng,
+          app     => 'puppet'
+      }
+  }
+In this example, this role allows ssh access from all puppetmasters (for rsync):
+  class fw::roles::puppetmaster_sync_from_all_puppetmasters {
+      include fw::networks
+      fw::rules { 'allow_puppetmaster_sync':
+          sources => [ $::fw::networks::non_distingushed_puppetmasters,
+                       $::fw::networks::distingushed_puppetmaster ],
+          app     => 'ssh'
+      }
+  }
-To simply activate the firewall, but not allow any additional flows:
+And finally, this role allows ssh access from the jumphosts:
-   include fw
+   class fw::roles::ssh_from_rejh_logging {
+      include fw::networks
+      fw::rules { 'allow_ssh_from_rejh_logging':
+          sources =>  $::fw::networks::rejh,
+          app     => 'ssh',
+          log     => true
+      }
+  }
-To activate the firewall and allow a specific flow:
+=== Profiles ===
+Now we can take the previous roles and build a profile for the distinguished puppetmaster:
+  class fw::profiles::distinguished_puppetmaster {
+      include ::fw::roles::puppetmaster_from_all_releng
+      include ::fw::roles::puppetmaster_sync_from_all_releng
+      include ::fw::roles::ssh_from_rejh_logging
+  }
+'''Note:''' the ssh role is a logging role, therefore it will log the connections in addition to allowing connections
-   fw::port {
+=== Using profiles ===
-       "tcp/3399": ;
+To apply this profile to the distinguished puppetmaster, simply include the profile in the node definition.  Here we also include a node scope variable ($fw_allow_all) which changes the default policy to allow all traffic.
+   node 'releng-puppet2.srv.releng.scl3.mozilla.com' {
+      $aspects       = [ 'maximum-security' ]
+      $fw_allow_all  = true
+      include fw::profiles::distinguished_puppetmaster
+       include toplevel::server::puppetmaster
    }
-This will allow connections to tcp/3399 from any IP.
+=== Logging ===
+Logging can be enabled for any rule.  Simply add 'log => true' to the rule being defined with fw::rules.  This will cause the connection to be logged when the connection state is created.<br />
+For example:
+    fw::rules { 'allow_vnc_from_anywhere_logging':
+        sources =>  $::fw::networks::everywhere,
+        app     => 'vnc',
+        log     => true
+    }
+=== Default policy and overriding it ===
+The default policy for both IPTables and PF is '''default deny'''. This also means every rule within a role is an explicit '''allow rule'''.<br />
+If you wish to override the default deny policy for testing purposes, you must set the node scope variable ($fw_allow_all) explicitly '''true''' within the node definition.<br />
+  $fw_allow_all = true
+'''Note:''' To re-enable the default deny policy, simply remove the node scope variable
+=== Global allowed flows ===
+The only globably allowed flows for both IPTables and PF are:
+* established connections
+* ICMP
+All other flows are denied unless explicitly added.