Provided by: perdition_1.18-2build1_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)