diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2010-06-18 00:38:29 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2010-06-18 00:38:29 +0300 |
commit | e7f908a280718546f9690337e65e7bc8ac9364d6 (patch) | |
tree | 340a0cb47e9b89290e6cbd4f30b4e83e8ca0fac8 /doc | |
parent | 26959487f551abc36f85eb8b5577edd1abca7f8f (diff) | |
download | smap-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.texi | 241 | ||||
-rw-r--r-- | doc/sockmap.texi | 8 |
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 |