"Fossies" - the Fresh Open Source Software Archive

Member "shorewall-docs-xml-5.2.8/manpages/shorewall-snat.xml" (24 Sep 2020, 35789 Bytes) of package /linux/misc/shorewall/shorewall-docs-xml-5.2.8.tar.bz2:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0" encoding="UTF-8"?>
    2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
    3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
    4 <refentry>
    5   <refmeta>
    6     <refentrytitle>shorewall-snat</refentrytitle>
    7 
    8     <manvolnum>5</manvolnum>
    9 
   10     <refmiscinfo>Configuration Files</refmiscinfo>
   11   </refmeta>
   12 
   13   <refnamediv>
   14     <refname>snat</refname>
   15 
   16     <refpurpose>Shorewall SNAT/Masquerade definition file</refpurpose>
   17   </refnamediv>
   18 
   19   <refsynopsisdiv>
   20     <cmdsynopsis>
   21       <command>/etc/shorewall[6]/snat</command>
   22     </cmdsynopsis>
   23   </refsynopsisdiv>
   24 
   25   <refsect1>
   26     <title>Description</title>
   27 
   28     <para>This file is used to define dynamic NAT (Masquerading) and to define
   29     Source NAT (SNAT). It superseded <ulink
   30     url="shorewall-masq.html">shorewall-masq</ulink>(5) in Shorewall
   31     5.0.14.</para>
   32 
   33     <warning>
   34       <para>The entries in this file are order-sensitive. The first entry that
   35       matches a particular connection will be the one that is used.</para>
   36     </warning>
   37 
   38     <warning>
   39       <para>If you have more than one ISP link, adding entries to this file
   40       will <emphasis role="bold">not</emphasis> force connections to go out
   41       through a particular link. You must use entries in <ulink
   42       url="shorewall-rtrules.html">shorewall-rtrules</ulink>(5) or PREROUTING
   43       entries in <ulink
   44       url="shorewall-mangle.html">shorewall-mangle</ulink>(5) to do
   45       that.</para>
   46     </warning>
   47 
   48     <para>Beginning with Shorewall 5.2.6, the snat file supports two different
   49     formats:</para>
   50 
   51     <orderedlist>
   52       <listitem>
   53         <para>The SPORT (source port) column is omitted. This is the default
   54         unless a "?FORMAT 2" compiler directive is included.</para>
   55       </listitem>
   56 
   57       <listitem>
   58         <para>The SPORT column immediately follows the DPORT column.</para>
   59       </listitem>
   60     </orderedlist>
   61 
   62     <para>The columns in the file are as follows.</para>
   63 
   64     <variablelist>
   65       <varlistentry>
   66         <term><emphasis role="bold">ACTION</emphasis></term>
   67 
   68         <listitem>
   69           <para>Defines the type of rule to generate. Beginning with Shorewall
   70           5.1.9, with the exception of NFLOG and ULOG, the action may be
   71           followed by a colon (":") and a <replaceable>log level</replaceable>
   72           (see <ulink
   73           url="shorewall-logging.html">shorewall-logging(5)</ulink>).</para>
   74 
   75           <para>Choices for ACTION are:</para>
   76 
   77           <variablelist>
   78             <varlistentry>
   79               <term><emphasis
   80               role="bold"><replaceable>action</replaceable></emphasis>[+][(<replaceable>parameter</replaceable>,...)][:<replaceable>level</replaceable>]</term>
   81 
   82               <listitem>
   83                 <para>where <replaceable>action</replaceable> is an action
   84                 declared in <ulink
   85                 url="shorewall-actions.html">shorewall-actions(5)</ulink> with
   86                 the <option>nat</option> option. See <ulink
   87                 url="../Actions.html">https://shorewall.org/Actions.html</ulink>
   88                 for further information.</para>
   89               </listitem>
   90             </varlistentry>
   91 
   92             <varlistentry>
   93               <term><emphasis
   94               role="bold">CONTINUE</emphasis>[+]:<replaceable>level</replaceable></term>
   95 
   96               <listitem>
   97                 <para>Causes matching packets to be exempted from any
   98                 following rules in the file.</para>
   99               </listitem>
  100             </varlistentry>
  101 
  102             <varlistentry>
  103               <term><emphasis
  104               role="bold">LOG:<replaceable>level</replaceable></emphasis></term>
  105 
  106               <listitem>
  107                 <para>Added in Shorewall 5.1.9. Simply log the packet and
  108                 continue with the next rule.</para>
  109               </listitem>
  110             </varlistentry>
  111 
  112             <varlistentry>
  113               <term><emphasis
  114               role="bold">MASQUERADE[+]</emphasis>[([<replaceable>lowport</replaceable>[-<replaceable>highport</replaceable>]][<option>random</option>])][:<replaceable>level</replaceable>]</term>
  115 
  116               <listitem>
  117                 <para>Causes matching outgoing packages to have their source
  118                 IP address set to the primary IP address of the interface
  119                 specified in the DEST column. if
  120                 <replaceable>lowport</replaceable>-<replaceable>highport</replaceable>
  121                 is given, that port range will be used to assign a source
  122                 port. If only <replaceable>lowport</replaceable> is given,
  123                 that port will be assigned, if possible. If option
  124                 <option>random</option> is used then port mapping will be
  125                 randomized. MASQUERADE should only be used when the DEST
  126                 interface has a dynamic IP address. Otherwise, SNAT should be
  127                 used and should specify the interface's static address.</para>
  128               </listitem>
  129             </varlistentry>
  130 
  131             <varlistentry>
  132               <term><emphasis
  133               role="bold">NFLOG</emphasis>[(<replaceable>nflog-parameters</replaceable>)]</term>
  134 
  135               <listitem>
  136                 <para>Added in Shorewall 5.1.9. Queues matching packets to a
  137                 back end logging daemon via a netlink socket then continues to
  138                 the next rule. See <ulink
  139                 url="shorewall-logging.html">shorewall-logging(5)</ulink>.</para>
  140 
  141                 <para>The <replaceable>nflog-parameters</replaceable> are a
  142                 comma-separated list of up to 3 numbers:</para>
  143 
  144                 <itemizedlist>
  145                   <listitem>
  146                     <para>The first number specifies the netlink group
  147                     (0-65535). If omitted (e.g., NFLOG(,0,10)) then a value of
  148                     0 is assumed.</para>
  149                   </listitem>
  150 
  151                   <listitem>
  152                     <para>The second number specifies the maximum number of
  153                     bytes to copy. If omitted, 0 (no limit) is assumed.</para>
  154                   </listitem>
  155 
  156                   <listitem>
  157                     <para>The third number specifies the number of log
  158                     messages that should be buffered in the kernel before they
  159                     are sent to user space. The default is 1.</para>
  160                   </listitem>
  161                 </itemizedlist>
  162 
  163                 <para>NFLOG is similar to<emphasis role="bold">
  164                 LOG:NFLOG</emphasis>[(<replaceable>nflog-parameters</replaceable>)],
  165                 except that the log level is not changed when this ACTION is
  166                 used in an action or macro body and the invocation of that
  167                 action or macro specifies a log level.</para>
  168               </listitem>
  169             </varlistentry>
  170 
  171             <varlistentry>
  172               <term><emphasis
  173               role="bold">SNAT[+]</emphasis>([<emphasis>address-or-address-range</emphasis>][:<emphasis>lowport</emphasis><emphasis
  174               role="bold">[-</emphasis><emphasis>highport</emphasis>]][<emphasis
  175               role="bold">:random</emphasis>][:<option>persistent</option>]|<emphasis
  176               role="bold">detect</emphasis>)[:<replaceable>level</replaceable>]</term>
  177 
  178               <listitem>
  179                 <para>If you specify an address here, matching packets will
  180                 have their source address set to that address. If
  181                 ADD_SNAT_ALIASES is set to Yes or yes in <ulink
  182                 url="shorewall.conf.html">shorewall.conf</ulink>(5) then
  183                 Shorewall will automatically add this address to the INTERFACE
  184                 named in the first column (IPv4 only).</para>
  185 
  186                 <para>You may also specify a range of up to 256 IP addresses
  187                 if you want the SNAT address to be assigned from that range in
  188                 a round-robin fashion by connection. The range is specified by
  189                 <emphasis>first.ip.in.range</emphasis>-<emphasis>last.ip.in.range</emphasis>.
  190                 You may follow the port range with<emphasis role="bold">
  191                 :random</emphasis> in which case assignment of ports from the
  192                 list will be random. <emphasis role="bold">random</emphasis>
  193                 may also be specified by itself in this column in which case
  194                 random local port assignments are made for the outgoing
  195                 connections.</para>
  196 
  197                 <para>Example: 206.124.146.177-206.124.146.180</para>
  198 
  199                 <para>You may follow the port range (or <emphasis
  200                 role="bold">:random</emphasis>) with <emphasis
  201                 role="bold">:persistent</emphasis>. This is only useful when
  202                 an address range is specified and causes a client to be given
  203                 the same source/destination IP pair.</para>
  204 
  205                 <para>You may also use the special value
  206                 <option>detect</option> which causes Shorewall to determine
  207                 the IP addresses configured on the interface named in the DEST
  208                 column and substitute them in this column.</para>
  209 
  210                 <para>DNS Names names are not allowed.</para>
  211 
  212                 <para>Normally, Netfilter will attempt to retain the source
  213                 port number. You may cause netfilter to remap the source port
  214                 by following an address or range (if any) by ":" and a port
  215                 range with the format
  216                 <emphasis>lowport</emphasis>-<emphasis>highport</emphasis>. If
  217                 this is done, you must specify "tcp", "udp", "dccp" or "stcp"
  218                 in the PROTO column.</para>
  219 
  220                 <para>Examples:</para>
  221 
  222                 <programlisting>        192.0.2.4:5000-6000
  223         :4000-5000</programlisting>
  224 
  225                 <para>You may also specify a single port number, which will be
  226                 assigned to the outgoing connection, if possible.</para>
  227               </listitem>
  228             </varlistentry>
  229 
  230             <varlistentry>
  231               <term><emphasis
  232               role="bold">ULOG</emphasis>[(<replaceable>ulog-parameters</replaceable>)]</term>
  233 
  234               <listitem>
  235                 <para>IPv4 only. Added in Shorewall 5.1.9. Queues matching
  236                 packets to a back end logging daemon via a netlink socket then
  237                 continues to the next rule. See <ulink
  238                 url="shorewall-logging.html">shorewall-logging(5)</ulink>.</para>
  239 
  240                 <para>Similar to<emphasis role="bold">
  241                 LOG:ULOG</emphasis>[(<replaceable>ulog-parameters</replaceable>)],
  242                 except that the log level is not changed when this ACTION is
  243                 used in an action or macro body and the invocation of that
  244                 action or macro specifies a log level.</para>
  245               </listitem>
  246             </varlistentry>
  247           </variablelist>
  248 
  249           <para>Normally Masq/SNAT rules are evaluated after those for
  250           one-to-one NAT (defined in <ulink
  251           url="shorewall-nat.html">shorewall-nat</ulink>(5)). If you want the
  252           rule to be applied before one-to-one NAT rules, follow the action
  253           name with "+": This feature should only be required if you need to
  254           insert rules in this file that preempt entries in <ulink
  255           url="shorewall-nat.html">shorewall-nat</ulink>(5).</para>
  256         </listitem>
  257       </varlistentry>
  258 
  259       <varlistentry>
  260         <term><emphasis role="bold">SOURCE</emphasis> (Optional) -
  261         [<emphasis>interface</emphasis>|<emphasis>address</emphasis>[<emphasis
  262         role="bold">,</emphasis><emphasis>address</emphasis>...][<emphasis>exclusion</emphasis>]]</term>
  263 
  264         <listitem>
  265           <para>Set of hosts that you wish to masquerade. You can specify this
  266           as an <emphasis>address</emphasis> (net or host) or as an
  267           <emphasis>interface</emphasis>. Unless you want to perform SNAT in
  268           the INPUT chain (see DEST below), if you give the name of an
  269           interface (deprecated), the interface must be up before you start
  270           the firewall and the Shorewall rules compiler will warn you of that
  271           fact. (Shorewall will use your main routing table to determine the
  272           appropriate addresses to masquerade).</para>
  273 
  274           <para>The preferred way to specify the SOURCE is to supply one or
  275           more host or network addresses separated by comma. You may use ipset
  276           names preceded by a plus sign (+) to specify a set of hosts.</para>
  277         </listitem>
  278       </varlistentry>
  279 
  280       <varlistentry>
  281         <term><emphasis role="bold">DEST</emphasis> -
  282         {<emphasis>interface</emphasis>[<emphasis
  283         role="bold">:</emphasis><emphasis>digit][,</emphasis><emphasis>interface</emphasis>[<emphasis
  284         role="bold">:</emphasis><emphasis>digit</emphasis>]]...|$FW}[<emphasis
  285         role="bold">:</emphasis>[<emphasis>dest-address</emphasis>[<emphasis
  286         role="bold">,</emphasis><emphasis>dest-address</emphasis>]...[<emphasis>exclusion</emphasis>]]</term>
  287 
  288         <listitem>
  289           <para>Outgoing <emphasis>interface</emphasis>s and destination
  290           networks. Multiple interfaces may be listed when the ACTION is
  291           MASQUERADE, but this is usually just your internet interface. If
  292           ADD_SNAT_ALIASES=Yes in <ulink
  293           url="shorewall.conf.html">shorewall.conf</ulink>(5), you may add ":"
  294           and a <emphasis>digit</emphasis> to indicate that you want the alias
  295           added with that name (e.g., eth0:0). This will allow the alias to be
  296           displayed with ifconfig. <emphasis role="bold">That is the only use
  297           for the alias name; it may not appear in any other place in your
  298           Shorewall configuration.</emphasis></para>
  299 
  300           <para>Beginning with Shorewall 5.1.12, SNAT may be performed in the
  301           nat table's INPUT chain by specifying $FW rather than one or more
  302           interfaces.</para>
  303 
  304           <para>Each interface must match an entry in <ulink
  305           url="shorewall-interfaces.html">shorewall-interfaces</ulink>(5).
  306           Shorewall allows loose matches to wildcard entries in <ulink
  307           url="shorewall-interfaces.html">shorewall-interfaces</ulink>(5). For
  308           example, <filename class="devicefile">ppp0</filename> in this file
  309           will match a <ulink
  310           url="shorewall-interfaces.html">shorewall-interfaces</ulink>(5)
  311           entry that defines <filename
  312           class="devicefile">ppp+</filename>.</para>
  313 
  314           <para>Where <ulink url="../4.4/MultiISP.html#Shared">more that one
  315           internet provider share a single interface</ulink>, the provider is
  316           specified by including the provider name or number in
  317           parentheses:</para>
  318 
  319           <programlisting>        eth0(Avvanta)</programlisting>
  320 
  321           <para>In that case, you will want to specify the interface's address
  322           for that provider as the SNAT parameter.</para>
  323 
  324           <para>The interface may be qualified by adding the character ":"
  325           followed by a comma-separated list of destination host or subnet
  326           addresses to indicate that you only want to change the source IP
  327           address for packets being sent to those particular destinations.
  328           Exclusion is allowed (see <ulink
  329           url="shorewall-exclusion.html">shorewall-exclusion</ulink>(5)) as
  330           are ipset names preceded by a plus sign '+';</para>
  331 
  332           <para>If you wish to inhibit the action of ADD_SNAT_ALIASES for this
  333           entry then include the ":" but omit the digit:</para>
  334 
  335           <programlisting>        eth0(Avvanta):
  336         eth2::192.0.2.32/27</programlisting>
  337 
  338           <para>Comments may be attached to Netfilter rules generated from
  339           entries in this file through the use of ?COMMENT lines. These lines
  340           begin with ?COMMENT; the remainder of the line is treated as a
  341           comment which is attached to subsequent rules until another ?COMMENT
  342           line is found or until the end of the file is reached. To stop
  343           adding comments to rules, use a line containing only
  344           ?COMMENT.</para>
  345         </listitem>
  346       </varlistentry>
  347 
  348       <varlistentry>
  349         <term><emphasis role="bold">PROTO</emphasis> (Optional) - {<emphasis
  350         role="bold">-</emphasis>|[!]{<emphasis>protocol-name</emphasis>|<emphasis>protocol-number</emphasis>}[,...]|+<replaceable>ipset</replaceable>}</term>
  351 
  352         <listitem>
  353           <para>If you wish to restrict this entry to a particular protocol
  354           then enter the protocol name (from protocols(5)) or number here. See
  355           <ulink url="shorewall-rules.html">shorewall-rules(5)</ulink> for
  356           details.</para>
  357 
  358           <para>Beginning with Shorewall 4.5.12, this column can accept a
  359           comma-separated list of protocols.</para>
  360 
  361           <para>Beginning with Shorewall 4.6.0, an
  362           <replaceable>ipset</replaceable> name can be specified in this
  363           column. This is intended to be used with
  364           <firstterm>bitmap:port</firstterm> ipsets.</para>
  365         </listitem>
  366       </varlistentry>
  367 
  368       <varlistentry>
  369         <term><emphasis role="bold">{PORT|DPORT}</emphasis> (Optional) -
  370         {-|[!]<emphasis>port-name-or-number</emphasis>[,<emphasis>port-name-or-number</emphasis>]...|+<replaceable>ipset</replaceable>}</term>
  371 
  372         <listitem>
  373           <para>The column was renamed to DPORT in Shorewall 5.2.6. Beginning
  374           with that release, both PORT and DPORT are accepted in the
  375           alternative input format,</para>
  376 
  377           <para>If the PROTO column specifies TCP (6), UDP (17), DCCP (33),
  378           SCTP (132) or UDPLITE (136) then you may list one or more port
  379           numbers (or names from services(5)) or port ranges separated by
  380           commas.</para>
  381 
  382           <para>Port ranges are of the form
  383           <emphasis>lowport</emphasis>:<emphasis>highport</emphasis>.</para>
  384 
  385           <para>Beginning with Shorewall 4.6.0, an
  386           <replaceable>ipset</replaceable> name can be specified in this
  387           column. This is intended to be used with
  388           <firstterm>bitmap:port</firstterm> ipsets.</para>
  389         </listitem>
  390       </varlistentry>
  391 
  392       <varlistentry>
  393         <term><emphasis role="bold">SPORT
  394         {-|[!]<replaceable>port-name-or-number</replaceable>[,<replaceable>port-name-or-number</replaceable>]...|+<replaceable>ipset</replaceable>}</emphasis></term>
  395 
  396         <listitem>
  397           <para>FORMAT 2 only.</para>
  398 
  399           <para>If the PROTO column specifies TCP (6), UDP (17), DCCP (33),
  400           SCTP (132) or UDPLITE (136) then you may list one or more port
  401           numbers (or names from services(5)) or port ranges separated by
  402           commas.</para>
  403 
  404           <para>Port ranges are of the form
  405           <emphasis>lowport</emphasis>:<emphasis>highport</emphasis>.</para>
  406 
  407           <para>An <replaceable>ipset</replaceable> name can be specified in
  408           this column. This is intended to be used with
  409           <firstterm>bitmap:port</firstterm> ipsets.</para>
  410         </listitem>
  411       </varlistentry>
  412 
  413       <varlistentry>
  414         <term><emphasis role="bold">IPSEC</emphasis> (Optional) -
  415         [<emphasis>option</emphasis>[<emphasis
  416         role="bold">,</emphasis><emphasis>option</emphasis>]...]</term>
  417 
  418         <listitem>
  419           <para>If you specify a value other than "-" in this column, you must
  420           be running kernel 2.6 and your kernel and iptables must include
  421           policy match support.</para>
  422 
  423           <para>Comma-separated list of options from the following. Only
  424           packets that will be encrypted via an SA that matches these options
  425           will have their source address changed.</para>
  426 
  427           <variablelist>
  428             <varlistentry>
  429               <term><emphasis
  430               role="bold">reqid=</emphasis><emphasis>number</emphasis></term>
  431 
  432               <listitem>
  433                 <para>where <emphasis>number</emphasis> is specified using
  434                 setkey(8) using the 'unique:<emphasis>number</emphasis> option
  435                 for the SPD level.</para>
  436               </listitem>
  437             </varlistentry>
  438 
  439             <varlistentry>
  440               <term><emphasis role="bold">spi=</emphasis>&lt;number&gt;</term>
  441 
  442               <listitem>
  443                 <para>where <emphasis>number</emphasis> is the SPI of the SA
  444                 used to encrypt/decrypt packets.</para>
  445               </listitem>
  446             </varlistentry>
  447 
  448             <varlistentry>
  449               <term><emphasis role="bold">proto=</emphasis><emphasis
  450               role="bold">ah</emphasis>|<emphasis
  451               role="bold">esp</emphasis>|<emphasis
  452               role="bold">ipcomp</emphasis></term>
  453 
  454               <listitem>
  455                 <para>IPSEC Encapsulation Protocol</para>
  456               </listitem>
  457             </varlistentry>
  458 
  459             <varlistentry>
  460               <term><emphasis
  461               role="bold">mss=</emphasis><emphasis>number</emphasis></term>
  462 
  463               <listitem>
  464                 <para>sets the MSS field in TCP packets</para>
  465               </listitem>
  466             </varlistentry>
  467 
  468             <varlistentry>
  469               <term><emphasis role="bold">mode=</emphasis><emphasis
  470               role="bold">transport</emphasis>|<emphasis
  471               role="bold">tunnel</emphasis></term>
  472 
  473               <listitem>
  474                 <para>IPSEC mode</para>
  475               </listitem>
  476             </varlistentry>
  477 
  478             <varlistentry>
  479               <term><emphasis
  480               role="bold">tunnel-src=</emphasis><emphasis>address</emphasis>[/<emphasis>mask</emphasis>]</term>
  481 
  482               <listitem>
  483                 <para>only available with mode=tunnel</para>
  484               </listitem>
  485             </varlistentry>
  486 
  487             <varlistentry>
  488               <term><emphasis
  489               role="bold">tunnel-dst=</emphasis><emphasis>address</emphasis>[/<emphasis>mask</emphasis>]</term>
  490 
  491               <listitem>
  492                 <para>only available with mode=tunnel</para>
  493               </listitem>
  494             </varlistentry>
  495 
  496             <varlistentry>
  497               <term><emphasis role="bold">strict</emphasis></term>
  498 
  499               <listitem>
  500                 <para>Means that packets must match all rules.</para>
  501               </listitem>
  502             </varlistentry>
  503 
  504             <varlistentry>
  505               <term><emphasis role="bold">next</emphasis></term>
  506 
  507               <listitem>
  508                 <para>Separates rules; can only be used with strict</para>
  509               </listitem>
  510             </varlistentry>
  511 
  512             <varlistentry>
  513               <term><emphasis role="bold">yes</emphasis></term>
  514 
  515               <listitem>
  516                 <para>When used by itself, causes all traffic that will be
  517                 encrypted/encapsulated to match the rule.</para>
  518               </listitem>
  519             </varlistentry>
  520           </variablelist>
  521         </listitem>
  522       </varlistentry>
  523 
  524       <varlistentry>
  525         <term><emphasis role="bold">MARK</emphasis> - [<emphasis
  526         role="bold">!</emphasis>]<emphasis>value</emphasis>[/<emphasis>mask</emphasis>][<emphasis
  527         role="bold">:C</emphasis>]</term>
  528 
  529         <listitem>
  530           <para>Defines a test on the existing packet or connection mark. The
  531           rule will match only if the test returns true.</para>
  532 
  533           <para>If you don't want to define a test but need to specify
  534           anything in the following columns, place a "-" in this field.</para>
  535 
  536           <variablelist>
  537             <varlistentry>
  538               <term>!</term>
  539 
  540               <listitem>
  541                 <para>Inverts the test (not equal)</para>
  542               </listitem>
  543             </varlistentry>
  544 
  545             <varlistentry>
  546               <term><emphasis>value</emphasis></term>
  547 
  548               <listitem>
  549                 <para>Value of the packet or connection mark.</para>
  550               </listitem>
  551             </varlistentry>
  552 
  553             <varlistentry>
  554               <term><emphasis>mask</emphasis></term>
  555 
  556               <listitem>
  557                 <para>A mask to be applied to the mark before testing.</para>
  558               </listitem>
  559             </varlistentry>
  560 
  561             <varlistentry>
  562               <term><emphasis role="bold">:C</emphasis></term>
  563 
  564               <listitem>
  565                 <para>Designates a connection mark. If omitted, the packet
  566                 mark's value is tested.</para>
  567               </listitem>
  568             </varlistentry>
  569           </variablelist>
  570         </listitem>
  571       </varlistentry>
  572 
  573       <varlistentry>
  574         <term><emphasis role="bold">USER</emphasis> (Optional) - [<emphasis
  575         role="bold">!</emphasis>][<emphasis>user-name-or-number</emphasis>][<emphasis
  576         role="bold">:</emphasis><emphasis>group-name-or-number</emphasis>][<emphasis
  577         role="bold">+</emphasis><emphasis>program-name</emphasis>]</term>
  578 
  579         <listitem>
  580           <para>This column was formerly labelled USER/GROUP.</para>
  581 
  582           <para>Only locally-generated connections will match if this column
  583           is non-empty.</para>
  584 
  585           <para>When this column is non-empty, the rule matches only if the
  586           program generating the output is running under the effective
  587           <emphasis>user</emphasis> and/or <emphasis>group</emphasis>
  588           specified (or is NOT running under that id if "!" is given).</para>
  589 
  590           <para>Examples:</para>
  591 
  592           <variablelist>
  593             <varlistentry>
  594               <term>joe</term>
  595 
  596               <listitem>
  597                 <para>program must be run by joe</para>
  598               </listitem>
  599             </varlistentry>
  600 
  601             <varlistentry>
  602               <term>:kids</term>
  603 
  604               <listitem>
  605                 <para>program must be run by a member of the 'kids'
  606                 group</para>
  607               </listitem>
  608             </varlistentry>
  609 
  610             <varlistentry>
  611               <term>!:kids</term>
  612 
  613               <listitem>
  614                 <para>program must not be run by a member of the 'kids'
  615                 group</para>
  616               </listitem>
  617             </varlistentry>
  618 
  619             <varlistentry>
  620               <term>+upnpd</term>
  621 
  622               <listitem>
  623                 <para>#program named upnpd</para>
  624 
  625                 <important>
  626                   <para>The ability to specify a program name was removed from
  627                   Netfilter in kernel version 2.6.14.</para>
  628                 </important>
  629               </listitem>
  630             </varlistentry>
  631           </variablelist>
  632         </listitem>
  633       </varlistentry>
  634 
  635       <varlistentry>
  636         <term><emphasis role="bold">SWITCH -
  637         [!]<replaceable>switch-name</replaceable>[={0|1}]</emphasis></term>
  638 
  639         <listitem>
  640           <para>Added in Shorewall 4.5.1 and allows enabling and disabling the
  641           rule without requiring <command>shorewall restart</command>.</para>
  642 
  643           <para>The rule is enabled if the value stored in
  644           <filename>/proc/net/nf_condition/<replaceable>switch-name</replaceable></filename>
  645           is 1. The rule is disabled if that file contains 0 (the default). If
  646           '!' is supplied, the test is inverted such that the rule is enabled
  647           if the file contains 0.</para>
  648 
  649           <para>Within the <replaceable>switch-name</replaceable>, '@0' and
  650           '@{0}' are replaced by the name of the chain to which the rule is a
  651           added. The <replaceable>switch-name</replaceable> (after '@...'
  652           expansion) must begin with a letter and be composed of letters,
  653           decimal digits, underscores or hyphens. Switch names must be 30
  654           characters or less in length.</para>
  655 
  656           <para>Switches are normally <emphasis role="bold">off</emphasis>. To
  657           turn a switch <emphasis role="bold">on</emphasis>:</para>
  658 
  659           <simplelist>
  660             <member><command>echo 1 &gt;
  661             /proc/net/nf_condition/<replaceable>switch-name</replaceable></command></member>
  662           </simplelist>
  663 
  664           <para>To turn it <emphasis role="bold">off</emphasis> again:</para>
  665 
  666           <simplelist>
  667             <member><command>echo 0 &gt;
  668             /proc/net/nf_condition/<replaceable>switch-name</replaceable></command></member>
  669           </simplelist>
  670 
  671           <para>Switch settings are retained over <command>shorewall
  672           restart</command>.</para>
  673 
  674           <para>Beginning with Shorewall 4.5.10, when the
  675           <replaceable>switch-name</replaceable> is followed by
  676           <option>=0</option> or <option>=1</option>, then the switch is
  677           initialized to off or on respectively by the
  678           <command>start</command> command. Other commands do not affect the
  679           switch setting.</para>
  680         </listitem>
  681       </varlistentry>
  682 
  683       <varlistentry>
  684         <term><emphasis role="bold">ORIGDEST</emphasis> - [<emphasis
  685         role="bold">-</emphasis>|<emphasis>address</emphasis>[,<emphasis>address</emphasis>]...[<emphasis>exclusion</emphasis>]|<emphasis>exclusion</emphasis>]</term>
  686 
  687         <listitem>
  688           <para>(Optional) Added in Shorewall 4.5.6. This column may be
  689           included and may contain one or more addresses (host or network)
  690           separated by commas. Address ranges are not allowed. When this
  691           column is supplied, rules are generated that require that the
  692           original destination address matches one of the listed addresses. It
  693           is useful for specifying that SNAT should occur only for connections
  694           that were acted on by a DNAT when they entered the firewall.</para>
  695 
  696           <para>This column was formerly labelled ORIGINAL DEST.</para>
  697         </listitem>
  698       </varlistentry>
  699 
  700       <varlistentry>
  701         <term><emphasis role="bold">PROBABILITY</emphasis> -
  702         [<replaceable>probability</replaceable>]</term>
  703 
  704         <listitem>
  705           <para>Added in Shorewall 5.0.0. When non-empty, requires the
  706           <firstterm>Statistics Match</firstterm> capability in your kernel
  707           and ip6tables and causes the rule to match randomly but with the
  708           given <replaceable>probability</replaceable>. The
  709           <replaceable>probability</replaceable> is a number 0 &lt;
  710           <replaceable>probability</replaceable> &lt;= 1 and may be expressed
  711           at up to 8 decimal points of precision.</para>
  712         </listitem>
  713       </varlistentry>
  714     </variablelist>
  715   </refsect1>
  716 
  717   <refsect1>
  718     <title>Examples</title>
  719 
  720     <variablelist>
  721       <varlistentry>
  722         <term>IPv4 Example 1:</term>
  723 
  724         <listitem>
  725           <para>You have a simple masquerading setup where eth0 connects to a
  726           DSL or cable modem and eth1 connects to your local network with
  727           subnet 192.168.0.0/24.</para>
  728 
  729           <para>Your entry in the file will be:</para>
  730 
  731           <programlisting>        #ACTION    SOURCE              DEST
  732         MASQUERADE 192.168.0.0/24      eth0</programlisting>
  733         </listitem>
  734       </varlistentry>
  735 
  736       <varlistentry>
  737         <term>IPv4 Example 2:</term>
  738 
  739         <listitem>
  740           <para>You add a router to your local network to connect subnet
  741           192.168.1.0/24 which you also want to masquerade. You then add a
  742           second entry for eth0 to this file:</para>
  743 
  744           <programlisting>        #ACTION    SOURCE              DEST
  745         MASQUERADE 192.168.0.0/24      eth0
  746         MASQUERADE 192.168.1.0/24      eth0</programlisting>
  747         </listitem>
  748       </varlistentry>
  749 
  750       <varlistentry>
  751         <term>IPv4 Example 3:</term>
  752 
  753         <listitem>
  754           <para>You want all outgoing traffic from 192.168.1.0/24 through eth0
  755           to use source address 206.124.146.176 which is NOT the primary
  756           address of eth0. You want 206.124.146.176 to be added to eth0 with
  757           name eth0:0.</para>
  758 
  759           <programlisting>        #ACTION                 SOURCE          DEST
  760         SNAT(206.124.146.176)   192.168.1.0/24  eth0:0</programlisting>
  761         </listitem>
  762       </varlistentry>
  763 
  764       <varlistentry>
  765         <term>IPv4 Example 4:</term>
  766 
  767         <listitem>
  768           <para>You want all outgoing SMTP traffic entering the firewall from
  769           172.20.1.0/29 to be sent from eth0 with source IP address
  770           206.124.146.177. You want all other outgoing traffic from
  771           172.20.1.0/29 to be sent from eth0 with source IP address
  772           206.124.146.176.</para>
  773 
  774           <programlisting>        #INTERFACE   SOURCE           ADDRESS         PROTO   DPORT
  775         eth0         172.20.1.0/29    206.124.146.177 tcp     smtp
  776         eth0         172.20.1.0/29    206.124.146.176</programlisting>
  777 
  778           <programlisting>        #ACTION                 SOURCE          DEST        PROTO     PORT
  779         SNAT(206.124.146.177)   172.20.1.0/29   eth0        tcp       smtp
  780         SNAT(206.124.146.176)   172.20.1.0/29   eth0</programlisting>
  781 
  782           <warning>
  783             <para>The order of the above two rules is significant!</para>
  784           </warning>
  785         </listitem>
  786       </varlistentry>
  787 
  788       <varlistentry>
  789         <term>IPv4 Example 5:</term>
  790 
  791         <listitem>
  792           <para>Connections leaving on eth0 and destined to any host defined
  793           in the ipset <emphasis>myset</emphasis> should have the source IP
  794           address changed to 206.124.146.177.</para>
  795 
  796           <programlisting>        #ACTION                 SOURCE          DEST
  797         SNAT(206.124.146.177)   -               eth0:+myset[dst]</programlisting>
  798         </listitem>
  799       </varlistentry>
  800 
  801       <varlistentry>
  802         <term>IPv4 Example 6:</term>
  803 
  804         <listitem>
  805           <para>SNAT outgoing connections on eth0 from 192.168.1.0/24 randomly
  806           to addresses 1.1.1.1, 1.1.1.3, and 1.1.1.9 (Shorewall 5.0.0 and
  807           later).</para>
  808 
  809           <programlisting>/etc/shorewall/snat:
  810 
  811        #ACTION                 SOURCE          DEST
  812        SNAT(1.1.1.1)           192.168.1.0/24  eth0  { probability=0.33 }
  813        SNAT(1.1.1.3)           192.168.1.0/24  eth0  { probability=0.50 }
  814        SNAT(1.1.1.9)           192.168.1.0/24  eth0</programlisting>
  815         </listitem>
  816       </varlistentry>
  817 
  818       <varlistentry>
  819         <term>IPv6 Example 1:</term>
  820 
  821         <listitem>
  822           <para>You have a simple 'masquerading' setup where eth0 connects to
  823           a DSL or cable modem and eth1 connects to your local network with
  824           subnet 2001:470:b:787::0/64</para>
  825 
  826           <para>Your entry in the file will be:</para>
  827 
  828           <programlisting>        #ACTION      SOURCE                  DEST
  829         MASQUERADE   2001:470:b:787::0/64    eth0</programlisting>
  830         </listitem>
  831       </varlistentry>
  832 
  833       <varlistentry>
  834         <term>IPv6 Example 2:</term>
  835 
  836         <listitem>
  837           <para>Your sit1 interface has two public IP addresses:
  838           2001:470:a:227::1 and 2001:470:b:227::1. You want to use the
  839           iptables statistics match to masquerade outgoing connections evenly
  840           between these two addresses.</para>
  841 
  842           <programlisting>/etc/shorewall/snat:
  843 
  844        #ACTION                      SOURCE     DEST
  845        SNAT(2001:470:a:227::1)      ::/0       sit1              { probability=0.50 }
  846        SNAT(2001:470:a:227::2)      ::/0       sit</programlisting>
  847         </listitem>
  848       </varlistentry>
  849     </variablelist>
  850   </refsect1>
  851 
  852   <refsect1>
  853     <title>FILES</title>
  854 
  855     <para>/etc/shorewall/snat</para>
  856 
  857     <para>/etc/shorewall6/snat</para>
  858   </refsect1>
  859 
  860   <refsect1>
  861     <title>See ALSO</title>
  862 
  863     <para><ulink
  864     url="../configuration_file_basics.htm#Pairs">https://shorewall.org/configuration_file_basics.htm#Pairs</ulink></para>
  865 
  866     <para>shorewall(8)</para>
  867   </refsect1>
  868 </refentry>