shorewall_code/Shorewall6/manpages/shorewall6-interfaces.xml
Tom Eastep 4869f61a25
'allow' now works with ipset-based dynamic blacklisting
Signed-off-by: Tom Eastep <teastep@shorewall.net>
2016-06-09 08:44:25 -07:00

665 lines
25 KiB
XML

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<refentry>
<refmeta>
<refentrytitle>shorewall6-interfaces</refentrytitle>
<manvolnum>5</manvolnum>
<refmiscinfo>Configuration Files</refmiscinfo>
</refmeta>
<refnamediv>
<refname>interfaces</refname>
<refpurpose>shorewall6 interfaces file</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>/etc/shorewall6/interfaces</command>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>The interfaces file serves to define the firewall's network
interfaces to shorewall6. The order of entries in this file is not
significant in determining zone composition.</para>
<para>Beginning with Shorewall 4.5.3, the interfaces file supports two
different formats:</para>
<variablelist>
<varlistentry>
<term>FORMAT 1 (default - deprecated)</term>
<listitem>
<para>There is a ANYCAST column which provides compatibility with
older versions of Shorewall..</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FORMAT 2</term>
<listitem>
<para>The BROADCAST column is omitted.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The format is specified by a line as follows:</para>
<blockquote>
<para><emphasis role="bold">?FORMAT {1|2}</emphasis></para>
</blockquote>
<para>The columns in the file are as follows.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">ZONE</emphasis> -
<emphasis>zone-name</emphasis></term>
<listitem>
<para>Zone for this interface. Must match the name of a zone
declared in /etc/shorewall6/zones. You may not list the firewall
zone in this column.</para>
<para>If the interface serves multiple zones that will be defined in
the <ulink
url="/manpages6/shorewall6-hosts.html">shorewall6-hosts</ulink>(5)
file, you should place "-" in this column.</para>
<para>If there are multiple interfaces to the same zone, you must
list them in separate entries.</para>
<para>Example:</para>
<blockquote>
<programlisting>#ZONE INTERFACE BROADCAST
loc eth1 -
loc eth2 -</programlisting>
</blockquote>
<para>Beginning with Shorewall 4.5.17, if you specify a zone for the
'lo' interface, then that zone must be defined as type
<option>local</option> in <ulink
url="/manpages6/shorewall6-zones.html">shorewall6-zones</ulink>(5).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">INTERFACE</emphasis> -
<emphasis>interface</emphasis><emphasis
role="bold">[:</emphasis><emphasis>port</emphasis><emphasis
role="bold">]</emphasis></term>
<listitem>
<para>Logical name of interface. Each interface may be listed only
once in this file. You may NOT specify the name of a "virtual"
interface (e.g., eth0:0) here; see <ulink
url="/FAQ.htm#faq18">http://www.shorewall.net/FAQ.htm#faq18</ulink>.
If the <option>physical</option> option is not specified, then the
logical name is also the name of the actual interface.</para>
<para>You may use wildcards here by specifying a prefix followed by
the plus sign ("+"). For example, if you want to make an entry that
applies to all PPP interfaces, use 'ppp+'; that would match ppp0,
ppp1, ppp2, …Please note that the '+' means '<emphasis
role="bold">one</emphasis> or more additional characters' so 'ppp'
does not match 'ppp+'.</para>
<para>Care must be exercised when using wildcards where there is
another zone that uses a matching specific interface. See <ulink
url="/manpages6/shorewall6-nesting.html">shorewall6-nesting</ulink>(5)
for a discussion of this problem.</para>
<para>Shorewall6 allows '+' as an interface name.</para>
<para>There is no need to define the loopback interface (lo) in this
file.</para>
<para>If a <replaceable>port</replaceable> is given, then the
<replaceable>interface</replaceable> must have been defined
previously with the <option>bridge</option> option. The OPTIONS
column must be empty when a <replaceable>port</replaceable> is
given.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">ANYCAST</emphasis> - <emphasis
role="bold">-</emphasis></term>
<listitem>
<para>Enter '<emphasis role="bold">-'</emphasis> in this column. It
is here for compatibility between Shorewall6 and Shorewall and is
omitted if FORMAT is 2.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">OPTIONS</emphasis> (Optional) -
[<emphasis>option</emphasis>[<emphasis
role="bold">,</emphasis><emphasis>option</emphasis>]...]</term>
<listitem>
<para>A comma-separated list of options from the following list. The
order in which you list the options is not significant but the list
should have no embedded white-space.</para>
<variablelist>
<varlistentry>
<term><emphasis
role="bold">accept_ra</emphasis>[={0|1|2}]</term>
<listitem>
<para>Added in Shorewall 4.5.16. Values are:</para>
<variablelist>
<varlistentry>
<term>0</term>
<listitem>
<para>Do not accept Router Advertisements.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>1</term>
<listitem>
<para>Accept Route Advertisements if forwarding is
disabled.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>2</term>
<listitem>
<para>Overrule forwarding behavior. Accept Route
Advertisements even if forwarding is enabled.</para>
</listitem>
</varlistentry>
</variablelist>
<para>If the option is specified without a value, then the
value 1 is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">blacklist</emphasis></term>
<listitem>
<para>Check packets arriving on this interface against the
<ulink
url="/manpages6/shorewall6-blacklist.html">shorewall6-blacklist</ulink>(5)
file.</para>
<para>Beginning with Shorewall 4.4.13:</para>
<itemizedlist>
<listitem>
<para>If a <replaceable>zone</replaceable> is given in the
ZONES column, then the behavior is as if <emphasis
role="bold">blacklist</emphasis> had been specified in the
IN_OPTIONS column of <ulink
url="/manpages6/shorewall6-zones.html">shorewall6-zones</ulink>(5).</para>
</listitem>
<listitem>
<para>Otherwise, the option is ignored with a
warning:</para>
<blockquote>
<para><emphasis role="bold">WARNING: The 'blacklist'
option is ignored on multi-zone
interfaces</emphasis></para>
</blockquote>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">bridge</emphasis></term>
<listitem>
<para>Designates the interface as a bridge. Beginning with
Shorewall 4.4.7, setting this option also sets
<option>routeback</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">destonly</emphasis></term>
<listitem>
<para>Added in Shorewall 4.5.17. Causes the compiler to omit
rules to handle traffic from this interface.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">dhcp</emphasis></term>
<listitem>
<para>Specify this option when any of the following are
true:</para>
<orderedlist spacing="compact">
<listitem>
<para>the interface gets its IP address via DHCP</para>
</listitem>
<listitem>
<para>the interface is used by a DHCP server running on
the firewall</para>
</listitem>
<listitem>
<para>the interface has a static IP but is on a LAN
segment with lots of DHCP clients.</para>
</listitem>
<listitem>
<para>the interface is a <ulink
url="/SimpleBridge.html">simple bridge</ulink> with a DHCP
server on one port and DHCP clients on another
port.</para>
<note>
<para>If you use <ulink
url="/bridge-Shorewall-perl.html">Shorewall-perl for
firewall/bridging</ulink>, then you need to include
DHCP-specific rules in <ulink
url="/manpages/shorewall-rules.html">shorewall-rules</ulink>(8).
DHCP uses UDP ports 546 and 547.</para>
</note>
</listitem>
</orderedlist>
<para>This option allows DHCP datagrams to enter and leave the
interface.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">forward</emphasis>[={0|1}]</term>
<listitem>
<para>Sets the /proc/sys/net/ipv6/conf/interface/forwarding
option to the specified value. If no value is supplied, then 1
is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">ignore[=1]</emphasis></term>
<listitem>
<para>When specified, causes the generated script to ignore
up/down events from Shorewall-init for this device.
Additionally, the option exempts the interface from hairpin
filtering. When '=1' is omitted, the ZONE column must contain
'-' and <option>ignore</option> must be the only
OPTION.</para>
<para>Beginning with Shorewall 4.5.5, may be specified as
'<option>ignore=1</option>' which only causes the generated
script to ignore up/down events from Shorewall-init; hairpin
filtering is still applied. In this case, the above
restrictions on the ZONE and OPTIONS columns are
lifted.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">loopback</emphasis></term>
<listitem>
<para>Added in Shorewall 4.6.6. Designates the interface as
the loopback interface. This option is assumed if the
interface's physical name is 'lo'. Only one interface man have
the <option>loopback</option> option specified.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis
role="bold">mss</emphasis>=<emphasis>number</emphasis></term>
<listitem>
<para>Causes forwarded TCP SYN packets entering or leaving on
this interface to have their MSS field set to the specified
<replaceable>number</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis
role="bold">nets=(<emphasis>net</emphasis>[,...])</emphasis></term>
<listitem>
<para>Limit the zone named in the ZONE column to only the
listed networks. If you specify this option, be sure to
include the link-local network (ff80::/10).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">nets=dynamic</emphasis></term>
<listitem>
<para>Added in Shorewall 4.4.21. Defines the zone as
<firstterm>dynamic</firstterm>. Requires ipset match support
in your iptables and kernel. See <ulink
url="/Dynamic.html">http://www.shorewall.net/Dynamic.html</ulink>
for further information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">nodbl</emphasis></term>
<listitem>
<para>Added in Shorewall 5.0.8. When specified, dynamic
blacklisting is disabled on the interface.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">optional</emphasis></term>
<listitem>
<para>When <option>optional</option> is specified for an
interface, shorewall6 will be silent when:</para>
<itemizedlist>
<listitem>
<para>a <filename
class="directory">/proc/sys/net/ipv6/conf/</filename>
entry for the interface cannot be modified.</para>
</listitem>
<listitem>
<para>The first global IPv6 address of the interface
cannot be obtained.</para>
</listitem>
</itemizedlist>
<para>This option may not be specified together with <emphasis
role="bold">required</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">physical</emphasis>=<emphasis
role="bold"><emphasis>name</emphasis></emphasis></term>
<listitem>
<para>Added in Shorewall 4.4.4. When specified, the interface
or port name in the INTERFACE column is a logical name that
refers to the name given in this option. It is useful when you
want to specify the same wildcard port name on two or more
bridges. See <ulink
url="/bridge-Shorewall-perl.html#Multiple">http://www.shorewall.net/bridge-Shorewall-perl.html#Multiple</ulink>.</para>
<para>If the <emphasis>interface</emphasis> name is a wildcard
name (ends with '+'), then the physical
<emphasis>name</emphasis> must also end in '+'.</para>
<para>If <option>physical</option> is not specified, then it's
value defaults to the <emphasis>interface</emphasis>
name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">required</emphasis></term>
<listitem>
<para>Added in Shorewall 4.4.10. When specified, the firewall
will fail to start if the interface named in the INTERFACE
column is not usable. May not be specified together with
<emphasis role="bold">optional</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">routeback[={0|1}]</emphasis></term>
<listitem>
<para>If specified, indicates that shorewall6 should include
rules that allow traffic arriving on this interface to be
routed back out that same interface. This option is also
required when you have used a wildcard in the INTERFACE column
if you want to allow traffic between the interfaces that match
the wildcard.</para>
<para>If you specify this option, then you should also specify
<option>rpfilter</option> (see below) if you are running
Shorewall 4.5.7 or later; otherwise, you should specify
<option>sfilter</option> (see below).</para>
<para>Beginning with Shorewall 4.5.18, you may specify this
option to explicitly reset (e.g., <emphasis
role="bold">routeback=0</emphasis>). This can be used to
override Shorewall's default setting for bridge devices which
is <emphasis role="bold">routeback=1</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">rpfilter</emphasis></term>
<listitem>
<para>Added in Shorewall 4.5.7. This is an anti-spoofing
measure that requires the 'RPFilter Match' capability in your
iptables and kernel. It provides a more efficient alternative
to the <option>sfilter</option> option below.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis
role="bold">sourceroute[={0|1}]</emphasis></term>
<listitem>
<para>If this option is not specified for an interface, then
source-routed packets will not be accepted from that interface
unless explicitly enabled via sysconf. Only set this option to
1 (enable source routing) if you know what you are doing. This
might represent a security risk and is not usually
needed.</para>
<para>Only those interfaces with the
<option>sourceroute</option> option will have their setting
changed; the value assigned to the setting will be the value
specified (if any) or 1 if no value is given.</para>
<note>
<para>This option does not work with a wild-card
<replaceable>interface</replaceable> name (e.g., eth0.+) in
the INTERFACE column.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis
role="bold">sfilter=(<emphasis>net</emphasis>[,...])</emphasis></term>
<listitem>
<para>Added in Shorewall 4.4.20. At this writing (spring
2011), Linux does not support reverse path filtering (RFC3704)
for IPv6. In its absence, <option>sfilter</option> may be used
as an anti-spoofing measure.</para>
<para>This option should be used on bridges or other
interfaces with the <option>routeback</option> option. On
these interfaces, <option>sfilter</option> should list those
local networks that are connected to the firewall through
other interfaces.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">tcpflags[={0|1}]</emphasis></term>
<listitem>
<para>Packets arriving on this interface are checked for
certain illegal combinations of TCP flags. Packets found to
have such a combination of flags are handled according to the
setting of TCP_FLAGS_DISPOSITION after having been logged
according to the setting of TCP_FLAGS_LOG_LEVEL.</para>
<para>Beginning with Shorewall 4.6.0, tcpflags=1 is the
default. To disable this option, specify tcpflags=0.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">proxyndp</emphasis>[={0|1}]</term>
<listitem>
<para>Sets
/proc/sys/net/ipv6/conf/<emphasis>interface</emphasis>/proxy_ndp.</para>
<para><emphasis role="bold">Note</emphasis>: This option does
not work with a wild-card <replaceable>interface</replaceable>
name (e.g., eth0.+) in the INTERFACE column.</para>
<para>Only those interfaces with the <option>proxyndp</option>
option will have their setting changed; the value assigned to
the setting will be the value specified (if any) or 1 if no
value is given.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">unmanaged</emphasis></term>
<listitem>
<para>Added in Shorewall 4.5.18. Causes all traffic between
the firewall and hosts on the interface to be accepted. When
this option is given:</para>
<itemizedlist>
<listitem>
<para>The ZONE column must contain '-'.</para>
</listitem>
<listitem>
<para>Only the following other options are allowed with
<emphasis role="bold">unmanaged</emphasis>:</para>
<simplelist>
<member><emphasis
role="bold">accept_ra</emphasis></member>
<member><emphasis
role="bold">forward</emphasis></member>
<member><emphasis role="bold">ignore</emphasis></member>
<member><emphasis
role="bold">optional</emphasis></member>
<member><emphasis
role="bold">physical</emphasis></member>
<member><emphasis
role="bold">sourceroute</emphasis></member>
<member><emphasis
role="bold">proxyndp</emphasis></member>
</simplelist>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis
role="bold">wait</emphasis>=<emphasis>seconds</emphasis></term>
<listitem>
<para>Added in Shorewall 4.4.10. Causes the generated script
to wait up to <emphasis>seconds</emphasis> seconds for the
interface to become usable before applying the <emphasis
role="bold">required</emphasis> or <emphasis
role="bold">optional</emphasis> options.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Example</title>
<variablelist>
<varlistentry>
<term>Example 1:</term>
<listitem>
<para>Suppose you have eth0 connected to a DSL modem and eth1
connected to your local network You have a DMZ using eth2.</para>
<para>Your entries for this setup would look like:</para>
<programlisting>FORMAT 2
#ZONE INTERFACE OPTIONS
net eth0 -
loc eth1 -
dmz eth2 -</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>Example 4 (Shorewall 4.4.9 and later):</term>
<listitem>
<para>You have a bridge with no IP address and you want to allow
traffic through the bridge.</para>
<programlisting>FORMAT 2
#ZONE INTERFACE OPTIONS
- br0 bridge</programlisting>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>FILES</title>
<para>/etc/shorewall6/interfaces</para>
</refsect1>
<refsect1>
<title>See ALSO</title>
<para><ulink
url="/configuration_file_basics.htm#Pairs">http://www.shorewall.net/configuration_file_basics.htm#Pairs</ulink></para>
<para>shorewall6(8), shorewall6-accounting(5), shorewall6-actions(5),
shorewall6-blacklist(5), shorewall6-hosts(5), shorewall6-maclist(5),
shorewall6-netmap(5),shorewall6-params(5), shorewall6-policy(5),
shorewall6-providers(5), shorewall6-rtrules(5),
shorewall6-routestopped(5), shorewall6-rules(5), shorewall6.conf(5),
shorewall6-secmarks(5), shorewall6-tcclasses(5), shorewall6-tcdevices(5),
shorewall6-mangle(5), shorewall6-tos(5), shorewall6-tunnels(5),
shorewall6-zones(5)</para>
</refsect1>
</refentry>