Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PERDITIONDB(5)		      File Formats Manual		PERDITIONDB(5)

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  op-
       tion  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	infor-
       mation 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 in-
       formation 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 us-
       ing the -M|--map_library	command	line option or configuration file  op-
       tion.

       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 spec-
       ifying 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 ac-
       tually 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	 regu-
       lar expressions.

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

       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/perdi-
       tion/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/perdi-
       tion/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 es-
       caped 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 expres-
       sions  are  extended posix regular expressions. The last	example	illus-
       trates 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", "its-
       flim"  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 be-
       fore 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 us-
       ing 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 de-
       scribed below.  All fields must be literal character strings.  The  al-
       lowed  length  of  the  strings is not important, however, it is	recom-
       mended that the length of the user field	be kept	under 128 to avoid ex-
       ceeding	  perdition's	 internal    query    length   limit,	PERDI-
       TIONDB_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	exclu-
       sively 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 con-
       sequence	 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_li-
       brary 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 ini-
       tialise the database.  For more information please see the MySQL	 docu-
       mentation 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 us-
       ing the -M|--map_library	command	line option or configuration file  op-
       tion.

       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 omit-
       ting 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_li-
       brary 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 com-
       mand 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  implementa-
       tions.  If  you	inspect	the local ldap.h file, the values of LDAP_VER-
       SION_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  at-
       tributes	 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	anony-
       mous 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	speci-
       fying 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	exten-
       sions 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	 prob-
	      lems.

	      -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	perdi-
	      tion(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	 prob-
	      lems.

	      -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	 prob-
	      lems.

	      -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 db-
       server_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  connec-
	      tion was accepted	on.

SEE ALSO
       perdition(8),	  makegdbm(1),	   makebdb(1),	   make(1),	perdi-
       tiondb_mysql_makedb(8),	   perditiondb_postgresql_makedb(8)	perdi-
       tiondb_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)

NAME | DESCRIPTION | DATABASE ACCESS LIBRARIES | LIBRARY FUNCTIONS | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=perditiondb&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help