home.conf

home.conf - format of libhome configuration file

The home.conf file is used to set parameters to libhome.

Format

Lines begining by "#", empty lines, blanks lines are skipped. First blanks of lines are ignored. Directives are on remaining lines who are read one by one.

Directive selection

Certains directives could be used by certains programs only. It’s done by interting them after a tag with program name enclosed by

  [program1]
  # lines below will be executed by ’program1’ only

It’s possible to specify several programs by separating them by commas (’,’). Also, an asterisk at the end on a program name allow program with the same prefix :

 [bar,foo*]
 # lines below will be executed by ’bar’
 # and program with name begining with ’foo’

Connection type

mode [mysql|pgsql|ldap|system|pam]

Connect to the specified type of database. default is mysql.

MySQL connection directives

This directives indicate how to connect to MySQL databases.

myuser account

use this account to connect to the database

mypasswd password

use this password to connect

myhosts host1 host2 ...

list of hosts to connect. If the first does not respond, the library use the second, etc..

mydatabase db

Name of the MySQL database containing informations.

Postgresql connection directives

This directives indicate how to connect to Postgresql databases.

pg_user account

use this account to connect to the database

pg_passwd password

use this password to connect

pg_hosts host1 host2 ...

list of hosts to connect. If the first does not respond, the library use the second, etc..

pg_database db

Name of the PgSQL database containing informations.

MySQL and Postgresql common directives

table name

name of the table used for the SQL query

backtime seconds

maximum number of seconds the connection will use backup hosts. When the limit is reached, a connection will be retried to the first host.

LDAP connection directives

ld_hosts hosts

list of LDAP host to try connect to

ld_passwd passwd

password in use to connect to LDAP server

ld_dn DN

the DN entry to bind

ld_base regexp substitution

list of regexp to determine the DN to start the search from the canonified user name. If a user name match a regexp,

ld_version [0|2|3]

Set the version of LDAP protocol to use. If 0 (default), use the default API version.

ld_crypt [yes|on|off|true|false|0|1...]

Crypt the returned password with crypt(3) if not already crypted.

ld_timeout secs

Define timeout in seconds for misc LDAP operations. When set to 0 (default), no timeout is used and operation may take theyre time.

ld_extra_attributes attr ...

Space separated list of extra LDAP attributes to be retrieved for string expansion.

System database method

sys_shadow [1|0]

set to 1 if you want to use shadow password information in system mode.

PAM authentification method

PAM method is only able to check if an user exist. Password, UID, GID, homedir, shell, etc are not avaiable with this method. You have to set them using "passwd", "uid", "gid", "home", "shell", etc. configuration command and rebuild a home with "hash".

pam_service service_name

set to the name of the PAM service (default is "other")

Field comparison and selection

The following directives are used to contruct the SQL queries.

user field

field used to retrieve the user name pw_name

passwd field

field used to retrieve the password pw_passwd. Value will be rewritten with passwd_rew directive. If the retrived password is empty, the library will responds as if the user doesn’t not exists.

home field

field used to retrieve the user home directory informations. This field will be rewritten using the hash directive described below

uid field

field or attribute used to retrieve the user ID pw_uid

gid field

field or attribute used to retrieve the user group ID pw_gid

gecos field

field or attribute used to retrieve the user full name pw_gid

shell something

field or attribute used to retrieve the user shell pw_gid

class field

field or attribute used to retrieve the user class pw_class

expire field

field or attribute used to retrieve the user expiration time pw_expire The returned value will be parsed by strptime according format defined in expire_fmt directive.

quota field

field or attribute used to retrieve the user disk quota pw_quota The returned value will be multiplied by quota_unit to return quota in bytes.

where field

field or attribute to compare with the canonified user name. default is the same as user

conditions MySQL or PGSQL directives or LDAP filter

checks for additionnal conditions in requests

alias field

field containing a canonified user name will be used to get the informations. If alias is not empty, another query will be done using the alias. If the aliased user is hisself an alias and the user will not be found. Alias resolution is made before fallback.

Within LDAP mode, the filter will be build using the where and conditions directives like this :

(&( where = %s ) conditions )

where %s is the LDAP-escaped canonified user name. If an attribute directive ( user, passwd ... ) is enclosed by simple or double quote, the librarie returns the unquoted string instead of the attribute value.

Within MySQL or PgSQL mode, the query wil be build like this :

SELECT ... FROM table WHERE where = ’%s’ and conditions

User canonification and entries rewriting

Requests in the databases are using canonified user names for comparisons. To canonify a user name, the library pass the name into rewrite regexp, then its case could be lowered ou uppered according usercase directive. Finally, it could be replaced by the value of some DB databases specified in rewritedb

rewrite regexp substitution

used to canonify the user name. If the username match the regexp, it’s replaced according substitution string. Regexp are extented case insensitive regular exepression. Within substitution $1, $2, ... are replaced by first, second.. parenthesis group. When substitution is empty, getpwnam will NULL. It could have more than once rewrite directives

fallback regexp substitution

When the user is not found in the database, the canonical name is rewritten using the fallback regexp list and another match is tried. When no fallback directive is set or a directive has a empty substitution for certains users, getpw* routines return than this users are not found.

usercase [lower|upper|none]

Ensure the canonified username is lowercase, uppercase or untouched.

rewritedb [database ...]

Rewrite the user name according DB3 databases.

hash regexp substitution

Rewrite the user name returned by the request (pw_name) to get the home directory and append the user home directory information (from the home directive). If user home directory information has the form ~someuser[/path], someuser will be used for rewritting instead of the canonified user name. If user home directory information is an absolute file name, nothing is rewritten. It could have more than once hash directives. Final home directory must be defined and must begin by ’\’.

passwd_rew [regexp list]

Rewrite the password according given regural expressions. If some expression has a null substitution, the library will return as if the user does not exists

crypt_always_crypted boolean

Indicate the internal crypt(3) subroutine that the password is alway crypted. Default is false, a password is clear text unless it’s prefixed by "{crypt}". Value is alway true in system mode.

quota_unit integer

Multiply the returned quota value by this integer to return bytes. default is 1 (one byte).

expire_fmt [strptime format]

The value returned by the expire directive will be parsed (by strptime(3)) using this format. If expire_fmt is not defined, default is the number of second since epoch. If an error in conversion occurs, expire value will be 0 (zero).

homecase [lower|uppper|none|tryupper|trylower|trynull]

rewrite the home directory according argument. lower and uppper rewrite it in lower case or upper case. tryupper and trylower rewrite it in lower case or upper case is it does not exists in current case. trynull test if the directory exits and return a NULL directory if not. Default is none who doesn’t touch the case nor make any test.

pures [user1 user2...]

Search the users using system password only. No rewriting or checks are done for the users. They must be found in system password tables.

Errors

errmsg message

If this directive is set, the message will be send to standart output. The following substitution are made in the message :

- %s is substitued by a description of the error

- \n and \e by LF and CR

- \0 exits the program

log.version boolean

log the libhome version when the configuration file is read.

log.stderr boolean

send errors messages to standart error instead of syslog

Cache directives

results of remote requests are able to be cached in DB3 or DB4 local databases if the cache_file directive is set.

cache_file filename

Use filename to store database. filename must have abolute path (i.e. must begin by ’/’) to be used. Its directory is used for database environment. Different databases files should be used for differents SQL or LDAP requests. If the directory part if separed by a double ’//’ from the file base name, the DB version is suffixed to the directory. This allow multiple DB version to run with the same configuration file.

cache_ttl value

Set the time in seconds the information remain valid in the database. Value of 0 implies that records don’t expire.

cache_size value

Set the size in Kb the database environment is using.

LDAP query may be subject to variable expansion. When a attribute begins by ’=’, the remaining string will be expanded and returned.

In expansion, any characters can be escaped with a backslash (‘\’). The following format is used to expand variables:

${variable[:modifier[:...]]}

Where variable is an LDAP queried attribute. Modifiers begin by one colon and one of the following special characters:

+n

Converts the variable in integer then substract the number n.

n is subject to string expansion.

+n

Converts the variable in integer then substract the number n

n is subject to string expansion.

u

Converts variable to upper-case letters.

l

Converts variable to upper-case letters.

?xxx

Use default value. If variable is empty, the expansion of xxx is substituted, otherwise, the value is untouched.

s/old/new/[g]

Modify the first occurence of old in value, replacing if with new. If a ’g’ is appended to the last slash, all all occurrences in each word are replaced. If old begins with a caret (‘^’), old is is anchored at the beginning of each word. If old ends with a dollar sign (‘$’), it is anchored at the end of each word. Any character may be used as a delimiter for the parts of the modifier string. The anchoring, ampersand, and delimiter characters may be escaped with a backslash (‘\’).

String expansion occurs in old and new. In new the empty variable (${}) is expanded by old.

  # database connection
  mydatabase guys
  myuser root
  mypasswd foo
  myhosts base localhost
  mode mysql

 # field selection
  where user
  user user
  home ""
  uid id+1000
  gid 1000
  conditions status = ’Payed’
  table accounts

 cache_ttl 7200

 # need password for them
  [pop*,imap*,ftp*]
    passwd encrypt(passwd)
    cache_file /var/db/home/passwd.db

 # protocol specific error messages
  [pop*]
    errmsg -ERR access error: %s\r\n\0
  [ftp*]
    errmsg 453 access error: %s\r\n\0

 # password not needed
  [mail.local,finger*]
    passwd "*"
    cache_file /var/db/home/nopasswd.db

 [mail.local]
    fallback .*@(.*)   default@$1

/usr/local/etc/home.conf -- default configuration file

getpwent(3), re_format(7), ldap_init(3), strptime(3), getprogname(3), shadow(4)

Laurent Wacrenier <lwa@teaser.fr>