1 files changed, 213 insertions, 0 deletions
diff --git a/doc/ex-meta1.texi b/doc/ex-meta1.texi
new file mode 100644
index 0000000..905e135
--- /dev/null
+++ b/doc/ex-meta1.texi
@@ -0,0 +1,213 @@
+@c This file is part of the Smap manual.
+@c Copyright (C) 2010 Sergey Poznyakoff
+@c See file smap.texi for copying conditions.
+@c *******************************************************************
+  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.
+
+@menu
+* userdb-meta1::  Configure local_user_map.
+* aliases-meta1:: Configure aliases.
+* smapd-meta1::   Smapd configuration.
+* conf-meta1::    Configure MeTA1.
+@end menu
+
+@node userdb-meta1
+@appendixsec Configure local_user_map.
+
+Let's configure @samp{local_user_map} first.  User data will be
+stored in the table @samp{userdb}, which has the following structure:
+
+@example
+@group
+CREATE TABLE userdb (
+  user varchar(32) NOT NULL default '',
+  mailbox text
+  PRIMARY KEY (user)
+);
+@end group
+@end example
+
+Module configuration file @file{/etc/mailutils.d/meta1-userdb}
+begins with the following stanza:
+
+@example
+@group
+auth @{
+  authentication clear;
+  authentication sql;
+  authorization clear;
+  authorization sql;
+@}
+@end group
+@end example
+
+This clears any previous settings that the authorization engine might
+have read from the main configuration file, and requests that only
+@samp{sql} method be used for both authentication and authorization.
+
+Now, we need to supply a @samp{sql} statement.  Mailutils requires
+that the @code{getpwnam} query return at least six fields, whereas the
+@samp{userdb} table contains only two columns.  So we will need to supply
+defaults for the remaining four:
+
+@example
+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 example
+
+  That's all we need to have in @file{/etc/mailutils.d/meta1-userdb}.
+
+@node aliases-meta1
+@appendixsec Configure aliases
+
+We are going to store aliases in the table @samp{aliases} which has
+the following structure:
+
+@example
+@group
+CREATE TABLE userdb (
+  user varchar(32) NOT NULL default '',
+  alias text
+  PRIMARY KEY (user)
+);
+@end group
+@end example
+
+It will be served by @samp{alias} database, which will read
+the configuration for Mailutils from the file
+@file{/etc/mailutils.d/meta1-alias}.  This file is similar to
+@file{meta1-userdb}, but uses a different query in its @samp{sql}
+section:
+
+@example
+auth @{
+  authentication clear;
+  authentication sql;
+  authorization clear;
+  authorization sql;
+@}
+
+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 example
+
+@node smapd-meta1
+@appendixsec Smapd configuration
+
+  Let's now configure @file{smapd.conf}.  Suppose it will run a single
+server, which we will call @samp{local}.  The server will listen on a
+UNIX socket @file{/var/spool/meta1/smap/userdb}.  It is important that
+@samp{meta1} be able to read from and write to that socket, so we will make
+it owned by user @samp{meta1m}:
+
+@example
+server local unix:///var/spool/meta1/smap/userdb begin
+ user meta1m
+end
+@end example
+
+  Next task is to configure the databases.  The @samp{userdb} database is
+pretty simple:   
+
+@example
+database userdb mailutils mode=auth \
+         config-file=/etc/mailutils.d/meta1-userdb
+@end example
+
+  It will return @samp{OK} if the user is found in the database and
+@samp{NOTFOUND} otherwise, which is exactly what the @acronym{MTA} needs.
+
+  The @samp{aliasdb} database is a bit different.  In case of a
+positive reply, it must return the expanded alias value, so we need to
+supply a new @samp{positive-reply} template:
+
+@example
+database aliasdb mailutils mode=auth \
+         config-file=/usr/local/etc/mailutils.d/meta1-alias \
+         positive-reply="OK $@{name@}"
+@end example
+
+  The @samp{$@{name@}} will be replaced with the value of the first
+column in the tuple returned by the @acronym{SQL} database
+(@pxref{aliases-meta1, getpwnam}).
+
+  To dispatch queries to these databases, the following rules will
+suffice:
+
+@example
+dispatch map alias database aliasdb
+dispatch map userdb database userdb
+@end example
+
+@node conf-meta1
+@appendixsec MeTA1 configuration
+
+  Finally we need to inform @acronym{MeTA1} about new maps.  This is
+done in the file @file{/etc/meta1/meta1.conf}, section @samp{smar}.
+
+  First, the @samp{userdb} map:
+
+@example
+  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 example
+
+As a result, @acronym{MeTA1} will look up users in the system database
+first, and, if that fails, in the @acronym{SQL} database.
+
+  Next, the @samp{aliasdb} map:
+
+@example
+  map lum @{
+        type = socket;
+        path = "/var/spool/meta1/smap/userdb";
+        mapname = aliases;
+  @}
+  map stdal @{ file = "aliases.db"; type = hash; @}
+  map aliasmap @{ type = sequence; maps = @{ lum, stdal @}; @}
+  aliases @{
+        name = aliasmap;
+        flags = @{ localpart, local_domains @};
+  @}
+@end example
+  
+  As for @samp{userdb}, this map declaration also uses two different
+databases.  First, it asks @command{smapd} to find the alias.  If it
+returns a negative reply, the map falls back to the default
+@file{aliases.db} database.
+
+