aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2010-06-18 00:38:29 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2010-06-18 00:38:29 +0300
commite7f908a280718546f9690337e65e7bc8ac9364d6 (patch)
tree340a0cb47e9b89290e6cbd4f30b4e83e8ca0fac8 /doc
parent26959487f551abc36f85eb8b5577edd1abca7f8f (diff)
downloadsmap-e7f908a280718546f9690337e65e7bc8ac9364d6.tar.gz
smap-e7f908a280718546f9690337e65e7bc8ac9364d6.tar.bz2
Update and spell-check the docs.
* doc/smap.texi: Update. * doc/sockmap.texi: Update.
Diffstat (limited to 'doc')
-rw-r--r--doc/smap.texi241
-rw-r--r--doc/sockmap.texi8
2 files changed, 240 insertions, 9 deletions
diff --git a/doc/smap.texi b/doc/smap.texi
index aed6119..4dcb758 100644
--- a/doc/smap.texi
+++ b/doc/smap.texi
@@ -92,6 +92,9 @@ The Socket Map Server
* operation modes:: Smapd Operation Modes.
* logging::
* debugging:: Tracing and Debugging.
+* privileges:: Runtime Privileges.
+* servers:: Server Configuration.
+* loadable modules:: Loadable Modules.
* options-smapd:: Command Line Syntax.
* config-smapd:: Smapd Configuration File.
* exit codes:: Smapd Exit Codes.
@@ -216,7 +219,7 @@ module, thereby creating several instances of the same lookup driver.
(shown as @dfn{Db a} through @dfn{Db f}), interfacing to three
different modules (boxes @dfn{Mod A} through @dfn{Mod C}). The
databases @samp{a} and @samp{b} interface to module @samp{A},
-databases @samp{c}, @samp{d} and @samp{e} iterface to module @samp{B},
+databases @samp{c}, @samp{d} and @samp{e} interface to module @samp{B},
and database @samp{f} interfaces to module @samp{B}. All three
modules are linked with the @file{libsmap} library.
@@ -286,7 +289,7 @@ itself and everything after it up to next newline is ignored. For a
detailed description, see @ref{config-smapd}.
You can instruct @command{smapd} to read an alternative
-configuration file instead of the default one. It may be necessaty,
+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.:
@@ -323,6 +326,10 @@ $ smapd --lint --config ./mysmapd.conf
* operation modes:: Smapd Operation Modes.
* logging::
* debugging:: Tracing and Debugging.
+* privileges:: Runtime Privileges.
+* servers:: Server Configuration.
+* loadable modules:: Loadable Modules.
+* databases:: Databases.
* options-smapd:: Command Line Syntax.
* config-smapd:: Smapd Configuration File.
* exit codes:: Smapd Exit Codes.
@@ -330,7 +337,7 @@ $ smapd --lint --config ./mysmapd.conf
@node operation modes
@section Smapd Operation Modes
-@cindex operaton modes
+@cindex operation modes
@cindex modes, operation
@cindex standalone mode
@cindex mode, standalone
@@ -363,7 +370,7 @@ using @samp{inet-mode yes} statement.
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 apllies also if its standard input is not attached to a
+The same applies also if its standard input is not attached to a
terminal.
Two command line options are provided to manually alter these
@@ -460,6 +467,230 @@ 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
+ 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
+user daemon
+@end example
+
+The above example instructs @command{smapd} to switch to the UID of
+the user @samp{daemon} and to the GID of its principal group. The
+rest of groups the user might be a member of is dropped. To retain
+all supplementary user groups, use the @code{allgroup} statement. Its
+argument is a @dfn{boolean value}, i.e. @samp{yes}, @samp{on},
+@samp{true}, or @samp{t} to indicate the @dfn{true value},
+and @samp{no}, @samp{off}, @samp{false} or @samp{nil} to indicate
+@dfn{false}. So, to switch to the user @samp{daemon} and also retain
+all its supplementary groups, one would write:
+
+@example
+user daemon
+allgroups yes
+@end example
+
+ You may also retain only some of the user's group, or even some
+groups the user is not member of. This is done using the @code{group}
+statement:
+
+@example
+user faemon
+group mail mysql
+@end example
+
+ Arguments to @code{group} are any number of valid group names.
+
+ Notice, that while running @command{smapd} with non-root privileges
+might be a good idea, it may render some modules useless. For
+example, the @file{mailutils} module in @samp{mbq} mode (FIXME: pxref
+needed) 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
+ @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.
+
+ 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
+address may be given either in ``dotted-quad'' notation or as a hostname.
+Port may be specified either as a port number, or as a name of a
+service from @file{/etc/services}.
+
+@item unix://@var{pathname}
+ Listen on the UNIX socket @var{pathname}. Notice that the name of the
+socket must be absolute, so you would usually have three slashes running
+together, e.g. the notation
+
+@example
+unix:///var/run/smap.sock
+@end example
+
+@noindent
+means UNIX socket @file{/var/run/smap.sock}.
+@end table
+
+ 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
+@end example
+
+ These statements configure two servers. The one called @samp{main}
+is listening on IP 10.10.1.11, port 3056. The one called @samp{local}
+listens on UNIX socket @file{/var/run/smap.sock}.
+
+ The @code{server} statement has also another form, called @dfn{block
+form}, which allows to configure more details. In this form, the
+statement is given third argument -- the word @samp{begin}. This
+statement is followed by one or more statements supplying additional
+configuration for this server, followed by the word @samp{end} on a
+line by itself, which closes the construct. This is illustrated in
+the following example:
+
+@example
+server local unix:///var/run/smap.sock begin
+ backlog 10
+ user mail
+end
+@end example
+
+ Statements which may be used between @samp{begin} and @samp{end}
+fall into two categories: privilege control statements, and socket
+configuration statements.
+
+ The former are @code{user}, @code{allgroups} and @code{group},
+described in the previous section (@pxref{privileges}). Syntactically
+they are exactly the same as their public scope counterparts. The only
+difference is that they apply only to child processes spawned to
+handle connections to that particular URL. For example, consider the
+following statement:
+
+@example
+server local unix:///var/run/smap.sock begin
+ user faemon
+ group mail mysql
+end
+@end example
+
+ This configuration works as follows. The master @command{smapd}
+process runs with root privileges. When a connection is requested to
+socket @file{/var/run/smap.sock}, the master spawns a subprocess
+to handle that connection. This subprocess switches to the UID and
+GID of user @samp{daemon} and retains GIDs of the groups @samp{mail}
+and @samp{mysql} and then enters the mail read-and-reply loop.
+
+ Of course, the per-server privilege control statements work only if
+the master daemon runs with the root privileges.
+
+ The second group of server statements are socket configuration
+statements. Similarly to privilege control statements, these too
+may appear inside a server block statement as well as outside of it,
+in the global scope. When used in global scope, they affect all
+@code{server} statements. When used in per-server context, they
+apply to that particular server only. These statements are:
+
+@deffn {Config} backlog number
+ Sets the maximum size of pending connections queue for sockets. If a
+connection request arrives when the queue is full, the client receives an
+error with an indication of @samp{ECONNREFUSED}.
+
+Default backlog is 8.
+@end deffn
+
+@deffn {Config} reuseaddr bool
+ If @var{bool} is @samp{yes} reuse existing socket addresses (both
+INET and UNIX). This is the default.
+@end deffn
+
+@deffn {Config} max-children number
+ Maximum number of children processes allowed to run simultaneously.
+When the actual number of children reaches @var{number}, the server
+stops refusing further connections until any of them terminates. The
+value of @samp{0} means @samp{unlimited}.
+
+The default limit is @samp{128}.
+@end deffn
+
+@deffn {Config} single-process bool
+ Operate in single-process mode. This options may become necessary
+only when debugging the @command{smapd} daemon. @emph{Never use it in
+production environment!}
+@end deffn
+
+@node loadable modules
+@section Loadable 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:
+
+@deffn {Config} module module-id module-name [args]
+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
+
+ 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};
+@item Additional search directories specified by the @code{load-path}
+statement (see below);
+@item Directories specified in the environment variable
+@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
+
+ 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,
+it tries to append the following suffixes to it:
+
+@enumerate 1
+@item the libtool archive suffix @samp{.la}
+
+@item the suffix used for native dynamic libraries on the host
+platform, e.g.: @samp{.so}, @samp{.sl}, etc.
+@end enumerate
+
+ Additional search directories may be configured with the
+@code{load-path} statement:
+
+@deffn {Config} load-path path
+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
+FIXME
+
@node options-smapd
@section Command Line Syntax
Most command line options have two forms, called short and long
@@ -597,7 +828,7 @@ to the end of line are ignored.
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, backlslash character introduces an @dfn{escape
+doubly-quoted string, backslash character introduces an @dfn{escape
sequence}. The following escape sequences are supported:
@float Table, escape-sequences
diff --git a/doc/sockmap.texi b/doc/sockmap.texi
index bcac7c2..60fc0f0 100644
--- a/doc/sockmap.texi
+++ b/doc/sockmap.texi
@@ -49,10 +49,10 @@ Status codes understood by Sendmail are:
@item OK [@var{result}] @tab the key was found; @var{result} contains the
looked up value.
@item NOTFOUND @tab the key was not found
-@item TEMP [@var{reason}] @tab a temporary failure occured; optional
+@item TEMP [@var{reason}] @tab a temporary failure occurred; optional
@var{reason} field contains an explanatory message.
@item TIMEOUT [@var{reason}] @tab same as @samp{TEMP}.
-@item PERM @tab a permanent failure occured
+@item PERM @tab a permanent failure occurred
@end multitable
@end float
@@ -69,10 +69,10 @@ MeTA1 further extends the protocol. The result codes it understands are:
looked up value.
@item NOTFOUND @tab the key was not found
@item NOMORE @tab the key was not found, stop further search
-@item TEMP [@var{reason}] @tab a temporary failure occured; optional
+@item TEMP [@var{reason}] @tab a temporary failure occurred; optional
@var{reason} field contains an explanatory message.
@item TIMEOUT [@var{reason}] @tab same as @samp{TEMP}.
-@item PERM [@var{reason}] @tab a permanent failure occured; optional
+@item PERM [@var{reason}] @tab a permanent failure occurred; optional
@var{reason} field contains an explanatory message.
@end multitable
@end float

Return to:

Send suggestions and report system problems to the System administrator.