Pubcookie Home > Documentation 
Pubcookie Homepage Pubcookie 3.2
Config File Variable Reference
Audience:  All
Modified:  January 2, 2006

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.
login_uri full-uri
The full URI of the login cgi.
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.
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 under which all participating hosts will live. Must be at least a second level domain; used to scope "granting" cookies sent between the login server and application servers. Servers outside this domain must use the Pubcookie relay cgi to authenticate users.
Example: or
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.
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.
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.
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

LDAP Verifier Variables

ldap_uri list
The full LDAP URI.
URI Format:
Note: (uid=%s) is the search filter for finding an account by netid. The %s will be replaced with the netid. The host string can optionally contain a port number. The filter can only contain one %s at this time.
Note: x-BindDN and x-Password are the Bind DN and Password, URL encoded. They may be omitted entirely if the connection is anonymous.
Warning: Commas must be encoded as %2c and spaces as %20.
cert_db_path string
Path to where Netscape's cert7.db and key3.db can be found.
Default: PREFIX/keys

Other Variables

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.
relay_login_uri string
The full URI used by the relay cgi for its login cgi.
relay_template_path string
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.


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

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

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.

[Pubcookie Home Page]
Copyright © 2002-2008 University of Washington
UW Technology Services
Pubcookie Contact Info
Modified: January 2, 2006