forked from extern/shorewall_code
311 lines
12 KiB
XML
311 lines
12 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>shorewall-names</refentrytitle>
|
|
|
|
<manvolnum>5</manvolnum>
|
|
|
|
<refmiscinfo>Configuration Files</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>Names</refname>
|
|
|
|
<refpurpose>Shorewall object names</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>When you define an object in Shorewall (<ulink
|
|
url="manpages/shorewall-zones.html">Zone</ulink>, <link
|
|
linkend="Logical">Logical Interface</link>, <ulink
|
|
url="ipsets.html">ipsets</ulink>, <ulink
|
|
url="Actions.html">Actions</ulink>, etc., you give it a name. Shorewall
|
|
names start with a letter and consist of letters, digits or underscores
|
|
("_"). Except for Zone names, Shorewall does not impose a limit on name
|
|
length.</para>
|
|
|
|
<para>When an ipset is referenced, the name must be preceded by a plus
|
|
sign ("+").</para>
|
|
|
|
<para>The last character of an interface may also be a plus sign to
|
|
indicate a wildcard name.</para>
|
|
|
|
<para>Physical interface names match names shown by 'ip link ls'; if the
|
|
name includes an at sign ("@"), do not include that character or any
|
|
character that follows. For example, "sit1@NONE" is referred to as simply
|
|
'sit1".</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Zone and Chain Names</title>
|
|
|
|
<para>For a pair of zones, Shorewall creates two Netfilter chains; one for
|
|
connections in each direction. The names of these chains are formed by
|
|
separating the names of the two zones by either "2" or "-".</para>
|
|
|
|
<para>Example: Traffic from zone A to zone B would go through chain A2B
|
|
(think "A to B") or "A-B".</para>
|
|
|
|
<para>In Shorewall 4.6, the default separator is "-" but you can override
|
|
that by setting ZONE_SEPARATOR="2" in <ulink
|
|
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5).</para>
|
|
|
|
<note>
|
|
<para>Prior to Shorewall 4.6, the default separator was "2".</para>
|
|
</note>
|
|
|
|
<para>Zones themselves have names that begin with a letter and are
|
|
composed of letters, numerals, and "_". The maximum length of a name is
|
|
dependent on the setting of LOGFORMAT in <ulink
|
|
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5). See <ulink
|
|
url="manpages/shorewall-zones.html">shorewall-zones</ulink> (5) for
|
|
details.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Using DNS Names</title>
|
|
|
|
<caution>
|
|
<para>I personally recommend strongly against using DNS names in
|
|
Shorewall configuration files. If you use DNS names and you are called
|
|
out of bed at 2:00AM because Shorewall won't start as a result of DNS
|
|
problems then don't say that you were not forewarned.</para>
|
|
</caution>
|
|
|
|
<para>Host addresses in Shorewall configuration files may be specified as
|
|
either IP addresses or DNS Names.</para>
|
|
|
|
<para>DNS names in iptables rules aren't nearly as useful as they first
|
|
appear. When a DNS name appears in a rule, the iptables utility resolves
|
|
the name to one or more IP addresses and inserts those addresses into the
|
|
rule. So changes in the DNS->IP address relationship that occur after
|
|
the firewall has started have absolutely no effect on the firewall's rule
|
|
set.</para>
|
|
|
|
<para>For some sites, using DNS names is very risky. Here's an
|
|
example:</para>
|
|
|
|
<programlisting>teastep@ursa:~$ dig pop.gmail.com
|
|
|
|
; <<>> DiG 9.4.2-P1 <<>> pop.gmail.com
|
|
;; global options: printcmd
|
|
;; Got answer:
|
|
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 1774
|
|
;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 7, ADDITIONAL: 0
|
|
|
|
;; QUESTION SECTION:
|
|
;pop.gmail.com. IN A
|
|
|
|
;; ANSWER SECTION:
|
|
pop.gmail.com. <emphasis role="bold">300</emphasis> IN CNAME gmail-pop.l.google.com.
|
|
gmail-pop.l.google.com. <emphasis role="bold">300</emphasis> IN A 209.85.201.109
|
|
gmail-pop.l.google.com. <emphasis role="bold">300</emphasis> IN A 209.85.201.111</programlisting>
|
|
|
|
<para>Note that the TTL is 300 -- 300 seconds is only 5 minutes. So five
|
|
minutes later, the answer may change!</para>
|
|
|
|
<para>So this rule may work for five minutes then suddently stop
|
|
working:</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
POP(ACCEPT) loc net:pop.gmail.com</programlisting>
|
|
|
|
<para>There are two options in <ulink
|
|
url="manpages/shorewall.conf.html">shorewall[6].conf(5)</ulink> that
|
|
affect the use of DNS names in Shorewall[6] config files:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>DEFER_DNS_RESOLUTION - When set to No, DNS names are resolved at
|
|
compile time; when set to Yes, DNS Names are resolved at
|
|
runtime.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>AUTOMAKE - When set to Yes, <command>start</command>,
|
|
<command>restart</command> and <command>reload</command> only result
|
|
in compilation if one of the files on the CONFIG_PATH has changed
|
|
since the the last compilation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>So by setting AUTOMAKE=Yes, and DEFER_DNS_RESOLUTION=No, compilation
|
|
will only take place at boot time if a change had been make to the config
|
|
but no <command>restart</command> or <command>reload</command> had taken
|
|
place. This is clearly spelled out in the shorewall.conf manpage. So with
|
|
these settings, so long as a 'reload' or 'restart' takes place after the
|
|
Shorewall configuration is changes, there should be no DNS-related
|
|
problems at boot time.</para>
|
|
|
|
<important>
|
|
<para>When DEFER_DNS_RESOLUTION=No and AUTOMAKE=Yes and a DNS change
|
|
makes it necessary to recompile an existing firewall script, the
|
|
<option>-c</option> option must be used with the
|
|
<command>reload</command> or <command>restart</command> command to force
|
|
recompilation.</para>
|
|
</important>
|
|
|
|
<para>If your firewall rules include DNS names then, even if
|
|
DEFER_DNS_RESOLUTION=No and AUTOMAKE=Yes:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If your <filename>/etc/resolv.conf </filename>is wrong then your
|
|
firewall may not start.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If your <filename>/etc/nsswitch.conf</filename> is wrong then
|
|
your firewall may not start.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If your Name Server(s) is(are) down then your firewall may not
|
|
start.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If your startup scripts try to start your firewall before
|
|
starting your DNS server then your firewall may not start.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Factors totally outside your control (your ISP's router is down
|
|
for example), can prevent your firewall from starting.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You must bring up your network interfaces prior to starting your
|
|
firewall, or the firewall may not start.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Each DNS name must be fully qualified and include a minimum of two
|
|
periods (although one may be trailing). This restriction is imposed by
|
|
Shorewall to insure backward compatibility with existing configuration
|
|
files.</para>
|
|
|
|
<example id="validdns">
|
|
<title>Valid DNS Names</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>mail.shorewall.net</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>shorewall.net. (note the trailing period).</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</example>
|
|
|
|
<example id="invaliddns">
|
|
<title>Invalid DNS Names</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>mail (not fully qualified)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>shorewall.net (only one period)</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</example>
|
|
|
|
<para>DNS names may not be used as:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The server address in a DNAT rule (/etc/shorewall/rules
|
|
file)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In the ADDRESS column of an entry in /etc/shorewall/masq.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para/>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In the <filename>/etc/shorewall/nat</filename> file.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>These restrictions are imposed by Netfilter and not by
|
|
Shorewall.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Logical Interface Names</title>
|
|
|
|
<para>When dealing with a complex configuration, it is often awkward to
|
|
use physical interface names in the Shorewall configuration.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>You need to remember which interface is which.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you move the configuration to another firewall, the interface
|
|
names might not be the same.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Beginning with Shorewall 4.4.4, you can use logical interface names
|
|
which are mapped to the actual interface using the
|
|
<option>physical</option> option in <ulink
|
|
url="manpages/shorewall-interfaces.html">shorewall-interfaces</ulink>
|
|
(5).</para>
|
|
|
|
<para>Here is an example:</para>
|
|
|
|
<programlisting>#ZONE INTERFACE OPTIONS
|
|
net <emphasis role="bold">COM_IF </emphasis> dhcp,blacklist,tcpflags,optional,upnp,routefilter=0,nosmurfs,logmartians=0,<emphasis
|
|
role="bold">physical=eth0</emphasis>
|
|
net <emphasis role="bold">EXT_IF</emphasis> dhcp,blacklist,tcpflags,optional,routefilter=0,nosmurfs,logmartians=0,proxyarp=1,<emphasis
|
|
role="bold">physical=eth2</emphasis>
|
|
loc <emphasis role="bold">INT_IF </emphasis> dhcp,logmartians=1,routefilter=1,tcpflags,nets=172.20.1.0/24,<emphasis
|
|
role="bold">physical=eth1</emphasis>
|
|
dmz <emphasis role="bold">VPS_IF </emphasis> logmartians=1,routefilter=0,routeback,<emphasis
|
|
role="bold">physical=venet0</emphasis>
|
|
loc <emphasis role="bold">TUN_IF</emphasis> <emphasis role="bold">physical=tun+</emphasis></programlisting>
|
|
|
|
<para>In this example, COM_IF is a logical interface name that refers to
|
|
Ethernet interface <filename class="devicefile">eth0</filename>, EXT_IF is
|
|
a logical interface name that refers to Ethernet interface <filename
|
|
class="devicefile">eth2</filename>, and so on.</para>
|
|
|
|
<para>Here are a couple of more files from the same configuration:</para>
|
|
|
|
<para><ulink url="manpages/shorewall-masq.html">shorewall-masq</ulink>
|
|
(5):</para>
|
|
|
|
<programlisting>#INTERFACE SOURCE ADDRESS
|
|
|
|
COMMENT Masquerade Local Network
|
|
<emphasis role="bold">COM_IF</emphasis> 0.0.0.0/0
|
|
<emphasis role="bold">EXT_IF </emphasis> !206.124.146.0/24 206.124.146.179:persistent</programlisting>
|
|
|
|
<para><ulink
|
|
url="manpages/shorewall-providers.html">shorewall-providers</ulink>
|
|
(5)</para>
|
|
|
|
<programlisting>#NAME NUMBER MARK DUPLICATE INTERFACE GATEWAY OPTIONS COPY
|
|
Avvanta 1 0x10000 main <emphasis role="bold">EXT_IF </emphasis> 206.124.146.254 loose,fallback <emphasis
|
|
role="bold">INT_IF,VPS_IF,TUN_IF</emphasis>
|
|
Comcast 2 0x20000 main <emphasis role="bold">COM_IF</emphasis> detect balance <emphasis
|
|
role="bold">INT_IF,VPS_IF,TUN_IF</emphasis></programlisting>
|
|
|
|
<para>Note in particular that Shorewall translates TUN_IF to <filename
|
|
class="devicefile">tun*</filename> in the COPY column.</para>
|
|
</refsect1>
|
|
</refentry>
|