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. + + + + + +
+ +
+ + + <para/> + </section> </section> </section> </article>