diff --git a/docs/Internals.xml b/docs/Internals.xml
index 40ad20390..5cb9b490a 100644
--- a/docs/Internals.xml
+++ b/docs/Internals.xml
@@ -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.
-
+ The build environment components are not released and are
discussed in the Shorewall Build
@@ -242,6 +242,10 @@ shorewall_cli $@
Capability Detection
+
+
+ Miscellaneous utility functions.
+
@@ -403,7 +407,7 @@ export -p
The operation of the generated script is illustrated in this
diagram.
-
+ 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
direct dependencies are not shown where there is also a transitive
dependency.
-
+ Config Module
-
+ As mentioned above, the Config module offers several related
+ services. Each will be described in a separate sub-section.
+
+
+ Pre-processor
+
+ 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.
+
+ The major exported functions in the pre-processor are:
+
+
+
+ open_file( $ )
+
+
+ The single argument names the file to be opened and is
+ usually a simple filename such as
+ shorewall.conf. open_file calls find_file 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.
+
+
+
+ $currentfile
+
+
+ Handle for the file open
+
+
+
+
+ $currentfilename (exported)
+
+
+ The fully-qualified name of the file.
+
+
+
+
+ $currentlinenumber
+
+
+ Set to zero.
+
+
+
+
+ If the file is not found or if it has zero size, false
+ ('') is returned.
+
+
+
+
+ push_open( $ )
+
+
+ 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.
+
+ push_open pushes
+ $currentfile, $currentfilename, $currentlinenumber and $ifstack onto @includestack, copies @includestack into a local array, pushes
+ a reference to the local array onto @openstack, and empties @includestack
+
+ As its final step, push_open calls open_file.
+
+
+
+
+ pop_open()
+
+
+ The pop_open function
+ must be called after the file opened by push_open is processed. This is true even
+ in the case where push_open
+ returned false.
+
+ pop_open pops @openstack and restores $currentfile, $currentfilename, $currentlinenumber, $ifstack and @includestack.
+
+
+
+
+ close_file()
+
+
+ close_file is called to
+ close the current file. Higher-level modules should only call
+ close_file to close the current
+ file prior to end-of-file.
+
+
+
+
+ first_entry( $ )
+
+
+ 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 >= 1. If the argument is a function reference, the
+ function (usually a closure) is called.
+
+ first_entry may called
+ after a successful call to open_file. If it is not called, then the
+ pre-processor takes no action when the first non-blank
+ non-commentary line is found.
+
+ first_entry returns no
+ significant value.
+
+
+
+
+ read_a_line( $ )
+
+
+ This function delivers the next logical input line to the
+ caller. The single argument is defined by the following
+ constants:
+
+ use constant { PLAIN_READ => 0, # No read_a_line options
+ EMBEDDED_ENABLED => 1, # Look for embedded Shell and Perl
+ EXPAND_VARIABLES => 2, # Expand Shell variables
+ STRIP_COMMENTS => 4, # Remove comments
+ SUPPRESS_WHITESPACE => 8, # Ignore blank lines
+ CHECK_GUNK => 16, # Look for unprintable characters
+ CONFIG_CONTINUATION => 32, # Suppress leading whitespace if
+ # continued line ends in ',' or ':'
+ DO_INCLUDE => 64, # Look for INCLUDE <filename>
+ NORMAL_READ => -1 # All options
+ };
+
+ The actual argument may be a bit-wise OR of any of the
+ above constants.
+
+ The function does not return the logical line; that line
+ is rather stored in the module-global variable $currentline (exported). The function
+ simply returns true if a line was read or false if end-of-file
+ was reached. read_a_line
+ automatically calls close_file
+ at EOF.
+
+
+
+
+ split_line1
+
+
+ Most of the callers of read_a_line want to treat each line as
+ whitespace-separated columns. The split_line and split_line1 functions return an array
+ containing the contents of those columns.
+
+ The arguments to split_line1 are:
+
+
+
+ A =>
+ column-number pair for each of
+ the columns in the file. These are used to handle lines that
+ use the alternate input
+ methods and also serve to define the number of
+ columns in the file's records.
+
+
+
+ A hash reference defining
+ => number-of-columns pairs.
+ For example "{ COMMENT => 0, FORMAT 2 }" allows COMMENT
+ lines of an unlimited number of space-separated tokens and
+ it allows FORMAT lines with exactly two columns.
+
+
+
+ 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.
+
+
+
+
+ split_line
+
+
+ split_line simply returns
+ split_line1( @_, {} ).
+
+
+
+
+
+
+ Error and Progress Message Production
+
+ There are several exported functions dealing with error and
+ warning messages:
+
+
+
+ fatal_error
+
+
+ The argument(s) to this function describe the error. The
+ generated error message is:
+
+
+ "ERROR: @_" followed by the name of the file and the
+ line number where the error occurred.
+
+
+ The mesage is written to the STARTUP_LOG, if any.
+
+ The function does not return but rather passes the message
+ to die or to confess, depending on whether the "-T"
+ option was specified.
+
+
+
+
+ warning_message
+
+
+ The warning_message is very similar to fatal_error but
+ avoids calling die or confess. It also prefixes the argument(s)
+ with "WARNING: " rather than "ERROR: ".
+
+ It message is written to Standard Out and to the
+ STARTUP_LOG, if any.
+
+
+
+
+ progress_message, progress_message2, progress_message3 and
+ progress_message_nocompress
+
+
+ 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.
+
+
+
+ progress_message only
+ write messages when the verbosity is 2. This function also
+ preserves leading whitespace while removing superflous
+ embedded whitespace from the messages.
+
+
+
+ progress_message2
+ writes messages with the verbosity is >= 1.
+
+
+
+ progress_message3
+ writes messages when the verbosity is >= 0.
+
+
+
+ progress_message_nocompress is like
+ progress_message except
+ that it does not preserve leading whitespace nor does it
+ eliminate superfluous embedded whitespacve from the
+ messages.
+
+
+
+
+
+
+
+
+
+
+
+