Linux Certif

Toute la documentation sur la certification Linux LPI

home.conf

NAME

home.conf - format of libhome configuration file

DESCRIPTION

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 keywords are compared without '.' and '_' characters. "mode", "m.od_e" and "m_o_d_e" are the same keywords.

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 [' and ']'. Exemple :

   [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|proxy]

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")

Proxy authentification method

The proxy method allow to query a home_proxy server. All directives are ignored except proxy specific one and those below.

proxy_socket path

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: pures, getpwuid.

This is only for the proxy client (proxy mode). The proxy server may use any directives.

Proxy server

The proxy server may use any directive, plus a specific one.

proxy.deny [ rule1 ...]

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 condition[:permission]. A condition has the form [what][comparator][value].

what 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)

comparator 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.

value is either a number or the character '@' to check against the returned uid/gid from the database.

permission 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 permissions.

Field comparison and selection

The following directives are used to contruct the SQL or LDAP 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

where.uid field

field or attribute to compare with the calculated uid. default is the same as uid

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
 

With LDAP, returned fields (user, passwd, uid, gid, quota, home, gecos, shell, expire) may be subject to string expansion if the argument begin by equal character '='.

where directive is replaced by where.uid when a getpwuid() call is required.

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.

uid.calc [op1 op2...]

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

getpwuid [lib|system lib|system ...]

List ordering the methods used to retrieve user information by uid

lib

ask the configured database

system

ask the system password database

Default is empty which mean that getpwuid() always return NULL.

Errors

retries interger

Number of query retry when a transcient condition occurs. Default is 0.

retry.delay time

Number of seconds between retries. Default is 0.

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.

cache_lockers value

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.

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:

   ${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.

mpattern

Keep the value when matching pattern, 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 (`\').

npattern

The opposite of m. Substitute the empty string if the value match pattern.

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.

EXAMPLE

   # 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
 

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.

FILES

/etc/home.conf -- default configuration file

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/

AUTHOR

Laurent Wacrenier <lwa@teaser.fr>