"Fossies" - the Fresh Open Source Software Archive 
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 <export directory></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 <export directory></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 <export directory></command>
495 <command>/sbin/shorewall remote-start <firewall system></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 <export directory></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 > capabilities</command>
544 <command>scp capabilities <admin system>:<this system's config dir></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 <cmd>" is the same as running
555 "shorewall-lite <cmd>" 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><directory
637 name></replaceable> ] [ <replaceable><path name></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><directory
664 name></replaceable>.</para>
665 </listitem>
666 </varlistentry>
667
668 <varlistentry>
669 <term><directory name></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><directory-name></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><directory name>/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><path name></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=<iptables binary> ] [
771 MODULESDIR=<kernel modules directory> ]
772 /usr/share/shorewall-lite/shorecap > 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 >
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><program> [ -q ] [ -v ] [ -n ]
804 start</command></member>
805
806 <member><command><program> [ -q ] [ -v ] [ -n ]
807 stop</command></member>
808
809 <member><command><program> [ -q ] [ -v ] [ -n ]
810 clear</command></member>
811
812 <member><command><program> [ -q ] [ -v ] [ -n ]
813 refresh</command></member>
814
815 <member><command><program> [ -q ] [ -v ] [ -n ]
816 reset</command></member>
817
818 <member><command><program> [ -q ] [ -v ] [ -n ]
819 restart</command></member>
820
821 <member><command><program> [ -q ] [ -v ] [ -n ]
822 status</command></member>
823
824 <member><command><program> [ -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>