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