<!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="helpconf-connmark">

<refmeta>
<refentrytitle>connmark config helper: sanewall-connmark</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>

<refnamediv>
<refdescriptor>sanewall-connmark</refdescriptor>
<refname>sanewall-connmark</refname>
<refpurpose>set a stateful mark on a connection</refpurpose>
</refnamediv>

<refsynopsisdiv>
  <cmdsynopsis>
    <command>connmark</command>
    <group choice="req">
       <arg choice="plain"><replaceable>value</replaceable></arg>
       <arg choice="plain">save</arg>
       <arg choice="plain">restore</arg>
    </group>
    <arg choice="plain"><replaceable>chain</replaceable></arg>
    <arg choice="opt"><replaceable>rule-params</replaceable></arg>
  </cmdsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
  <para>
    The <command>connmark</command> helper command sets a mark on a whole
    connection. It applies to both directions.
  </para>
  <note><para>
    To set a mark on packets matching particular rules, regardless of
    any connection, see <xref linkend="helpconf-mark"/>.
  </para></note>
  <para>
    The <replaceable>value</replaceable> is the mark value to set (a 32 bit
    integer). If you specify <option>save</option> then the mark on the
    matched packet will be turned into a connmark. If you specify
    <option>restore</option> then the matched packet will have its mark
    set to the current connmark.
  </para>
  <para>
    The <replaceable>chain</replaceable> will be used to find traffic to
    mark. It can be any of the <command>iptables</command> built in chains
    belonging to the <option>mangle</option> table. The chain names
    are: INPUT, FORWARD, OUTPUT, PREROUTING and POSTROUTING. The names are
    case-sensitive.
  </para>
  <para>
    The <option><replaceable>rule-params</replaceable></option> define
    a set of rule parameters to match the traffic that is to be marked
    within the chosen chain.
    See <xref linkend="rule-params"/> for more details.
  </para>
  <para>
    Any <command>connmark</command> commands will affect all traffic
    matched. They must be declared before the first router or interface.
  </para>
</refsect1>

<refsect1><title>Examples</title>
    <para>
      Consider a scenario with 3 ethernet ports, where eth0 is on the local
      LAN, eth1 connects to ISP 'A' and eth2 to ISP 'B'. To ensure traffic
      leaves via the same ISP as it arrives from you can mark the traffic:
    <programlisting># mark connections when they arrive from the ISPs
connmark 1 PREROUTING inface eth1
connmark 2 PREROUTING inface eth2

# restore the mark (from the connmark) when packets arrive from the LAN
connmark restore OUTPUT
connmark restore PREROUTING inface eth0
    </programlisting>
      It is then possible to use the commands from
      <application>iproute2</application> such as <command>ip</command>,
      to pick the correct routing table based on the mark on the packets.
    </para>
</refsect1>

<refsect1><title>See Also</title>
  <simplelist type="vert">
    <member><xref linkend="sanewall"/></member>
    <member><xref linkend="sanewall.conf"/></member>
    <member><xref linkend="helpconf-mark"/></member>
    <member>administration tool for IPv4 firewalls: iptables(8)</member>
    <member>show / manipulate routing, devices, policy routing and tunnels: ip(8)</member>
    <member><ulink url="http://www.lartc.org/lartc.html">Linux Advanced Routing &amp; Traffic Control HOWTO</ulink></member>
  </simplelist>
</refsect1>

</refentry>
