diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2010-06-19 18:18:58 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2010-06-19 18:18:58 +0300 |
commit | 3b49db92dc4a67f72a4d641f3ac9492f4a44578c (patch) | |
tree | 8701771e3e5f3631b03b85e1a62f98f71ef6973d | |
parent | b4ff3aa84bd151a4a575c10b141be425ecc9b867 (diff) | |
download | smap-3b49db92dc4a67f72a4d641f3ac9492f4a44578c.tar.gz smap-3b49db92dc4a67f72a4d641f3ac9492f4a44578c.tar.bz2 |
Bugfixes
* doc/macros.texi: New file.
* doc/Makefile.am (smap_TEXINFOS): Add macros.texi
* doc/Config: Override $image hanlder.
* doc/ex-meta1.texi: Add indexing commands.
* doc/gendocs_template: Fix copy-paste errors.
* doc/smap.texi: Add indexing commands.
* configure.ac, NEWS: Version 0.0.94
-rw-r--r-- | NEWS | 4 | ||||
-rw-r--r-- | configure.ac | 2 | ||||
-rw-r--r-- | doc/Config | 36 | ||||
-rw-r--r-- | doc/Makefile.am | 7 | ||||
-rw-r--r-- | doc/ex-meta1.texi | 1 | ||||
-rwxr-xr-x | doc/gendocs_template | 4 | ||||
-rw-r--r-- | doc/macros.texi | 13 | ||||
-rw-r--r-- | doc/smap.texi | 140 |
8 files changed, 196 insertions, 11 deletions
@@ -1,14 +1,14 @@ -Smap NEWS -- history of user-visible changes. 2010-06-18 +Smap NEWS -- history of user-visible changes. 2010-06-19 Copyright (C) 2006, 2007, 2008, 2009, 2010 Sergey Poznyakoff See the end of file for copying conditions. Please send Smap bug reports to <gray+smap@gnu.org.ua> -Version 0.0.93 (Git) +Version 0.0.94 (Git) * First release ========================================================================= Copyright information: diff --git a/configure.ac b/configure.ac index 7ccd286..5848e32 100644 --- a/configure.ac +++ b/configure.ac @@ -14,13 +14,13 @@ # You should have received a copy of the GNU General Public License # along with Smap. If not, see <http://www.gnu.org/licenses/>. AC_PREREQ(2.63) m4_define([SMAP_VERSION_MAJOR], 0) m4_define([SMAP_VERSION_MINOR], 0) -m4_define([SMAP_VERSION_PATCH], 93) +m4_define([SMAP_VERSION_PATCH], 94) AC_INIT([smap], SMAP_VERSION_MAJOR.SMAP_VERSION_MINOR[]m4_ifdef([SMAP_VERSION_PATCH],.SMAP_VERSION_PATCH), [gray+smap@gnu.org.ua]) AC_CONFIG_SRCDIR([src/smapd.c]) AC_CONFIG_HEADERS([config.h]) AC_CONFIG_AUX_DIR([build-aux]) @@ -110,12 +110,13 @@ $print_section = \&gray_print_section; $print_navigation = \&gray_print_navigation; $print_head_navigation = \&gray_print_head_navigation; $print_foot_navigation = \&gray_print_foot_navigation; $print_About = \&gray_print_About; $cell = \&gray_multitable_cell; $print_page_foot = \&gray_print_page_foot; +$image = \&gray_default_image; sub gray_multitable_cell($$) { my $text = shift; my $row_macro = shift; @@ -360,6 +361,41 @@ sub gray_print_section &$print_foot_navigation($fh); print $fh "$SMALL_RULE\n"; &$print_navigation($fh, \@NODE_FOOTER_BUTTONS) if (!defined($WORDS_IN_PAGE) or (defined ($nw) and $nw >= $WORDS_IN_PAGE)); } } + +sub gray_default_image($$$$$$$$$$$) +{ + my $file = shift; + my $base = shift; + my $preformatted = shift; + my $file_name = shift; + my $alt = shift; + my $width = shift; + my $height = shift; + my $raw_alt = shift; + my $extension = shift; + my $working_dir = shift; + my $file_path = shift; + + if (!defined($file_path) or $file_path eq '') + { + if (defined($extension) and $extension ne '') + { + $file = "$base.$extension"; + } + else + { + $file = "$base.jpg"; + } + main::echo_warn ("no image file for $base, (using $file)"); + } + $alt = &$protect_text($base) if (!defined($alt) or ($alt eq '')); + return "[ $alt ]" if ($preformatted); + # it is possible that $file_name is more correct as it allows the user + # to chose the relative path. + $file = &$protect_text($file_name); + return "<img src=\"/software/smap/graphics/$file\" alt=\"$alt\">"; +} + diff --git a/doc/Makefile.am b/doc/Makefile.am index 1a6e3b0..d1e8bdb 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -16,13 +16,14 @@ info_TEXINFOS=smap.texi smap_TEXINFOS=\ fdl.texi\ sockmap.texi\ debugcat.texi\ - ex-meta1.texi + ex-meta1.texi\ + macros.texi EXTRA_DIST = \ gendocs_template\ mastermenu.el\ untabify.el\ smapflow.txt\ @@ -68,9 +69,11 @@ manual: TEXINPUTS=$(srcdir):$(top_srcdir)/build-aux:$(TEXINPUTS) \ MAKEINFO="$(MAKEINFO) $(MAKEINFOFLAGS)" \ TEXI2DVI="$(TEXI2DVI) -t @finalout" \ $(GENDOCS) --texi2html $(PACKAGE) '$(PACKAGE_NAME) manual' manual.tar.bz2: manual - tar cfj manual.tar.bz2 manual + tar cf manual.tar manual + tar -r -f manual.tar --transform 's|^|graphics/|' smapflow.png + bzip2 -f manual.tar man-tar: manual.tar.bz2 diff --git a/doc/ex-meta1.texi b/doc/ex-meta1.texi index 905e135..1cf02ac 100644 --- a/doc/ex-meta1.texi +++ b/doc/ex-meta1.texi @@ -1,10 +1,11 @@ @c This file is part of the Smap manual. @c Copyright (C) 2010 Sergey Poznyakoff @c See file smap.texi for copying conditions. @c ******************************************************************* +@cindex MeTA1 In this appendix we will show how to use the @samp{mailutils} module (@pxref{mailutils module}) to configure local user and alias maps for @acronym{MeTA1}. For this purpose, we will assume that the actual data is stored in two tables in a @acronym{MySQL} database. The two maps will be served by two separate databases, each of which uses a separate configuration file. diff --git a/doc/gendocs_template b/doc/gendocs_template index 30bf3c4..0e0bb50 100755 --- a/doc/gendocs_template +++ b/doc/gendocs_template @@ -1,21 +1,21 @@ <?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> - <title>Mailfromd - General-Purpose Mail Filter</title> + <title>SMAP - Socket Map Server</title> <link rev="made" href="mailto:gray@gnu.org.ua" /> <link rel="stylesheet" type="text/css" href="gray.css" /> <link rel="icon" type="image/png" href="/graphics/gnu-head-icon.png" /> </head> <body> <!--#include virtual="inc/header.html" --> <ul class='tabs'> - <li><a href="mailfromd.html">Main</a></li> + <li><a href="smap.html">Main</a></li> <li><a href="download.html">Downloads</a></li> <li><a class="active" href="manual.html">Documentation</a></li> </ul> <div id="main"> <p>The manual for <b>%%PACKAGE%%</b> is available in the following formats:</p> diff --git a/doc/macros.texi b/doc/macros.texi new file mode 100644 index 0000000..810c6a0 --- /dev/null +++ b/doc/macros.texi @@ -0,0 +1,13 @@ +@c This file is part of the Smap manual. +@c Copyright (C) 2010 Sergey Poznyakoff +@c See file smap.texi for copying conditions. +@c ******************************************************************* +@macro smapdopidx{long,short} +@opindex \short\, -\short\ option, @command{smapd} +@opindex \long\, --\long\ option, @command{smapd} +@end macro + +@macro smapcopidx{long,short} +@opindex \short\, -\short\ option, @command{smapc} +@opindex \long\, --\long\ option, @command{smapc} +@end macro diff --git a/doc/smap.texi b/doc/smap.texi index 452d4f5..6faef2c 100644 --- a/doc/smap.texi +++ b/doc/smap.texi @@ -18,12 +18,13 @@ @syncodeindex op cp @syncodeindex pr cp @syncodeindex kw cp @syncodeindex fl cp @include version.texi +@include macros.texi @ifinfo @dircategory Email @direntry * Smap:: Socket map framework. * smapd: (smap) smapd. Socket map server. @@ -281,12 +282,13 @@ itself, such as client IP address or map name from the request, and compare them with some static data. If the condition yields true, the destination part of the rule points to the database which will handle this request. @node smapd @chapter The Socket Map Server +@prindex smapd Socket map server @command{smapd} is the main part of the package. When invoked, it reads the @dfn{configuration file} and parses its command line to determine its configuration settings. Command line settings override ones from the configuration file. The default configuration file is @file{/etc/smapd.conf}@footnote{To be precise, it is @file{@var{sysconfdir}/smapd.conf}, where @var{sysconfdir} is @@ -310,22 +312,24 @@ an argument. For more information on option syntax, see @ref{smapd-options}. occupies a single line. Very long lines may be split into several physical lines by ending each one with a backslash character. Comments are introduced with the @samp{#} character: the character itself and everything after it up to next newline is ignored. For a detailed description, see @ref{smapd-config}. +@cindex smapd, alternative configuration file for You can instruct @command{smapd} to read an alternative configuration file instead of the default one. It may be necessary, for example, to test a new configuration. To do so, use the @option{--config=@var{file}} (@option{-c @var{file}}) command line option. Its argument specifies the file name to read, e.g.: @example $ smapd -c ./mysmapd.conf @end example +@cindex smapd, configuration checking To check whether your configuration is error-free, use the @option{--lint} (@option{-t}) option. It instructs @command{smapd} to parse the configuration file and exit after that. Any errors found are reported on the standard error. The exit code is @samp{0} if the file parsed without errors and @samp{78} otherwise (@pxref{exit codes}, for a full list of exit codes). For example: @@ -387,12 +391,13 @@ file. using @samp{inet-mode yes} statement. @node logging @section Logging @cindex logging @cindex diagnostics +@cindex syslog The server determines automatically where its diagnostics output should go. By default, it goes to standard error. However, after detaching from the terminal in standalone mode, @command{smapd} sends diagnostics to syslog, using facility @samp{daemon} by default. The same applies also if its standard input is not attached to a terminal. @@ -414,12 +419,15 @@ argument is the facility number or symbolic name. Valid names are: Similarly, the log tag can also be changed, either from the configuration file, using the @samp{log-tag} statement, or from the command line, using the @option{--log-tag} (@option{-L}) option, @node debugging @section Tracing and Debugging +@cindex debugging +@cindex query traces +@cindex tracing queries The amount of information logged by the server is configurable. By default, it is quite silent and outputs only diagnostics that call to special attention, such as errors and the like. You may request more information, however. For further discussion, it is convenient to introduce two main information groups: query traces and debugging information. @dfn{Query traces} are log messages that show @@ -440,12 +448,14 @@ command line option or @samp{trace yes} statement in the configuration file. When using syslog, query traces are reported using the @samp{info} priority. @anchor{trace-pattern} +@cindex trace patterns +@cindex patterns in query traces Some requests may be of particular interest to you, whereas others may not be relevant at all. There is a way to abridge the traces to show those relevant requests only. If you give the @option{--trace-pattern=@var{pattern}} option, only those requests that begin with @var{pattern}@footnote{Actually, the argument would better be named @var{prefix}, but I plan to implement globbing @@ -465,17 +475,24 @@ trace-pattern OK @end example Any number of @option{--trace-pattern} options (or configuration statements) may be given. The server will log only those queries that match one of the patterns specified by them. +@cindex debugging information @dfn{Debugging information} is auxiliary diagnostics reflecting various details of internal functionality of @command{smapd}. Although aimed primarily to help in debugging the server, it may occasionally be of use for server administrators as well. +@cindex debugging specification +@cindex specification, debugging +@cindex debug level +@cindex level, debugging +@cindex debug category +@cindex category, debugging Debugging information is requested using the @option{--debug} (@option{-x}) command line option or @samp{debug} configuration statement. In both cases, the argument is a @dfn{debug specification}, consisting of two parts, separated by a dot: @samp{@var{cat}.@var{lev}}. The @var{cat} part is a @dfn{debug category}. It is either an integer number identifying the category, @@ -491,12 +508,15 @@ values are useful only for debugging. To enable several debug categories, use several @option{--debug} option (or @samp{debug} configuration statements). @node privileges @section Runtime Privileges +@cindex runtime privileges +@cindex privileges, runtime +@cindex setuid By default @command{smapd} runs with the privileges of the user that started it. Normally, this user is root. If you wish it to switch to some unprivileged user after startup, use the @code{user} configuration statement: @example @@ -536,18 +556,20 @@ requires root privileges for normal operation. To allow for such uses, instead of setting global user privileges, set them on a per-server basis. @xref{servers}, for a detailed discussion of this technique. @node servers @section Server Configuration +@cindex server configuration @dfn{Servers} are internal @command{smapd} objects, responsible for listening on sockets and handling socket I/O operations. Each server has a @dfn{server id}, which is a unique name associated to it, and @dfn{socket address}, which describes the socket this server handles. @anchor{smap url} +@cindex URL Socket addresses are represented as @dfn{URL}s. Smap version @value{VERSION} recognizes the following URL forms: @table @asis @item inet://@var{ip}:@var{port} Listen on the IPv4 address @var{ip}, on the given @var{port}. IP @@ -565,12 +587,13 @@ unix:///var/run/smap.sock @end example @noindent means UNIX socket @file{/var/run/smap.sock}. @end table +@kwindex server The @code{server} statement configures servers. It takes two mandatory arguments: the socked ID and URL, e.g.: @example server main inet://10.10.1.11:3056 server local unix:///var/run/smap.sock @@ -686,18 +709,18 @@ be omitted. There are following cases: Set UID of the user @var{user}, but do not change the GID. @item owner :@var{group} Set only owner GID, do not change the UID. @end table - Note, that this statement cannot be used outside of @code{server} scope. @end deffn @node loadable modules @section Loadable Modules +@cindex modules @dfn{Mapper modules} are external pieces of software designed to handle a particular subset of map queries. They are built as shared libraries and loaded into @command{smapd} at startup. Modules are loaded using the @code{module} command: @@ -706,12 +729,14 @@ Load module @file{module-name}. Additional arguments (@var{args}), if specified, are passed to the module initialization function. The @var{module-id} is a unique identifier, which will subsequently be used to refer to that module. @end deffn +@cindex load path +@cindex module load path A @dfn{module load path} is an internal list of directories which @command{smapd} scans in order to find a loadable file name specified in @code{module} statement. By default the scan order is as follows: @enumerate 1 @item Smap module directory: @file{$prefix/lib/smap}; @@ -721,12 +746,14 @@ statement (see below); @env{LTDL_LIBRARY_PATH}. @item The system dependent library search path (e.g. on GNU/Linux it is set by the file @file{/etc/ld.so.conf} and the environment variable @env{LD_LIBRARY_PATH}). @end enumerate +@vrindex LTDL_LIBRARY_PATH +@vrindex LD_LIBRARY_PATH Values of @env{LTDL_LIBRARY_PATH} and @env{LD_LIBRARY_PATH} must be colon-separated lists of absolute directory names, for example: @samp{/usr/lib/mypkg:/lib/foo'}. In any of these directories, @command{smapd} first attempts to find and the given @var{module-name} verbatim and to load it. If this fails, @@ -747,12 +774,13 @@ Adds the directories listed in its argument to the module load path. The @var{path} argument must be a colon-separated list of absolute directory names. @end deffn @node databases @section Databases +@cindex database, smap A @dfn{database} is a logical entity associated with a particular module, that provides a specific configuration for it. In other words, database is a configured instance of the module. Databases are declared using the following statement: @@ -777,23 +805,27 @@ database tempfail echo TEMP Try again later The @samp{nomap} database always sends the string @samp{NOTFOUND No such map} in reply. The @samp{tempfail} database replies with the string @samp{TEMP Try again later}. @node dispatch rules @section Query Dispatch Rules +@cindex dispatch rules +@cindex rules, dispatch +@kwindex dispatch When a query arrives, @command{smapd} uses @dfn{query dispatch rules} to decide to what database to dispatch this query. Dispatch rules are somewhat similar to ACLs: each rule consists of a set of conditions and a target part. The rules are joined in a list. When applied to a particular query, this list is scanned from top down. The conditions of each rule are evaluated using the query as their argument. If all conditions return @samp{True}, then the target part of this rule indicates the database to dispatch this query to. If the list is exhausted and no matching rule was found, @command{smapd} sends back the default @samp{NOTFOUND} reply. +@kwindex map Consider for example the following rule: @example dispatch map eq alias database maildb @end example @@ -817,12 +849,13 @@ matches queries whose map part begins with @samp{us}. dispatch map regexp /(alias)|(virtusers)/ database maildb @end example @xref{cond-map, The map condition}, for a detailed description of this condition. +@kwindex from Another important condition is @code{from}. It returns @samp{True} if its argument, which is an IP address or a CIDR, matches the IP of the machine that sent the query. For example, the following rule directs all queries coming from IP addresses 192.168.0.1 through 192.168.0.31 to the database @samp{local}: @@ -872,12 +905,13 @@ prefix before it, e.g.: @example dispatch from 192.168.0.0/27 \ not map regexp /^(alias)|(virtuser)$/ \ database user @end example +@kwindex default, dispatch condition There is a special condition which is convenient for the last rule in the list. The @samp{default} condition always returns @samp{True}, so this rule: @example dispatch default database nomap @@ -886,12 +920,17 @@ dispatch default database nomap @noindent will match any rule and dispatch it to a database named @samp{nomap}. The @samp{default} condition cannot be combined with other conditions. @node exit codes @section Smapd Exit Codes +@cindex exit codes +@kwindex EX_OK +@kwindex EX_USAGE +@kwindex EX_UNAVAILABLE +@kwindex EX_CONFIG The following table summarizes exit codes used by @command{smapd}. For each code it lists its decimal number, symbolic name from the @file{sysexits.h} header file, and its meaning. @multitable @columnfractions 0.1 0.4 0.5 @headitem Code @tab Name @tab Meaning @@ -900,16 +939,20 @@ For each code it lists its decimal number, symbolic name from the @item 69 @tab EX_UNAVAILABLE @tab Some other error occurred. @item 78 @tab EX_CONFIG @tab Errors in configuration file detected. @end multitable @node smapd-options @chapter Command Line Syntax +@cindex options, command line +@cindex command line options Most command line options have two forms, called short and long forms. Both forms are absolutely identical in function; they are interchangeable. +@cindex short option form +@cindex option, short form The @dfn{short} form is a traditional form for UNIX utilities. In this form, the option consists of a single dash, followed by a single letter, e.g. @option{-c}. Short options which require arguments take their arguments immediately following the option letter, optionally separated by white @@ -922,12 +965,14 @@ required to do this. When short options are clumped as a set, use one -v -l}. However, only options that do not take arguments may be clustered this way. If an option takes an argument, it can only be the last option in such a cluster, otherwise it would be impossible to specify the argument for it. Anyway, it is much more readable to specify such options separated. +@cindex long option form +@cindex option, long form The @dfn{long} option names are probably easier to memorize than their short counterparts. They consist of two dashes, followed by a multi-letter option name, which is usually selected to be a mnemonics for the operation it requests. For example, @option{--verbose} is a long option that increases the verbosity of a utility. In addition, long option names can abbreviated, provided that such an abbreviation @@ -950,100 +995,120 @@ following notations: @option{--file=name} or @option{--file name}. The following table summarizes the options available for @command{smapd}. For each option a brief description is given and a cross reference is provided to more in-depth explanation in the body of the manual. @table @option +@smapdopidx{c, config} @item -c @var{file} @itemx --config=@var{file} Read configuration from @var{file}, instead of the default @file{/etc/smapd.conf}. @xref{smapd,, --config}. +@smapdopidx{t, lint} @item -t @itemx --lint Test configuration and exit with code @samp{0} if the file parsed without errors and @samp{78} otherwise. Any errors found are reported on the standard error. @xref{smapd,, --lint}. +@smapdopidx{f, foreground} @item -f @itemx --foreground Do not detach from the controlling terminal, operate in foreground. +@smapdopidx{e, stderr} @item -e @itemx --stderr Output diagnostic to stderr. @xref{logging}. +@smapdopidx{l, syslog} @item -l @itemx --syslog Output diagnostic to syslog (default). @xref{logging}. +@smapdopidx{s, single-process} @item -s @itemx --single-process Operate in single-process mode. This option is intended to help in debugging @command{smapd}. @emph{Do not use it in production environment!} +@smapdopidx{i, inetd} @item -i @itemx --inetd Operate in inetd mode (@pxref{inetd-mode}). +@smapdopidx{T, trace} @item -T @itemx --trace Trace queries and replies. @xref{debugging,, Query traces}. +@smapdopidx{p, trace-pattern} @item -p @var{pattern} @itemx --trace-pattern=@var{pattern} Trace only queries that begin with the given @var{pattern}. @xref{trace-pattern}. +@smapdopidx{x, debug} @item -x @var{level} @itemx --debug=@var{level} Set debug verbosity level. @xref{debugging,,Debugging information}. +@smapdopidx{L, log-tag} @item -L @itemx --log-tag=@var{tag} Set syslog tag. @xref{logging}. -@item -f @var{facility} +@smapdopidx{F, log-facility} +@item -F @var{facility} @itemx --log-facility=@var{facility} Set syslog facility. @xref{logging,, log-facility}. +@smapdopidx{h, help} @item -h @itemx --help Give a concise summary of the command line options. +@opindex --usage, --usage option, @command{smapd} @item --usage Give a short usage reminder. +@smapdopidx{V, version} @item -V @itemx --version Print program version. @end table @node smapd-config @chapter Smapd Configuration File +@cindex configuration file, @command{smapd} The @command{smapd} configuration file consists, on a lexical level, of logical lines. A @dfn{logical line} is any sequence of characters between two unescaped newline characters. The word @samp{unescaped} means a newline character not preceded by a single backslash. Thus, escaped newlines allow to combine several physical lines into a single logical one. +@cindex comments, configuration Within a logical line, unescaped @samp{#} character introduces a comment. The character itself and the rest of characters after it up to the end of line are ignored. Empty lines are ignored as well. +@cindex configuration statement +@cindex statement, configuration Each not empty line constitutes a @dfn{configuration statement}. The statement is first split into words. A @dfn{word} is any contiguous sequence of non-whitespace characters. Singly-quoted and doubly-quoted strings are also considered words. Within a doubly-quoted string, backslash character introduces an @dfn{escape sequence}. The following escape sequences are supported: +@cindex escape sequences @float Table, escape-sequences @caption{Escape sequences} @multitable @columnfractions 0.30 .5 @item Sequence @tab Replaced with @item \a @tab Audible bell character (@acronym{ASCII} 7) @item \b @tab Backspace character (@acronym{ASCII} 8) @@ -1229,12 +1294,14 @@ following statements are allowed for use in the block statement: @item backlog @item group @item max-children @item reuseaddr @item single-process @item user +@item socket-mode +@item socket-owner @end itemize Their meaning is the same as of the corresponding statements in global scope (see above), but applies to that particular server only. @end deffn @@ -1318,17 +1385,21 @@ algorithm: @table @asis @item eq @itemx is Literal equality. Map name must be exactly the same as @var{string}. +@cindex globbing patterns +@cindex pattern, globbing @item like @itemx fnmatch Match using shell wildcard patterns (@pxref{glob,Globbing patterns,,glob(7), Glob(7) man page}). +@cindex regular expressions +@cindex expression, regular @item regexp Match using regular expressions. @var{String} must have the following form: @example /@var{expr}/@var{flags} @@ -1374,12 +1445,13 @@ particular database. The syntax is: Pass this query to the database @var{dbname} (@pxref{config-database,dbname}). @end deffn @end deffn @node modules @chapter Modules Shipped with Smap +@cindex module installation directory Smap is shipped with a set of loadable modules, which are installed in its default module directory, @file{@var{$prefix}/lib/smap}. The modules are configurable on a per-module (@pxref{loadable modules}), and per-database (@pxref{databases}) levels. Smap version @value{VERSION} contains the following modules: @@ -1391,12 +1463,13 @@ in detail in the following sections. * mailutils module:: * guile module:: @end menu @node echo module @section The @samp{echo} Module +@kwindex echo The echo module is the simplest of all modules. It sends back a static reply string, no matter what the query was. This module is useful for default databases, which catch erroneous or not handled queries. @subheading Loading @@ -1421,24 +1494,27 @@ dispatch rule: @example dispatch default database default @end example @node mailutils module @section The @samp{mailutils} Module +@kwindex mailutils This module uses GNU Mailutils (@uref{http://www.gnu.org/software/mailutils}) and provides two main modes: @table @samp +@cindex auth, mailutils mode @item auth This mode uses GNU Mailutils authorization mechanism to obtain user data (similar to the system @samp{getpwnam} routine) and returns positive reply if the data were retrieved and negative reply otherwise. @xref{MeTA1}, for an example on how to use it as a local user and alias database. +@cindex mbq, mailutils mode @item mbq This mode allows to check whether the user's mailbox exceeded the allotted quota, and if not, whether it is able to accept a message of the given size without exceeding it. The mode name is an abbreviation of @dfn{Mailbox Quota}. @end table @@ -1450,57 +1526,74 @@ abbreviation of @dfn{Mailbox Quota}. * auth:: Mailutils Auth Mode * mbq:: Mailutils MBQ Mode @end menu @node expansion @subsection Variable Expansion +@cindex variable expansion +@cindex expansion, variable In the discussion below we often refer to @dfn{meta-variable expansion} in strings. This is a process, whereby any sequence @samp{$@{@var{variable}@}} is replaced with the value of @var{variable}. The defined variables are: @table @asis +@kwindex db @item db The database name. +@kwindex map @item map The map name. +@kwindex key @item key The lookup key. +@kwindex diag @item diag If the key was not found or some error occurred, this variable expands to a short diagnostics string, suitable for return message. Otherwise, expands to empty string. +@kwindex name @item name The @samp{name} field from the retrieved record. Empty string if the user not found. +@kwindex passwd @item passwd The @samp{passwd} field from the retrieved record. Empty string if the user not found. +@kwindex uid @item uid The @samp{uid} field from the retrieved record. If the user was not found, expands to @samp{-1}. +@kwindex gid @item gid The @samp{gid} field from the retrieved record. If the user was not found, expands to @samp{-1}. +@kwindex gecos @item gecos The @samp{gecos} field from the retrieved record. Empty string if the user not found. +@kwindex dir @item dir The @samp{dir} field from the retrieved record. Empty string if the user not found. +@kwindex shell @item shell The @samp{shell} field from the retrieved record. Empty string if the user not found. +@kwindex mailbox @item mailbox The @samp{mailbox} field from the retrieved record. Empty string if the user not found. +@kwindex quota @item quota The @samp{quota} field from the retrieved record. If the user was not found, expands to @samp{NONE}. +@kwindex mbsize @item mbsize Mailbox size, in bytes. Defined only in @samp{mbq} mode. +@kwindex msgsize @item msgsize Expected message size, in bytes. Defined only in @samp{mbq} mode. @end table @node load-mailutils @subsection Mailutils Loading Sequence @@ -1509,40 +1602,47 @@ Expected message size, in bytes. Defined only in @samp{mbq} mode. module mailutils mailutils [args] @end example Arguments are: @table @option +@kwindex config-verbose @item config-verbose Verbosely trace the processing of the main Mailutils configuration files. +@kwindex config-dump @item config-dump Dump the parse tree from the Mailutils configuration. +@kwindex positive-reply @item positive-reply=@var{str} Declare default positive reply string. This string is returned when the underlying database was able to found the requested key. Prior to returning, @var{str} is subject to meta-variable expansion, as described above. Default positive reply string is @samp{OK}. +@kwindex negative-reply @item negative-reply=@var{str} Declare default negative reply string. This string is returned when the underlying database failed to found the requested key. Prior to returning, @var{str} is subject to meta-variable expansion. Default negative reply string is @samp{NOTFOUND}. +@kwindex onerror-reply @item onerror-reply=@var{str} Declare a reply to be returned on error. Prior to returning, @var{str} is subject to meta-variable expansion. Default string is @samp{NOTFOUND}. @end table +@cindex configuration file, mailutils +@cindex mailutils configuration file The module reads most of its configuration settings from the main Mailutils configuration file. @xref{configuration, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}, for a description of GNU Mailutils configuration system. It looks for @command{smap}-specific settings in the section @samp{program smap-mailutils}. @@ -1587,50 +1687,55 @@ Here, @var{name} is the database name, @var{mode} is @samp{auth} if the database should work in auth mode, and @samp{mbq} if it should run in mbq mode. If the @samp{mode} argument is omitted, @samp{auth} is assumed. Optional @var{args} may be used to supply additional database configuration. These are: @table @option +@kwindex positive-reply @item positive-reply=@var{str} Declare positive reply string. This string is returned when the underlying database was able to found the requested key. Prior to returning, @var{str} is subject to meta-variable expansion, as described above. Default positive reply string is @samp{OK}, unless overridden by the module-level @option{positive-reply} option (@pxref{db-mailutils, positive-reply}. +@kwindex negative-reply @item negative-reply=@var{str} Declare negative reply string. This string is returned when the underlying database failed to found the requested key. Prior to returning, @var{str} is subject to meta-variable expansion. Default negative reply string is @samp{NOTFOUND}, unless overridden by the module-level @option{positive-reply} option (@pxref{db-mailutils, negative-reply}. +@kwindex onerror-reply @item onerror-reply=@var{str} Declare a reply to be returned on error. Prior to returning, @var{str} is subject to meta-variable expansion. Default string is @samp{NOTFOUND}, unless overridden by the module-level @option{positive-reply} option (@pxref{db-mailutils, onerr-reply}. @end table @node auth @subsection Mailutils Auth Mode +@cindex auth mode, mailutils Mailutils module in @samp{auth} mode uses GNU Mailutils authorization mechanism to obtain user data. It returns @samp{positive-reply} if the data were retrieved and @samp{negative-reply} otherwise. This mode is often used for databases of local users and aliases. The key is normally a user name (either local part or fully qualified). @xref{MeTA1}, for an example on how to use it. - + +@cindex mbq mode, mailutils @node mbq @subsection Mailutils MBQ Mode @acronym{MBQ}, or @dfn{Mailbox Quota} mode, uses key as the name of a local user. It obtains the user parameters via Mailutils authorization mechanism and then switches to this user privileges and opens his mailbox for a brief period of time. After opening it @@ -1646,14 +1751,16 @@ this case, @samp{positive-reply} is returned if the actual mailbox size plus the message size is less than quota. Two additional meta-variables may be used in reply templates to return quota-related information: @table @asis +@kwindex mbsize @item mbsize Mailbox size, in bytes. Defined only in @samp{mbq} mode. +@kwindex msgsize @item msgsize Expected message size, in bytes. Defined only in @samp{mbq} mode. @end table The following example shows a definition of @samp{mbq} database which the author uses on his servers: @@ -1685,12 +1792,13 @@ if message of the given size cannot be delivered to mailbox without violating its quota. Notice, that this mode requires superuser privil |