." -*- nroff -*- ." Copyright 2000, 2001, 2002, 2004 Laurent Wacrenier ." ." This file is part of libhome ." ." libhome is free software; you can redistribute it and/or modify it ." under the terms of the GNU Lesser General Public License as ." published by the Free Software Foundation; either version 2 of the ." License, or (at your option) any later version. ." ." libhome is distributed in the hope that it will be useful, ." but WITHOUT ANY WARRANTY; without even the implied warranty of ." MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ." GNU Lesser General Public License for more details. ." ." You should have received a copy of the GNU Lesser General Public ." License along with libhome; if not, write to the Free Software ." Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 ." USA ." ." $Id: home.conf.5.in,v 1.37 2005/06/30 14:25:49 lwa Exp $ .TH home.conf 5 .SH NAME .B home.conf - format of libhome configuration file .SH DESCRIPTION The home.conf file is used to set parameters to libhome. .SS Format Lines begining by "\fC#\fP", empty lines, blanks lines are skipped. First blanks of lines are ignored. Directives are on remaining lines who are read one by one. Directive keywords are compared without '.' and '_' characters. "mode", "m.od_e" and "m_o_d_e" are the same keywords. .SS 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 '\fC[\fP' and '\fC]\fP'. Exemple : .nf [program1] # lines below will be executed by 'program1' only .fi It's possible to specify several programs by separating them by commas ('\fC,\fP'). Also, an asterisk at the end on a program name allow program with the same prefix : .nf [bar,foo*] # lines below will be executed by 'bar' # and program with name begining with 'foo' .fi .SS Connection type .HP .B mode .I [mysql|pgsql|ldap|system|pam|proxy] .RS Connect to the specified type of database. default is .I mysql. .RE .SS MySQL connection directives This directives indicate how to connect to MySQL databases. .HP .B myuser .I account .RS use this account to connect to the database .RE .HP .B mypasswd .I password .RS use this password to connect .RE .HP .B myhosts .I host1 .I host2 .I ... .RS list of hosts to connect. If the first does not respond, the library use the second, etc.. .RE .HP .B mydatabase .I db .RS Name of the MySQL database containing informations. .RE .SS Postgresql connection directives This directives indicate how to connect to Postgresql databases. .HP .B pg_user .I account .RS use this account to connect to the database .RE .HP .B pg_passwd .I password .RS use this password to connect .RE .HP .B pg_hosts .I host1 .I host2 .I ... .RS list of hosts to connect. If the first does not respond, the library use the second, etc.. .RE .HP .B pg_database .I db .RS Name of the PgSQL database containing informations. .RE .SS MySQL and Postgresql common directives .HP .B table .I name .RS name of the table used for the SQL query .RE .HP .B backtime .I seconds .RS maximum number of seconds the connection will use backup hosts. When the limit is reached, a connection will be retried to the first host. .RE .SS LDAP connection directives .HP .B ld_hosts .I hosts .RS list of LDAP host to try connect to .RE .HP .B ld_passwd .I passwd .RS password in use to connect to LDAP server .RE .HP .B ld_dn .I DN .RS the DN entry to bind .RE .HP .B ld_base .I regexp substitution .RS list of regexp to determine the DN to start the search from the canonified user name. If a user name match a \fIregexp\fP, .RE .HP .B ld_version .I [0|2|3] .RS Set the version of LDAP protocol to use. If 0 (default), use the default API version. .RE .HP .B ld_crypt .I [yes|on|off|true|false|0|1...] .RS Crypt the returned password with crypt(3) if not already crypted. .RE .HP .B ld_timeout .I secs .RS Define timeout in seconds for misc LDAP operations. When set to 0 (default), no timeout is used and operation may take theyre time. .RE .HP .B ld_extra_attributes .I attr ... .RS Space separated list of extra LDAP attributes to be retrieved for string expansion. .RE .SS System database method .HP .B sys_shadow .I [1|0] .RS set to 1 if you want to use shadow password information in \fIsystem\fP mode. .RE .SS 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". .HP .B pam_service .I service_name .RS set to the name of the PAM service (default is "other") .RE .SS Proxy authentification method The proxy method allow to query a home_proxy server. All directives are ignored except proxy specific one and those below. .HP .B proxy_socket .I path .RS set the path of the proxy unix socket. If the path begin by a dollar ($), its value is taken from the environment variable. .RE Also, this directive may be used to ask system password information directly, bypassing the proxy: \fBpures\fP, \fBgetpwuid\fP. This is only for the proxy client (proxy mode). The proxy server may use any directives. .SS Proxy server The proxy server may use any directive, plus a specific one. .HP .B proxy.deny .I [ rule1 ...] .RS List of a set of rules to revoke some permissions to the proxy according returned user or group ID or (if the system support it) with the caller effective user or group ID. Each rule of the list will be checked Per default, all permissions are granted. A rule has the form \fIcondition\fP[:\fIpermission\fP]. A \fIcondition\fP has the form [\fIwhat\fP][\fIcomparator\fP][\fIvalue\fP]. \fIwhat\fP is either 'u' (for a comparison with the caller euid, witch is the default), 'g' (for a comparison with the caller egid), 'U' (for a comparison with the returned UID), 'G' (for a comparison with the returned GID) or '*' (always match) \fIcomparator\fP may be one of '==', '!=', '<', '<=', '>', '>=' to compare if the value is equal, different, lesser, lesser or equal, greater, lesser of equal. '=' and '!' are also supported as synonyms as '=' and '!='. Default comparator is equal. \fIvalue\fP is either a number or the character '@' to check against the returned uid/gid from the database. \fIpermission\fP is a string of characters in which 'n' means that getpwnam() calls are disallowed, 'u' that getpwuid() call are disallowed and 'p' that the password field is replaced by a "*" and '-' means that all permissions are revoked. Example: \fCproxy.deny 0 g0 <100:up U<100:p @:p *:-\fP allows root and the group 0 to retrieve anything, the users with UID less than 100 are able to call getpwnam() with password field hidden, the informations about user with UID and the user itself to call getpwuid() and getpwnam() on its own account with password field hidden and the rest of the world has no permissions. .RE .SS Field comparison and selection The following directives are used to contruct the SQL or LDAP queries. .HP .B user .I field .RS field used to retrieve the user name .I pw_name .RE .HP .B passwd .I field .RS field used to retrieve the password .I pw_passwd. Value will be rewritten with .B passwd_rew directive. If the retrived password is empty, the library will responds as if the user doesn't not exists. .RE .HP .B home .I field .RS field used to retrieve the user home directory informations. This field will be rewritten using the .B hash directive described below .RE .HP .B uid .I field .RS field or attribute used to retrieve the user ID .I pw_uid .RE .HP .B gid .I field .RS field or attribute used to retrieve the user group ID .I pw_gid .RE .HP .B gecos .I field .RS field or attribute used to retrieve the user full name .I pw_gid .RE .HP .B shell .I something .RS field or attribute used to retrieve the user shell .I pw_gid .RE .HP .B class .I field .RS field or attribute used to retrieve the user class .I pw_class .RE .HP .B expire .I field .RS field or attribute used to retrieve the user expiration time .I pw_expire The returned value will be parsed by strptime according format defined in .B expire_fmt directive. .RE .HP .B quota .I field .RS field or attribute used to retrieve the user disk quota .I pw_quota The returned value will be multiplied by .B quota_unit to return quota in bytes. .RE .HP .B where .I field .RS field or attribute to compare with the canonified user name. default is the same as .B user .RE .HP .B where.uid .I field .RS field or attribute to compare with the calculated uid. default is the same as .B uid .RE .HP .B conditions .I MySQL or PGSQL directives or LDAP filter .RS checks for additionnal conditions in requests .RE .HP .B alias .I field .RS 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. .RE Within LDAP mode, the filter will be build using the .B where and .B conditions directives like this : (&( .I where = .I %s ) .I conditions ) where %s is the LDAP-escaped canonified user name. If an attribute directive ( .B 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 : .nf SELECT ... FROM \fItable\fP WHERE \fIwhere\fP = '%s' and \fIconditions\fP .fi With LDAP, returned fields (user, passwd, uid, gid, quota, home, gecos, shell, expire) may be subject to \fIstring expansion\fP if the argument begin by equal character '='. \fIwhere\fP directive is replaced by \fIwhere.uid\fP when a getpwuid() call is required. .SS 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 \fIrewrite\fR regexp, then its case could be lowered ou uppered according \fIusercase\fR directive. Finally, it could be replaced by the value of some DB databases specified in \fIrewritedb\fR .HP .B rewrite .I regexp .I substitution .RS used to canonify the user name. If the username match the .I regexp, it's replaced according .I substitution string. Regexp are extented case insensitive regular exepression. Within .I substitution $1, $2, ... are replaced by first, second.. parenthesis group. When .I substitution is empty, getpwnam will NULL. It could have more than once .B rewrite directives .RE .HP .B fallback .I regexp .I substitution .RS 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. .RE .HP .B usercase .I [lower|upper|none] .RS Ensure the canonified username is lowercase, uppercase or untouched. .RE .HP .B rewritedb .I [database ...] .RS Rewrite the user name according DB3 databases. .RE .HP .B hash .I regexp .I substitution .RS Rewrite the user name returned by the request (pw_name) to get the home directory and append the user home directory information (from the .I home directive). If user home directory information has the form .I ~someuser[/path], .I 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 .B hash directives. Final home directory must be defined and must begin by '\\'. .RE .HP .B passwd_rew .I [regexp list] .RS 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 .RE .HP .B crypt_always_crypted .I boolean .RS 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 "\fI{crypt}\fP". Value is alway true in \fIsystem\fP mode. .RE .HP .B quota_unit .I integer .RS Multiply the returned quota value by this integer to return bytes. default is 1 (one byte). .RE .HP .B expire_fmt .I [strptime format] .RS The value returned by the .B expire directive will be parsed (by strptime(3)) using this format. If .B expire_fmt is not defined, default is the number of second since epoch. If an error in conversion occurs, .B expire value will be 0 (zero). .RE .HP .B homecase .I [lower|uppper|none|tryupper|trylower|trynull] .RS rewrite the home directory according argument. .I lower and .I uppper rewrite it in lower case or upper case. .I tryupper and .I trylower rewrite it in lower case or upper case is it does not exists in current case. .I trynull test if the directory exits and return a NULL directory if not. Default is .I none who doesn't touch the case nor make any test. .RE .HP .B pures .I [user1 user2...] .RS Search the users using system password only. No rewriting or checks are done for the users. They must be found in system password tables. .RE .HP .B uid.calc .I [op1 op2...] .RS List of operation needed to get the UID from the database. Operations have the form .RS .HP -\fIn\fP .RS substract the number \fIn\fP to the uid .RE .HP -\fIn\fP .RS add the number \fIn\fP to the uid .RE .RE .RE .HP .B getpwuid .I [lib|system lib|system ...] .RS List ordering the methods used to retrieve user information by uid .HP .B lib .RS ask the configured database .RE .HP .B system .RS ask the system password database .RE Default is empty which mean that getpwuid() always return NULL. .RE .SS Errors .HP .B retries .I interger .RS Number of query retry when a transcient condition occurs. Default is 0. .RE .HP .B retry.delay .I time .RS Number of seconds between retries. Default is 0. .RE .HP .B errmsg .I message .RS If this directive is set, the message will be send to standart output. The following substitution are made in the message : .RS .TP - \fC%s\fP is substitued by a description of the error \" FIXME : bug un grohtml, \x is impossible to write .TP - \fC\[rs]\fPn and \fC\[rs]\fPe by LF and CR .TP - \fC\[rs]\fP0 exits the program .RE .RE .HP .B log.version .I boolean .RS log the libhome version when the configuration file is read. .RE .HP .B log.stderr .I boolean .RS send errors messages to standart error instead of syslog .RE .SS Cache directives results of remote requests are able to be cached in DB3 or DB4 local databases if the .B cache_file directive is set. .HP .B cache_file .I filename .RS Use .I filename to store database. .I filename must have abolute path (i.e. must begin by '\fC/\fP') 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 '\fC//\fP' 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. .RE .HP .B cache_ttl .I value .RS Set the time in seconds the information remain valid in the database. Value of 0 implies that records don't expire. .RE .HP .B cache_size .I value .RS Set the size in Kb the database environment is using. .RE .HP .B cache_lockers .I value .RS Set the maximal number of internal locks, lockers and objects in database environment (default 1000). Increase if your application complaint because of too few lockers. .RE .SH STRING EXPANSION 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: .RS ${variable[:modifier[:...]]} .RE Where \fIvariable\fP is an LDAP queried attribute. Modifiers begin by one colon and one of the following special characters: .HP \fB+\fP\fIn\fP .RS Converts the variable in integer then substract the number \fIn\fP. \fIn\fP is subject to string expansion. .RE .HP \fB+\fP\fIn\fP .RS Converts the variable in integer then substract the number \fIn\fP \fIn\fP is subject to string expansion. .RE .HP \fBu\fP .RS Converts variable to upper-case letters. .RE .HP .HP \fBl\fP .RS Converts variable to upper-case letters. .RE .HP \fB?\fP\fIxxx\fP .RS Use default value. If variable is empty, the expansion of \fIxxx\fP is substituted, otherwise, the value is untouched. .RE .HP \fBm\fP\fIpattern\fP .RS Keep the value when matching \fIpattern\fP, otherwise, replace it by the empty string. The standard shell wildcard characters (`*', `?', and `[]') may be used. The wildcard characters may be escaped with a backslash (`\\'). .RE .HP \fBn\fP\fIpattern\fP .RS The opposite of \fBm\fP. Substitute the empty string if the value match \fIpattern\fP. .RE .HP \fBs\fP/\fIold\fP/\fInew\fP/[\fBg\fP] .RS Modify the first occurence of \fIold\fP in value, replacing if with \fInew\fP. If a 'g' is appended to the last slash, all all occurrences in each word are replaced. If \fIold\fP begins with a caret (`^'), \fIold\fP is is anchored at the beginning of each word. If \fIold\fP 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 \fIold\fP and \fInew\fP. In \fInew\fP the empty variable (${}) is expanded by \fIold\fP. .RE .SH EXAMPLE .RS .nf # 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 .fi .RE .SH SECURITY - Don't let your database password in home.conf publicaly readable or, at least, use read only dabase accounts and crypted user password. - Don't let the cache files publicaly writable. - As it run in a separated process with its own privileges, the proxy may be considered more secure. Don't use an environment variable as proxy socket path if users have some control on the environment. .SH FILES \fC${prefix}/etc/home.conf\fP -- default configuration file .SH SEE ALSO getpwent(3), re_format(7), ldap_init(3), strptime(3), getprogname(3), shadow(4), fnmatch(3), home_proxy(8) http://pll.sourceforge.net/ .SH AUTHOR Laurent Wacrenier \fC\fP