diff --git a/docs/formatnwfilter.html.in b/docs/formatnwfilter.html.in index 42ea866b9e..3862d04aca 100644 --- a/docs/formatnwfilter.html.in +++ b/docs/formatnwfilter.html.in @@ -277,6 +277,13 @@ Valid values are in the range of 0 to 1000. If this attribute is not provided, the value 500 will automatically be assigned. +
The above example indicates that the traffic of type ip
@@ -1117,6 +1124,118 @@
+ The following sections discuss advanced filter configuration + topics. +
+
+ The network filtering subsystem (on Linux) makes use of the connection
+ tracking support of iptables. This helps in enforcing the
+ directionality of network traffic (state match) as well as
+ counting and limiting the number of simultaneous connections towards
+ a VM. As an example, if a VM has TCP port 8080
+ open as a server, clients may connect to the VM on port 8080.
+ Connection tracking and enforcement of directionality then prevents
+ the VM from initiating a connection from
+ (TCP client) port 8080 to the host back to a remote host.
+ More importantly, tracking helps to prevent
+ remote attackers from establishing a connection back to a VM. For example,
+ if the user inside the VM established a connection to
+ port 80 on an attacker site, then the attacker will not be able to
+ initiate a connection from TCP port 80 back towards the VM.
+ By default the connection state match that enables connection tracking
+ and then enforcement of directionality of traffic is turned on.
+ The following shows an example XML fragement where this feature has been
+ turned off for incoming connections to TCP port 12345.
+
+ [...] + <rule direction='in' action='accept' statematch='false'> + <tcp dstportstart='12345'/> + </rule> + [...] ++
+ This now allows incoming traffic to TCP port 12345, but would also + enable the initiation from (client) TCP port 12345 within the VM, + which may or may not be desirable. +
+ ++ To limit the number of connections a VM may establish, a rule must + be provided that sets a limit of connections for a given + type of traffic. If for example a VM + is supposed to be allowed to only ping one other IP address at a time + and is supposed to have only one active incoming ssh connection at a + time, the following XML fragment can be used to achieve this. +
++ [...] + <rule action='drop' direction='in' priority='400'> + <tcp connlimit-above='1'/> + </rule> + <rule action='accept' direction='in' priority='500'> + <tcp dstportstart='22'/> + </rule> + <rule action='drop' direction='out' priority='400'> + <icmp connlimit-above='1'/> + </rule> + <rule action='accept' direction='out' priority='500'> + <icmp/> + </rule> + <rule action='accept' direction='out' priority='500'> + <udp dstportstart='53'/> + </rule> + <rule action='drop' direction='inout' priority='1000'> + <all/> + </rule> + [...] ++
+ Note that the rule for the limit has to logically appear
+ before the rule for accepting the traffic.
+ An additional rule for letting DNS traffic to port 22
+ go out the VM has been added to avoid ssh sessions not
+ getting established for reasons related to DNS lookup failures
+ by the ssh daemon. Leaving this rule out may otherwise lead to
+ fun-filled debugging joy (symptom: ssh client seems to hang
+ while trying to connect).
+
+ Lot of care must be taken with timeouts related
+ to tracking of traffic. An ICMP ping that
+ the user may have terminated inside the VM may have a long
+ timeout in the host's connection tracking system and therefore
+ not allow another ICMP ping to go through for a while. Therefore,
+ the timeouts have to be tuned in the host's sysfs, i.e.,
+
+ echo 3 > /proc/sys/net/netfilter/nf_conntrack_icmp_timeout ++
+ sets the ICMP connection tracking timeout to 3 seconds. The
+ effect of this is that once one ping is terminated, another
+ one can start after 3 seconds.
+ Further, we want to point out that a client that for whatever
+ reason has not properly closed a TCP connection may cause a
+ connection to be held open for a longer period of time,
+ depending to what timeout the TCP established
state
+ timeout has been set to on the host. Also, idle connections may time
+ out in the connection tracking system but can be reactivated once
+ packets are exchanged. However, a newly initiated connection may force
+ an idle connection into TCP backoff if the number of allowed connections
+ is set to a too low limit, the new connection is established
+ and hits (not exceeds) the limit of allowed connections and for
+ example a key is pressed on the old ssh session, which now has become
+ unresponsive due to its traffic being dropped.
+ Therefore, the limit of connections should be rather high so that
+ fluctuations in new TCP connections don't cause odd
+ traffic behavior in relaton to idle connections.
+
The libvirt command line tool virsh
has been extended