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