(#13216) Fix README so setup instructions actually work

The old setup instructions were vague, and incorrect. This fixes those
instructions so they actually work, and breaks them out into their own
section.(#13216) Fix README so setup instructions actually work

README.markdown

@@ -74,6 +74,85 @@ need to run Puppet on the master first:
 You may also need to restart Apache, although this shouldn't always be the
 case.
 
+### Recommended Setup
+
+At the moment you need to provide some setup outside of what we provide in the 
+module to support proper ordering, purging and firewall peristence.
+
+So It is recommended that you provide the following in top scope somewhere
+(such as your site.pp):
+
+    # Always persist firewall rules
+    exec { 'persist-firewall':
+      command     => $operatingsystem ? {
+        'debian'          => '/sbin/iptables-save > /etc/iptables/rules.v4',
+        /(RedHat|CentOS)/ => '/sbin/iptables-save > /etc/sysconfig/iptables',
+      },
+      refreshonly => true,
+    }
+
+    # These defaults ensure that the persistence command is executed after 
+    # every change to the firewall, and that pre & post classes are run in the
+    # right order to avoid potentially locking you out of your box during the
+    # first puppet run.
+    Firewall {
+      notify  => Exec['persist-firewall'],
+      before  => Class['my_fw::post'],
+      require => Class['my_fw::pre'],
+    }
+    Firewallchain {
+      notify  => Exec['persist-firewall'],
+    }
+
+    # Purge unmanaged firewall resources
+    #
+    # This will clear any existing rules, and make sure that only rules
+    # defined in puppet exist on the machine
+    resources { "firewall":
+      purge => true
+    }
+
+In this case, it uses classes called 'my_fw::pre' & 'my_fw::post' to define
+default pre and post rules. These rules are required to run in catalog order
+to avoid locking yourself out of your own boxes when Puppet runs, as
+the firewall class applies rules as it processes the catalog.
+
+An example of the pre class would be:
+
+    # This would be located in my_fw/manifests/pre.pp
+    class my_fw::pre {
+      Firewall {
+        require => undef,
+      }
+
+      # Default firewall rules
+      firewall { '000 accept all icmp':
+        proto   => 'icmp',
+        action  => 'accept',
+      }->
+      firewall { '001 accept all to lo interface':
+        proto   => 'all',
+        iniface => 'lo',
+        action  => 'accept',
+      }->
+      firewall { '002 accept related established rules':
+        proto   => 'all',
+        state   => ['RELATED', 'ESTABLISHED'],
+        action  => 'accept',
+      }
+    }
+
+And an example of a post class:
+
+    # This would be located in my_fw/manifests/post.pp:
+    class my_fw::post {
+      firewall { '999 drop all':
+        proto   => 'all',
+        action  => 'drop',
+        before  => undef,
+      }
+    }
+
 ### Examples
 
 Basic accept ICMP request example:
@@ -117,39 +196,6 @@ Creating a new rule that forwards to a chain, then adding a rule to this chain:
       dport   => 5000,
     }
 
-You can make firewall rules persistent with the following iptables example:
-
-    exec { "persist-firewall":
-      command => $operatingsystem ? {
-        "debian" => "/sbin/iptables-save > /etc/iptables/rules.v4",
-        /(RedHat|CentOS)/ => "/sbin/iptables-save > /etc/sysconfig/iptables",
-      }
-      refreshonly => true,
-    }
-    Firewall {
-      notify => Exec["persist-firewall"]
-    }
-    Firewallchain {
-      notify => Exec["persist-firewall"]
-    }
-
-If you wish to ensure any reject rules are executed last, try using stages.
-The following example shows the creation of a class which is where your
-last rules should run, this however should belong in a puppet module.
-
-    class my_fw::drop {
-      iptables { "999 drop all":
-        action => "drop"
-      }
-    }
-
-    stage { pre: before => Stage[main] }
-    stage { post: require => Stage[main] }
-
-    class { "my_fw::drop": stage => "post" }
-
-By placing the 'my_fw::drop' class in the post stage it will always be inserted
-last thereby avoiding locking you out before the accept rules are inserted.
 
 ### Further documentation