Provided by: perdition_1.19~rc4-4build1_i386 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)