@c This file is part of the Mailfromd manual. @c Copyright (C) 2008, 2009 Sergey Poznyakoff @c See file mailfromd.texi for copying conditions. @c ******************************************************************* @command{Smap} implements a general-purpose configurable @dfn{socket map} for @acronym{MeTA1}. Socket maps are a unique feature of @acronym{MeTA1} that makes it easily extendable. They allow to easily implement new storages for such data as user or alias lists, relay tables etc. The protocol format for socket maps is explained in @uref{http://meta1.org/current/doc/README.html#SECTION001110000000000000000, MeTA1 Socket Maps}. For instructions on how to configure @acronym{MeTA1} to use new socket maps, see @uref{http://meta1.org/current/doc/README.html#SECTION00491000000000000000, Declaring Maps for SMAR}. @menu * smap-conf:: Smap Configuration. * smap-invoke:: Smap Command Line Arguments. * smap-examples:: Examples of Using Smap @end menu @node smap-conf @section Smap Configuration @command{Smap} reads its configuration from the main Mailutils configuration file. @xref{configuration, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}, for a description of GNU Mailutils configuration system. In few words, this means that it reads the configuration from the GNU Mailutils configuration file. It looks for @command{smap}-specific settings in the section @samp{program smap}. The following standard Mailutils statements are understood: @multitable @columnfractions 0.3 0.6 @headitem Statement @tab Reference @item server @tab @xref{Server Settings, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}. @item auth @tab @xref{Auth Statement, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}. @item pam @tab @xref{PAM Statement, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}. @item virtdomain @tab @xref{Virtdomain Statement, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}. @item radius @tab @xref{Radius Statement, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}. @item sql @tab @xref{SQL Statement, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}. @item ldap @tab @xref{LDAP Statement, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}. @item debug @tab @xref{Debug Statement, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}. @item logging @tab @xref{Logging Statement, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}. @item include @tab @xref{Include, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}. @end multitable @command{Smap} uses GNU Mailutils authorization databases to obtain the requested data. This concept is described in detail in @ref{Auth Statement, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}. @deffn {Pmult Conf} user @var{username} After startup switch to the UID and GID of the user @var{username}. Example: @smallexample user meta1m; @end smallexample @end deffn @deffn {Pmult Conf} group @var{groups} When switching to the username privileges, retain also supplementary @var{groups}. The argument is a list of group names or GIDs. Example: @smallexample group (mail, smtp); @end smallexample @end deffn @deffn {Pmult Conf} allgroups @var{bool} If @var{bool} is @samp{true}, retain all supplementary groups of which the user supplied by the @code{user} statement is a member. @end deffn @deffn {Pmult Conf} positive-reply @var{string} If the item is found, reply with the @var{string}. Before replying, @var{string} is subject to the meta-variable expansion, whereby any sequence @samp{$@{@var{variable}@}} is replaced with the value of @var{variable}. Valid variable names and their corresponding values are: @table @asis @item key The lookup key. @item name The @samp{name} field from the retrieved record. @item passwd The @samp{passwd} field from the retrieved record. @item uid The @samp{uid} field from the retrieved record. @item gid The @samp{gid} field from the retrieved record. @item gecos The @samp{gecos} field from the retrieved record. @item dir The @samp{dir} field from the retrieved record. @item shell The @samp{shell} field from the retrieved record. @item mailbox The @samp{mailbox} field from the retrieved record. @item quota The @samp{quota} field from the retrieved record. @end table @end deffn @deffn {Pmult Conf} negative-reply @var{string} If the item is found, reply with the @var{string}. Before replying, any ocurrence of @samp{$@{key@}} in @var{string} is replaced with the actual lookup key. @end deffn @node smap-invoke @section Smap Invocation @table @option @item -d@var{number} @itemx --daemon[=@var{number}] Run in daemon mode with a maximum of @var{number} children. @item --foreground Remain in foreground. @item -i @itemx --inetd Run in inetd mode. @item --negative-reply=@var{string} Overrides the @code{negative-reply} configuration statement (@pxref{smap-conf, negative-reply}). @item --positive-reply=@var{string} Overrides the @code{positive-reply} configuration statement (@pxref{smap-conf, positive-reply}). @item -U @var{name} @itemx --user=@var{name} Overrides the @code{user} configuration statement (@pxref{smap-conf, user}). @item --debug-auth Debug authentication functions. @end table @node smap-examples @section Smap Examples In this section we will show how to use @command{smap} to configure local user and alias maps in @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 instances of @command{smap}. To ensure that each instance is using its proper configuration settings, the program's notion about its name will be changed by using the @option{--program-name} command line option. It is a hidden command line option (i.e. it is not displayed in @command{smap --help} output), which sets the @code{argv[0]} to the value of its argument. In @file{/etc/mailutils.rc} file we will use the statement: @smallexample include /etc/mailutils.d; @end smallexample @noindent where @file{/etc/mailutils.d} is a directory. This means, that @command{smap} will by default look for its configuration in file @file{/etc/mailutils.d/smap}. When invoked as: @smallexample smap --program-name=userdb @end smallexample @noindent it will use the configuration file @file{/etc/mailutils.d/userdb}. Since both maps use @acronym{SQL} as the storage engine, they will share some configuration settings. Namely, we will put the following stanza to the main configuration file (@file{/etc/mailutils.rc}): @smallexample @group auth @{ authentication clear; authentication sql; authorization clear; authorization sql; @} @end group @end smallexample @menu * smap-userdb:: Configure local_user_map. * smap-aliases:: Configure aliases. @end menu @node smap-userdb @subsection Configure local_user_map. This section shows an example of configuring @command{smap} for @dfn{local_user_map}. The user data are stored in the table @samp{userdb}. It has the following structure: @smallexample @group CREATE TABLE userdb ( user varchar(32) NOT NULL default '', mailbox text PRIMARY KEY (user) ); @end group @end smallexample @command{Smap} will be started using the following command line: @smallexample smap --program-name smap-userdb @end smallexample Now, we can write the @file{/etc/mailutils.d/smap-userdb} configuration file. Let's start from the @samp{sql} statement. Mailutils requires that the @code{getpwnam} query return at least six fields, whereas the @code{userdb} contains only two columns. So we will need to supply defaults for the remaining four: @smallexample sql @{ interface mysql; host sql.host.name user smap; passwd guessme; db mail; getpwnam "SELECT user as name, 'x' as passwd,10000 as uid, 10000 as gid, " "'/nonexistent' as dir, '/sbin/nologin' as shell " "FROM userdb WHERE user='$@{user@}'"; @}; @end smallexample Positive reply will return the value of the @code{user} column: @smallexample positive-reply "$@{name@}"; @end smallexample The rest of statements instructs @command{smap} on how to start up: @smallexample user meta1m; mode daemon; pidfile /var/run/smap-userdb.pid; server unix:///var/spool/meta1/smap/userdb @{ transcript yes; # @r{Good for debugging}. @} @end smallexample The @command{smap} configuration file is finished. Now we need to inform @acronym{MeTA1} about the new map. To do so, we add the following to the configuration file @file{/etc/meta1/meta1.conf}, section @samp{smar}: @smallexample map password @{ type = passwd; @} map userdb @{ type = socket; path = "/var/spool/meta1/smap/userdb"; mapname = userdb; @} map locusr @{ type = sequence; maps = @{ password, userdb @}; @} local_user_map @{ name = "locusr"; flags = @{ localpart, local_domains @}; @} @end smallexample As a result, @acronym{MeTA1} will look up users in the system database first, and, if that fails, in the @acronym{SQL} database. @node smap-aliases @subsection Configure aliases Aliases are stored in the table @samp{aliases} which has the following structure: @smallexample @group CREATE TABLE userdb ( user varchar(32) NOT NULL default '', alias text PRIMARY KEY (user) ); @end group @end smallexample @command{Smap} will be started using the following command line: @smallexample smap --program-name smap-aliases @end smallexample The @file{/etc/mailutils.d/smap-aliases} configuration file is similar to that described in the previous subsection: @smallexample # The smap-aliases configuration file user meta1m; mode daemon; pidfile /var/run/smap-aliases.pid; server unix:///var/spool/meta1/smap/aliases @{ transcript yes; @} positive-reply "$@{name@}"; sql @{ interface mysql; host sql.host.name user smap; passwd guessme; db mail; getpwnam "SELECT alias as name, 'x' as passwd,1 as uid, 1 as gid, " "'/nonexistent' as dir, '/sbin/nologin' as shell " "FROM aliases WHERE name='$@{user@}'"; @} @end smallexample The corresponding part in @file{/etc/meta1/meta1.conf} file is: @smallexample map lum @{ type = socket; path = "/var/spool/meta1/smap/aliases"; mapname = aliases; @} map stdal @{ file = "aliases.db"; type = hash; @} map aliasmap @{ type = sequence; maps = @{ lum, stdal @}; @} aliases @{ name = aliasmap; flags = @{ localpart, local_domains @}; @} @end smallexample