Documentation.

1 files changed, 27 insertions, 25 deletions

diff --git a/roles/common/files/usr/local/sbin/update-firewall.sh b/roles/common/files/usr/local/sbin/update-firewall.sh
index 54a66e8..f7ab925 100755
--- a/roles/common/files/usr/local/sbin/update-firewall.sh
+++ b/roles/common/files/usr/local/sbin/update-firewall.sh
@@ -1,34 +1,34 @@
 #!/bin/bash
 #
-# Create iptables (v4 and v6) rules. Unless one of [-f] or [-c] is
+# Create iptables (v4 and v6) rules.  Unless one of [-f] or [-c] is
 # given, or if the ruleset is unchanged, a confirmation is asked after
 # loading the new rulesets; if the user answers No or doesn't answer,
-# the old ruleset is restored. If the user answer Yes (or if the flag
+# the old ruleset is restored.  If the user answer Yes (or if the flag
 # [-f] is given), the new ruleset is made persistent (requires a pre-up
 # hook) by moving it to /etc/iptables/rules.v[46].
 #
-# The [-c] flag switch to dry-run (check) mode. The rulesets are not
-# applied, but merely checked against the existing ones. The return
+# The [-c] flag switch to dry-run (check) mode.  The rulesets are not
+# applied, but merely checked against the existing ones.  The return
 # value is 0 iff. they do not differ.
 #
-# This firewall is only targeted towards end-servers, not gateways. In
+# This firewall is only targeted towards end-servers, not gateways.  In
 # particular, there is no NAT'ing at the moment.
 #
 # Dependencies: netmask(1)
 #
 # Copyright 2013 Guilhem Moulin <guilhem@fripost.org>
 #
 # Licensed under the GNU GPL version 3 or higher.
 #
 
 set -ue
 PATH=/usr/sbin:/usr/bin:/sbin:/bin
 timeout=10
 
 force=0
 check=0
 verbose=0
 addrfam=
 
 fail2ban_re='^(\[[0-9]+:[0-9]+\]\s+)?-A fail2ban-\S'
 IPSec_re=' -m policy --dir (in|out) --pol ipsec .* --proto esp -j ACCEPT$'
@@ -68,58 +68,58 @@ commit() {
 inet46() {
     case "$1" in
         4) echo "$2";;
         6) echo "$3";;
     esac
 }
 ipt-chains() {
     # Define new (tables and) chains.
     while [ $# -gt 0 ]; do
         case "$1" in
             ?*:*) echo ":${1%:*} ${1##*:} [0:0]";;
             ?*)   echo "*$1";;
         esac
         shift
     done >> "$new"
 }
 
 ipt-trim() {
     # Remove dynamic chain/rules from the input stream, as they are
     # automatically included by third-party servers (such as strongSwan
-    # or fail2ban). The output is ready to be made persistent.
+    # or fail2ban).  The output is ready to be made persistent.
     grep -Ev -e '^:fail2ban-\S' \
              -e "$IPSec_re" \
              -e '-j fail2ban-\S+$' \
              -e "$fail2ban_re"
 }
 
 ipt-diff() {
     # Get the difference between two rulesets.
     if [ $verbose -eq 1 ]; then
         /usr/bin/diff -u -I '^#' "$1" "$2"
     else
         /usr/bin/diff -q -I '^#' "$1" "$2" >/dev/null
     fi
 }
 
 ipt-persist() {
-    # Make the current ruleset persistent. (Requires a pre-up hook
+    # Make the current ruleset persistent.  (Requires a pre-up hook
     # script to load the rules before the network is configured.)
 
     log "Making ruleset persistent... "
     [ -d /etc/iptables ] || mkdir /etc/iptables
 
     local f rs table
     for f in "${!tables[@]}"; do
         ipts=/sbin/$(inet46 $f iptables ip6tables)-save
         rs=/etc/iptables/rules.v$f
 
         for table in ${tables[$f]}; do
             /bin/ip netns exec $netns $ipts -t $table
         done | ipt-trim > "$rs"
         chmod 0600 "$rs"
     done
 }
 
 ipt-revert() {
     [ $check -eq 0 ] || return
     log "Reverting to old ruleset... "
@@ -148,80 +148,82 @@ run() {
                  | sed -nr "/^[0-9]+:\s+(sec[0-9]+)@$if:\s.*/ {s//\1/p;q}" )
 
     # The (host-scoped) IP reserved for IPSec.
     local ipsec= secmark
     if [ -n "$ifsec" -a $f = 4 ]; then
         tables+=( [$f]=' mangle nat' )
         ipsec=$( /bin/ip -$f address show dev "$ifsec" scope host \
                | sed -nr '/^\s+inet\s(\S+).*/ {s//\1/p;q}' )
         secmark=0x1
     fi
 
     # Store the old (current) ruleset
     local old=$(mktemp -t current-rules.v$f.XXXXXX) \
           new=$(mktemp -t new-rules.v$f.XXXXXX)
     for table in ${tables[$f]}; do
         $ipt-save -ct $table
     done > "$old"
     rss+=( [$f]="$old" )
 
     local fail2ban=0
-    # XXX: As of Wheezy, fail2ban is IPv4 only. See
+    # XXX: As of Wheezy, fail2ban is IPv4 only.  See
     #      https://github.com/fail2ban/fail2ban/issues/39 for the current
     #      state of the art.
     if [ "$f" = 4 ] && which /usr/bin/fail2ban-server >/dev/null; then
         fail2ban=1
     fi
 
     if [ -n "$ipsec" ]; then
-        # We DNAT the IPSec paquets to $ipsec after decapsulation, and
-        # SNAT them before encapsulation. We need to do the NAT'ing
-        # before packets enter the IPSec stack because they are signed
+        # DNAT the IPSec paquets to $ipsec after decapsulation, and SNAT
+        # them before encapsulation.  We need to do the NAT'ing before
+        # packets enter the IPSec stack because they are signed
         # afterwards, and NAT'ing would mess up the signature.
         ipt-chains mangle PREROUTING:ACCEPT INPUT:ACCEPT \
                           FORWARD:DROP \
                           OUTPUT:ACCEPT POSTROUTING:ACCEPT
         # Mark all IPSec packets to keep track of them and NAT them
-        # after decapsulation. Unmarked packets that are to be sent to
+        # after decapsulation.  Unmarked packets that are to be sent to
         # $ipsec are dropped.
         iptables -A PREROUTING -p esp -j MARK --set-mark $secmark
         iptables -A INPUT -d "$ipsec" -m mark \! --mark $secmark -j DROP
         commit
 
         ipt-chains nat PREROUTING:ACCEPT INPUT:ACCEPT \
                        OUTPUT:ACCEPT POSTROUTING:ACCEPT
-        # DNAT all marked packets that have been decapsulated. Packets
-        # originating from our IPSec are SNAT'ed (MASQUERADE). We cannot
-        # mark them here (it won't survivethe NAT'ing), but any reply
-        # not going through IPSec would be dropped (since unmarked).
+        # DNAT all marked packets that have been decapsulated.  Packets
+        # originating from our IPSec are SNAT'ed (MASQUERADE).  XXX:
+        # xfrm lookup occurs *after* NAT POSTROUTING, so sadly we can't
+        # DROP packets not matching an IPSec policy. However, any reply
+        # not going through IPSec would be dropped (since unmarked);
+        # this is the best we can do for now.
         iptables -A PREROUTING \! -p esp -m mark --mark "$secmark" \
                      -j DNAT --to "${ipsec%/*}"
         iptables -A POSTROUTING -s "$ipsec" -j MASQUERADE
         commit
     fi
 
     # The usual chains in filter, along with the desired default policies.
     ipt-chains filter INPUT:DROP FORWARD:DROP OUTPUT:DROP
 
     if [ -z "$if" ]; then
         # If the interface is not configured, we stop here and DROP all
-        # packets by default. Thanks to the pre-up hook this tight
+        # packets by default.  Thanks to the pre-up hook this tight
         # policy will be activated whenever the interface goes up.
         mv "$new" /etc/iptables/rules.v$f
         return 0
     fi
 
     # Fail2ban-specific chains and traps
     if [ $fail2ban -eq 1 ]; then
         echo ":fail2ban - [0:0]"
         # Don't remove existing rules & traps in the current rulest
         grep    -- '^:fail2ban-\S'      "$old" || true
         grep -E -- ' -j fail2ban-\S+$'  "$old" || true
         grep -E -- "$fail2ban_re"       "$old" || true
     fi >> "$new"
 
     if [ -n "$ifsec" ]; then
         # (Host-to-host) IPSec tunnels come first. TODO: test IPSec with IPv6.
         grep -E -- "$IPSec_re" "$old" >> "$new" || true
 
         # Allow any IPsec ESP protocol packets to be sent and received.
         iptables -A INPUT  -i $if -p esp -j ACCEPT
@@ -260,54 +262,54 @@ run() {
             iptables -A INPUT -i $if -s "$ip" -j DROP
             iptables -A INPUT -i $if -d "$ip" -j DROP
         done
     fi
 
     # DROP INVALID packets immediately.
     iptables -A INPUT  -m state --state INVALID -j DROP
     iptables -A OUTPUT -m state --state INVALID -j DROP
 
     # DROP bogus TCP packets.
     iptables -A INPUT -p tcp -m tcp --tcp-flags FIN,SYN FIN,SYN -j DROP
     iptables -A INPUT -p tcp -m tcp --tcp-flags SYN,RST SYN,RST -j DROP
 
     # Allow all input/output to/from the loopback interface.
     local localhost=$(inet46 $f '127.0.0.1/32' '::1/128')
     iptables -A INPUT  -i lo -s "$localhost" -d "$localhost" -j ACCEPT
     iptables -A OUTPUT -o lo -s "$localhost" -d "$localhost" -j ACCEPT
 
     if [ -n "$ipsec" ]; then
         # ACCEPT any, *marked* traffic destinating to the non-routable
-        # $ipsec. Also ACCEPT all traffic originating from $ipsec, as it
-        # is MASQUERADE'd.
+        # $ipsec.  Also ACCEPT all traffic originating from $ipsec, as
+        # it is MASQUERADE'd.
         iptables -A INPUT  -i "$if" -d "$ipsec" -m mark --mark "$secmark" -j ACCEPT
         iptables -A OUTPUT -s "$ipsec" -o "$if" -j ACCEPT
     fi
 
-    # Prepare fail2ban. We make fail2ban insert its rules in a dedicated
-    # chain, so that it doesn't mess up the existing rules.
+    # Prepare fail2ban.  We make fail2ban insert its rules in a
+    # dedicated chain, so that it doesn't mess up the existing rules.
     [ $fail2ban -eq 1 ] && iptables -A INPUT -i $if -j fail2ban
 
     if [ "$f" = 4 ]; then
-        # Allow only ICMP of type 0, 3 and 8. The rate-limiting is done
+        # Allow only ICMP of type 0, 3 and 8.  The rate-limiting is done
         # directly by the kernel (net.ipv4.icmp_ratelimit and
-        # net.ipv4.icmp_ratemask runtime options). See icmp(7).
+        # net.ipv4.icmp_ratemask runtime options).  See icmp(7).
         local t
         for t in  'echo-reply' 'destination-unreachable' 'echo-request'; do
             iptables -A INPUT  -i $if -p icmp -m icmp --icmp-type $t -j ACCEPT
             iptables -A OUTPUT -o $if -p icmp -m icmp --icmp-type $t -j ACCEPT
         done
     elif [ $f = 6 ]; then
         iptables -A INPUT -i $ip -p icmpv6 -j ACCEPT
     fi
 
 
     ########################################################################
     # ACCEPT new connections to the services we provide, or to those we want
     # to connect to.
 
     sed -re 's/#.*//; /^\s*$/d' -e "s/^(in|out|inout)$f?(\s.*)/\1\2/" \
             /etc/iptables/services | \
     grep -Ev '^(in|out|inout)\S\s' | \
     while read dir proto dport sport; do
         # We add two entries per config line: we need to accept the new
         # connection, and latter the reply.
@@ -330,42 +332,42 @@ run() {
             ?*)      optsNew+=" --sport $sport"
                      optsEst+=" --dport $sport";;
         esac
         case "$dir" in
             in|inout) iptNew="-A INPUT  -i";  iptEst="-A OUTPUT -o";;
             out)      iptNew="-A OUTPUT -o";  iptEst="-A INPUT  -i";;
             *) fatal "Error: Unknown direction: '$dir'."
         esac
 
         iptables $iptNew $if -p $proto $optsNew -m state --state $stNew -j ACCEPT
         iptables $iptEst $if -p $proto $optsEst -m state --state $stEst -j ACCEPT
     done
 
     ########################################################################
     commit
 
 
     local rv1=0 rv2=0 persistent=/etc/iptables/rules.v$f
     local oldz=$(mktemp -t current-rules.v$f.XXXXXX)
 
-    # Reset the counters. They are not useful for comparing and/or
-    # storing persistent ruleset. (We don't use sed -i because we want
+    # Reset the counters.  They are not useful for comparing and/or
+    # storing persistent ruleset.  (We don't use sed -i because we want
     # to restore the counters when reverting.)
     sed -r -e '/^:/ s/\[[0-9]+:[0-9]+\]$/[0:0]/' \
            -e 's/^\[[0-9]+:[0-9]+\]\s+//' \
            "$old" > "$oldz"
 
     /usr/bin/uniq "$new" | /bin/ip netns exec $netns $ipt-restore || ipt-revert
 
     for table in ${tables[$f]}; do
        /bin/ip netns exec $netns $ipt-save -t $table
     done > "$new"
 
     ipt-diff "$oldz" "$new" || rv1=$?
 
     if ! [ -f "$persistent" -a -x /etc/network/if-pre-up.d/iptables ]; then
         rv2=1
     else
         ipt-trim < "$oldz" | ipt-diff - "$persistent" || rv2=$?
     fi
 
     local update="Please run '${0##*/}'."