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