aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2010-06-19 18:18:58 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2010-06-19 18:18:58 +0300
commit3b49db92dc4a67f72a4d641f3ac9492f4a44578c (patch)
tree8701771e3e5f3631b03b85e1a62f98f71ef6973d
parentb4ff3aa84bd151a4a575c10b141be425ecc9b867 (diff)
downloadsmap-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--NEWS4
-rw-r--r--configure.ac2
-rw-r--r--doc/Config36
-rw-r--r--doc/Makefile.am7
-rw-r--r--doc/ex-meta1.texi1
-rwxr-xr-xdoc/gendocs_template4
-rw-r--r--doc/macros.texi13
-rw-r--r--doc/smap.texi140
8 files changed, 196 insertions, 11 deletions
diff --git a/NEWS b/NEWS
index 77af17a..fb1e6aa 100644
--- a/NEWS
+++ b/NEWS
@@ -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])
diff --git a/doc/Config b/doc/Config
index ecd455f..51a1c1d 100644
--- a/doc/Config
+++ b/doc/Config
@@ -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