plug venet0 chains into PVEFW-FORWARD
[pve-firewall.git] / README
1 Experimental software, only used for testing!
2 =============================================
3
4 Note: you need to change values in /etc/sysctl.d/pve.conf to:
5
6 net.bridge.bridge-nf-call-ip6tables = 1
7 net.bridge.bridge-nf-call-iptables = 1
8 net.bridge.bridge-nf-call-arptables = 1
9 net.bridge.bridge-nf-filter-vlan-tagged = 1
10
11 and reboot after that change.
12
13 Quick Intro
14 ===========
15
16 VM firewall rules are read from /etc/pve/firewall/<VMID>.fw
17
18 You can find examples in the example/ dir
19
20 Note: All commands overwrites /etc/shorewall/, so don't use if you have
21 and existing shorewall config you want to keep.
22
23 Use the following command to generate shorewall configuration:
24
25 ./pvefw compile
26
27 To compile and start the firewall:
28
29 ./pvefw start
30
31 To compile and restart the firewall:
32
33 ./pvefw restart
34
35 To stop the firewall:
36
37 ./pvefw stop
38
39 To clear all iptable rules:
40
41 ./pvefw clear
42
43
44 Implementation details
45 ======================
46
47 We do not write iptables rules directly. Instead we use shorewall to
48 do that low level stuff. 
49
50 Each VM can have its own firewall definition file in 
51
52 /etc/pve/firewall/<VMID>.fw
53
54 That file has two sections for inbound [IN] and outbound [OUT] traffic.
55
56 Format is: ACTION IFACE SOURCE DEST PROTO D-PORT S-PORT
57
58 * ACTION: shorewall action
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 We translate those rules into an appropriate shorewall configuration.
67
68 There are a number of restrictions when using iptables to filter
69 bridged traffic. Shorewall reflects that by applying the following
70 restrictions:
71
72 * BP zones may only be associated with bridge ports.
73
74 * All ports associated with a given BP zone must be on the same bridge.
75
76 * Policies from a non-BP zone to a BP are disallowed.
77
78 * Rules where the SOURCE is a non-BP zone and the DEST is a BP zone are disallowed.
79
80 See: http://www.shorewall.net/bridge-Shorewall-perl.html
81
82 We simply define one zone for each bridge/vm pair.
83
84 Shorewall zones names are limited to 5 characters, so we need to
85 translate our names into shorter ones. The mapping is store in
86 /etc/shorewall/params, so we can use shell variables with long names
87 to refer to those zones.
88
89 Example: One bridge vmbr0 and one VM with id 100
90
91 Content of /etc/shorewall/params
92  # PVE zones
93  FW=fw
94  ZVMBR0=z0
95  ZVMBR0EXT=z1
96  ZVMBR0VM100=z2
97
98 Content of /etc/shorewall/zones 
99  #ZONE                          TYPE       OPTIONS        
100  $FW                            firewall                  
101  $ZVMBR0                        ipv4                      
102  $ZVMBR0EXT:$ZVMBR0             bport                     
103  $ZVMBR0VM100:$ZVMBR0           bport                     
104  #LAST LINE - ADD YOUR ENTRIES ABOVE THIS ONE - DO NOT REMOVE
105
106 Content of /etc/shorewall/interfaces
107  #ZONE                     INTERFACE            BROADCAST  OPTIONS        
108  $ZVMBR0                   vmbr0                detect     bridge,optional
109  $ZVMBR0EXT                vmbr0:eth0           -                         
110  $ZVMBR0VM100              vmbr0:tap100i0       -          maclist        
111  #LAST LINE - ADD YOUR ENTRIES ABOVE THIS ONE - DO NOT REMOVE
112
113 Zone $ZVMBR0VM100 contains all network interfaces from VM100.
114
115 Zone $ZVMBR0EXT contains all physical network interfaces. We consider this zone to be the external world.
116
117 A shorewall rule for inbound traffic looks like this:
118
119  SSH(ACCEPT)     all       $ZVMBR0VM100:tap100i0 
120
121 Outbound rules looks like:
122
123  SSH(ACCEPT)     $ZVMBR0VM100:tap100i0          all
124
125
126 Problems
127 ===================
128
129 Inbound rules with source IP does not work, because shorewall
130 does not allow rules like:
131
132  SSH(ACCEPT)     all:IP_ADDRESS       $ZVMBR0VM100:tap100i0
133
134 As workaroud, we create one rule for each BP zone on the same
135 bridge:
136
137  SSH(ACCEPT)     $ZVMBR0:IP_ADDRESS       $ZVMBR0VM100:tap100i0
138  SSH(ACCEPT)     $ZVMBR0VM777:IP_ADDRESS  $ZVMBR0VM100:tap100i0
139  SSH(ACCEPT)     $ZVMBR0EXT:IP_ADDRESS    $ZVMBR0VM100:tap100i0
140
141
142
143
144
145
146
147