<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- For license information see sanewall-manual-info.xml.in -->
<refentry id="sanewall.conf">

<refmeta>
<refentrytitle>Sanewall configuration: sanewall.conf</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>

<refnamediv>
<refdescriptor>sanewall.conf</refdescriptor>
<refname>sanewall.conf</refname>
<refpurpose>Sanewall configuration file</refpurpose>
</refnamediv>

<refsect1><title>Description</title>
  <para>
    <filename>/etc/sanewall/sanewall.conf</filename> is the default
    configuration file for <xref linkend="sanewall"/>. It defines the
    stateful firewall that will be produced.
  </para>

  <para>A configuration file starts with an optional version indicator
    which looks like this:
    <programlisting>version 5</programlisting>
    See <xref linkend="helpconf-version"/> for full details.
  </para>

  <para>
    A configuration file contains one or more
    <command>interface</command> definitions, which look like this:
    <programlisting>interface eth0 lan
  client all accept # This host can access any remote service
  server ssh accept # Remote hosts can access SSH on local server
  # ...
    </programlisting>
    The above definition has name "lan" and specifies a network interface
    (eth0).
    A definition may contain zero or more subcommands.
    See <xref linkend="def-interface"/> for full details.
  </para>

  <para>
    A configuration file contains one or more
    <command>router</command> definitions, which look like this:
    <programlisting>DMZ_IF=eth0
WAN_IF=eth1
router wan2dmz inface ${WAN_IF} outface ${DMZ_IF}
  route http accept  # Hosts on WAN may access HTTP on hosts in DMZ
  server ssh accept  # Hosts on WAN may access SSH on hosts in DMZ
  client pop3 accept # Hosts in DMZ may access POP3 on hosts on WAN
  # ...
    </programlisting>
    The above definition has name "wan2dmz" and specifies incoming and
    outgoing network interfaces (eth1 and eth0) using variables.
    A definition may contain zero or more subcommands.
    Note that a router is not required to specify network interfaces to
    operate on. See <xref linkend="def-router"/> for full details.
  </para>

  <para>
    It is simple to add extra service definitions which can then
    be used in the same way as those provided as standard. See
    <xref linkend="adding-services"/>.
  </para>

  <para>
    The configuration file is parsed as a <command>bash(1)</command>
    script, allowing you to set up and use variables, flow control and
    external commands.
  </para>

  <para>
    Special <xref linkend="sanewall-variables"/> may be set up and used
    outside of any definition as can the functions in
    <xref linkend="sanewall-config-helpers"/> and
    <xref linkend="sanewall-helpers"/>.
  </para>
</refsect1>

<refsect1 id="variables-available"><title>Variables Available</title>
  <para>
    The following variables are made available in the
    <application>Sanewall</application> configuration file and
    can be accessed as ${VARIABLE}.
  </para>
  <variablelist>
    <varlistentry><term><envar>UNROUTABLE_IPS</envar></term>
      <listitem>
        <para>
          This variable includes the IPs from both <envar>PRIVATE_IPS</envar>
          and <envar>RESERVED_IPS</envar>. It is useful to restrict
          traffic on interfaces and routers accepting Internet traffic,
          for example:
          <programlisting>
interface eth0 internet src not "${UNROUTABLE_IPS}"
          </programlisting>
        </para>
      </listitem>
    </varlistentry>
    <varlistentry><term><envar>PRIVATE_IPS</envar></term>
      <listitem>
        <para>
          This variable includes all the IP addresses defined as Private
          or Test by
          <ulink url="https://tools.ietf.org/html/rfc3330">RFC 3330</ulink>.
        </para>
        <para>
          You can override the default values by creating a file called
          <filename>/etc/sanewall/PRIVATE_IPS</filename>.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry><term><envar>RESERVED_IPS</envar></term>
      <listitem>
        <para>
          This variable includes all the IP addresses defined by
          <ulink url="http://www.iana.org/">IANA</ulink> as reserved.
        </para>
        <para>
          You can override the default values by creating a file called
          <filename>/etc/sanewall/RESERVED_IPS</filename>.
        </para>
        <para>
          Now that IPv4 address space has all been allocated there is very
          little reason that this value will need to change in future.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry><term><envar>MULTICAST_IPS</envar></term>
      <listitem>
        <para>
          This variable includes all the IP addresses defined as Multicast by
          <ulink url="https://tools.ietf.org/html/rfc3330">RFC 3330</ulink>.
        </para>
        <para>
          You can override the default values by creating a file called
          <filename>/etc/sanewall/MULTICAST_IPS</filename>.
        </para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>

<refsect1 id="adding-services"><title>Adding Services</title>
  <para>
    To define new services you add the appropriate lines before using them
    later in the configuration file.
  </para>
  <para>
    The following are required:
    <programlisting>server_<replaceable>myservice</replaceable>_ports="<replaceable>proto/sports</replaceable>"
client_<replaceable>myservice</replaceable>_ports="<replaceable>cports</replaceable>"
    </programlisting>
  </para>
  <para>
    <replaceable>proto</replaceable> is anything
    <command>iptables(8)</command> accepts e.g. "tcp", "udp", "icmp",
    including numeric protocol values.
  </para>
  <para>
    <replaceable>sports</replaceable> is the ports the server is listening at.
    It is a space-separated list of port numbers, names and ranges (from:to).
    The keyword <option>any</option> will match any server port.
  </para>
  <para>
    <replaceable>cports</replaceable> is the ports the client may use to
    initiate a connection.
    It is a space-separated list of port numbers, names and ranges (from:to).
    The keyword <option>any</option> will match any client port.
    The keyword <option>default</option> will match default client ports.
    For the local machine (e.g. a <command>client</command> within an
    <command>interface</command>) it resolves to <command>sysctl</command>
    variable <envar>net.ipv4.ip_local_port_range</envar> (or
    <filename>/proc/sys/net/ipv4/ip_local_port_range</filename>). For
    a remote machine (e.g. a <command>client</command> within an
    <command>interface</command> or anything in a <command>router</command>)
    it resolves to the variable <envar>DEFAULT_CLIENT_PORTS</envar> (see
    <xref linkend="sanewall-variables"/>).
  </para>
  <para>
    The following are optional:
    <programlisting>require_<replaceable>myservice</replaceable>_modules="<replaceable>modules</replaceable>"
require_<replaceable>myservice</replaceable>_nat_modules="<replaceable>nat-modules</replaceable>"
    </programlisting>
    The named kernel modules will be loaded when the definition is used.
    The NAT modules will only be loaded if <envar>SANEWALL_NAT</envar> is
    non-zero (see <xref linkend="sanewall-variables"/>).
  </para>
  <para>
    For example, for a service named <option>daftnet</option> that listens
    at two ports, port 1234 TCP and 1234 UDP where the expected client
    ports are the default random ports a system may choose, plus the same
    port numbers the server listens at, with further dynamic ports requiring
    kernel modules to be loaded:
    <programlisting>version 5
	
server_daftnet_ports="tcp/1234 udp/1234"
client_daftnet_ports="default 1234"
require_daftnet_modules="ip_conntrack_daftnet"
require_daftnet_nat_modules="ip_nat_daftnet"

interface eth0 lan0
    server daftnet accept
	
interface eth1 lan1
    client daftnet reject
	
router lan2lan inface eth0 outface eth1
    route daftnet accept
    </programlisting>
  </para>
  <para>
    Where multiple ports are provides (as per the example),
    <application>Sanewall</application> simply determines all of the
    combinations of client and server ports and generates multiple iptables
    statements to match them.
  </para>
  <para>
     To create more complex rules, or stateless rules,
     you will need to create a bash function prefixed <option>rules_</option>
     e.g. <option>rules_myservice</option>. The best reference
     is the many such functions in the main <command>sanewall</command>
     executable.
  </para>
  <para>
     When adding a service which uses modules, or via a custom function,
     you may also wish to include the following:
    <programlisting>ALL_SHOULD_ALSO_RUN="${ALL_SHOULD_ALSO_RUN} <replaceable>myservice</replaceable>"
    </programlisting>
     which will ensure your service is set-up correctly as part of the
     <command>all</command> service.
  </para>
  <note>
    <para>
      To allow definitions to be shared you can instead create files and
      install them in the <filename>/etc/sanewall/services</filename>
      directory with a <filename>.conf</filename> extension.
    </para>
    <para>
      The first line must read:
      <programlisting>FHVER 1:213</programlisting>
      1 is the service definition API version. It will be changed if the
      API is ever modified. 213 refers to a <application>FireHOL</application>
      version and is retained for compatibility.
    </para>
    <para>
      <application>Sanewall</application> will refuse to run if the
       API version does not match the expected one. The minor number
       is ignored.
    </para>
    <para>
      At version 1:213, the API and therefore service definitions are
      compatible with <application>FireHOL</application>.
    </para>
  </note>
</refsect1>

<refsect1><title>Definitions</title>
  <simplelist type="vert">
    <member><xref linkend="def-interface"/></member>
    <member><xref linkend="def-router"/></member>
  </simplelist>
</refsect1>

<refsect1><title>Subcommands</title>
  <simplelist type="vert">
    <member><xref linkend="cmd-policy"/></member>
    <member><xref linkend="cmd-protection"/></member>
    <member><xref linkend="cmd-server"/></member>
    <member><xref linkend="cmd-client"/></member>
    <member><xref linkend="cmd-group"/></member>
  </simplelist>
</refsect1>

<refsect1 id="sanewall-helpers"><title>Helper Commands</title>
  <para>
    These helpers can be used in <command>interface</command> and
    <command>router</command> definitions as well as before them.
  </para>
  <simplelist type="vert">
    <member><xref linkend="helpcmd-iptables"/></member>
    <member><xref linkend="helpcmd-masquerade"/></member>
  </simplelist>
  <para>
    This helper can be used in <command>router</command> definitions
    as well as before any <command>router</command> or
    <command>interface</command>.
  </para>
  <simplelist type="vert">
    <member><xref linkend="helpcmd-tcpmss"/></member>
  </simplelist>
</refsect1>

<refsect1 id="sanewall-config-helpers"><title>Configuration Helper Commands</title>
  <para>
    These helpers should only be used outside of <command>interface</command>
    and <command>router</command> definitions (i.e. before the first
    interface is defined).
  </para>
  <simplelist type="vert">
    <member><xref linkend="helpconf-version"/></member>
    <member><xref linkend="helpconf-action"/></member>
    <member><xref linkend="helpconf-blacklist"/></member>
    <member><xref linkend="helpconf-classify"/></member>
    <member><xref linkend="helpconf-connmark"/></member>
    <member><xref linkend="helpconf-dscp"/></member>
    <member><xref linkend="helpconf-mac"/></member>
    <member><xref linkend="helpconf-mark"/></member>
    <member><xref linkend="helpconf-nat"/></member>
    <member><xref linkend="helpconf-proxy"/></member>
    <member><xref linkend="helpconf-tos"/></member>
    <member><xref linkend="helpconf-tosfix"/></member>
  </simplelist>
</refsect1>

<refsect1><title>See Also</title>
  <simplelist type="vert">
    <member><xref linkend="sanewall"/></member>
    <member><xref linkend="sanewall-variables"/></member>
    <member><xref linkend="ref-services"/></member>
    <member><xref linkend="ref-actions"/></member>
    <member>Sanewall Manual: sanewall-manual.pdf</member>
    <member><ulink url="http://www.sanewall.org/">Sanewall Online Documentation</ulink></member>
  </simplelist>
</refsect1>

</refentry>
