Provided by: perdition_2.2-3ubuntu2_amd64 bug

NAME

       perditiondb - perdition modular popmap support

DESCRIPTION

       Perdition  supports a dynamic library mechanism to access arbitrary databases that resolve
       a user to a host and port.

DATABASE ACCESS LIBRARIES

       If you are using the -s|--default server option then creating an empty database will cause
       all  users to use the default server. Alternatively, setting no popmap by passing an empty
       string to the -m|--map_name option will cause no map lookups to take place  and  only  the
       default server to be used.

       E.g.: perdition -m ""

       In this case, if no default server is set then perdition will still run but users will not
       be able to connect to a real server.

       GDBM

       This is the default library used by perdition.  The gdbm library  reads  server  and  port
       information  from  a  GDBM database. The database is opened each time perdition looks up a
       server and port pair.  The information for each lookup key  is  stored  in  a  flat  file,
       popmap with the format:

       <key>:[<username><domain_delimiter>]<host>[:<port>]

       Where: host: hostname or ip address
              port: port name or number

       E.g.

       horms:foo.bar:110
       jain:jane@foo.bar

       A  domain_delimiter of "@" is used in the example above.  For more information on keys and
       the domain delimiter, see perdition(8).

       If the -n|--no_lookup option is in effect, then ip addresses and port names should be used
       as host and port names will not be resolved.

       To  build  the  flat  file into a binary format the makegdbm utility, which is provided as
       part of perdition should be used.

       makegdbm popmap.gdbm.db < popmap

       A makefile is provided and you can  simply  run  make  to  rebuild  the  popmap.  This  is
       installed into /etc/perdition/ in the RPM and Debian distributions.

       An   alternate   location   for   the   popmap.gdbm.db   can   be   specified   using  the
       -m|--map_library_opt command line option or configuration file option.

       E.g.

       perdition -m /etc/my_popmap.gdbm.db

       This map library is the default. It may also be used explicitly, used  by  specifying  the
       full  path  to the library using the -M|--map_library command line option or configuration
       file option.

       E.g.

       perdition -M /usr/lib/libperditiondb_gdbm.so.0

       Where /usr/lib is the directory in which the perdition libraries were installed.

       Berkeley DB

       This is analogous to the GDBM library, except that a popmap.bdb.db should be created using
       makebdb.

       This  library  may  be  used  by  specifying  the  full  path  to  the  library  using the
       -M|--map_library command line option or configuration file option.

       E.g.

       perdition -M /usr/lib/libperditiondb_bdb.so.0

       Where /usr/lib is the directory in which the perdition libraries were installed.

       YP/NIS

       The NIS library reads a YP/NIS map, the key is the userid, the value is the servername.

       The default map name is 'user_mail_server', and can be changed by specifying the map  name
       with the -m flag.

       To use this library, you need to specify:

       perdition -M /usr/lib/libperditiondb_nis.so.0

       Where /usr/lib is the directory in which the perdition libraries were installed.  You will
       need to customise your yp server's Makefile to actually get a new map on the server.  This
       map  library  is  intended  for sites that already have a significant infrastructure based
       around YP/NIS.

       POSIX REGULAR EXPRESSIONS

       This library allows users to be looked matched against a list of regular expressions.

       This library  can  be  used  by  specifying  the  full  path  to  the  library  using  the
       -M|--map_library command line option or configuration file option.

       E.g.

       perdition -M /usr/lib/libperditiondb_posix_regex.so.0

       Where /usr/lib is the directory in which the perdition libraries were installed.

       The  regular  expression  is kept in a flat file, by default /etc/perdition/popmap.re .  A
       sample map file is shipped with the source and can be  found  in  etc/perdition/popmap.re,
       this  is installed into /etc/perdition/popmap.re in the RPM and Debian distributions.  The
       format for the flat file is:

       <regular expression>: [<username><domain_delimiter>]<server>[:<port>]

       A single colon may follow a regular_expression Some amount of white space must follow this
       colon  or  the regular_expression if the colon is omitted.  Blank lines are ignored, as is
       anything including and after a # (hash) on a line. If a  precedes  a  new  line  then  the
       lines  will  be concatenated.  If a  precedes any other character, including a # (hash) it
       will be treated as a literal. Anything inside single quotes  (')  will  be  treated  as  a
       literal.  Anything other than a (') inside double quotes (") will be treated as a literal.
       Whitespace in a regular_expression must be escaped or quoted. Whitespace in a substitution
       need not be escaped or quoted.

       Information  on setting the domain_delimiter is found in perdition(8), "@" is used in this
       example.

       E.g.

       ^[a-k]: localhost
       ^[^a-k]: localhost:110
       ^user: user2@localhost
       (.*)@(.*): $1_$2@localhost

       The first matching regular expression will be used. The regular expressions  are  extended
       posix   regular   expressions.   The  last  example  illustrates  the  ability  to  expand
       backreferances.  Backreferences may be used by inserting $n in the substitution where n is
       in the range 1..9.  The backreference substitution code in this library is courtesy of Wim
       Bonis and in turn the PHP3 project.

       E.g.

       For the regex (.*)@(.*): $1_$2@localhost
       user@x.y.z.de
       would return
       user_x.y.z.de@localhost

       Note that there is no implicit ^ or $ around the regular  expressions.  The  popmap  entry
       "flim:  localhost" will match "flim", "flimstix", "itsflim" and "totallyflimless". To only
       match "flim" you need the popmap entry "^flim$: localhost".

       The map file is read once on startup and cached. This is to increase  performance  as  the
       regular  expressions must be compiled internally before they can be used. The map file can
       be re read by sending perdition a SIGHUP. An alternate location for the popmap.re  can  be
       specified using the -m|--map_library_opt command line option or configuration file option.

       E.g.

       perdition -m /etc/perdition/my_popmap.re

       MYSQL

       This  map  library  can  be  used  by  specifying  the  full path to the library using the
       -M|--map_library command line option or configuration file option.

       E.g.

       perdition -M /usr/lib/libperditiondb_mysql.so.0

       Where /usr/lib is the directory in which the perdition libraries were installed.

       The library will connect to a MySQL database and do a query on a table  expected  to  have
       the columns:

       +------------+--------------+------+-----+---------+-------+
       | Field      | Type         | Null | Key | Default | Extra |
       +------------+--------------+------+-----+---------+-------+
       | user       | varchar(128) |      | PRI |         |       |
       | servername | varchar(255) |      |     |         |       |
       | port       | varchar(8)   | YES  |     | NULL    |       |
       +------------+--------------+------+-----+---------+-------+

       The fields may be in a different order and other, non-perdition fields may also be present
       in this table. The names of the columns can be other than their above  defaults  by  using
       the  library option string described below.  All fields must be literal character strings.
       The allowed length of the strings is not important, however, it is  recommended  that  the
       length  of  the user field be kept under 128 to avoid exceeding perdition's internal query
       length limit, PERDITIONDB_MYSQL_QUERY_LENGTH which is 256 by default. This may be  altered
       by  recompiling  perdition.   The user field must also be a unique index as an exact match
       will be made of this field from the username supplied by the user.

       The servername is of the form.

       [<username><domain_delimiter>]<host>[:<port>]

       Where: host: hostname or ip address
              port: port name or number

       If the -n|--no_lookup option is in effect then ip addresses and  port  numbers  should  be
       used as host and port names will not be resolved.

       The port is the TCP port to use when connecting to the server. This field can be specified
       if the back-end server answers on a non-standard port (standard ports being 110  for  POP3
       and  143  for  IMAP). Only specify this field in the database if you intend to use POP3 or
       IMAP exclusively as it will try to use this port no matter what protocol is being used. If
       POP3  and  IMAP are both being used on non-standard back-end server ports, those ports can
       be specified with the -p argument when you invoke the perdition executable.

       The database is accessed each time perdition needs to find the host and port for  a  user.
       The default database values are as follows:

       database host:     localhost
       database port:     (MySQL Client Default: usually 3306)
       database name:     dbPerdition
       database table:    tblPerdition
       database user:     perdition
       database password: perdition
       user column:       user
       server column:     servername
       port column:       port

       A  script, perditiondb_mysql_makedb, is provided to initialise such a database.  Alternate
       values can be set using the -m|--map_library_opt command line option or configuration file
       option  with  an  argument  of the following form. (N.B.: this example has been split over
       multiple lines for ease of reading)

       <dbhost>[:<dbport>[:<dbname>[:<dbtable>[:<dbuser>
       [:<dbpwd>[:<dbservercol>[:<dbusercol>[:<dbportcol>]]]]]]]]

       E.g.

       perdition -m "some.host.com:3306:aDb:bTable:cUser:"\
       "dPassword:eSrvCol:fUserCol:gPortCol"

       Arguments may be omitted from the end of the option string with no consequence other  than
       that the default value for any omitted argument will be used. Arguments may not be omitted
       if any argument to its right is defined. Someone  seeking  to  set  only  the  server  and
       password to something other than the default might attempt the following:

       perdition -m some.host.com:::::OddPassword

       This  will  not  work.  It  will  set the server and password to the values shown, but all
       arguments in between will be set as NULL rather than the default. In the author's  opinion
       it is always best to specify all of the arguments to avoid confusion.

       Database  servers  may  be grouped together for higher performance or high availability by
       using ODBC and accessing them using the ODBC module.

       Multiple MySQL Servers

       It is possible to specify multiple MySQL  servers  by  specifying  them,  comma  separated
       (without any space), in the dbhost column.  In this case all MySQL servers need to have an
       identical configuration, because all other options are shared.  If the first server is not
       reachable, perdition will fall back to the second etc.

       POSTGRESQL

       This  is  a port of the MySQL library to PostgreSQL, The library can be used by specifying
       the  full  path  to  the  library  using  the  -M|--map_library  command  line  option  or
       configuration file option.

       E.g.

       perdition -M /usr/lib/libperditiondb_postgresql.so.0

       Where  /usr/lib  is  the  directory  in  which  the perdition libraries were installed.  A
       script, perditiondb_postgresql_makedb is provided to initialise the  database.   For  more
       information please see the MySQL documentation above.

       ODBC

       This  is  a  port of the MySQL library to ODBC. It may be used to access databases that do
       not have a perditiondb module.  It may  also  be  used  to  group  database  servers  into
       clusters.

       The  library  can  be  used  by  specifying  the  full  path  to  the  library  using  the
       -M|--map_library command line option or configuration file option.

       E.g.

       perdition -M /usr/lib/libperditiondb_odbc.so.0

       Where /usr/lib is the directory in  which  the  perdition  libraries  were  installed.   A
       script,  perditiondb_odbc_makedb is provided to seed the.  For more information please see
       the MySQL documentation above.  The database options passed using -m are the same  as  for
       MySQL except that the database name (dbname) is the Data Source Name (DSN).

       <dbhost>[:<dbport>[:<DSN>[:<dbtable>[:<dbuser>
       [:<dbpwd>[:<dbsrvcol>[:<dbusercol>[:<dbportcol>]]]]]]]]

       E.g.

       perdition -m "some.host.com:3306:aDb:bTable:cUser:"\
       "dPassword:eSrvCol:fUserCol:gPortCol"

       As per the notes in the MySQL documentation above, please avoid omitting values.

       LDAP

       This  library  allows access to LDAP based popmaps. This library can be used by specifying
       the  full  path  to  the  library  using  the  -M|--map_library  command  line  option  or
       configuration file option.

       E.g.

       perdition -M /usr/lib/libperditiondb_ldap.so.0

       Where /usr/lib is the directory in which the perdition libraries were installed.

       Options  are  parsed  to this module using the -m|--map_library_opt command line option or
       configuration file option.  It has the form:

       [ldap_version:][ldap_url]

       The ldap_version is the version of the ldap procotol used.  It should be a numeric  value.
       At the time of writing, OpenLdap supports 2 or 3, and defaults to 2. This may vary between
       different ldap implementations. If you inspect  the  local  ldap.h  file,  the  values  of
       LDAP_VERSION_MIN,  LDAP_VERSION_MAX  and  LDAP_VERSION should reflect the minimum, maximum
       and default ldap protocol versions respectively.

       The ldap_url is the query made to the ldap server.  The default URL is  as  follows.  Note
       that this has been split onto multiple lines for ease of reading.

       ldap://localhost/ou=mailbox,dc=nodomain?
       username,mailhost,port?one?(uid=%s)

       Perdition  will  replace  any  instance  of  %s  with  the  key being used for the lookup.
       Optionally, there may be an integer between the % and the s, in which case the key will be
       white-space padded to this width, with the key right justified.

       The attribute names (username, mailhost and port) may be changed.  But the first attribute
       will be used as the username, the second attribute as the host and the third  atribute  as
       the  port.  Any  subsequent  attributes  will be ignored.  Trailing attributes may also be
       omitted. So if there are only two attributes the port will not be read from the database.

       A script, perditiondb_ldap_makedb is provided to initialise LDAP.

       x-bindpw bindname

       Perdition can be configured to use use  an  alternate  bind  name,  and  the  non-standard
       "x-bindpw".  In  fact  perdition  can  use  any extensions that are supported by openldap.
       (N.B.: these examples have been split over multiple lines for ease or reading)

       ldap://ldap.mydomain.com/o=domain.com?
       uid,mailhost,port?sub?(uid=%s)?!bindname=uid=perdition%2co=domain.com

       ldap://ldap.mydomain.com/o=domain.com?uid,mailhost,port?
       sub?(uid=%s)?!BINDNAME=uid=perdition%2co=domain.com,X-BINDPW=secret

       The first example does the usual LDAP lookup,  but  tries  to  bind  to  the  server  with
       "uid=perdition,o=domain.com"  rather  than  the usual anonymous binding.  Note: The commas
       inside the bind string itself must be URL encoded, thus the %2c.

       The second example is the same as the first, but in addition to specifying a  bind  string
       it  also  uses  the  non-standard "x-bindpw" extension to specify a password, in this case
       "secret".

       The "!" character is used to ensure Perdition supports the "bindname"  extension.   If  it
       didn't,  the  LDAP  connection would be aborted.  Right now it isn't really needed, but it
       may become useful as other extensions appear.  For full details of this, take  a  look  at
       RFC2255.

       Multiple LDAP Servers

       It  is  possible  to specify multiple LDAP servers by specifying them, space delimited, in
       the LDAP UDL. If this is the case an attempt will be made to open  a  connection  to  each
       host in order, the first host to which a connection is successfully made will be used.

       For example: (N.B.: this example has been split over multiple lines for ease or reading)

       ldap://host1 host2 host3/ou=mailbox,dc=nodomain?
       username,mailhost,port?one?(uid=%s)

       perdition.schema

       A  schema has been defined for perdition and is supplied as part of perdition. To use this
       you should install it on the LDAP server in the LDAP daemon's schema directory and include
       it in slapd.conf, after other includes and before any database definitions.

LIBRARY FUNCTIONS

       The  database  is accessed using the dlopen(3) mechanism on a library.  The library should
       define the symbol dbserver_get with the following semantics.

       int (*dbserver_get)(char *, char *, char **, size_t *)

       Find the server (value) given the user (key)

       pre:   key_str: Key as a null terminated string

              options_str: Options string. The usage of this is implementation dependent.

              str_return: Value is returned here

              len_return: Length of value is returned here

       post:  The str_key is looked up and the corresponding value is returned in str_return  and
              len_return.

       return:
              0 on success

              -1  on db access error This includes file, connection and other data access errors.
              It does not cover memory allocation problems.

              -2 if key cannot be found in map

              -3 on other error

       Note:  The string returned in str_return should be in the  following  form.   Setting  the
              domain_delimiter is discussed in the perdition(8), "@" is used in this example.

              [<username><domain_delimiter>]<servername>[:<port>]

              E.g.:

              localhost:110
              user@localhost:110
              user@localhost
              localhost

       As  the  library  is  opened  using  the  dlopen(3)  mechanism the library may also export
       functions _init and _fini that will be executed when the  library  is  opened  and  closed
       respectively.   In  addition  if the symbols following  symbols are defined then these are
       run when the library is opened and closed respectively.  If defined these  symbols  should
       have the following semantics.

       int *(*dbserver_init)(char *)

       Initialise db as necessary

       pre:   options_str: Options string. The usage of this is implementation dependent.

       post:  db is initialised

       return:
              0 on success

              -1  on db access error This includes file, connection and other data access errors.
              It does not cover memory allocation problems.

              -2 if key cannot be found in map

              -3 on other error

       int *(*dbserver_fini)(void)

       Shut down db as necessary

       pre:   none

       post:  db is shut down

       return:
              0 on success

              -1 on db access error This includes file, connection and other data access  errors.
              It does not cover memory allocation problems.

              -2 if key cannot be found in map

              -3 on other error

       In  addition,  if  a  SIGHUP  is  sent  to  a  process  then  a  signal  handler will call
       dbserver_fini  if  it  is  defined  and  then  dbserver_init  if  it  is  defined.   Note:
       dbserver_init will be called if defined, even if dbserver_fini is not defined.

       In  the  case of the posix regular expressions library this will cause popmap.re to be re-
       parsed, hence effecting any changes that have been made to that file. For the GDBM library
       it  will  reopen  the  database  and  for  the  other  libraries  it will reinitialise its
       connection to the database, LDAP or NIS server.

       The shared library has access to the following global symbols exported by perdition.

       struct utsname *system_uname
              The uname information for the system as per uname(2)

       struct sockaddr_in *peername
              The sockaddr_in for address and port of the client end of the connection.

       struct sockaddr_in *sockname
              The sockaddr_in for the local address and port that the client connected to.  Note:
              Under  Solaris  7  and  above,  this  is actually the sockaddr_in bound to, not the
              address and port the connection was accepted on.

SEE ALSO

       perdition(8),    makegdbm(1),    makebdb(1),     make(1),     perditiondb_mysql_makedb(8),
       perditiondb_postgresql_makedb(8) perditiondb_ldap_makedb(8), perditiondb_odbc_makedb(8)

AUTHORS

       Lead
       Horms <horms@vergenet.net>

       Perditiondb Library Authors
       Frederic Delchambre <dedel@freegates.be>      (MySQL)
       Chris Stratford: <chriss@uk.uu.net>           (LDAP and BDB)
       Nathan Neulinger <nneul@umr.edu>              (NIS)

       Contributing Authors
       Daniel Roesen <droesen@entire-systems.com>
       Clinton Work <work@scripty.com>
       Youri <ya@linkline.be>
       Jeremy Nelson <jnelson@optusnet.com.au>
       Wim Bonis <bonis@solution-service.de>
       Arvid Requate <arvid@Team.OWL-Online.DE>
       Mikolaj J. Habryn <dichro@rcpt.to>
       Ronny Cook <ronny@asiaonline.net>
       Geoff Mitchell <g.mitchell@videonetworks.com>
       Willi Langenberger <wlang@wu-wien.ac.at>
       Matt Prigge <mprigge@pobox.com>
       Wolfgang Breyha <wolfgang.breyha@uta.at>

                                         6th August 2003                           PERDITIONDB(5)