add a README with documentation

COPYING

+Copyright (C) 2012, Autistici/Inventati <info@inventati.org>.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Makefile

@@ -14,6 +14,7 @@ install:
 	$(INSTALL) -d $(DESTDIR)$(sysconfdir)/firewall/filter.d
 	$(INSTALL) -d $(DESTDIR)$(sysconfdir)/firewall/nat.d
 	$(INSTALL) -d $(DESTDIR)$(sysconfdir)/firewall/mangle.d
+	$(INSTALL) -m 644 README $(DESTDIR)$(sysconfdir)/firewall/README
 	(for f in ./conf-dist/filter.d/* ; do \
 	 $(INSTALL) -m 644 $$f $(DESTDIR)$(sysconfdir)/firewall/filter.d ; done)
 

README

+
+ai-firewall
+===========
+
+A shell-based DSL for quick and easy configuration of an iptables
+firewall, primarily targeted at individual servers, supporting both
+IPv4 and IPv6.
+
+ai-firewall will perform some basic setup and then execute
+application-specific configuration snippets from the /etc/firewall
+tree. This setup allows packages to plug into the firewall setup by
+simply deploying a snippet in /etc/firewall.
+
+The configuration is loaded from the directories below /etc/firewall,
+every iptables table (such as 'filter', 'nat', and 'mangle') is
+configured independently from its own subdirectory named after itself,
+with a '.d' extension. Individual files from each directory are loaded
+in lexicographical order (like run-parts, for instance).
+
+
+Configuration syntax
+--------------------
+
+Configuration files are simple shell scripts. Rules are generated by
+invoking the following predefined helper functions:
+
+
+    create_chain <CHAIN_NAME>
+
+        Create a new chain with the specified name.
+
+
+    add_rule <IPTABLES_ARGS>
+    add_rule4 <IPTABLES_ARGS>
+    add_rule6 <IPTABLES_ARGS>
+
+        This function will generate a full iptables rule exactly as
+        specified.  The first form will generate the rule for IPv4 and
+        IPv6, the other two are protocol-specific.
+
+        An example:
+
+          add_rule -A bad-host -s 1.2.3.4 -j DROP
+
+
+    add_to_chain <CHAIN_NAME> <IPTABLES_ARGS>
+
+        A shortcut for 'add_rule -A <CHAIN_NAME> <IPTABLES_ARGS>'.
+
+
+    add_user_port <PROTOCOL> <PORT> [<TARGET>]
+
+        Allow incoming traffic to the specified protocol / port.
+
+
+    add_user_ports <PROTOCOL> <PORT_SPEC>
+
+        Allow incoming traffic to the specified ports. PORT_SPEC
+        should be a comma-separated list of destination ports.
+
+
+