CGIpaf Configuration

CGIpaf 1.3.2 Configuration

Content

Syntax

The configuration file (cgipaf.conf) contains one directive per line. The directive names are case insensitive, the values are case sensitive. Everything after a hash ( # ) is ignored. Empty lines and whitespaces are also ignored. If a directive appears more than ones the last one is used. Sections are grouped between <section_name> ... </section_name>, the section names are like the directive names case insensitive.

Sections

The configuration file has three sections "global", "passwd" and "mailcfg". The directives that don't belong to a section are global. Global directives apply to all sections unless they're overwritten in the sections.
The "passwd" section is used by passwd.cgi, viewmailcfg.cgi and mailcfg.cgi use the "mailcfg" section.

Directives

The following parameters control cgipaf features and configuration. If a option is not specified or invalid the default built-in messages are used.

syslog

Syntax: syslog on|off
Default: on
Context: global, <passwd>, <mailcfg>

enable syslog messages

all the authentication events are logged with LOG_AUTHPRIV facility, other events are logged with the LOG_USER facility

loglevel

Syntax: loglevel number
Default: 6
Context: global, <passwd>, <mailcfg>

set the syslog level, messages of a higher significance will be reported as well.
e.g. if loglevel is set to 1 (LOG_ALERT) messages with loglevel 0 (LOG_EMERG) are also reported.

0	LOG_EMERG	system is unusable
1	LOG_ALERT	action must be taken immediately
2	LOG_CRIT	critical conditions
3	LOG_ERR	error conditions
4	LOG_WARNING	warning conditions
5	LOG_NOTICE	normal, but significant, condition
6	LOG_INFO	informational message
7	LOG_DEBUG	debug-level message

pam_service

Syntax: pam_service pam service name
Default: passwd
Context: global, <passwd>, <mailcfg>

Set the pam service name, if not set "passwd" is used. The passwd pam service ( /etc/pam.d/passwd ) usually doesn't have an entry for user authentication, therefor /etc/pam.d/other has to have a line auth set to pam_unix.so.


 auth required pam_unix.so
 account required pam_unix.so

If you don't like this for security reason etc, you can set the pam_service directive to "cgipaf" and create the file /etc/pam.d/cgipaf that looks like this


 auth required pam_unix.so
 account required pam_unix.so
 password required pam_unix.so md5

document_root

Syntax: document_root path
Default: not set
Context: global, <passwd>, <mailcfg>

location of the custom html message files

login_document

Syntax: login_document filename OR login_document Redirect location
Default: "error reading data please contact the webmaster\n"
Context: <passwd>, <mailcfg>

if the program is executed without parameters this message is displayed

error_loginname

Syntax: error_loginname filename OR error_loginname Redirect location
Default: "Can't read loginname\n"
Context: <passwd>, <mailcfg>

The user forgot to type his loginname.

error_access

Syntax: error_access filename OR error_access Redirect location
Default:"Access denied...\n"
Context: <passwd>, <mailcfg>

The user try to logon as root or the user's uid isn't between min_uid & max_uid.

error_invalid

Syntax: error_invalid filename OR error_invalid Redirect location
Default: "Invalid password or username.\n"
Context: <passwd>, <mailcfg>

The password is incorrect or the user doesn't exists

error_newpassword

Syntax: error_newpasswd filename OR error_newpassord Redirect location
Default: "Can't read new password\n"
Context: <passwd>

can't read new password

error_match

Syntax: error_match filename OR error_match Redirect location
Default: "They don't match\n"
Context: <passwd>

The new passwords doesn't match

error_unchanged

Syntax: error_unchanged filename OR error_unchanged Redirect location
Default: "Password Unchanged\n"
Context: <passwd>

Password Unchanged

error_tooshort

Syntax: error_tooshort filename OR error_tooshort Redirect location
Default: "Password too short...\n"
Context: <passwd>

the password length is below min_length

error_toolong

Syntax: error_toolong filename OR error_toolong Redirect location
Default: "Password too long...\n"
Context: <passwd>

the password length is above max_length

error_locked

Syntax: error_locked filename OR error_locked Redirect location
Default: "Maximum number of tries exceeded...\n"
Context: <passwd>, <mailcfg>

The user has exceeded the max_invalid tries

error_forwardto

Syntax: error_forwardto filename OR error_forwardto Redirect location
Default:"Forward to who???"
Context: <mailcfg>

The user has enabled mail forwarding, but didn't supply a forward to mail address

error_invalidforwardto

Syntax: error_invalidforwardto filename OR error_invalidforwardto Redirect location
Default: not set
Context: <mailcfg>

The forward to email address is invalid

msg_success

Syntax: msg_success filename OR msg_success Redirect location
Default: not set
Context: <passwd>, <mailcfg>

The password or mail configuration is updated successfully

msg_changed

Syntax: msg_changed filename OR msg_changed Redirect location
Default: not set
Context: <passwd>, <mailcfg>

see msg_success

msg_updated

Syntax: msg_updated filename OR msg_updated Redirect location
Default: not set
Context: <passwd>, <mailcfg>

see msg_success

error_readname

Syntax: error_readname filename OR error_readname Redirect location
Default: "[CGIpaf] Can't read loginname\n"
Context: <mailcfg>

mailcfg.cgi is unable to read to username, this is probably an error in mailcfg_document.

error_readforward

Syntax: error_readforward filename OR error_readforward Redirect location
Default: "[CGIpaf] Can't read forward\n"
Context: <mailcfg>

mailcfg.cgi is unable to read forward, this is probably an error in mailcfg_document.

error_readkeepmsg

Syntax: error_readkeepmsg filename OR error_readkeepmsg Redirect location
Default: "[CGIpaf] Can't read keepmsg\n"
Context: <mailcfg>

mailcfg.cgi is unable to read keep_msg, this is probably an error in mailcfg_document.

error_readautoreply

Syntax: error_readautoreply filename ORerror_readautoreply Redirect location
Default: "[CGIpaf] Can't read autoreply\n"
Context: <mailcfg>

mailcfg.cgi is unable to read autoreply, this is probably an error in mailcfg_document.

error_autoreply_msg

Syntax: error_autoreplymsg filename OR error_autoreplymsg Redirect location
Default: "Can't read autoreply_msg...\n"
Context: <mailcfg>

The user has enabled autoreply, but didn't supply a autoreply message.

error_cookie

Syntax: error_cookie filename OR error_cookie Redirect location
Default: "To update your mail configuration your browser need to support cookies...\n"
Context: <mailcfg>

mailcfg.cgi can't update the mail configuration without cookies.

error_cookietimeout

Syntax: error_cookietimeout filename OR error_cookietimeout Redirect location
Default: "Cookie timeout exceeded...\n"
Context: <mailcfg>

mailcfg.cgi can't update the mail configuration because the cookie is too old.

error_accessdb

Syntax: error_accessdb filename OR error_accessdb Redirect location
Default: "[CGIpaf] configuration error, (view)mailcfg needs a accessdb.\n Please contact the webmaster"
Context: <mailcfg>

(view)mailcfg.cgi can't work without an accessdb

error_cracklib

Syntax: error_cracklib filename OR error_cracklib Redirect location
Default: "BAD PASSWORD, %{cracklib_error}
Context: <passwd>

cracklib error

error_mailcfgscript

Syntax: error_mailcfgscript filename OR error_mailcfgscript Redirect location
Default: "run_mailcfg returns a non-null value, %{mailcfg_exitcode}
Context: <mailcfg>

run_mailcfg failed.

error_viewmailcfgscript

Syntax: error_viewmailcfgscript filename OR error_viewmailcfgscript Redirect location
Default: "run_viewmailcfg returns a non-null value, %{mailcfg_exitcode}
Context: <mailcfg>

run_viewmailcfg failed.

error_pam

Syntax: error_pam filename OR error_pam Redirect location
Default: "Can't update password, errno, %{pam_error}
Context: <passwd>

pam error

error_illegalword

Syntax: error_illegalword filename OR error_illegalword Redirect location
Default: bad password Context: <passwd>

The new password contains an illegal word.

min_uid

Syntax: min_uid uid
Default: 100
Context: global, <passwd>, <mailcfg>

minimum user id, if a uid is bellow min_uid access will be denied. You can't set min_uid lower then 10.

max_uid

Syntax: max_uid uid
Default: not set
Context: Global, <passwd>, <mailcfg>

maximum user id, if the uid is higher than max_uid access will be denied. If max_uid isn't set there is no maximum.

min_length

Syntax: min_length length
Default: 6
Context: <passwd>

minimum password length

max_length

Syntax: max_length length
Default: 8
Context: <passwd>

maximum password length

accessdb

Syntax: accessdb path
Default: not set
Context: global, <passwd>, <mailcfg>

accessdb path, if not set no access database is used. If not set Users can try to change their password as many times they like. (view)mailcfg.cgi don't work without an accessdb.

cracklib

Syntax: cracklib on|off
Default: off
Context: <passwd>

enable cracklib test, the new password is tested with cracklib. if the password is invalid error_cracklib is displayed.

you have to set the cracklib_dictpath directive to your cracklib dictpath otherwise cracklib is disabled.

CGIpaf support cracklib password testing in the PAM configuration, if cracklib is enabled in your PAM configuration and you should set cracklib to off.

cracklib_dictpath

Syntax: cracklib_dictpath /path/to/cracklib_dict
Default: off
Context: <passwd>

Set the cracklib_dictpath, the cracklib_dictpath should be set to the dictionary filename without the extension ( .pwi ), not the directory path.

vmail_support

Syntax: vmail_support yes|no
Default: off
Context: global, <passwd>, <mailcfg>

Enable support for Linuxconf virtual email domains passwords
This directive is only available if you've compiled CGIpaf without PAM support and isn't supported on *BSD systems.

passwd_location

Syntax: passwd_location /path/to/your/passwd_file
Default: system passwd
Context: global, <passwd>, <mailcfg>

Set the password file location. This directive is only available if you've compiled CGIpaf without PAM support and isn't supported on *BSD systems.

shadow_location

Syntax: passwd_location /path/to/your/shadow_file
Default: system shadow
Context: global, <passwd>, <mailcfg>

Set the shadow file location. This directive is only available if you've compiled CGIpaf without PAM support and isn't supported on *BSD systems.

illegal_words

Syntax: illegal_words word1 word2
Default: not set
Context: <passwd>

Specify a list of words that are illegal to use as a part of a new password

set_PAM_CHANGE_EXPIRED_AUTHTOK

Syntax: set_PAM_CHANGE_EXPIRED_AUTHTOK on|off
Default: on
Context: <passwd>

Set the PAM_CHANGE_EXPIRED_AUTHTOK flag.
This directive is obsolete and will be removed in the next Releases of CGIpaf

max_invalid

Syntax: max_invalid tries
Default: 3
Context: global, <passwd>, <mailcfg>

maximum invalid tries, if not set the default value (3) will be used.

invalid_timeout

Syntax: invalid_timeout seconds Default: 600
Context: global, <passwd>, <mailcfg>

time in seconds that a user will be locked out if the max_invalid tries has been exceeded.

sendmail

Syntax: sendmail path_to_sendmail
Default: "/usr/lib/sendmail"
Context: <mailcfg>

mailcfg.cgi uses the path_to_sendmail in ~/.procmailrc, if your mailer is on another location than "/usr/lib/sendmail" you've to set the sendmail directive.

formail

Syntax: formail path_to_formail
Default: "formail"
Context: <mailcfg>

mailcfg.cgi uses the path_to_formail in ~/.procmailrc, by default the basename 'forname' is used.

domain

Syntax: domain domain_name
Default: nisdomain or domain name in /etc/resolv.conf
Context: <mailcfg>

A "X-loop: user@domainname" header is added to the forwarded or the replied mail to avoid mail looping. With the domain directive you can set the domainname in the "X-loop" header. If domain is not set mailcfg.cgi will use hostname.nisadomainname, if your server isn't part of a NIS domain it'll use the domain in /etc/resolv.conf.

use_statefile

Syntax: use_statefile yes|no Default no
Context: <mailcfg>

CGIpaf creates a state file ( $HOME/.cgipaf_state ) in the user's home directory. This file contains the user's current mail configuration state. This file is used by run_before_mailcfg, run_after_mailcfg and run_mailcfg.
By default viewmailcfg.cgi doesn't use this file ( mainly for compatibility reasons ), but reads the user's .procmailrc to determine the user mail configuration. If you set "use_statefile" to "yes" viewmailcfg.cgi will read the state file instead of the user's .procmailrc to get the user's current mail configuration.
If your user's uses their own .procmailrc to distribute their mailinglists into separated mailboxes you must set "use_statefile" to "yes". The user's original .procmailrc could confuse CGIpaf.

run_success

Syntax: run_success path_to_script stdout
Default: not set
Run as: root
Context: <passwd>, <mailcfg>

runs a script is a password / mail configuration is successfully updated. Example:


 run_success "/usr/sbin/smbpasswd -U %{name} > /dev/null 2>&1" "%{password}\n%{password}\n"

Will update the SAMBA password file.

run_locked

Syntax: run_locked path_to_script stdout
Default: not set
Run as: root
Context: <passwd>, <mailcfg>

run a script is a user is locked.

run_before_mailcfg

Syntax: run_before_mailcfg script
Default: not set
Run as: mail user
Context: <mailcfg>

run a script before the mail configuration. mailcfg.cgi will execute the "run_before_mailcfg" script if the mail configuration state goes from not active ( no mail forwarding and no autoreply ) to active.
This can be used to copy the user's .procmailrc to a backup file.

run_after_mailcfg

Syntax: run_after_mailcfg script
Default: not set
Context: <mailcfg>

run a script after the mail configuration. mailcfg.cgi will execute the "run_after_mailcfg" script if the mail configuration state goes from active ( mail forwarding or autoreply enabled ) to non-active.
This script can be used to restore the user's .procmailrc to his original state

run_mailcfg

Syntax: run_mailcfg path_to_script
Default: built-in procmailrc update
Run as: user
Context: <mailcfg>

define a mail configuration script, if not set the built-in procmail configuration updater is used
if set, use_statefile is enabled.

mailcfg_check

Syntax: mailcfg_check on|off
Default: on
Context: <mailcfg>

enables or disables mailcfg.cgi internal HTTP POST parameters checking
you can only disable mailcfg_check if run_mailcfg is defined.

if disabled mailcfg.cgi will run run_mailcfg after the authentication without testing the HTTP POST variables. This is something you must do within your run_mailcfg script.

if mailcfg_check is disabled:

the forward, not_forward, keep_msg, not_keep_msg, autoreply, not_autoreply, autoreply_msg etc variables are undefined.
the statefile and $homedir/vacations.txt are not updated
run_before_mailcfg and run_after_mailcfg are not executed

run_viewmailcfg

Syntax: run_viewmailcfg path_to_script
Default: built-in
Run as: user
Context: <mailcfg>

defines a view mail configuration script.
if not set the mailcfg_document is used after a successful login.

set_script_filename

Syntax: set_script_filename on|off
Default: off
Run as: user
Context: <passwd>, <mailcfg>

set the SCRIPT_FILENAME environment variable to the real scriptname.

unset_script_filename

Syntax: unset_script_filename on|off
Default: off
Run as: user
Context: <passwd>, <mailcfg>

unset the SCRIPT_FILENAME environment variable.

cookie_timeout

Syntax: cookie_timeout seconds Default: 300
Context: <mailcfg>

cookie life time in seconds.

mailcfg_document

Syntax: mailcfg_document filename OR mailcfg_document Redirect Location
Default: built-in message
Context: <mailcfg>

Path to the mail configuration document

error_deldotforward

Syntax: error_deldotforward filename OR error_deldotforward Redirect Location
Default: "Can't delete ~/.forward please contact the webmaster"
Context: <mailcfg>

Unable to delete .forward

error_deldotprocmailrc

Syntax: error_deldotprocmailrc filename OR error_deldotprocmailrc Redirect Location
Default: "Can't delete ~/.procmailrc please contact the webmaster"
Context: <mailcfg>

Unable to delete .forward

error_openvacations

Syntax: error_openvacations filename OR error_openvacations Redirect Location
Default: "Can't open ~/.vacations.txt please contact the webmaster"
Context: <mailcfg>

Unable to open ~/vacations.txt

error_updateprocmailrc

Syntax: error_updateprocmailrc filename OR error_updateprocmailrc Redirect Location
Default: "Can't update ~/.procmailrc, please contact the webmaster" webmaster"
Context: <mailcfg>

Unable to update ~/.procmailrc

AclOrder

Syntax: AclOrder Deny,All OR Allow,Deny
Default: Deny,Allow
Context: Global,<passwd>,<mailcfg>

Set the Acl order.

AllowUsers

Syntax: AllowUsers user1 user2 OR *
Default: see Access Control List
Context: Global,<passwd>,<mailcfg>

Specify a list of users that are allowed to use CGIpaf see Access Control List

DenyUsers

Syntax: DenyUsers user1 user2 OR *
Default: see Access Control List
Context: Global,<passwd>,<mailcfg>

Specify a list of users that are denied to use CGIpaf see acl

AllowGroups

Syntax: AllowGroups group1 group2 OR *
Default: see Access Control List
Context: Global,<passwd>,<mailcfg>

Specify a list of groups that are allowed to use CGIpaf see acl

DenyGroups

Syntax: DenyGroups group1 group2 OR *
Default: see Access Control List
Context: Global,<passwd>,<mailcfg>

Specify a list of groups that are denied to use CGIpaf see acl

Variables

For each document you can as use a plain html file with a few PHP extensions (see bellow) or a redirect. In a redirect, file or run_success and run_locked you can use the following variables:

Variable name	Description

name	loginname
min_length	minimum password length
max_length	maximum password length
max_invalid	maximum invalid tries
invalid_timeout	time in seconds that a user will be locked out if the max_invalid tries has been exceeded.
invalid_wait	a locked user will have to wait invalid_wait seconds
forward_to	the email where the mails will forward to
forward	if mail forwarding is enabled $forward is set to "yes". if mail forwarding is disabled $forward is "no"
not_forward	not_forward is the reverse of forward, so if $forward is "yes" $not_forward is "no"
keep_msg	$keep_msg is set to "yes" if the use want to keep his forwarded mails, set to "no" otherwise
not_keep_msg	the reverse of $keep_msg
autoreply	is "yes" if the use has enabled autoreply
not_autoreply	reverse of $autoreply
autoreply_msg	the autoreply message
cookietimeout	cookie lifetime is seconds
cracklib_error	cracklib error message
bad_password	The new password contains a illegal word, is set to cracklib_error if there is cracklib error
pam_error	pam error message
password	the user's new password, is only set at run_success
mailcfg_exitcode	exitcode of the run_mailcfg script
viewmailcfg_exitcode	exitcode of the run_viewmailcfg script
homedir	the user's home directory
domain	the domainname, only set by mailcfg.cgi
user_maildomain	The user maildomain ( only available if vmail support is enabled
message	A string with the default message
post_string	A string with the original HTTP POST
_POST[]	An associative array of variables with the original HTTP POST

Redirect

example:

 
 msg_success redirect /pwchanged.php?name="%{name}"

Will redirect to /pwchanged.php?name="loginname" after a user has succeed to change his password.

HTML files

If you don't use a redirect you can use plain html files with two PHP extensions "include" and "echo". The same variables as by a redirect are available.


 <? echo $name; include "bottom.php" ?>

Will print the user's name and include bottom.php. Please note that the PHP implementation is very limited. include("bottom.php") won't work for example.

Scripts

Overview

With run_success it's possible to run a script when a has update his password/mail configuration.
run_locked allow you to run a script when a user has too many invalid logins.
run_before_mailcfg and run_after_mailfg allow you to run a script before and after the mail configuration.
With run_mailcfg it's possible to run script to update the mail configuration.
run_viewmailcfg makes it possible to run a script after a user has login successfully to viewmailcfg.cgi

Syntax

The first argument is the script name, the second argument is send to stdout. The second argument is usually used to pass the new password to a script.

Examples


 <passwd>
 ...
 run_success "/usr/sbin/smbpasswd -U %{name} > /dev/null 2>&1" "%{password}\n%{password}\n"
 ...
 </passwd>

Executes a script to update the SAMBA password file after the system password is updated.


 <mailcfg>
 ...
 mailcfg_check off
 
 run_viewmailcfg /etc/cgipaf/scripts/mailcfg.pl "%{poststring}"
 run_mailcfg "/etc/cgipaf/scripts/mailcfg.pl update %{domain}" "%{poststring}"
 ...
 </mailcfg>

Emulates a cgi environment for the mail configuration.
The original http post is send back to stdout.
mailcfg.cgi doesn't evaluate the httpd parameters since mailcfg_check is disabled. This way CGIpaf only handles the authentication.

Access Control List

With the Access Control list you can allow or deny users or groups.

The AclOrder directive control the default access state and the order in which the acl is processed.

Allow,Deny: The AllowUsers and AllowGroups directives are evaluated before the DenyUsers and DenyGroups directives. Access is denied by default.
Deny,Allow: The DenyUsers and DenyGroups directives are evaluated before the AllowUsers and AllowGroups>. Access is granted by default.

A star (*) in the user or group list means any user or group other wildcards are not supported.

Examples


AclOrder Deny,Allow
DenyUsers *
AllowUsers foo

Access to user "foo" will be allowed and all others will be denied.


AclOrder Allow,Deny
AllowUsers foo

Give the same result as above.


AclOrder Allow,Deny

Will denied access to all, because the default state is set to deny.