X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=README;h=2f0840dc90656f3a256e9e62d89b0b004ebb59e5;hb=4a9b18ad31bb180cceb3e88f8774781dec9069ca;hp=03d2d2c7e7b880041805a67b12da4929cdb1eef9;hpb=6ef37bfd64f524a8784650deeb470a7071189fef;p=pve-firewall.git

diff --git a/README b/README
index 03d2d2c..2f0840d 100644
--- a/README
+++ b/README
@@ -1 +1,113 @@
-Experimental software, only used for testing
\ No newline at end of file
+Experimental software, only used for testing!
+=============================================
+
+
+Quick Intro
+===========
+
+VM firewall rules are read from /etc/pve/firewall/<VMID>.fw
+
+Security group rules are read from /etc/pve/firewall/groups.fw
+
+Host firewall rules are read from /etc/pve/local/host.fw
+
+You can find examples in the example/ dir
+
+
+Use the following command to mange the firewall:
+
+To test the firewall configuration:
+
+./pvefw compile
+
+To start or update the firewall:
+
+./pvefw start
+
+To update the firewall rules (the firewall is not started if it
+is not already running):
+
+./pvefw update
+
+To stop the firewall:
+
+./pvefw stop
+
+
+Implementation details
+======================
+
+We write iptables rules directly, an generate the following chains 
+as entry points in the 'forward' table:
+
+PVEFW-INPUT
+PVEFW-OUTPUT
+PVEFW-FORWARD
+
+We do not touch other (user defined) chains.
+
+Each VM can have its own firewall definition file in 
+
+/etc/pve/firewall/<VMID>.fw
+
+That file has a section [RULES] to define firewall rules.
+
+Format is: TYPE ACTION IFACE SOURCE DEST PROTO D-PORT S-PORT
+
+* TYPE: IN|OUT|GROUP 
+* ACTION: action or macro
+* IFACE: vm network interface (net0 - net5), or '-' for all interfaces
+* SOURCE: source IP address, or '-' for any source
+* DEST: dest IP address, or '-' for any destination address
+* PROTO: see /etc/protocols
+* D-PORT: destination port
+* S-PORT: source port
+
+A rule for inbound traffic looks like this:
+
+IN SSH(ACCEPT) net0
+
+Outbound rules looks like:
+
+OUT SSH(ACCEPT)
+
+Problems
+===================
+
+There are a number of restrictions when using iptables to filter
+bridged traffic. The physdev match feature does not work correctly
+when traffic is routed from host to bridge:
+
+  * when a packet being sent through a bridge entered the firewall on another interface 
+    and was being forwarded to the bridge.
+
+  * when a packet originating on the firewall itself is being sent through a bridge.
+
+So we disable the firewall if we detect such case (bridge with assigned IP address).
+You can enable it again (if you do not care) by setting "allow_bridge_route: 1" in "host.fw".
+
+The correct workaround is to remove the IP address from the bridge device, and
+use a veth device which is plugged into the bridge:
+
+---/etc/network/interfaces----
+
+...
+
+auto vmbr0
+iface vmbr0 inet manual
+	bridge_ports bond0
+	bridge_stp off
+	bridge_fd 0
+
+# this create the veth device and plug it into vmbr0
+auto pm0
+iface pm0 inet static
+	address  192.168.10.10
+	netmask  255.255.255.0
+	gateway  192.168.10.1
+	VETH_BRIDGETO vmbr0
+
+...
+
+--------------------------------
+