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