"Fossies" - the Fresh Open Source Software Archive

Member "shorewall-docs-xml-5.2.8/Shorewall-Lite.xml" (24 Sep 2020, 34196 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 article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
    3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
    4 <article>
    5   <!--$Id$-->
    6 
    7   <articleinfo>
    8     <title>Shorewall Lite</title>
    9 
   10     <authorgroup>
   11       <author>
   12         <firstname>Tom</firstname>
   13 
   14         <surname>Eastep</surname>
   15       </author>
   16     </authorgroup>
   17 
   18     <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
   19 
   20     <copyright>
   21       <year>2006-2011</year>
   22 
   23       <holder>Thomas M. Eastep</holder>
   24     </copyright>
   25 
   26     <legalnotice>
   27       <para>Permission is granted to copy, distribute and/or modify this
   28       document under the terms of the GNU Free Documentation License, Version
   29       1.2 or any later version published by the Free Software Foundation; with
   30       no Invariant Sections, with no Front-Cover, and with no Back-Cover
   31       Texts. A copy of the license is included in the section entitled
   32       <quote><ulink url="GnuCopyright.htm">GNU Free Documentation
   33       License</ulink></quote>.</para>
   34     </legalnotice>
   35   </articleinfo>
   36 
   37   <caution>
   38     <para><emphasis role="bold">This article applies to Shorewall 4.3 and
   39     later. If you are running a version of Shorewall earlier than Shorewall
   40     4.3.5 then please see the documentation appropriate for your
   41     version.</emphasis></para>
   42   </caution>
   43 
   44   <section id="Overview">
   45     <title>Overview</title>
   46 
   47     <para>Shorewall has the capability to compile a Shorewall configuration
   48     and produce a runnable firewall program script. The script is a complete
   49     program which can be placed on a system with <emphasis>Shorewall
   50     Lite</emphasis> installed and can serve as the firewall creation script
   51     for that system.</para>
   52 
   53     <section id="Lite">
   54       <title>Shorewall Lite</title>
   55 
   56       <para>Shorewall Lite is a companion product to Shorewall and is designed
   57       to allow you to maintain all Shorewall configuration information on a
   58       single system within your network.</para>
   59 
   60       <orderedlist numeration="loweralpha">
   61         <listitem>
   62           <para>You install the full Shorewall release on one system within
   63           your network. You need not configure Shorewall there and you may
   64           totally disable startup of Shorewall in your init scripts. For ease
   65           of reference, we call this system the 'administrative
   66           system'.</para>
   67 
   68           <para>The administrative system may be a GNU/Linux system, a Windows
   69           system running <ulink url="http://www.cygwin.com/">Cygwin</ulink> or
   70           an <ulink url="http://www.apple.com/mac/">Apple MacIntosh</ulink>
   71           running OS X. Install from a shell prompt <ulink
   72           url="Install.htm">using the install.sh script</ulink>.</para>
   73         </listitem>
   74 
   75         <listitem>
   76           <para>On each system where you wish to run a Shorewall-generated
   77           firewall, you install Shorewall Lite. For ease of reference, we will
   78           call these systems the 'firewall systems'.</para>
   79 
   80           <note>
   81             <para>The firewall systems do <emphasis role="bold">NOT</emphasis>
   82             need to have the full Shorewall product installed but rather only
   83             the Shorewall Lite product. Shorewall and Shorewall Lite may be
   84             installed on the same system but that isn't encouraged.</para>
   85           </note>
   86         </listitem>
   87 
   88         <listitem>
   89           <para>On the administrative system you create a separate 'export
   90           directory' for each firewall system. You copy the contents of
   91           <filename
   92           class="directory">/usr/share/shorewall/configfiles</filename> into
   93           each export directory.</para>
   94 
   95           <note>
   96             <para>Users of Debian and derivatives that install the package
   97             from their distribution will be disappointed to find that
   98             <filename
   99             class="directory">/usr/share/shorewall/configfiles</filename> does
  100             not exist on their systems. They will instead need to
  101             either:</para>
  102 
  103             <itemizedlist>
  104               <listitem>
  105                 <para>Copy the files in
  106                 /usr/share/doc/shorewall/default-config/ into each export
  107                 directory.</para>
  108               </listitem>
  109 
  110               <listitem>
  111                 <para>Copy /etc/shorewall/shorewall.conf into each export
  112                 directory and remove /etc/shorewall from the CONFIG_PATH
  113                 setting in the copied files.</para>
  114               </listitem>
  115             </itemizedlist>
  116 
  117             <para>or</para>
  118 
  119             <itemizedlist>
  120               <listitem>
  121                 <para>Download the Shorewall tarball corresponding to their
  122                 package version.</para>
  123               </listitem>
  124 
  125               <listitem>
  126                 <para>Untar and copy the files from the
  127                 <filename>configfiles</filename> sub-directory in the untarred
  128                 <filename>shorewall-...</filename> directory.</para>
  129               </listitem>
  130             </itemizedlist>
  131           </note>
  132 
  133           <para>After copying, you may need to change two setting in the copy
  134           of shorewall.conf:</para>
  135 
  136           <itemizedlist>
  137             <listitem>
  138               <para>CONFIG_PATH=/usr/share/shorewall</para>
  139             </listitem>
  140 
  141             <listitem>
  142               <para>STARTUP_LOG=/var/log/shorewall-lite-init.log</para>
  143             </listitem>
  144           </itemizedlist>
  145 
  146           <para>Older versions of Shorewall included copies of shorewall.conf
  147           with these settings already modified. This practice was discontinued
  148           in Shorewall 4.4.20.1.</para>
  149         </listitem>
  150 
  151         <listitem>
  152           <para>Prior to Shorewall 4.5.8, the
  153           <filename>/etc/shorewall/shorewall.conf</filename> file was used to
  154           determine the VERBOSITY setting which determines how much output the
  155           compiler generates. All other settings were taken from the
  156           <filename>shorewall.conf </filename>file in the remote systems
  157           export directory.</para>
  158 
  159           <caution>
  160             <para>Prior to Shorewall 4.5.8, if you want to be able to allow
  161             non-root users to manage remote firewall systems, then the files
  162             <filename>/etc/shorewall/params</filename> and
  163             <filename>/etc/shorewall/shorewall.conf</filename> must be
  164             readable by all users on the administrative system. Not all
  165             packages secure the files that way and you may have to change the
  166             file permissions yourself.</para>
  167 
  168             <para>Prior to Shorewall 4.5.14,
  169             <filename>/etc/shorewall/params</filename> must be readable by
  170             non-root users or each export directory must have its own params
  171             file.</para>
  172           </caution>
  173         </listitem>
  174 
  175         <listitem id="Debian">
  176           <para>On each firewall system, If you are running Debian or one of
  177           its derivatives like Ubuntu then edit
  178           <filename>/etc/default/shorewall-lite</filename> and set
  179           startup=1.</para>
  180         </listitem>
  181 
  182         <listitem>
  183           <para>On the administrative system, for each firewall system you do
  184           the following (this may be done by a non-root user who has root ssh
  185           access to the firewall system):</para>
  186 
  187           <orderedlist>
  188             <listitem>
  189               <para>modify the files in the corresponding export directory
  190               appropriately (i.e., <emphasis>just as you would if you were
  191               configuring Shorewall on the firewall system itself</emphasis>).
  192               It's a good idea to include the IP address of the administrative
  193               system in the <ulink
  194               url="manpages/shorewall-stoppedrules.html"><filename>stoppedrules</filename>
  195               file</ulink>.</para>
  196 
  197               <para>It is important to understand that with Shorewall Lite,
  198               the firewall's export directory on the administrative system
  199               acts as <filename class="directory">/etc/shorewall</filename>
  200               for that firewall. So when the Shorewall documentation gives
  201               instructions for placing entries in files in the firewall's
  202               <filename class="directory">/etc/shorewall</filename>, when
  203               using Shorewall Lite you make those changes in the firewall's
  204               export directory on the administrative system.</para>
  205 
  206               <para>The CONFIG_PATH variable is treated as follows:</para>
  207 
  208               <itemizedlist>
  209                 <listitem>
  210                   <para>The value of CONFIG_PATH in
  211                   <filename>/etc/shorewall/shorewall.conf</filename> is
  212                   ignored when compiling for export (the -e option in given)
  213                   and when the <command>load</command> or
  214                   <command>reload</command> command is being executed (see
  215                   below).</para>
  216                 </listitem>
  217 
  218                 <listitem>
  219                   <para>The value of CONFIG_PATH in the
  220                   <filename>shorewall.conf</filename> file in the export
  221                   directory is used to search for configuration files during
  222                   compilation of that configuration.</para>
  223                 </listitem>
  224 
  225                 <listitem>
  226                   <para>The value of CONFIG_PATH used when the script is run
  227                   on the firewall system is
  228                   "/etc/shorewall-lite:/usr/share/shorewall-lite".</para>
  229                 </listitem>
  230 
  231                 <listitem>
  232                   <para>Prior to Shorewall 4.5.14, the export directory should
  233                   contain a <filename>params</filename> file, even if it is
  234                   empty. Otherwise, <filename>/sbin/shorewall</filename> will
  235                   attempt to read<filename>
  236                   /etc/shorewall/params</filename>.</para>
  237                 </listitem>
  238 
  239                 <listitem>
  240                   <para>If the remote system has a different directory layout
  241                   from the administrative system, then the export directory
  242                   should contain a copy of the remote system's shorewallrc
  243                   file (normally found in
  244                   /usr/share/shorewall/shorewallrc).</para>
  245                 </listitem>
  246               </itemizedlist>
  247             </listitem>
  248 
  249             <listitem>
  250               <programlisting><command>cd &lt;export directory&gt;</command>
  251 <command>/sbin/shorewall remote-start firewall</command></programlisting>
  252 
  253               <para>The <ulink
  254               url="starting_and_stopping_shorewall.htm#Load"><command>remote-start</command></ulink>
  255               command compiles a firewall script from the configuration files
  256               in the current working directory (using <command>shorewall
  257               compile -e</command>), copies that file to the remote system via
  258               scp and starts Shorewall Lite on the remote system via
  259               ssh.</para>
  260 
  261               <para>Example (firewall's DNS name is 'gateway'):</para>
  262 
  263               <para><command>/sbin/shorewall remote-start
  264               gateway</command><note>
  265                   <para>Although scp and ssh are used by default, you can use
  266                   other utilities by setting RSH_COMMAND and RCP_COMMAND in
  267                   <filename>/etc/shorewall/shorewall.conf</filename>.</para>
  268                 </note></para>
  269 
  270               <para>The first time that you issue a <command>load</command>
  271               command, Shorewall will use ssh to run
  272               <filename>/usr/share/shorewall-lite/shorecap</filename> on the
  273               remote firewall to create a capabilities file in the firewall's
  274               administrative direction. It also uses scp to copy the
  275               shorewallrc file from the remote firewall system. See <link
  276               linkend="Shorecap">below</link>.</para>
  277             </listitem>
  278           </orderedlist>
  279         </listitem>
  280 
  281         <listitem>
  282           <para>If you later need to change the firewall's configuration,
  283           change the appropriate files in the firewall's export directory
  284           then:</para>
  285 
  286           <programlisting><command>cd &lt;export directory&gt;</command>
  287 <command>/sbin/shorewall remote-reload firewall</command></programlisting>
  288 
  289           <para>The <ulink
  290           url="manpages/shorewall.html"><command>remote-reload</command></ulink>
  291           command compiles a firewall script from the configuration files in
  292           the current working directory (using <command>shorewall compile
  293           -e</command>), copies that file to the remote system via scp and
  294           reloads Shorewall Lite on the remote system via ssh. The <emphasis
  295           role="bold">remote-reload</emphasis> command also supports the '-c'
  296           option.</para>
  297         </listitem>
  298       </orderedlist>
  299 
  300       <para>There is a <filename>shorewall-lite.conf</filename> file installed
  301       as part of Shorewall Lite
  302       (<filename>/etc/shorewall-lite/shorewall-lite.conf</filename>). You can
  303       use that file on the firewall system to override some of the settings
  304       from the shorewall.conf file in the export directory.</para>
  305 
  306       <para>Settings that you can override are:</para>
  307 
  308       <blockquote>
  309         <simplelist>
  310           <member>VERBOSITY</member>
  311 
  312           <member>LOGFILE</member>
  313 
  314           <member>LOGFORMAT</member>
  315 
  316           <member>IPTABLES</member>
  317 
  318           <member>PATH</member>
  319 
  320           <member>SHOREWALL_SHELL</member>
  321 
  322           <member>SUBSYSLOCK</member>
  323 
  324           <member>RESTOREFILE</member>
  325         </simplelist>
  326       </blockquote>
  327 
  328       <para>You will normally never touch
  329       <filename>/etc/shorewall-lite/shorewall-lite.conf</filename> unless you
  330       run Debian or one of its derivatives (see <link
  331       linkend="Debian">above</link>).</para>
  332 
  333       <para>The <filename>/sbin/shorewall-lite</filename> program included
  334       with Shorewall Lite supports the same set of commands as the
  335       <filename>/sbin/shorewall</filename> program in a full Shorewall
  336       installation with the following exceptions:</para>
  337 
  338       <blockquote>
  339         <simplelist>
  340           <member>add</member>
  341 
  342           <member>compile</member>
  343 
  344           <member>delete</member>
  345 
  346           <member>refresh</member>
  347 
  348           <member>reload</member>
  349 
  350           <member>try</member>
  351 
  352           <member>safe-start</member>
  353 
  354           <member>safe-restart</member>
  355 
  356           <member>show actions</member>
  357 
  358           <member>show macros</member>
  359         </simplelist>
  360       </blockquote>
  361 
  362       <para>On systems with only Shorewall Lite installed, I recommend that
  363       you create a symbolic link <filename>/sbin/shorewall</filename> and
  364       point it at <filename>/sbin/shorewall-lite</filename>. That way, you can
  365       use <command>shorewall</command> as the command regardless of which
  366       product is installed.</para>
  367 
  368       <blockquote>
  369         <programlisting><command>ln -sf shorewall-lite /sbin/shorewall</command></programlisting>
  370       </blockquote>
  371 
  372       <section>
  373         <title>Module Loading</title>
  374 
  375         <para>As with a normal Shorewall configuration, the shorewall.conf
  376         file can specify LOAD_HELPERS_ONLY which determines if the
  377         <filename>modules</filename> file (LOAD_HELPERS_ONLY=No) or
  378         <filename>helpers</filename> file (LOAD_HELPERS_ONLY=Yes) is used.
  379         Normally, the file on the firewall system is used. If you want to
  380         specify modules at compile time on the Administrative System, then you
  381         must place a copy of the appropriate file
  382         (<filename>modules</filename> or <filename>helpers</filename>) in the
  383         firewall's configuration directory before compilation.</para>
  384 
  385         <para>In Shorewall 4.4.17, the EXPORTMODULES option was added to
  386         shorewall.conf (and shorewall6.conf). When EXPORTMODULES=Yes, any
  387         <filename>modules</filename> or <filename>helpers</filename> file
  388         found on the CONFIG_PATH on the Administrative System during
  389         compilation will be used.</para>
  390 
  391         <para>In Shorewall 5.2.3, the LOAD_HELPERS_ONLY option was removed and
  392         the behavior is that which was formerly obtained by setting
  393         LOAD_HELPERS_ONLY=Yes.</para>
  394       </section>
  395 
  396       <section id="Converting">
  397         <title>Converting a system from Shorewall to Shorewall Lite</title>
  398 
  399         <para>Converting a firewall system that is currently running Shorewall
  400         to run Shorewall Lite instead is straight-forward.</para>
  401 
  402         <orderedlist numeration="loweralpha">
  403           <listitem>
  404             <para>On the administrative system, create an export directory for
  405             the firewall system.</para>
  406           </listitem>
  407 
  408           <listitem>
  409             <para>Copy the contents of <filename
  410             class="directory">/etc/shorewall/</filename> from the firewall
  411             system to the export directory on the administrative
  412             system.</para>
  413           </listitem>
  414 
  415           <listitem>
  416             <para>On the firewall system:</para>
  417 
  418             <para>Be sure that the IP address of the administrative system is
  419             included in the firewall's export directory
  420             <filename>stoppedrules</filename> file.</para>
  421 
  422             <programlisting><command>shorewall stop</command></programlisting>
  423 
  424             <para><emphasis role="bold">We recommend that you uninstall
  425             Shorewall at this point.</emphasis></para>
  426           </listitem>
  427 
  428           <listitem>
  429             <para>Install Shorewall Lite on the firewall system.</para>
  430 
  431             <para>If you are running Debian or one of its derivatives like
  432             Ubuntu then edit <filename>/etc/default/shorewall-lite</filename>
  433             and set startup=1.</para>
  434           </listitem>
  435 
  436           <listitem>
  437             <para>On the administrative system:</para>
  438 
  439             <para>It's a good idea to include the IP address of the
  440             administrative system in the firewall system's <ulink
  441             url="manpages/shorewall-stoppedrules.html"><filename>stoppedrules</filename>
  442             file</ulink>.</para>
  443 
  444             <para>Also, edit the <filename>shorewall.conf</filename> file in
  445             the firewall's export directory and change the CONFIG_PATH setting
  446             to remove <filename class="directory">/etc/shorewall</filename>.
  447             You can replace it with <filename
  448             class="directory">/usr/share/shorewall/configfiles</filename> if
  449             you like.</para>
  450 
  451             <para>Example:</para>
  452 
  453             <blockquote>
  454               <para>Before editing:</para>
  455 
  456               <programlisting>CONFIG_PATH=<emphasis role="bold">/etc/shorewall</emphasis>:/usr/share/shorewall</programlisting>
  457 
  458               <para>After editing:</para>
  459 
  460               <programlisting>CONFIG_PATH=<emphasis role="bold">/usr/share/shorewall/configfiles</emphasis>:/usr/share/shorewall</programlisting>
  461             </blockquote>
  462 
  463             <para>Changing CONFIG_PATH will ensure that subsequent
  464             compilations using the export directory will not include any files
  465             from <filename class="directory">/etc/shorewall</filename> other
  466             than <filename>shorewall.conf</filename> and
  467             <filename>params</filename>.</para>
  468 
  469             <para>If you set variables in the params file, there are a couple
  470             of issues:</para>
  471 
  472             <para>The <filename>params</filename> file is not processed at run
  473             time if you set EXPORTPARAMS=No in
  474             <filename>shorewall.conf</filename>. For run-time setting of shell
  475             variables, use the <filename>init</filename> extension script.
  476             Beginning with Shorewall 4.4.17, the variables set in the
  477             <filename>params</filename> file are available in the firewall
  478             script when EXPORTPARAMS=No.</para>
  479 
  480             <para>If the <filename>params</filename> file needs to set shell
  481             variables based on the configuration of the firewall system, you
  482             can use this trick:</para>
  483 
  484             <programlisting>EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</programlisting>
  485 
  486             <para>The <command>shorewall-lite call</command> command allows
  487             you to to call interactively any Shorewall function that you can
  488             call in an extension script.</para>
  489 
  490             <para>After having made the above changes to the firewall's export
  491             directory, execute the following commands.</para>
  492 
  493             <blockquote>
  494               <programlisting><command>cd &lt;export directory&gt;</command>
  495 <command>/sbin/shorewall remote-start &lt;firewall system&gt;</command>
  496 </programlisting>
  497 
  498               <para>Example (firewall's DNS name is 'gateway'):</para>
  499 
  500               <para><command>/sbin/shorewall remote-start
  501               gateway</command></para>
  502             </blockquote>
  503 
  504             <para>The first time that you issue a
  505             <command>remote-start</command> command, Shorewall will use ssh to
  506             run <filename>/usr/share/shorewall-lite/shorecap</filename> on the
  507             remote firewall to create a capabilities file in the firewall's
  508             administrative direction. See <link
  509             linkend="Shorecap">below</link>.</para>
  510 
  511             <para>The <ulink
  512             url="starting_and_stopping_shorewall.htm#Load"><command>load</command></ulink>
  513             command compiles a firewall script from the configuration files in
  514             the current working directory (using <command>shorewall compile
  515             -e</command>), copies that file to the remote system via
  516             <command>scp</command> and starts Shorewall Lite on the remote
  517             system via <command>ssh</command>.</para>
  518           </listitem>
  519 
  520           <listitem>
  521             <para>If you later need to change the firewall's configuration,
  522             change the appropriate files in the firewall's export directory
  523             then:</para>
  524 
  525             <programlisting><command>cd &lt;export directory&gt;</command>
  526 <command>/sbin/shorewall remote-reload firewall</command></programlisting>
  527 
  528             <para>The <ulink
  529             url="starting_and_stopping_shorewall.htm#Reload"><command>reload</command></ulink>
  530             command compiles a firewall script from the configuration files in
  531             the current working directory (using <command>shorewall compile
  532             -e</command>), copies that file to the remote system via
  533             <command>scp</command> and restarts Shorewall Lite on the remote
  534             system via <command>ssh</command>.</para>
  535           </listitem>
  536 
  537           <listitem>
  538             <para>If the kernel/iptables configuration on the firewall later
  539             changes and you need to create a new
  540             <filename>capabilities</filename> file, do the following on the
  541             firewall system:</para>
  542 
  543             <programlisting><command>/usr/share/shorewall-lite/shorecap &gt; capabilities</command>
  544 <command>scp capabilities &lt;admin system&gt;:&lt;this system's config dir&gt;</command></programlisting>
  545 
  546             <para>Or simply use the -c option the next time that you use the
  547             <command>remote-reload</command> command (e.g., <command>shorewall
  548             remote-reload -c gateway</command>).</para>
  549           </listitem>
  550 
  551           <listitem>
  552             <para>Shorewall6-lite works with Shorewall6 in the same way that
  553             Shorewall-lite works with Shorewall. Beginning with Shorewall
  554             5.0.0, running 'shorewall &lt;cmd&gt;" is the same as running
  555             "shorewall-lite &lt;cmd&gt;" when Shorewall is not installed.. To
  556             continue to use the "shorewall6" command after switching to
  557             Shoerwall6-lite, you need to add this to your .profile (or to
  558             .bashrc if root's shell is bash):</para>
  559 
  560             <programlisting>    alias shorewall6=shorewall6-lite</programlisting>
  561           </listitem>
  562         </orderedlist>
  563       </section>
  564     </section>
  565 
  566     <section id="Restrictions">
  567       <title>Restrictions</title>
  568 
  569       <para>While compiled Shorewall programs (as are used in Shorewall Lite)
  570       are useful in many cases, there are some important restrictions that you
  571       should be aware of before attempting to use them.</para>
  572 
  573       <orderedlist>
  574         <listitem>
  575           <para>All extension scripts used are copied into the program (with
  576           the exception of <ulink url="shorewall_extension_scripts.htm">those
  577           executed at compile-time by the compiler</ulink>). The ramifications
  578           of this are:</para>
  579 
  580           <itemizedlist>
  581             <listitem>
  582               <para>If you update an extension script, the compiled program
  583               will not use the updated script.</para>
  584             </listitem>
  585 
  586             <listitem>
  587               <para>The <filename>params</filename> file is only processed at
  588               compile time if you set EXPORTPARAMS=No in
  589               <filename>shorewall.conf</filename>. For run-time setting of
  590               shell variables, use the <filename>init</filename> extension
  591               script. Although the default setting is EXPORTPARAMS=Yes for
  592               compatibility, the recommended setting is EXPORTPARAMS=No.
  593               Beginning with Shorewall 4.4.17, the variables set in the
  594               <filename>params</filename> file are available in the firewall
  595               script when EXPORTPARAMS=No.</para>
  596 
  597               <para>If the <filename>params</filename> file needs to set shell
  598               variables based on the configuration of the firewall system, you
  599               can use this trick:</para>
  600 
  601               <programlisting>EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</programlisting>
  602 
  603               <para>The <command>shorewall-lite call</command> command allows
  604               you to to call interactively any Shorewall function that you can
  605               call in an extension script.</para>
  606             </listitem>
  607           </itemizedlist>
  608         </listitem>
  609 
  610         <listitem>
  611           <para>You must install Shorewall Lite on the system where you want
  612           to run the script. You then install the compiled program in
  613           /usr/share/shorewall-lite/firewall and use the /sbin/shorewall-lite
  614           program included with Shorewall Lite to control the firewall just as
  615           if the full Shorewall distribution was installed.</para>
  616         </listitem>
  617 
  618         <listitem>
  619           <para>Beginning with Shorewall 4.4.9, the compiler detects bridges
  620           and sets the <emphasis role="bold">bridge</emphasis> and <emphasis
  621           role="bold">routeback</emphasis> options explicitly. That can't
  622           happen when the compilation no longer occurs on the firewall
  623           system.</para>
  624         </listitem>
  625       </orderedlist>
  626     </section>
  627   </section>
  628 
  629   <section id="Compile">
  630     <title>The "shorewall compile" command</title>
  631 
  632     <para>A compiled script is produced using the <command>compile</command>
  633     command:</para>
  634 
  635     <blockquote>
  636       <para><command>shorewall compile [ -e ] [ <replaceable>&lt;directory
  637       name&gt;</replaceable> ] [ <replaceable>&lt;path name&gt;</replaceable>
  638       ]</command></para>
  639     </blockquote>
  640 
  641     <para>where</para>
  642 
  643     <blockquote>
  644       <variablelist>
  645         <varlistentry>
  646           <term>-e</term>
  647 
  648           <listitem>
  649             <para>Indicates that the program is to be "exported" to another
  650             system. When this flag is set, neither the "detectnets" interface
  651             option nor DYNAMIC_ZONES=Yes in shorewall.conf are allowed. The
  652             created program may be run on a system that has only Shorewall
  653             Lite installed</para>
  654 
  655             <para>When this flag is given, Shorewall does not probe the
  656             current system to determine the kernel/iptables features that it
  657             supports. It rather reads those capabilities from
  658             <filename>/etc/shorewall/capabilities</filename>. See below for
  659             details.</para>
  660 
  661             <para>Also, when <option>-e</option> is specified you should have
  662             a copy of the remote firewall's <filename>shorewallrc</filename>
  663             file in the the directory specified by <replaceable>&lt;directory
  664             name&gt;</replaceable>.</para>
  665           </listitem>
  666         </varlistentry>
  667 
  668         <varlistentry>
  669           <term>&lt;directory name&gt;</term>
  670 
  671           <listitem>
  672             <para>specifies a directory to be searched for configuration files
  673             before those directories listed in the CONFIG_PATH variable in
  674             <filename>shorewall.conf</filename>.</para>
  675 
  676             <para>When -e <replaceable>&lt;directory-name&gt;</replaceable> is
  677             included, only the SHOREWALL_SHELL and VERBOSITY settings from
  678             <filename>/etc/shorewall/shorewall.conf</filename> are used and
  679             these apply only to the compiler itself. The settings used by the
  680             compiled firewall script are determined by the contents of
  681             <filename>&lt;directory name&gt;/shorewall.conf</filename>.</para>
  682 
  683             <note>
  684               <para>Beginning with Shorewall 4.5.7.2,
  685               <filename>/etc/shorewall/shorewall.conf</filename> is not read
  686               if there is a <filename>shorewall.conf</filename> file in the
  687               specified configuration directory.</para>
  688             </note>
  689           </listitem>
  690         </varlistentry>
  691 
  692         <varlistentry>
  693           <term>&lt;path name&gt;</term>
  694 
  695           <listitem>
  696             <para>specifies the name of the script to be created. If not
  697             given, ${VARDIR}/firewall is assumed (by default, ${VARDIR} is
  698             <filename>/var/lib/shorewall/</filename>)</para>
  699           </listitem>
  700         </varlistentry>
  701       </variablelist>
  702     </blockquote>
  703 
  704     <para>The compile command can be used to stage a new compiled strict that
  705     can be activated later using</para>
  706 
  707     <simplelist>
  708       <member><command>shorewall restart -f</command></member>
  709     </simplelist>
  710   </section>
  711 
  712   <section id="Shorecap">
  713     <title>The /etc/shorewall/capabilities file and the shorecap
  714     program</title>
  715 
  716     <para>As mentioned above, the
  717     <filename>/etc/shorewall/capabilities</filename> file specifies that
  718     kernel/iptables capabilities of the target system. Here is a sample
  719     file:</para>
  720 
  721     <blockquote>
  722       <programlisting>#
  723 # Shorewall detected the following iptables/netfilter capabilities - Tue Jul 15 07:28:12 PDT 2008
  724 #
  725 NAT_ENABLED=Yes
  726 MANGLE_ENABLED=Yes
  727 MULTIPORT=Yes
  728 XMULTIPORT=Yes
  729 CONNTRACK_MATCH=Yes
  730 POLICY_MATCH=Yes
  731 PHYSDEV_MATCH=Yes
  732 PHYSDEV_BRIDGE=Yes
  733 LENGTH_MATCH=Yes
  734 IPRANGE_MATCH=Yes
  735 RECENT_MATCH=Yes
  736 OWNER_MATCH=Yes
  737 IPSET_MATCH=Yes
  738 CONNMARK=Yes
  739 XCONNMARK=Yes
  740 CONNMARK_MATCH=Yes
  741 XCONNMARK_MATCH=Yes
  742 RAW_TABLE=Yes
  743 IPP2P_MATCH=
  744 CLASSIFY_TARGET=Yes
  745 ENHANCED_REJECT=Yes
  746 KLUDGEFREE=Yes
  747 MARK=Yes
  748 XMARK=Yes
  749 MANGLE_FORWARD=Yes
  750 COMMENTS=Yes
  751 ADDRTYPE=Yes
  752 TCPMSS_MATCH=Yes
  753 HASHLIMIT_MATCH=Yes
  754 NFQUEUE_TARGET=Yes
  755 REALM_MATCH=Yes
  756 CAPVERSION=40190</programlisting>
  757     </blockquote>
  758 
  759     <para>As you can see, the file contains a simple list of shell variable
  760     assignments — the variables correspond to the capabilities listed by the
  761     <command>shorewall show capabilities</command> command and they appear in
  762     the same order as the output of that command.</para>
  763 
  764     <para>To aid in creating this file, Shorewall Lite includes a
  765     <command>shorecap</command> program. The program is installed in the
  766     <filename class="directory">/usr/share/shorewall-lite/</filename>
  767     directory and may be run as follows:</para>
  768 
  769     <blockquote>
  770       <para><command>[ IPTABLES=&lt;iptables binary&gt; ] [
  771       MODULESDIR=&lt;kernel modules directory&gt; ]
  772       /usr/share/shorewall-lite/shorecap &gt; capabilities</command></para>
  773     </blockquote>
  774 
  775     <para>The IPTABLES and MODULESDIR options have their <ulink
  776     url="manpages/shorewall.conf.html">usual Shorewall default
  777     values</ulink>.</para>
  778 
  779     <para>The <filename>capabilities</filename> file may then be copied to a
  780     system with Shorewall installed and used when compiling firewall programs
  781     to run on the remote system.</para>
  782 
  783     <para>The <filename>capabilities</filename> file may also be creating
  784     using <filename>/sbin/shorewall-lite</filename>:<blockquote>
  785         <para><command>shorewall-lite show -f capabilities &gt;
  786         capabilities</command></para>
  787       </blockquote></para>
  788 
  789     <para>Note that unlike the <command>shorecap</command> program, the
  790     <command>show capabilities</command> command shows the kernel's current
  791     capabilities; it does not attempt to load additional kernel
  792     modules.</para>
  793   </section>
  794 
  795   <section id="Running">
  796     <title>Running compiled programs directly</title>
  797 
  798     <para>Compiled firewall programs are complete shell programs that support
  799     the following command line forms:</para>
  800 
  801     <blockquote>
  802       <simplelist>
  803         <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
  804         start</command></member>
  805 
  806         <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
  807         stop</command></member>
  808 
  809         <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
  810         clear</command></member>
  811 
  812         <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
  813         refresh</command></member>
  814 
  815         <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
  816         reset</command></member>
  817 
  818         <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
  819         restart</command></member>
  820 
  821         <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
  822         status</command></member>
  823 
  824         <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
  825         version</command></member>
  826       </simplelist>
  827     </blockquote>
  828 
  829     <para>The options have the same meanings as when they are passed to
  830     <filename>/sbin/shorewall</filename> itself. The default VERBOSITY level
  831     is the level specified in the <filename>shorewall.conf</filename> file
  832     used when the program was compiled.</para>
  833   </section>
  834 </article>