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.
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.
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.
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).
- 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_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_path string
- Location of shadow file.
- Default: /etc/shadow
- verify_exe string
- Location of program used by fork verifier.
- Example: /path/to/script.pl
- 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/
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.