Merge branch '2.5'

docs/weavenpc-design.md

@@ -9,7 +9,9 @@ destroyed automatically in response to Pod, Namespace and
 NetworkPolicy object updates from the k8s API server:
 
 * A `hash:ip` set per namespace, containing the IP addresses of all
-  pods in that namespace
+  pods in that namespace for which default ingress is allowed
+* A `hash:ip` set per namespace, containing the IP addresses of all
+  pods in that namespace for which default egress is allowed  
 * A `list:set` per distinct (across all network policies in all
   namespaces) namespace selector mentioned in a network policy,
   containing the names of any of the above hash:ip sets whose
@@ -18,6 +20,9 @@ NetworkPolicy object updates from the k8s API server:
   containing network policy's namespace) pod selector mentioned in a
   network policy, containing the IP addresses of all pods in the
   namespace whose labels match that selector
+* A `hash:net` set for each distinct (within the scope of the
+  containing network policy's namespace) `except` list of CIDR's mentioned in
+  the network policies
 
 IPsets are implemented by the kernel module `xt_set`, without which
 weave-npc will not work.
@@ -38,11 +43,21 @@ hashing to avoid clashes.
 
 # iptables chains
 
-The policy controller maintains two iptables chains in response to
-changes to pods, namespaces and network policies. One chain contains
-the ingress rules that implement the network policy specifications,
-and the other is used to bypass the ingress rules for namespaces which
-have an ingress isolation policy of `DefaultAllow`.
+The policy controller maintains several iptables chains in response to
+changes to pods, namespaces and network policies. 
+
+## Static `WEAVE-NPC` chain
+
+`WEAVE-NPC` chain contains static rules to ACCEPT traffic that is `RELATED,ESTABLISHED`
+and run `NEW` traffic through `WEAVE-NPC-DEFAULT` followed by `WEAVE-NPC-INGRESS` chains 
+
+Static configuration:
+
+```
+iptables -A WEAVE-NPC -m state --state RELATED,ESTABLISHED -j ACCEPT
+iptables -A WEAVE-NPC -m state --state NEW -j WEAVE-NPC-DEFAULT
+iptables -A WEAVE-NPC -m state --state NEW -j WEAVE-NPC-INGRESS
+```
 
 ## Dynamically maintained `WEAVE-NPC-DEFAULT` chain
 
@@ -63,23 +78,58 @@ For each namespace network policy ingress rule peer/port combination:
 iptables -A WEAVE-NPC-INGRESS -p $PROTO [-m set --match-set $SRCSET] -m set --match-set $DSTSET --dport $DPORT -j ACCEPT
 ```
 
-## Static `WEAVE-NPC` chain
+## Static `WEAVE-NPC-EGRESS` chain
+
+`WEAVE-NPC-EGRESS` chain contains static rules to ACCEPT traffic that is `RELATED,ESTABLISHED`
+and run `NEW` traffic through `WEAVE-NPC-EGRESS-DEFAULT` followed by `WEAVE-NPC-EGRESS-CUSTOM` chains 
 
 Static configuration:
 
 ```
-iptables -A WEAVE-NPC -m state --state RELATED,ESTABLISHED -j ACCEPT
-iptables -A WEAVE-NPC -m state --state NEW -j WEAVE-NPC-DEFAULT
-iptables -A WEAVE-NPC -m state --state NEW -j WEAVE-NPC-INGRESS
+iptables -A WEAVE-NPC-EGRESS -m state --state RELATED,ESTABLISHED -j ACCEPT
+iptables -A WEAVE-NPC-EGRESS -m state --state NEW -j WEAVE-NPC-EGRESS-DEFAULT
+iptables -A WEAVE-NPC-EGRESS -m state --state NEW -m mark ! --mark 0x40000/0x40000 -j WEAVE-NPC-EGRESS-CUSTOM
+iptables -A WEAVE-NPC-EGRESS -m mark ! --mark 0x40000/0x40000 -j DROP
 ```
 
+## Dynamically maintained `WEAVE-NPC-EGRESS-DEFAULT` chain
+
+The policy controller maintains a rule in this chain for every
+namespace whose egress isolation policy is `DefaultAllow`. The
+purpose of this rule is simply to ACCEPT any traffic originating from such namespace before it reaches the egress chain.
+
+```
+iptables -A WEAVE-NPC-EGRESS-DEFAULT -m set --match-set $NSIPSET src -j WEAVE-NPC-EGRESS-ACCEPT
+iptables -A WEAVE-NPC-EGRESS-DEFAULT -m set --match-set $NSIPSET src -j RETURN
+```
+
+## Static `WEAVE-NPC-EGRESS-ACCEPT` chain
+
+`WEAVE-NPC-EGRESS-ACCEPTS` chain contains static rules to mark traffic
+
+Static configuration:
+
+```
+iptables -A WEAVE-NPC-EGRESS-ACCEPT -j MARK --set-xmark 0x40000/0x40000
+```
+
+## Dynamically maintained `WEAVE-NPC-EGRESS-CUSTOM` chain
+
+For each namespace network policy egress rule peer/port combination:
+
+```
+iptables -A WEAVE-NPC-EGRESS-CUSTOM -p $PROTO [-m set --match-set $SRCSET] -m set --match-set $DSTSET --dport $DPORT -j ACCEPT
+```
+
+
 # Steering traffic into the policy engine
 
 To direct traffic into the policy engine:
 
 ```
-iptables -A FORWARD -o weave -m physdev ! --physdev-out vethwe-bridge -j WEAVE-NPC
-iptables -A FORWARD -o weave -m physdev ! --physdev-out vethwe-bridge -j DROP
+iptables -A INPUT -i weave -j WEAVE-NPC-EGRESS
+iptables -A FORWARD -i weave -j WEAVE-NPC-EGRESS
+iptables -A FORWARD -o weave -j WEAVE-NPC
 ```
 
 Note this only affects traffic which egresses the bridge on a physical