fix README
[pve-firewall.git] / README
1 Experimental software, only used for testing!
2 =============================================
3
4
5 Quick Intro
6 ===========
7
8 VM firewall rules are read from:
9
10  /etc/pve/firewall/<VMID>.fw
11
12 Cluster wide rules and security group are read from:
13  
14  /etc/pve/firewall/cluster.fw
15
16 Host firewall rules are read from:
17
18   /etc/pve/local/host.fw
19
20 You can find examples in the example/ dir
21
22
23 Use the following command to mange the firewall:
24
25 To test the firewall configuration:
26
27 ./pvefw compile
28
29 To start or update the firewall:
30
31 ./pvefw start
32
33 To update the firewall rules (the firewall is not started if it
34 is not already running):
35
36 ./pvefw update
37
38 To stop the firewall:
39
40 ./pvefw stop
41
42
43 Implementation details
44 ======================
45
46 We write iptables rules directly, an generate the following chains 
47 as entry points in the 'forward' table:
48
49 PVEFW-INPUT
50 PVEFW-OUTPUT
51 PVEFW-FORWARD
52
53 We do not touch other (user defined) chains.
54
55 Each VM can have its own firewall definition file in 
56
57 /etc/pve/firewall/<VMID>.fw
58
59 That file has a section [RULES] to define firewall rules.
60
61 Format is: TYPE ACTION IFACE SOURCE DEST PROTO D-PORT S-PORT
62
63 * TYPE: IN|OUT|GROUP 
64 * ACTION: action or macro
65 * IFACE: vm network interface (net0 - net5), or '-' for all interfaces
66 * SOURCE: source IP address, or '-' for any source
67 * DEST: dest IP address, or '-' for any destination address
68 * PROTO: see /etc/protocols
69 * D-PORT: destination port
70 * S-PORT: source port
71
72 A rule for inbound traffic looks like this:
73
74 IN SSH(ACCEPT) net0
75
76 Outbound rules looks like:
77
78 OUT SSH(ACCEPT)
79
80 Problems
81 ===================
82
83 There are a number of restrictions when using iptables to filter
84 bridged traffic. The physdev match feature does not work correctly
85 when traffic is routed from host to bridge:
86
87   * when a packet being sent through a bridge entered the firewall on another interface 
88     and was being forwarded to the bridge.
89
90   * when a packet originating on the firewall itself is being sent through a bridge.
91
92 So we disable the firewall if we detect such case (bridge with assigned IP address).
93 You can enable it again (if you do not care) by setting "allow_bridge_route: 1" in "host.fw".
94
95 The correct workaround is to remove the IP address from the bridge device, and
96 use a veth device which is plugged into the bridge:
97
98 ---/etc/network/interfaces----
99
100 ...
101
102 auto vmbr0
103 iface vmbr0 inet manual
104         bridge_ports bond0
105         bridge_stp off
106         bridge_fd 0
107
108 # this create the veth device and plug it into vmbr0
109 auto pm0
110 iface pm0 inet static
111         address  192.168.10.10
112         netmask  255.255.255.0
113         gateway  192.168.10.1
114         VETH_BRIDGETO vmbr0
115
116 auto vmbr1
117 iface vmbr1 inet manual
118       bridge_ports none
119       bridge_stp off
120       bridge_fd 0
121
122 # setup masqueraded bridge port vmbr1/pm1 using pm0
123 # NOTE: this needs kernel 3.10.0 or newer (for conntrack --zone) 
124 auto pm1
125 iface pm1 inet static
126        address 10.10.10.1
127        netmask 255.255.255.0
128        VETH_BRIDGETO vmbr1
129        VETH_MASQUERADE pm0
130
131 ...
132
133 --------------------------------
134