diff options
-rw-r--r-- | NEWS | 2 | ||||
-rw-r--r-- | README | 110 | ||||
-rw-r--r-- | README-alpha | 74 | ||||
-rw-r--r-- | configure.ac | 4 | ||||
-rw-r--r-- | doc/smap.texi | 82 | ||||
-rw-r--r-- | src/srvman.c | 2 |
6 files changed, 241 insertions, 33 deletions
@@ -5,7 +5,7 @@ See the end of file for copying conditions. Please send Smap bug reports to <gray+smap@gnu.org.ua> -Version 0.0.94 (Git) +Version 1.0, 2010-06-19 * First release @@ -5,12 +5,21 @@ Copyright (C) 2006, 2007, 2008, 2009, 2010 Sergey Poznyakoff ============== This file contains brief information about configuring, testing -and running Smap. For the time being, it is the only source of -documentation for the project. Real documentation will be -provided in the due course. - -Visit http://puszcza.gnu.org.ua/projects/smap, for additional -information about the project, including pointers to the repository +and running Smap. It is *not* intended as a replacement +for the documentation, and is provided as a brief reference only. +The complete documentation for Smap is available in +the doc/ subdirectory. To read it without installing the package +run `info -f doc/smap.info'. After the package is installed +the documentation can be accessed running `info Smap'. Invoking +`info smapd' will bring you to the description of `smapd' server. +Similarly, running `info smapc' will show the description of `smapc', +a client utility. + +An online copy of the documentation in various formats is available +at http://smap.man.gnu.org.ua. + +Visit http://www.gnu.org.ua/software/smap, for additional +information about the project, including pointers to the source repository and file downloads. * Overview @@ -19,36 +28,83 @@ and file downloads. Socket maps are a mechanism for extending the functionality of Sendmail and MeTA1. +Smap provides a comprehensive set of tools for configuring, testing and +writing socket maps. -* Protocol -========== +Its main component, `smapd', is a modular server which handles socket +map requests. Instead of handling each request itself, `smapd' relies on +loadable modules to provide the requested functionality. In other +words, the server is responsible for handling socket map protocol, and +for dispatching queries to appropriate modules. Modules, in their +turn, are responsible for looking up the requested key and returning +the result. + +Second important part of the package is a set of loadable modules for +`smapd'. These modules cover several important database management +systems and make it possible to easily configure servers for +retrieving data from them. + +Furthermore, the package provides a framework for writing new modules, +either in C or in Guile. + +And finally, Smap includes a client program, `smapc', which can be used +to query arbitrary socket servers from the command line. Beside other +possible uses, smapc is a valuable tool for testing your socket +servers. + +* Building + +Usual building rules apply: + +./configure +make + +Read the file INSTALL for a description of configure utility and its +generic options. Smap-specific options are: + +** --with-tcp-wrappers + +Compile with TCP wrappers (libwrap) support. This is the default. + +** --with-mailutils + +Compile with GNU Mailutils, build the `mailutils' module. By default, +this is enabled if configure determines that a sufficiently new +version of GNU Mailutils (i.e. 2.0 or newer) is installed. + +See http://www.gnu.org/software/mailutils for more information on GNU +Mailutils including file downloads. + +** --with-guile + +Compile with Guile support; build the `guile' module. By default, +this is enabled if configure determines that a sufficiently new +version of Guile (i.e. 1.8 or newer) is installed. + +See http://www.gnu.org/software/guile for additional information on +Guile including file downloads. -A socket map uses a simple request/reply protocol over TCP or UNIX -domain sockets. Both requests and replies are encoded in the -following manner: +** --with-guile-site-dir[=DIR] +Specify a directory to install guile modules to. Without argument -- +use Guile-specific default directory. - <len>:<text>, +** --with-readline -where <text> is the actual payload, and <len> is its length in -bytes, as a decimal number in ASCII representation. The colon -and comma are transmitted verbatim. For example, if <text> is -the string "hello there", then the socket map packet for transmitting -it is: +Compile with GNU readline. This is the default, - 11:hello there, - -** Requests ------------ +* Installing -Requests consist of the "map name" and the actual lookup key, separated -by a single space character. +After build finishes, run -** Replies ----------- + make install -Replies consist of the "status code" and optional data, separated -by a single space character. +If it was the first installation of Smap, it will install a +minimal configuration file (smapd.conf) to your `sysconfdir' +directory. Tailor it to your needs. Read the docs for a detailed +description of its format. +If you are upgrading an old installation, your previous smapd.conf +will remain intact. * Copyright information diff --git a/README-alpha b/README-alpha new file mode 100644 index 0000000..b4e74c8 --- /dev/null +++ b/README-alpha @@ -0,0 +1,74 @@ +This file is part of Smap. +See end of file for copying conditions. + +* Introduction + +This is a *pre-release* version, and not ready for production use yet. +If you are taking source from Git, you will need to have several +special tools to help contribute. See the file README-hacking for more +information. See chapter `Building' for the detailed instructions on +how to build the package. + +Please, note that the accompanying documentation may be inaccurate +or incomplete. The Git logs are the authoritative documentation of +all recent changes. To convert them to the traditional ChangeLog +format, run `make ChangeLog'. + +Send comments and problem reports to <gray+smap@gnu.org.ua>. + +* Checking Out the Sources + +The following instructions apply if you wish to obtain sources from +the Git repository: + +To clone the Smap repository, issue the following command: + + git clone git://git.gnu.org.ua/smap.git + +or + + git clone http://git.gnu.org.ua/repo/smap.git + +This will create a directory named `smap' and populate it with the +sources. + +If you are not interested in the entire development history, you can +abridge it by givint the `--depth' option to clone. For example, + + git clone --depth 2 git://git.gnu.org.ua/repo/smap.git + +will clone only two recent revisions from the repository. + +For more information about Git access, visit +http://puszcza.gnu.org.ua/git/?group=smap + +* Building + +Usual procedures apply: + + ./configure + make + make install + +See INSTALL and README for the detailed instructions. + +* Copyright information: + +Copyright (C) 2010 Sergey Poznyakoff + + Permission is granted to anyone to make or distribute verbatim copies + of this document as received, in any medium, provided that the + copyright notice and this permission notice are preserved, + thus giving the recipient permission to redistribute in turn. + + Permission is granted to distribute modified versions + of this document, or of portions of it, + under the above conditions, provided also that they + carry prominent notices stating who last changed them. + + +Local Variables: +mode: outline +paragraph-separate: "[ ]*$" +version-control: never +End: diff --git a/configure.ac b/configure.ac index 5848e32..4573e78 100644 --- a/configure.ac +++ b/configure.ac @@ -15,9 +15,9 @@ # 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_MAJOR], 1) m4_define([SMAP_VERSION_MINOR], 0) -m4_define([SMAP_VERSION_PATCH], 94) +dnl m4_define([SMAP_VERSION_PATCH], 0) AC_INIT([smap], SMAP_VERSION_MAJOR.SMAP_VERSION_MINOR[]m4_ifdef([SMAP_VERSION_PATCH],.SMAP_VERSION_PATCH), [gray+smap@gnu.org.ua]) diff --git a/doc/smap.texi b/doc/smap.texi index 6faef2c..353c341 100644 --- a/doc/smap.texi +++ b/doc/smap.texi @@ -99,6 +99,7 @@ The Socket Map Server * debugging:: Tracing and Debugging. * privileges:: Runtime Privileges. * servers:: Server Configuration. +* TCP wrappers:: How Network Access is Controlled. * loadable modules:: Loadable Modules. * databases:: Databases. * dispatch rules:: Query Dispatch Rules. @@ -118,6 +119,25 @@ The @samp{mailutils} Module * auth:: Mailutils Auth Mode * mbq:: Mailutils MBQ Mode +The @samp{guile} Module + +* Virtual Functions:: +* Guile Output Ports:: +* Guile Initialization:: +* Guile API:: +@c * Guile Example Module:: + +Socket map client + +* Single Query Mode:: +* Interactive Mode:: +* Initialization File:: +* Smap Invocation:: + +Interactive Mode + +* Command Summary:: + Example: Using @command{smapd} with MeTA1 * userdb-meta1:: Configure local_user_map. @@ -357,6 +377,7 @@ $ smapd --lint --config ./mysmapd.conf * debugging:: Tracing and Debugging. * privileges:: Runtime Privileges. * servers:: Server Configuration. +* TCP wrappers:: How Network Access is Controlled. * loadable modules:: Loadable Modules. * databases:: Databases. * dispatch rules:: Query Dispatch Rules. @@ -543,7 +564,7 @@ groups the user is not member of. This is done using the @code{group} statement: @example -user faemon +user daemon group mail mysql @end example @@ -562,7 +583,7 @@ this technique. @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 +has a @dfn{server id}, which is a unique name associated with it, and @dfn{socket address}, which describes the socket this server handles. @anchor{smap url} @@ -603,6 +624,12 @@ server local unix:///var/run/smap.sock is listening on IP 10.10.1.11, port 3056. The one called @samp{local} listens on UNIX socket @file{/var/run/smap.sock}. +@cindex TCP wrappers + If a server is assigned an @samp{inet} address, access to it will be +controlled by TCP wrappers. The server ID is used as @dfn{daemon +name}. See the next section (@pxref{TCP wrappers}) for a detailed +description. + 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 @@ -715,6 +742,56 @@ be omitted. There are following cases: Note, that this statement cannot be used outside of @code{server} scope. @end deffn +@node TCP wrappers +@section TCP Wrappers +@cindex TCP Wrappers + Access to servers having addresses in @samp{INET} family is +controlled using @dfn{TCP wrappers}@footnote{This feature requires +@command{smapd} to be compiled with the TCP wrappers library +@command{libwrap}. It is always enabled at configure time, unless +@command{libwrap} is absent, or you explicitly disable it.}. + +@findex /etc/hosts.allow +@findex /etc/hosts.deny +@cindex daemon name, TCP wrappers + This system is based on two files, called @dfn{tables}, containing +access rules. There are two tables: the @dfn{allow table}, stored in +file @file{/etc/hosts.allow}, and the @dfn{deny table}, kept in file +@file{/etc/hosts.deny}. The rules in each table begin with an +identifier called @dfn{daemon name}. Access to a Smap server is +controlled by two entries: a @dfn{global one}, with the daemon name +@samp{smapd}, and per-server one, with server ID (@pxref{servers, +server id} as its daemon name. The latter takes precedence over the +former. For example, if you have the following in your +@file{smapd.conf}: + +@example +server main inet://192.168.10.1 +@end example + +@noindent +and wish this server to be accessible only to machines 192.168.10.2 +and 192.168.10.3, then you would add the following line +to your @file{/etc/hosts.allow}: + +@example +main: 192.168.10.2 192.168.10.3 +@end example + +@noindent +and the following line to your @file{/etc/hosts.deny}: + +@example +main: ALL +@end example + +The former allows access from these two IPs, and the latter blocks it +from any other IPs. + +A detailed description of TCP wrapper table format lies outside the +scope of this document. Please, see @ref{ACCESS CONTROL FILES,,ACCESS +CONTROL FILES, hosts_access(5), hosts_access(5) man page}, for details. + @node loadable modules @section Loadable Modules @cindex modules @@ -1157,6 +1234,7 @@ time. If @var{bool} is @samp{yes} send log output to syslog. @end deffn +@anchor{log-tag} @deffn {Config} log-tag string Tag each log line in syslog with @var{string}. By default, the name of the program (@samp{smapd}) is used. diff --git a/src/srvman.c b/src/srvman.c index fed4704..2fd0b45 100644 --- a/src/srvman.c +++ b/src/srvman.c @@ -458,7 +458,7 @@ server_run(int connfd, struct smap_server *srv, { if (sa->sa_family == AF_INET && (!check_acl(srv->id, connfd) - || !check_acl(log_tag, connfd))) + || !check_acl(smap_progname, connfd))) return; if (srvman_param.single_process |