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
- 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
- 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
- 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.
- 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: example.edu 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 ... ]
- 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
- 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.
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
- 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
- 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
- cert_db_path string
- Path to where Netscape's cert7.db and key3.db can be found.
- Default: PREFIX/keys
- 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
- relay_login_uri string
- The full URI used by the relay cgi for its login cgi.
- Example: https://login.example.edu/
- 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.
- Example: https://appserver.example.edu/pcrelay/
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.