holm/shorewall_code
1
0
Fork 0
forked from extern/shorewall_code
Code Pull Requests Activity

Continue work on Internals document

Browse Source 
Signed-off-by: Tom Eastep <teastep@shorewall.net>
This commit is contained in:
Tom Eastep 2012-09-21 15:06:29 -07:00
parent 8bd5ee355c
commit 97cdc390c3
1 changed files with 316 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

320
docs/Internals.xml
View File

@ -116,7 +116,7 @@
release and installs them on an end-user's or a packager's system. It
is diagrammed in the following graphic.</para>
<graphic fileref="images/BuildInstall.png" />
<graphic fileref="images/BuildInstall.png"/>
<para>The build environment components are not released and are
discussed in the <ulink url="Build.html">Shorewall Build
@ -242,6 +242,10 @@ shorewall_cli $@</programlisting>
<listitem>
<para>Capability Detection</para>
</listitem>
<listitem>
<para>Miscellaneous utility functions.</para>
</listitem>
</itemizedlist>
</listitem>
@ -403,7 +407,7 @@ export -p</programlisting>
<para>The operation of the generated script is illustrated in this
diagram.</para>
<graphic fileref="images/RunningScript.png" />
<graphic fileref="images/RunningScript.png"/>
<para>The Netfilter ruleset is sometimes dependent on the environment
when the script runs. Dynamic IP addresses and gateways, for example,
@ -466,13 +470,321 @@ export -p</programlisting>
direct dependencies are not shown where there is also a transitive
dependency.</para>
<graphic fileref="images/ModuleDepencency.png" />
<graphic fileref="images/ModuleDepencency.png"/>
</section>
<section>
<title>Config Module</title>
<para></para>
<para>As mentioned above, the Config module offers several related
services. Each will be described in a separate sub-section.</para>
<section>
<title>Pre-processor</title>
<para>Unlike preprocessors like ccp, the Shorewall pre-processor does
it's work each time that the higher-level functions ask for the next
line of input.</para>
<para>The major exported functions in the pre-processor are:</para>
<variablelist>
<varlistentry>
<term>open_file( $ )</term>
<listitem>
<para>The single argument names the file to be opened and is
usually a simple filename such as
<filename>shorewall.conf</filename>. <emphasis
role="bold">open_file</emphasis> calls <emphasis
role="bold">find_file</emphasis> who traverses the CONFIG_PATH
looking for a file with the requested name. If the file is found
and has non-zero size, it is opened and module-global variables
are set as follows, and the fully-qualified name of the file is
returned by the function.</para>
<variablelist>
<varlistentry>
<term>$currentfile</term>
<listitem>
<para>Handle for the file open</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$currentfilename (exported)</term>
<listitem>
<para>The fully-qualified name of the file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$currentlinenumber</term>
<listitem>
<para>Set to zero.</para>
</listitem>
</varlistentry>
</variablelist>
<para>If the file is not found or if it has zero size, false
('') is returned.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>push_open( $ )</term>
<listitem>
<para>Sometimes, the higher-level modules need to suspend
processing of the current file and open another file. An obvious
example is when the Rules module needs to process a macro file.
The push_open function is called in these cases.</para>
<para><emphasis role="bold">push_open</emphasis> pushes
<emphasis role="bold">$currentfile</emphasis>, <emphasis
role="bold">$currentfilename</emphasis>, <emphasis
role="bold">$currentlinenumber</emphasis> and <emphasis
role="bold">$ifstack</emphasis> onto <emphasis
role="bold">@includestack</emphasis>, copies <emphasis
role="bold">@includestack</emphasis> into a local array, pushes
a reference to the local array onto <emphasis
role="bold">@openstack</emphasis>, and empties <emphasis
role="bold">@includestack</emphasis></para>
<para>As its final step, <emphasis
role="bold">push_open</emphasis> calls <emphasis
role="bold">open_file</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>pop_open()</term>
<listitem>
<para>The <emphasis role="bold">pop_open</emphasis> function
must be called after the file opened by <emphasis
role="bold">push_open</emphasis> is processed. This is true even
in the case where <emphasis role="bold">push_open</emphasis>
returned false.</para>
<para><emphasis role="bold">pop_open</emphasis> pops <emphasis
role="bold">@openstack</emphasis> and restores <emphasis
role="bold">$currentfile</emphasis>, <emphasis
role="bold">$currentfilename</emphasis>, <emphasis
role="bold">$currentlinenumber</emphasis>, <emphasis
role="bold">$ifstack</emphasis> and <emphasis
role="bold">@includestack</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>close_file()</term>
<listitem>
<para><emphasis role="bold">close_file</emphasis> is called to
close the current file. Higher-level modules should only call
<emphasis role="bold">close_file</emphasis> to close the current
file prior to end-of-file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>first_entry( $ )</term>
<listitem>
<para>This function is called to determine what happens when the
first non-commentary and no-blank line is read from the open
file. The argument may be either a scalar or a function
reference. If the argument is a scalar then it is treaded as a
progress message that should be issued if the VERBOSITY setting
is &gt;= 1. If the argument is a function reference, the
function (usually a closure) is called.</para>
<para><emphasis role="bold">first_entry</emphasis> may called
after a successful call to <emphasis
role="bold">open_file</emphasis>. If it is not called, then the
pre-processor takes no action when the first non-blank
non-commentary line is found.</para>
<para><emphasis role="bold">first_entry</emphasis> returns no
significant value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>read_a_line( $ )</term>
<listitem>
<para>This function delivers the next logical input line to the
caller. The single argument is defined by the following
constants:</para>
<programlisting>use constant { PLAIN_READ =&gt; 0, # No read_a_line options
EMBEDDED_ENABLED =&gt; 1, # Look for embedded Shell and Perl
EXPAND_VARIABLES =&gt; 2, # Expand Shell variables
STRIP_COMMENTS =&gt; 4, # Remove comments
SUPPRESS_WHITESPACE =&gt; 8, # Ignore blank lines
CHECK_GUNK =&gt; 16, # Look for unprintable characters
CONFIG_CONTINUATION =&gt; 32, # Suppress leading whitespace if
# continued line ends in ',' or ':'
DO_INCLUDE =&gt; 64, # Look for INCLUDE &lt;filename&gt;
NORMAL_READ =&gt; -1 # All options
};</programlisting>
<para>The actual argument may be a bit-wise OR of any of the
above constants.</para>
<para>The function does not return the logical line; that line
is rather stored in the module-global variable <emphasis
role="bold">$currentline</emphasis> (exported). The function
simply returns true if a line was read or false if end-of-file
was reached. <emphasis role="bold">read_a_line</emphasis>
automatically calls <emphasis role="bold">close_file</emphasis>
at EOF.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>split_line1</term>
<listitem>
<para>Most of the callers of <emphasis
role="bold">read_a_line</emphasis> want to treat each line as
whitespace-separated columns. The <emphasis
role="bold">split_line</emphasis> and <emphasis
role="bold">split_line1</emphasis> functions return an array
containing the contents of those columns.</para>
<para>The arguments to split_line1 are:</para>
<itemizedlist>
<listitem>
<para>A <option>name</option> =&gt;
<replaceable>column-number</replaceable> pair for each of
the columns in the file. These are used to handle lines that
use the <ulink
url="configuration_file_basics.htm#Pairs">alternate input
methods</ulink> and also serve to define the number of
columns in the file's records.</para>
</listitem>
<listitem>
<para>A hash reference defining <option>keyword</option>
=&gt; <replaceable>number-of-columns</replaceable> pairs.
For example "{ COMMENT =&gt; 0, FORMAT 2 }" allows COMMENT
lines of an unlimited number of space-separated tokens and
it allows FORMAT lines with exactly two columns. </para>
</listitem>
</itemizedlist>
<para>If there are fewer space-separated tokens on the line than
specified in the arguments, then "-" is returned for the the
trailing columns that were omitted.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>split_line</term>
<listitem>
<para><emphasis role="bold">split_line</emphasis> simply returns
<emphasis role="bold">split_line1( @_, {} )</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Error and Progress Message Production</title>
<para>There are several exported functions dealing with error and
warning messages:</para>
<variablelist>
<varlistentry>
<term>fatal_error</term>
<listitem>
<para>The argument(s) to this function describe the error. The
generated error message is:</para>
<simplelist>
<member>"ERROR: @_" followed by the name of the file and the
line number where the error occurred. </member>
</simplelist>
<para>The mesage is written to the STARTUP_LOG, if any.</para>
<para>The function does not return but rather passes the message
to <emphasis role="bold">die</emphasis> or to <emphasis
role="bold">confess</emphasis>, depending on whether the "-T"
option was specified.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>warning_message</term>
<listitem>
<para>The warning_message is very similar to fatal_error but
avoids calling <emphasis role="bold">die</emphasis> or <emphasis
role="bold">confess</emphasis>. It also prefixes the argument(s)
with "WARNING: " rather than "ERROR: ".</para>
<para>It message is written to Standard Out and to the
STARTUP_LOG, if any.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>progress_message, progress_message2, progress_message3 and
progress_message_nocompress</term>
<listitem>
<para>These procedures conditionally write their argument(s) to
Standard Out and to the STARTUP_LOG (if any), depending on the
settings of VERBOSITY and and LOG_VERBOSITY respectively.</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">progress_message</emphasis> only
write messages when the verbosity is 2. This function also
preserves leading whitespace while removing superflous
embedded whitespace from the messages.</para>
</listitem>
<listitem>
<para><emphasis role="bold">progress_message2</emphasis>
writes messages with the verbosity is &gt;= 1.</para>
</listitem>
<listitem>
<para><emphasis role="bold">progress_message3</emphasis>
writes messages when the verbosity is &gt;= 0.</para>
</listitem>
<listitem>
<para><emphasis
role="bold">progress_message_nocompress</emphasis> is like
<emphasis role="bold">progress_message</emphasis> except
that it does not preserve leading whitespace nor does it
eliminate superfluous embedded whitespacve from the
messages.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title/>
<para/>
</section>
</section>
</section>
</article>