home.conf(5) home.conf(5) NNAAMMEE hhoommee..ccoonnff - format of libhome configuration file DDEESSCCRRIIPPTTIIOONN The home.conf file is used to set parameters to libhome. FFoorrmmaatt 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 keywords are compared without '.' and '_' characters. "mode", "m.od_e" and "m_o_d_e" are the same keywords. DDiirreeccttiivvee sseelleeccttiioonn 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' CCoonnnneeccttiioonn ttyyppee mmooddee _[_m_y_s_q_l_|_p_g_s_q_l_|_l_d_a_p_|_s_y_s_t_e_m_|_p_a_m_|_p_r_o_x_y_] Connect to the specified type of database. default is _m_y_s_q_l_. MMyySSQQLL ccoonnnneeccttiioonn ddiirreeccttiivveess This directives indicate how to connect to MySQL databases. mmyyuusseerr _a_c_c_o_u_n_t use this account to connect to the database mmyyppaasssswwdd _p_a_s_s_w_o_r_d use this password to connect mmyyhhoossttss _h_o_s_t_1 _h_o_s_t_2 _._._. list of hosts to connect. If the first does not respond, the library use the second, etc.. mmyyddaattaabbaassee _d_b Name of the MySQL database containing informations. PPoossttggrreessqqll ccoonnnneeccttiioonn ddiirreeccttiivveess This directives indicate how to connect to Postgresql databases. ppgg__uusseerr _a_c_c_o_u_n_t use this account to connect to the database ppgg__ppaasssswwdd _p_a_s_s_w_o_r_d use this password to connect ppgg__hhoossttss _h_o_s_t_1 _h_o_s_t_2 _._._. list of hosts to connect. If the first does not respond, the library use the second, etc.. ppgg__ddaattaabbaassee _d_b Name of the PgSQL database containing informations. MMyySSQQLL aanndd PPoossttggrreessqqll ccoommmmoonn ddiirreeccttiivveess ttaabbllee _n_a_m_e name of the table used for the SQL query bbaacckkttiimmee _s_e_c_o_n_d_s maximum number of seconds the connection will use backup hosts. When the limit is reached, a connection will be retried to the first host. LLDDAAPP ccoonnnneeccttiioonn ddiirreeccttiivveess lldd__hhoossttss _h_o_s_t_s list of LDAP host to try connect to lldd__ppaasssswwdd _p_a_s_s_w_d password in use to connect to LDAP server lldd__ddnn _D_N the DN entry to bind lldd__bbaassee _r_e_g_e_x_p _s_u_b_s_t_i_t_u_t_i_o_n list of regexp to determine the DN to start the search from the canonified user name. If a user name match a _r_e_g_e_x_p, lldd__vveerrssiioonn _[_0_|_2_|_3_] Set the version of LDAP protocol to use. If 0 (default), use the default API version. lldd__ccrryypptt _[_y_e_s_|_o_n_|_o_f_f_|_t_r_u_e_|_f_a_l_s_e_|_0_|_1_._._._] Crypt the returned password with crypt(3) if not already crypted. lldd__ttiimmeeoouutt _s_e_c_s Define timeout in seconds for misc LDAP operations. When set to 0 (default), no timeout is used and operation may take theyre time. lldd__eexxttrraa__aattttrriibbuutteess _a_t_t_r _._._. Space separated list of extra LDAP attributes to be retrieved for string expansion. SSyysstteemm ddaattaabbaassee mmeetthhoodd ssyyss__sshhaaddooww _[_1_|_0_] set to 1 if you want to use shadow password information in _s_y_s_- _t_e_m mode. PPAAMM aauutthheennttiiffiiccaattiioonn mmeetthhoodd 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". ppaamm__sseerrvviiccee _s_e_r_v_i_c_e___n_a_m_e set to the name of the PAM service (default is "other") PPrrooxxyy aauutthheennttiiffiiccaattiioonn mmeetthhoodd The proxy method allow to query a home_proxy server. All directives are ignored except proxy specific one and those below. pprrooxxyy__ssoocckkeett _p_a_t_h set the path of the proxy unix socket. If the path begin by a dollar ($), its value is taken from the environment variable. Also, this directive may be used to ask system password information directly, bypassing the proxy: ppuurreess, ggeettppwwuuiidd. This is only for the proxy client (proxy mode). The proxy server may use any directives. PPrrooxxyy sseerrvveerr The proxy server may use any directive, plus a specific one. pprrooxxyy..ddeennyy _[ _r_u_l_e_1 _._._._] 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 _c_o_n_d_i_t_i_o_n[:_p_e_r_m_i_s_s_i_o_n]. A _c_o_n_d_i_t_i_o_n has the form [_w_h_a_t][_c_o_m_p_a_r_a_t_o_r][_v_a_l_u_e]. _w_h_a_t 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 compar- ison with the returned GID) or '*' (always match) _c_o_m_p_a_r_a_t_o_r 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. _v_a_l_u_e is either a number or the character '@' to check against the returned uid/gid from the database. _p_e_r_m_i_s_s_i_o_n 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 Example: proxy.deny 0 g0 <100:up U<100:p @:p *:- 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 permis- sions. FFiieelldd ccoommppaarriissoonn aanndd sseelleeccttiioonn The following directives are used to contruct the SQL or LDAP queries. uusseerr _f_i_e_l_d field used to retrieve the user name _p_w___n_a_m_e ppaasssswwdd _f_i_e_l_d field used to retrieve the password _p_w___p_a_s_s_w_d_. Value will be rewritten with ppaasssswwdd__rreeww directive. If the retrived password is empty, the library will responds as if the user doesn't not exists. hhoommee _f_i_e_l_d field used to retrieve the user home directory informations. This field will be rewritten using the hhaasshh directive described below uuiidd _f_i_e_l_d field or attribute used to retrieve the user ID _p_w___u_i_d ggiidd _f_i_e_l_d field or attribute used to retrieve the user group ID _p_w___g_i_d ggeeccooss _f_i_e_l_d field or attribute used to retrieve the user full name _p_w___g_i_d sshheellll _s_o_m_e_t_h_i_n_g field or attribute used to retrieve the user shell _p_w___g_i_d ccllaassss _f_i_e_l_d field or attribute used to retrieve the user class _p_w___c_l_a_s_s eexxppiirree _f_i_e_l_d field or attribute used to retrieve the user expiration time _p_w___e_x_p_i_r_e The returned value will be parsed by strptime accord- ing format defined in eexxppiirree__ffmmtt directive. qquuoottaa _f_i_e_l_d field or attribute used to retrieve the user disk quota _p_w___q_u_o_t_a The returned value will be multiplied by qquuoottaa__uunniitt to return quota in bytes. wwhheerree _f_i_e_l_d field or attribute to compare with the canonified user name. default is the same as uusseerr wwhheerree..uuiidd _f_i_e_l_d field or attribute to compare with the calculated uid. default is the same as uuiidd ccoonnddiittiioonnss _M_y_S_Q_L _o_r _P_G_S_Q_L _d_i_r_e_c_t_i_v_e_s _o_r _L_D_A_P _f_i_l_t_e_r checks for additionnal conditions in requests aalliiaass _f_i_e_l_d 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 fall- back. Within LDAP mode, the filter will be build using the wwhheerree and ccoonnddii-- ttiioonnss directives like this : (&( _w_h_e_r_e = _%_s ) _c_o_n_d_i_t_i_o_n_s ) where %s is the LDAP-escaped canonified user name. If an attribute directive ( uusseerr,, ppaasssswwdd ...... ) 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 _t_a_b_l_e WHERE _w_h_e_r_e = '%s' and _c_o_n_d_i_t_i_o_n_s With LDAP, returned fields (user, passwd, uid, gid, quota, home, gecos, shell, expire) may be subject to _s_t_r_i_n_g _e_x_p_a_n_s_i_o_n if the argument begin by equal character '='. _w_h_e_r_e directive is replaced by _w_h_e_r_e_._u_i_d when a getpwuid() call is required. UUsseerr ccaannoonniiffiiccaattiioonn aanndd eennttrriieess rreewwrriittiinngg Requests in the databases are using canonified user names for compar- isons. To canonify a user name, the library pass the name into _r_e_w_r_i_t_e regexp, then its case could be lowered ou uppered according _u_s_e_r_c_a_s_e directive. Finally, it could be replaced by the value of some DB data- bases specified in _r_e_w_r_i_t_e_d_b rreewwrriittee _r_e_g_e_x_p _s_u_b_s_t_i_t_u_t_i_o_n used to canonify the user name. If the username match the _r_e_g_- _e_x_p_, it's replaced according _s_u_b_s_t_i_t_u_t_i_o_n string. Regexp are extented case insensitive regular exepression. Within _s_u_b_s_t_i_t_u_- _t_i_o_n $1, $2, ... are replaced by first, second.. parenthesis group. When _s_u_b_s_t_i_t_u_t_i_o_n is empty, getpwnam will NULL. It could have more than once rreewwrriittee directives ffaallllbbaacckk _r_e_g_e_x_p _s_u_b_s_t_i_t_u_t_i_o_n 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. uusseerrccaassee _[_l_o_w_e_r_|_u_p_p_e_r_|_n_o_n_e_] Ensure the canonified username is lowercase, uppercase or untouched. rreewwrriitteeddbb _[_d_a_t_a_b_a_s_e _._._._] Rewrite the user name according DB3 databases. hhaasshh _r_e_g_e_x_p _s_u_b_s_t_i_t_u_t_i_o_n Rewrite the user name returned by the request (pw_name) to get the home directory and append the user home directory informa- tion (from the _h_o_m_e directive). If user home directory informa- tion has the form _~_s_o_m_e_u_s_e_r_[_/_p_a_t_h_]_, _s_o_m_e_u_s_e_r 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 hhaasshh directives. Final home directory must be defined and must begin by '\'. ppaasssswwdd__rreeww _[_r_e_g_e_x_p _l_i_s_t_] 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 ccrryypptt__aallwwaayyss__ccrryypptteedd _b_o_o_l_e_a_n 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 "_{_c_r_y_p_t_}". Value is alway true in _s_y_s_t_e_m mode. qquuoottaa__uunniitt _i_n_t_e_g_e_r Multiply the returned quota value by this integer to return bytes. default is 1 (one byte). eexxppiirree__ffmmtt _[_s_t_r_p_t_i_m_e _f_o_r_m_a_t_] The value returned by the eexxppiirree directive will be parsed (by strptime(3)) using this format. If eexxppiirree__ffmmtt is not defined, default is the number of second since epoch. If an error in conversion occurs, eexxppiirree value will be 0 (zero). hhoommeeccaassee _[_l_o_w_e_r_|_u_p_p_p_e_r_|_n_o_n_e_|_t_r_y_u_p_p_e_r_|_t_r_y_l_o_w_e_r_|_t_r_y_n_u_l_l_] rewrite the home directory according argument. _l_o_w_e_r and _u_p_p_p_e_r rewrite it in lower case or upper case. _t_r_y_u_p_p_e_r and _t_r_y_l_o_w_e_r rewrite it in lower case or upper case is it does not exists in current case. _t_r_y_n_u_l_l test if the directory exits and return a NULL directory if not. Default is _n_o_n_e who doesn't touch the case nor make any test. ppuurreess _[_u_s_e_r_1 _u_s_e_r_2_._._._] Search the users using system password only. No rewriting or checks are done for the users. They must be found in system password tables. uuiidd..ccaallcc _[_o_p_1 _o_p_2_._._._] List of operation needed to get the UID from the database. Operations have the form -_n substract the number _n to the uid -_n add the number _n to the uid ggeettppwwuuiidd _[_l_i_b_|_s_y_s_t_e_m _l_i_b_|_s_y_s_t_e_m _._._._] List ordering the methods used to retrieve user information by uid lliibb ask the configured database ssyysstteemm ask the system password database Default is empty which mean that getpwuid() always return NULL. EErrrroorrss rreettrriieess _i_n_t_e_r_g_e_r Number of query retry when a transcient condition occurs. Default is 0. rreettrryy..ddeellaayy _t_i_m_e Number of seconds between retries. Default is 0. eerrrrmmssgg _m_e_s_s_a_g_e 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 lloogg..vveerrssiioonn _b_o_o_l_e_a_n log the libhome version when the configuration file is read. lloogg..ssttddeerrrr _b_o_o_l_e_a_n send errors messages to standart error instead of syslog CCaacchhee ddiirreeccttiivveess results of remote requests are able to be cached in DB3 or DB4 local databases if the ccaacchhee__ffiillee directive is set. ccaacchhee__ffiillee _f_i_l_e_n_a_m_e Use _f_i_l_e_n_a_m_e to store database. _f_i_l_e_n_a_m_e 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. ccaacchhee__ttttll _v_a_l_u_e Set the time in seconds the information remain valid in the database. Value of 0 implies that records don't expire. ccaacchhee__ssiizzee _v_a_l_u_e Set the size in Kb the database environment is using. ccaacchhee__lloocckkeerrss _v_a_l_u_e Set the maximal number of internal locks, lockers and objects in database environment (default 1000). Increase if your applica- tion complaint because of too few lockers. SSTTRRIINNGG EEXXPPAANNSSIIOONN 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 _v_a_r_i_a_b_l_e 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. uu Converts variable to upper-case letters. ll Converts variable to upper-case letters. ??_x_x_x Use default value. If variable is empty, the expansion of _x_x_x is substituted, otherwise, the value is untouched. mm_p_a_t_t_e_r_n Keep the value when matching _p_a_t_t_e_r_n, 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 (`\'). nn_p_a_t_t_e_r_n The opposite of mm. Substitute the empty string if the value match _p_a_t_t_e_r_n. ss/_o_l_d/_n_e_w/[gg] Modify the first occurence of _o_l_d in value, replacing if with _n_e_w. If a 'g' is appended to the last slash, all all occurrences in each word are replaced. If _o_l_d begins with a caret (`^'), _o_l_d is is anchored at the beginning of each word. If _o_l_d 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 _o_l_d and _n_e_w. In _n_e_w the empty vari- able (${}) is expanded by _o_l_d. EEXXAAMMPPLLEE # 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 SSEECCUURRIITTYY - 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. FFIILLEESS ${prefix}/etc/home.conf -- default configuration file SSEEEE AALLSSOO getpwent(3), re_format(7), ldap_init(3), strptime(3), getprogname(3), shadow(4), fnmatch(3), home_proxy(8) http://pll.sourceforge.net/ AAUUTTHHOORR Laurent Wacrenier home.conf(5)