[pve-firewall.git] / debian / README

Experimental software, only used for testing!
=============================================


Quick Intro
===========

VM firewall rules are read from:

 /etc/pve/firewall/<VMID>.fw

Cluster wide rules and security group are read from:
 
 /etc/pve/firewall/cluster.fw

Host firewall rules are read from:

  /etc/pve/local/host.fw

You can find examples in the example/ dir


Use the following command to mange the firewall:

To test the firewall configuration:

./pvefw compile

To start or update the firewall:

./pvefw start

To update the firewall rules (the firewall is not started if it
is not already running):

./pvefw update

To stop the firewall:

./pvefw stop


Implementation details
======================

We write iptables rules directly, an generate the following chains 
as entry points in the 'forward' table:

PVEFW-INPUT
PVEFW-OUTPUT
PVEFW-FORWARD

We do not touch other (user defined) chains.

Each VM can have its own firewall definition file in 

/etc/pve/firewall/<VMID>.fw

That file has a section [RULES] to define firewall rules.

Format is: TYPE ACTION IFACE SOURCE DEST PROTO D-PORT S-PORT

* TYPE: IN|OUT|GROUP 
* ACTION: action or macro
* IFACE: vm network interface (net0 - net5), or '-' for all interfaces
* SOURCE: source IP address, or '-' for any source
* DEST: dest IP address, or '-' for any destination address
* PROTO: see /etc/protocols
* D-PORT: destination port
* S-PORT: source port

A rule for inbound traffic looks like this:

IN SSH(ACCEPT) net0

Outbound rules looks like:

OUT SSH(ACCEPT)

Problems
===================

There are a number of restrictions when using iptables to filter
bridged traffic. The physdev match feature does not work correctly
when traffic is routed from host to bridge:

  * when a packet being sent through a bridge entered the firewall on 
    another interface and was being forwarded to the bridge.

  * when a packet originating on the firewall itself is being sent through 
    a bridge.

We use a second bridge for each interface to avoid above problem.

eth0-->vmbr0<--tapXiY (non firewalled tap)
            <--linkXiY-->linkXiYp-->fwbrXiY-->tapXiY (firewalled tap)
Commit	Line	Data
	1	Experimental software, only used for testing!
	2	=============================================
	3
	4
	5	Quick Intro
	6	===========
	7
	8	VM firewall rules are read from:
	9
	10	/etc/pve/firewall/<VMID>.fw
	11
	12	Cluster wide rules and security group are read from:
	13
	14	/etc/pve/firewall/cluster.fw
	15
	16	Host firewall rules are read from:
	17
	18	/etc/pve/local/host.fw
	19
	20	You can find examples in the example/ dir
	21
	22
	23	Use the following command to mange the firewall:
	24
	25	To test the firewall configuration:
	26
	27	./pvefw compile
	28
	29	To start or update the firewall:
	30
	31	./pvefw start
	32
	33	To update the firewall rules (the firewall is not started if it
	34	is not already running):
	35
	36	./pvefw update
	37
	38	To stop the firewall:
	39
	40	./pvefw stop
	41
	42
	43	Implementation details
	44	======================
	45
	46	We write iptables rules directly, an generate the following chains
	47	as entry points in the 'forward' table:
	48
	49	PVEFW-INPUT
	50	PVEFW-OUTPUT
	51	PVEFW-FORWARD
	52
	53	We do not touch other (user defined) chains.
	54
	55	Each VM can have its own firewall definition file in
	56
	57	/etc/pve/firewall/<VMID>.fw
	58
	59	That file has a section [RULES] to define firewall rules.
	60
	61	Format is: TYPE ACTION IFACE SOURCE DEST PROTO D-PORT S-PORT
	62
	63	* TYPE: IN\|OUT\|GROUP
	64	* ACTION: action or macro
	65	* IFACE: vm network interface (net0 - net5), or '-' for all interfaces
	66	* SOURCE: source IP address, or '-' for any source
	67	* DEST: dest IP address, or '-' for any destination address
	68	* PROTO: see /etc/protocols
	69	* D-PORT: destination port
	70	* S-PORT: source port
	71
	72	A rule for inbound traffic looks like this:
	73
	74	IN SSH(ACCEPT) net0
	75
	76	Outbound rules looks like:
	77
	78	OUT SSH(ACCEPT)
	79
	80	Problems
	81	===================
	82
	83	There are a number of restrictions when using iptables to filter
	84	bridged traffic. The physdev match feature does not work correctly
	85	when traffic is routed from host to bridge:
	86
	87	* when a packet being sent through a bridge entered the firewall on
	88	another interface and was being forwarded to the bridge.
	89
	90	* when a packet originating on the firewall itself is being sent through
	91	a bridge.
	92
	93	We use a second bridge for each interface to avoid above problem.
	94
	95	eth0-->vmbr0<--tapXiY (non firewalled tap)
	96	<--linkXiY-->linkXiYp-->fwbrXiY-->tapXiY (firewalled tap)