Pubcookie Config File Variable Reference

This is the authoritative reference for variables you can use in the Pubcookie config file. Some variables are shared by all components; many pertain only to the login server components.

Included on this page:

See config.sample and config.login.sample for example configuration for an application server and login server, respectively.

Common Variables

The following variables are common to the keyclient, keyserver, and/or the login cgi:

audit_facility string
The log facility to log audit log messages.
general_facility string
The log facility to log general log messages.
granting_key_file string
Path and filename of the "granting" private key file (only found on login servers).
granting_cert_file string
Path and filename of the "granting" certificate file (found on all servers).
logging_level int
Defines how much information is logged; increase with your level of frustration.
Values: 0 (errors), 1 (audit activity, e.g. auths, redirects), 2 (debug lite), 3 (verbose debug), 5 (verbose debug with HTML)
login_host string
The hostname of login server.
Example: weblogin.example.edu
login_uri full-uri
The full URI of the login cgi.
Example: https://weblogin.example.edu
logout_prog string
The name under which direct logout is invoked, includes the path.
Example: /logout/index.cgi
keydir string
The location of the keystore; one symmetric encryption key for each participating server.
keymgt_uri string
The full URI of the keyserver.
Example: https://weblogin.washington.edu:2222
ssl_ca_file string
Path and filename containing trusted Cerificate Authority certificates used by keyclient and keyserver to verify peer certificates.
ssl_ca_path string
Path of directory containing trusted Certificate Authority certificates named with OpenSSL hashes. Used by keyclient and keyserver to verify peer certificates.
ssl_cert_file string
Path and filename of the SSL certificate.
ssl_key_file string
Path and filename of the SSL key.
umask string
The umask used when creating files.
debug int
Deprecated in Pubcookie 3.1. Use logging_level instead. Non-zero value enables debug logging. The higher the number, the more debugging output that is generated.

Login CGI Variables

The following variables are used only by the login cgi:

app_logout_string-servername-appid string
A custom logout response msg for appid on servername
append_realm switch
If true, the authentication realm is appended to the user name after authentication but before issuing cookies (eg, the cookie will contain user@REALM)
basic_verifier string
The active verifier used by the basic login flavor.
custom_login_message_dir string
The directory for custom login message templates.
Default: the root directory for login templates (see template_root).
custom_login_file_prefix string
The filename prefix used for each custom login message template. This prefix helps if custom login messages are stored in the same directory as the other login templates. The prefix helps you keep them apart.
Default: custom_login_msg
default_realm string
optional default authentication realm to pass to the verifier when none is submitted via the form
default_l_expire time
Defines the default duration of a single sign-on session (login cookie expiry).
Default: 8 hours.
egd_socket socket-locatin
Location of EGD socket (e.g. /dev/egd-pool) if your system lacks entropy.
enterprise_domain string
The DNS domain used to scope the cookies that carry the messages in Pubcookie's classic cookie-based messaging method. It must be at least a second level domain.
Note: Sites can use the POST-based messaging method to avoid DNS domain issues entirely. And sites in country code top-level domains (e.g. example.ca) must do so, since browsers don't allow cookies to be set to second level domains within country code top-level domains.
Example: .example.edu
form_expire_time time
Defines how long someone can take to log in before the login form expires. This provides some protection against replaying the login form later. The value is in seconds.
Default: 60 seconds.
kiosk special
Kiosk policy configuration for reduced SSO duration; matches by user-agent string, remote IP addresses, or IP address ranges.
Syntax: time agent|ip [agent|ip] ... [ time agent|ip ... ]
login_host_cookie_domain domain
The domain used by the login cgi when setting its own cookies.
Default: No domain is used unless this variable defines one.
Example: login.example.edu
lowercase_username int
Defines the site policy on changing the username entered to lower case.
Values: 1, changes to lower case. 0 doesn't.
Default: 0
min_countdown time
The minimum countdown for automatically reloading the status page.
mirrorfile string
Full path to a file to keep a mirrored copy of all output sent to the client by the most recent call to the login cgi
retain_username_on_failed_authn int
Defines whether the userid is retained on failed authentication attempts.
Values: 1 to retain; 0 not to retain.
Default: 0.
clear_username_at_logout int
Defines whether the userid is cleared on logout.
Values: 1 to clear; 0 not to clear.
Default: 0.
static_user_field enumerated
Defines the site policy on the editability of the userid field on the login page.
Values: never, which never denies the user to change the userid, even on session reauth; kind, which allows the user to change the userid if the login cookie has expired; and always, which keeps the userid field static and uneditable whenever there is a userid available in the login cookie (expired or otherwise).
Default: kind.
template_root string
The root directory for the templates.
Default: PREFIX/login_templates.
trim_username_to_atsign int
Defines the site policy on verifying userids that have been entered as email addresses.
Values: 1, trims off the realm before verifying; 0, doesn't trim.
Default: 1.
uppercase_username int
Defines the site policy on changing the username entered to upper case.
Values: 1, changes to upper case. 0 doesn't.
Default: 0
kiosk_keys list
Deprecated in Pubcookie 3.1. Use kiosk instead.
kiosk_values list
Deprecated in Pubcookie 3.1. Use kiosk instead.

Keyserver Variables

The following variables are used only by the keyserver:

login_servers list
List of all of the login servers URLs for our domain; keyserver uses this to distribute keys to the other login servers
keymgt_peers list
The peer host(s) authorized to push keys to this keyserver. Used when a keyserver host is not in the keyserver cluster.
keyserver_client_list list
The hosts authorized to use the keyclient "permit" option to add new servers to the keystore.
keyserver_max_wait_time time
Sets the maximum time that keyserver will wait for data after a connection is established. Non-zero value allows keyserver to break hung connections.
Default: zero (i.e. off, no timeout).

Kerberos Verifier Variables

kerberos5_keytab string
Full path to the K5 keytab file that contains the service key.
Default: /etc/krb5.keytab
kerberos5_service_name string
Service name or "primary" used in the principal for the service key.
Default: host
kerberos5_extralife time
Adds extra ticket lifetime to delegated kerberos5 tickets. The total lifetime is equal to default_l_expire + kerberos5_extralife. This provideds a longer ticket lifetime than the login cookie lifetime and can be helpful when delegating credentials to an application just before the login cookie expires.
save_credentials switch
Controls whether the basic flavor, when used with the Kerberos verifier, saves a copy of the user's master credentials for later use by flavor_getcred.
getcred_authz_file string
flavor_getcred uses this file to determine which application are authorized to request what credentials.

LDAP Verifier Variables

ldap_uri list
The full LDAP URI. The LDAP verifier uses this URI to bind to the directory and search for a DN that matches the userid as entered into the login form. If it finds an entry for the user, it does another bind to verify the user's password as entered into the login form. If it can't even connect to the directory, it will fail over to the next URI in the list, if there is another one to try.

URI Format: 

ldaps://host/o=searchbase???(uid=%s)?x-BindDN=Bind%20DN,x-Password=Password
ldap://host/o=searchbase???(uid=%s)?x-BindDN=Bind%20DN,x-Password=Password

Note: A port number can be optionally added to the host string.

Note: (uid=%s) is the search filter for finding an account by userid. The %s will be replaced with the userid as entered into the login form. The search filter can only contain one %s at this time.

Note: x-BindDN and x-Password are the initial bind DN and password, URL encoded. They may be omitted entirely if the connection is anonymous (and anonymous connections are allowed). Warning: Commas must be URL encoded as %2C and spaces as %20.

Note: x-Version=2 can be added to the URI to force LDAP version 2.

Example: 
ldaps://ldap.example.edu/dc=example,dc=edu???(uid=%s)?x-BindDN=cn=bind_user;%2Cou=people%2Cdc=example%2Cdc=edu,x-Password=bind_pw

Note: bind_user and bind_pw are userid and password used in the initial bind to the server.

cert_db_path string
Path to cert7.db and key3.db files when using Sun/Netscape/iPlanet LDAP libraries. (When using OpenLDAP libraries configure this sort of thing in your ldap.conf file.)
Default: PREFIX/keys
ldap_tls switch
Switch to enable LDAPS Connection.
ldap_key_file string
Key file for LDAPS
ldap_cert_file string
Certificate file for LDAPS
ldap_ca_file string
CA Certificate for verifying the LDAPS Server Certificate.

Shadow Verifier Variables

shadow_path string
Location of shadow file.
Default: /etc/shadow

Fork Verifier Variables

verify_exe string
Location of program used by fork verifier.
Example: /path/to/script.pl

Other Variables

relay_login_uri string
Deprecated. Cross dns domain support is built-in as of version 3.2. The full URI used by the relay cgi for its login cgi.
Example: https://login.example.edu/
relay_template_path string
Deprecated. Cross dns domain support is built-in as of version 3.2. Path and directory, with trailing slash, to the templates directory used by the relay cgi. The path is defined by setting the relay cgi's configuration --prefix option.
Example: /var/www/html/relay/templates/
relay_uri full-uri
Obsolete. This variable was removed in Pubcookie 3.1.1, as the relay can determine its URI by the request. In Pubcookie 3.1.0, it defines the full URI of the relay cgi. Configured in the application server's config file.
Example: https://appserver.example.edu/pcrelay/

Definitions

Some of the config variables share the same types of values.

int
an integer value
string
a character string value
list
a list of string values

time
an integer value representing time in seconds; use a suffix of 'm' to mean minutes or 'h' to mean hours, e.g. 5m means minutes, 1h means an hour.