.\" -*- nroff -*-
.\" $Cambridge: hermes/src/prayer/man/prayer.cf.5,v 1.4 2008/10/30 11:28:59 dpc22 Exp $
.Dd 17 August 2008
.Os "The Prayer Webmail Interface"
.ds volume-operating-system
.Dt PRAYER.CF 5
.Sh NAME
.Nm prayer.cf
.Nd main Prayer configuration file
.
.Sh DESCRIPTION
.
.Pa prayer.cf
is the configuration file of
.Xr prayer 8
and
.Xr prayer-session 8 .
.
.Sh SYNTAX
For the most part, prayer.cf consists of
.Ar option No = Ar value
pairs, but some configuration items are more complex. All values may
be enclosed in double quotes, which are stripped. Quotes must be used
if a value contains a
.Ql #
character. Otherwise, everything following it is treated as a comment.
Any line can be folded using a
.Ql \(rs
character at the end of the line; any linear white space at the beginning 
of the next line is removed.
.Pp
Simple options can be of the following types:
.Bl -tag
.
.It Vt string
No particular restrictions.
.It Vt path
A file or directory name. The configuration parser expands occurences of a few macros
in settings of this type. See
.Cd prefix
.No and Cd var_prefix
below.
.It Vt boolean
The following forms are interpreted as
.Sy true :
.Ql true , 
.Ql t ,
and
.Ql 1 . 
The following forms are interpreted as
.Sy false :
.Ql false , 
.Ql nil ,
.Ql 0 .
Capitalisation does not matter.
.
.It Vt number
An integer number (sequence of digits 0-9), optionally immediately followed by a single letter
.Ql K ,
causing the number to be multiplied by 1024, or
.Ql M
multiplying it by 1024 \(pc 1024.
.
.It Vt time
An integer number (sequence of digits 0-9) of seconds, optionally immediately
followed by a single case-insignificant letter
.Ql s ,
which has no effect,
.Ql m ,
causing the number to be multiplied by 60,
.Ql h ,
multiplying it by 60 \(pc 60, or
.Ql d ,
for a multiple of 24 \(pc 60 \(pc 60.
.It Vt perm
A file permission mode; an octal number of exactly four digits, where the first digit must be 0.
.El
.
.Sh OPTIONS
.
.Bl -tag -width Ds
.
.It Cd prefix Vt ( string ) , Cd var_prefix Vt ( string )
The values of these options can be referred to as 
.Li $prefix
(or
.Li ${prefix} ) ,
and
.Li $var_prefix
(or
.Li ${var_prefix} ) ,
respectively, in settings of type
.Vt path
in the rest of the file.
.Pp
.Sy Default : No none. Need to be set only if referenced later.
.
.It Cd prayer_user Vt ( string ) , Cd prayer_uid Vt ( number )
User name or ID to 
.Xr setuid 2
to if started as root. Either, but not both, must be set and must not specify
.Li uid 0 .
.Sy Default :
none.
.
.It Cd prayer_group Vt ( string ) , Cd prayer_gid Vt ( number )
Group name or ID to
.Xr setgid 2
to if we start off as root. In addition, prayer calls
.Xr initgroups 3
if
.Cd prayer_user
is set.
.Sy Default :
none.
.
.It Cd prayer_background Vt ( boolean )
Run prayer as background process. If true, prayer will return as soon
as valid configuration is found.
.Sy Default : Li true
.
.It Cd file_perms Vt ( perm )
Create mode for new files.
.Sy Default : Li 0640 No if Cd prayer_uid No or Cd prayer_user No is set, otherwise Li 0644 .
.
.It Cd directory_perms Vt ( perm )
Create mode for new directories.
.Sy Default : Li 0750 No if Cd prayer_uid No or Cd prayer_user No is set, otherwise Li 0755 .
.
.It Cd check_directory_perms Vt ( boolean )
Check existing directories under 
.Li ${var_prefix} ?
.El
.
.Ss Mail server settings
.
.Bl -tag -width Ds
.It Cd imapd_server Vt ( string )
Specifies the default IMAP server(s) using libc-client syntax:
.Bd -literal -offset indent
.Sm Ar host Oo : Ar port Oc Op / Ar flag Oo / Ar flag Oc Ar ...
.Sm on
.Ed
.Pp
Multiple server specifications can be listed, separated by commas. Common flags are:
.Bl -tag -compact
.It Li /ssl
Use SSL-on-connect (on port 993 by default).
.It Li /tls
Force use of TLS (using STARTTLS on the normal IMAP port) to encrypt the
session. Recommended if the server is remote, since otherwise a
downgrade attack is possible.
.It Li /notls
Don't issue STARTTLS even if the server supports it. Recommended if
the server is 
.Li localhost .
.It Li /novalidate-cert
Don't check the integrity of the server certificate.
.El
For the full list of flags, see naming.txt.gz in the current
libc-client package.
.
.It Cd imapd_user_map Vt ( path )
CDB lookup map overriding default imapd_server location. For information on CDB, see
.Bl -bullet -compact
.It
http://cr.yp.to/cdb.html
.It
http://en.wikipedia.org/wiki/Constant_Data_Base
.El
.
.It Cd prefs_folder_name Vt ( string )
Name of Prayer user preferences folder on IMAP server.
.
.It Cd use_namespace ( Vt boolean )
Use IMAP NAMESPACE command to find 
.Cd personal_hierarchy No and Cd hiersep .
.Sy Default : Li true .
.
.It Cd personal_hierarchy ( Vt string )
If not supplied by NAMESPACE.
.Sy Default : Li """""" .
.
.It Cd hiersep ( Vt string )
If not supplied by NAMESPACE.
.Sy Default : Li """/""" .
.
.It Cd dualuse ( Vt boolean )
Hint to Prayer that new mailboxes are dual use (i.e. can contain both
mail and inferior mailboxes). Things will mostly work if dualuse set to
.Li false No on a server which supports it, but people will be
unable to create children of newly created mailboxes without
refreshing the view.
.Pp
.Sy Default : Li false .
.
.It Cd sieved_server Vt ( string )
Talk to Cyrus timsieved using MANAGESIEVE protocol. Syntax is similar to
.Cd imapd_server ,
except the only recognised flag is 
.Li /ssl .
.
.It Cd sieved_user_map Vt ( path )
Can be used to provide individualised imapd_server settings in the form of a CDB file.
.
.It Cd sieved_timeout Vt ( time )
Default timsieved timeout is 10 minutes
.El
.
.Ss Mail domain configuration
.
.Bl -tag -width Ds
.
.It Cd local_domain
Define a valid local domain, and optionally the valid local parts in that domain.
This is a special directive that can appear multiple times and does not use an equals sign:
.Bd -unfilled
.Cd local_domain Ar domain Op Ar map
.Ed
.Pp
.No Without Ar map , Cd local_domain
simply defines a domain which will appear on the list visible to user
preferences. With
.Ar map ,
it also defines a list a CDB map file which defines valid entries in
that domain; used for personal name expansion and checking for valid
addresses: The keys are the valid local parts and the values are the
corresponding full names of the users.
.Pp
.Sy Default : No A single entry which corresponds to 
.Cd default_domain .
.
.It Cd return_path_domain Vt ( string )
Domain used in the return address given to 
.Xr sendmail 8 .
.Sy Default : No the default domain.
.
.It Cd filter_domain_pattern Vt ( string )
A filter pattern which is equivalent to, or at least approximates the
list of local domains.
.Sy Default : No the default domain.
.
.It Cd hostname Vt ( string )
Hostname is the canonical name for this particular system, used in
session and icon URLs which are generated by Prayer. This is derived
automatically using 
.Xr gethostname 2
.No and Xr gethostbyname 3
if no value is provided. However, there are situations, especially
involving SSL certificates, where the default hostname may not be
appropriate. The special value 
.Ql __UNDEFINED__
here means the startup script or command line must provide a hostname
using a 
.Fl -config-option
override or via the environment variable 
.Ev PRAYER_HOSTNAME .
This is just a safeguard for systems which use DNS round robining to
distribute load across a number of machines.
.
.It Cd hostname_service Vt ( string )
Host name common for all Prayer installations part of the same webmail
service. (Only) useful for large installations using DNS round robin
for load balancing (example: webmail.hermes.cam.ac.uk is an alias for
webmail[123].hermes.cam.ac.uk). This setting is used for two things:
The user is redirected to this hostname after logging out, and HTTP
requests are sanity checked against it in addition to the canonical
hostname.
.Pp
.Sy Default : No none
.
.It Cd fix_from_address ( Vt boolean )
suppresses the From address option from the Preferences and Roles
screens. 
.Sy Default : Li false .
.
.It Cd lookup_rpasswd ( Vt path )
Path to a CDB file that maps arbitrary search keys to colon- or
comma-separated lists of user names.
.Sy Note : No Keys must be Em lowercase ;
Prayer converts search strings to lowercase in order to provide
case-insensitive lookup.
.
.It Cd lookup_rusername ( Vt path )
Path to a second CDB file that maps arbitrary search keys to colon- or
comma-separated lists of user names.
.Pp
If the user enters a valid and existing username according to
.Xr getpwnam 3 , Prayer does not search these first two CDB files, 
but skips directly to the second stage of looking up user information.
.
.It Cd lookup_username ( Vt path )
Path to a CDB file that maps usernames to records consisting of the user's 
.Dq registered name
and his/her affiliation (department), separated by a vertical bar
.Ql ( "|" ) .
Additionally, if a second vertical bar follows, the account is
regarded as cancelled.
.Pp
When presenting the search results, the usernames found are combined with the
.Cd default_domain
to form email addresses. It is not possible at this time to let users
search for addresses in more than one domain using this facility.
.
.It Cd lookup_fullname ( Vt path )
Path to a CDB file that maps usernames to 
.Dq display names , 
possibly provided by the users themselves in some way. The display name
of a user is used together with the email address in recipient fields
.Pp
Note that all four lookup options must be set to valid CDB files for
the local lookup to work, but more than one option may conceivably
point to the same file.
.
.It Cd ldap_server ( Vt string )
Name or address of LDAP server.
.
.It Cd ldap_base_dn ( Vt string )
Base DN to search. After binding anonymously, Prayer performs a
one-level-scope search for entries with
.Li surname No or Li mail No attributes containing the search string. 
The following attributes are fetched and presented:
.Bl -bullet -compact 
.It
.Li uid
.It
.Li displayName
.It
.Li cn Dq ( registered name )
.It
.Li ou Dq ( affiliation )
.It
.Li mail
.It
.Li telephoneNumber
.El
.
.It Cd ldap_timeout ( Vt time )
Search timeout.
.Sy Default : Li 30s .
.El
.
.Ss HTTP and other frontend settings
.
.Bl -tag -width Ds
.
.It Cd use_http_port , use_https_port
Define a single HTTP[S] port to bind to.  You can define an arbitary list
of ports of both kinds by using a series of separate 
.Cd use_http_port No and Cd use_https_port
directives, with one port on each line. Syntax:
.Bd -literal -offset indent
.Cd use_http_port Oo Ar interface : Oc Ns Ar port
.Cd use_https_port Oo Ar interface : Oc Ns Ar port
.Ed
.Pp
.Ar interface
can be an IP (v4 or v6) address or a hostname. If provided, it is passed to
.Xr getaddrinfo 3
for resolution, and the first resulting address is used to bind to. Otherwise,
.Xr prayer 8
.No binds to Ar port No on all interfaces.
.
.It Cd ssl_default_port Vt ( number )
Prayer will put a warning on the login page for HTTP connections if
both HTTP and HTTPS sessions are available. This will provide a link
to the SSL version of the service, defaulting to port 443 or failing
that the first defined HTTPS port. ssl_default_port overrides the
built in logic.
.Pp
Should be rarely required now that Prayer automatically derives an
appropriate port if none is provided here.
.
.It Cd ssl_cert_file Vt ( path )
Locatation of SSL certificate file (only used if SSL ports defined).
Required if we are going to provide SSL services.
.
.It Cd ssl_privatekey_file Vt ( path )
Location of SSL private key file (only used if SSL ports defined).
Required if we are going to provide SSL services.
.
.It Cd ssl_rsakey_lifespan Vt ( time )
Master server will regenerate shared RSA key at this interval.
.Sy Default : Li 15m .
.
.It Cd ssl_rsakey_freshen Vt ( time )
RSA key remains fresh in child process for this long after first actual use.
.Sy Default : Li 15m .
.
.It Cd ssl_session_timeout Vt ( time )
SSL session cache TTL.
.Sy Default : Li 0 No (SSL session cache not used).
.Xr prayer-ssl-prune 8 should be run periodically to purge any stale session
data from the DBD database.
.
.It Cd egd_socket Vt ( path )
Path to entropy gathering daemon socket. If provided, it will be used in place of
or in addition to
.Pa /dev/urandom
.
.It Cd contact_email Vt ( string )
System administrator email address.
.Sy This setting is currently not used.
If you want to display support information to your users, customise the templates.
.
.It Cd fatal_dump_core Vt ( boolean )
Dump core on
.Fn fatal
error.
.Sy Default : No false.
.
.It Cd log_debug Vt ( boolean )
Enable somewhat more verbose logging, mainly in relation to SSL.
.Sy Default : No false.
.
.It Cd fix_client_ipaddr Vt ( boolean )
Client must connect from consistent IP addresses. May be useful as
a security measure in LAN environments. Painful for dialup users
whose connections may drop out.
.Sy Default : No false.
.
.It Cd gzip_allow_nets Vt ( string ) , Cd gzip_deny_nets Vt ( string )
.Xr prayer-session 8
gzip-compresses pages sent to clients if:
.Bl -enum -compact
.It
gzip compression enabled at compile time,
.It
.Cd use_gzip No is set in user preferences,
.It
User agent is known to support Content-Encoding: gzip,
.It
User agent asks for Content-Encoding: gzip or x-gzip,
.It
IP address of client appears in
.Cd gzip_allow_nets
.Em or No IP address of client does Em not No appear in Cd gzip_deny_nets .
.El
.Pp
The format of these options is a sequence of
.Ar ipaddr Ns Op / Ns Ar masklen
items, separated by colons
.Em and No whitespace (to allow for IPv6 addresses to be parsed easily). If
.Ar masklen No is omitted, the item is interpreted as a full host address.
.
.It Cd log_name_nets Vt ( string )
A network list in the same format as
.Cd gzip_allow_nets
above. To avoid delay when a user logs in,
.Xr prayer-session 8
only performs a reverse lookup of the remote address if matches this list.
.Sy Default : No empty; no reverse lookup are performed.
.
.It Cd limit_vm Vt ( number )
Virtual memory limit imposed on each process to stop runaway process killing system. See
.Xr setrlimit 2 .
.Sy Default : No no limit.
.
.It Cd http_max_method_size Vt ( number )
Prayer should in theory be able to cope with input of arbitrary
size. In practice however, the incoming request has to be stored
somewhere and without limits an attacker may exhaust available memory,
causing a denial of service attack.
.Pp
This sets the maximum size of the initial line of an HTTP request. 
.Sy Default : No no limit.
.
.It Cd http_max_hdr_size Vt ( number )
Maximum for headers associated with this request.
.
.It Cd http_max_body_size Vt ( number )
Maximum for HTTP payload. This is the most significant one in normal use.
.
.It Cd draft_att_single_max ( Vt number )
Maximum size of a single attachment when composing a mail.
.Sy Default : Li 0 No (unlimited).
.
.It Cd draft_att_total_max ( Vt number )
Maximum size of all attachments.
.Sy Default : Li 0 No (unlimited).
.
.It Cd http_min_servers Vt ( number )
Minimum number of preforked
.Xr prayer 8 HTTP servers. The master process forks new slave processes 
whenever the number of idle slaves falls below this number, unless the
total number of slaves would exceed
.Cd http_max_servers .
.Sy Default : Li 4.
.
.It Cd http_max_servers Vt ( number )
Maximum number of preforked
.Xr prayer 8 HTTP servers (active and idle). The master process does not, 
however, enforce any maximum number of
.Em idle No slave processes; they have to terminate voluntarily by timing out
or serving the maximum number of connections.
.Sy Default : Li 64 .
.
.It Cd http_max_connections Vt ( number )
Maximum number of connections that each frontend server will process.
.Sy Default : Li 0 No (no limit).
.
.It Cd http_timeout_idle Vt ( time )
Timeout for (dirty) spare server waiting for another HTTP connection.
.Sy Default : Li 30s .
.
.It Cd http_timeout_icons Vt ( time )
Timeout for HTTP connection that last served static content.
.Sy Default : Li 10s .
.
.It Cd http_timeout_session Vt ( time )
Timeout for HTTP connection that last served a session URL or has not served anything yet.
.Sy Default : Li 60s .
.
.It Cd http_cookie_use_port Vt ( boolean )
Present HTTP cookies to browser as 
.Dq Li username:port=value
rather than
.Dq Li username=value .
Allows simultaneous login sessions from a single client browser.
However can leave a trail of cookies behind. Probably don't want this
in the long term, it's here for experimentation purposes only at the
moment.
.
.It Cd icon_expire_timeout Vt ( time )
The amount of time in the future to set the HTTP 
.Li Expires: No field for static content.
.Sy Default : Li 7d .
(In contrast sessions URLs expire immediately: Browsers really
shouldn't be trying to cache this stuff, especially when it is coming
in over HTTPS).
.El
.
.Ss Session specific configuration
.
.Bl -tag -width Ds
.
.It Cd session_idle_time Vt ( time )
Session switches to idle mode after this much time: connections to
IMAP and accountd servers are shut down.
.Sy Default : Li 0 No (idle mode disabled).
.
.It Cd session_timeout Vt ( time )
Session terminates after this much idle time.
.Ql 0
means session never times out.
.Sy Default : Li 4h .
.
.It Cd session_timeout_compose Vt ( time )
Session terminates after this much idle time instead when the last command was
.Ql compose
.No or Ql sieve .
It should probably not be set lower than
.Cd session_timeout .
.Sy Default : Li 0 No (always use the same timeout).
.
.It Cd stream_ping_interval Vt ( time )
Ping INBOX, Other, and Draft streams at this interval.
.Sy Default : Li 5m .
.
.It Cd stream_checkpoint Vt ( boolean )
.No Use Li CHECKPOINT No instead of Li PING Li to \(lqping\(rq streams.
.Sy Default : Li true .
.
.It Cd stream_misc_timeout Vt ( time )
Shut down Postponed, Preferences and Transfer streams entirely
after this much idle time, but only if idle mode doesn't beat us to it.
.Sy Default : Li 0 No (disabled).
.
.It Cd log_ping_interval Vt ( time )
.Xr stat 2 log files at this interval to see if target file has been
renamed or removed.
.Ql 0s 
means stat() log file every time something is logged.
.Sy Default : Li 5m .
.
.It Cd db_ping_interval Vt ( time )
Interval at which to re-read CDB files containing the local domain.
.Sy Default : Li 30m .
.
.It Cd recips_max_msg Vt ( number )
Maximum number of recipients per message. 
.Sy Default : Li 0 (unlimited).
.
.It Cd recips_max_session Vt ( number )
Maximum number of recipients per session. Automatically creates file in
.Cd sending_block_dir
if limit reached and that is defined.
.Sy Default : Li 0 (unlimited).
.
.It Cd sending_allow_dir Vt ( path )
Create empty file named user in this directory to disable
.Cd recips_max_session
for that user.
.
.It Cd sending_block_dir Vt ( path )
Create empty file named user in this directory to disable outgoing email
for that user (automatic defense against phishing attacks).
.
.El
.Ss Display specific configuration
.
.Bl -tag -width Ds
.It Cd login_banner Vt ( string )
Used in the
.Li <title>
and heading of the login page
.Sy Default : Li """Webmail Service Login""" .
.
.It Cd login_service_name Vt ( string )
Used in the 
.Li <title> No and elsewhere to refer to the webmail system
.Em after No the user has logged in.
.Sy Default : Li """Prayer""" .
.
.It Cd login_template Vt ( string )
Template to use on the login screen.
.
.It Cd login_insert1_path Vt ( path )
Optional file to include in login page template (as $login_insert1).
.
.It Cd login_insert2_path Vt ( path )
Optional file to include in login page template (as $login_insert2).
.
.It Cd motd_path Vt ( path )
File to use as the part of the login page immediately following the login form.
.
.
.It Cd ssl_encouraged ( Vt boolean )
If the user connects over unencrypted HTTP, do not show the login form on the start
.Pa ( / ) No page. A link to Pa /login , No where the form is still displayed, is still provided.
.Sy Default : Li false . No Ignored if Cd ssl_redirect No or Cd ssl_required No is Li true .
.
.It Cd ssl_redirect ( Vt boolean )
If the user connects over unencrypted HTTP, return a 
.Ql 302
redirect to the default SSL port. Only the start
.Pa ( / ) No page is redirected and it may be possible to switch between http and
https after loggin in, subject to cookie rules.
.Pp
.Sy Default : Li false .
.
.It Cd ssl_required ( Vt boolean )
Return a
.Ql 403 Forbidden
error if the user tries to access anything over unencrypted HTTP.
.Cd ssl_redirect No still has effect, however.
.
.It Cd list_addr_maxlen Vt ( number )
The maximum number of characters to show from addresses on the mailbox list screen.
.Sy Default : Li 30 .
.
.It Cd list_subject_maxlen Vt ( number )
The maximum number of characters to show from the subject on the mailbox list screen.
.Sy Default : Li 30 .
.
.It Cd change_max_folders ( Vt number )
The maximum number of folders allowed in the quick folder change
dropdown list. If there would be too many folders, the quick list is
disabled altogether. Only folders that are expanded in the folder view
are included.
.Pp
.Sy Default : Li 20 .
.
.It Cd template_path ( Vt path )
Path to uncompiled template sets (directories).
.Sy Default : Li """../templates""" No (relative to
.Cd tmp_dir ) .
.
.It Cd template_set ( Vt string )
Template set to use.
.Sy Default : Li """xhtml_strict""" .
.
.It Cd template_use_compiled ( Vt boolean )
Use the compiled-in templates, ignoring
.Cd template_path .
.Sy Default : Li true .
.
.It Cd theme
Define themes and their colors.
.Em Semi-deprecated ; No Colours set with this directive are only used by the 
.Li xhtml_transitional No template set. The
.Li xhtml_strict No template set, as well as the login screen, use CSS instead.
It is still necessary to tell Prayer which themes are available, however.
.Pp
Syntax:
.Bd -literal -offset indent
.Cd theme Ar name Li description Ar description
.Cd theme Ar name element colour
.Cd theme Ar name element colour
\&...
.Ed
.Pp
.Ar description No is the label shown in the theme dropdown lists on the
General Preferences page.
.Pp
.Ar element No is one of
.Li fgcolor , fgcolor_link , bgcolor , bgcolor_banner , bgcolor_row1 , bgcolor_row2 ,
.Li bgcolor_status , bgcolor_status_none , fgcolor_quote1 , fgcolor_quote2 ,
.Li fgcolor_quote3 , No and Li fgcolor_quote4 .
The first three are not used by any standard template set, but are
available.  Please study the templates to understand how the rest are
used.
.Pp
.Ar colour No is any valid HTML Vt %Color No value.
Remember that strings containing hash marks need to be quoted.
.It Cd theme_default_main ( Vt string )
.No The Ar name No of the default theme.
.
.It Cd theme_default_main ( Vt string )
.No The Ar name No of the default theme in help mode.
.
.It Cd use_ispell_language
Ispell languages that we want to support, with some descriptive text
for the preferences screen. Syntax:
.Bd -literal -offset indent
.Cd use_ispell_language Ar wordlist Ar description
.Ed
.Pp
Example:
.Bd -literal -offset indent
.Li use_ispell_language british Qq British English
.Ed
.El
.
.Ss Paths etc.
.
.Bl -tag -width Ds
.
.It Cd aspell_path ( Vt path )
Location of Aspell Binary (takes precedence over 
.Cd ispell_path ) .
.
.It Cd bin_dir ( Vt path )
Location of Prayer binaries
.Xr ( prayer 8 and
.Xr prayer-session 8 ) .
.Sy Default : No none. Sy Must be set.
.
.It Cd icon_dir ( Vt path )
Location of icon files.
.Sy Default : No none. Sy Must be set.
.
.It Cd ispell_path ( Vt path )
Location of Ispell Binary (backwards compatibility only).
.
.It Cd log_dir ( Vt path )
Location of log files.
.Sy Default : No none. Sy Must be set.
.
.It Cd pid_dir ( Vt path )
Location for PID files of prayer and prayer-session master processes.
.Sy Default : No none. Sy Must be set.
.
.It Cd sendmail_path ( Vt path )
Location of sendmail binary or drop in replacement such as Exim.
.Sy Default : Pa /usr/lib/sendmail .
.
.It Cd socket_dir ( Vt path )
Location for unix domain sockets which connect
.Xr ( prayer 8 to
.Xr prayer-session 8 ) .
.
.It Cd socket_split_dir ( Vt boolean )
Split socket directory into 64 subdirs keyed on first letter of
sessionID. It is possible to switch back and forth without moving
sockets or killing sessions, since 
.Xr prayer 8 tries both variants. \&In effect, this setting merely controls where
.Xr prayer-session 8 creates the socket files.
.Sy Default : Li false .
.
.It Cd init_socket_name ( Vt string )
Name of Unix domain socket (in 
.Cd socket_dir ) No used for initial handshake
between prayer and prayer-session processes when a user logs in.
.Sy Default : No none. Sy Must be set.
.
.It Cd ssl_session_dir ( Vt path )
Location of the SSL session cache database.
.Sy Default : No none. Sy Must be set , No even if the SSL session cache is disabled.
.
.It Cd static_dir ( Vt path )
Location of other static files (CSS).
.Sy Default : No none. If unset, Prayer will not serve CSS files.
.
.It Cd tmp_dir ( Vt path )
As the directory both daemons
.Xr chdir 2
to at startup, it is where temporary files, such as attachments and
folders in transist during upload and download operations, are
written. Core files also end up here.
.Sy Default : No none. Sy Must be set.
.El
.
.Ss Defaults for user preferences
.
.Bl -tag -width Ds
.
.It Cd confirm_logout ( Vt boolean )
Confirmation dialogue when user logs out.
.Sy Default : Li true .
.
.It Cd confirm_expunge ( Vt boolean )
Confirmation dialogue when user hits expunge.
.Sy Default : Li false .
.
.It Cd confirm_rm ( Vt boolean )
Confirmation dialogue when user deletes mail folder or directory.
.Sy Default : Li true .
.
.It Cd default_domain Vt ( string )
Default domain for outgoing mail. Defaults to 
.Cd hostname No setting.
.
.It Cd expunge_on_exit ( Vt boolean )
Expunge deleted messages from inbox automatically on logout.
.Sy Default : Li false .
.
.It Cd html_inline ( Vt boolean )
Show text/html bodyparts inline. Content is scrubbed to remove
dangerous tags. text/html will be displayed in preference to text/plain
if this is set
.Sy Default : Li true .
.
.It Cd html_remote_images ( Vt boolean )
Show remote images automatically. If this is not set, "Show unsafe images"
links will appear on pages showing HTML mail.
.Sy Default : Li false .
.
.It Cd html_inline_auto ( Vt boolean )
Same as above for text/* bodyparts which start "<HTML>" (case-independent!)
Does anyone other than spammers actually use this?
.Sy Default : Li true .
.
.It Cd ispell_language ( Vt string )
Language for ispell.
.Sy Default : Li """british""" .
.
.It Cd msgs_per_page ( Vt number )
Number of messages per screen on message list screen.
.Sy Default : Li 12 .
.
.It Cd msgs_per_page_max ( Vt number )
Maximum value that users are allowed to set 
.Cd msgs_per_page No to.
.Sy Default : Li 50 .
.
.It Cd msgs_per_page_min ( Vt number )
Minimum value that users are allowed to set 
.Cd msgs_per_page No to.
.Sy Default : Li 4 .
.
.It Cd abook_per_page ( Vt number )
Number of addressbook entries per page on address book list screen.
.Sy Default : Li 12 .
.
.It Cd abook_per_page_max ( Vt number )
Maximum value that users are allowed to set 
.Cd abook_per_page No to.
.Sy Default : Li 50 .
.
.It Cd abook_per_page_min ( Vt number )
Minimum value that users are allowed to set 
.Cd abook_per_page No to.
.Sy Default : Li 4 .
.
.It Cd maildir ( Vt string )
Mail directory in user's account.
.Sy Default : Li """""" .
Typically needed with uw-imap. Typically not needed with e.g. Dovecot or Courier.
.
.It Cd suppress_dotfiles ( Vt boolean )
Supress dotfiles from directory listing.
.Sy Default : Li true .
.
.It Cd postponed_folder ( Vt string )
Name of the folder where messages to be sent later, a.k.a. drafts, are stored.
.Sy Default : Li """postponed-msgs""" .
.
.It Cd sent_mail_folder ( Vt string )
Name of folder for sent mail.
.Sy Default : Li """sent-mail""" .
.
.It Cd small_cols ( Vt number )
Width of small compose textarea in columns.
.Sy Default : Li 80 .
.
.It Cd small_rows ( Vt number )
Height of small compose textarea in lines.
.Sy Default : Li 18 .
.
.It Cd large_cols ( Vt number )
Width of large compose textarea in columns.
.Sy Default : Li 80 .
.
.It Cd large_rows ( Vt number )
Height of large compose textarea in lines.
.Sy Default : Li 32 .
.
.It Cd sort_mode ( Vt string )
Default Sort mode for mailbox list. One of
.Li ARRIVAL , DATE , FROM , TO , CC , SIZE , SUBJECT , REFERENCES , ORDEREDSUBJECT .
.Sy Default : Li ARRIVAL No is most efficient, and recommended.
.
.It Cd sort_reverse ( Vt boolean )
Favour reverse sort rather than normal sort order?
.Sy Default : Li false .
.
.It Cd abook_sort_mode ( Vt string )
Default Sort mode for addressbook list. One of:
.Li ORDERED , ALIAS , NAME , COMMENT , ADDRESS .
.Sy Default : Li ORDERED .
.
.It Cd abook_sort_reverse ( Vt boolean )
Favour reverse sort rather than normal sort order?
.Sy Default : Li false .
.
.It Cd line_wrap_len ( Vt number )
Wrap lines at this many characters.
.Sy Default : Li 76 .
.
.It Cd line_wrap_advanced ( Vt boolean )
Enable advanced line wrap options?
.Sy Default : Li false .
.
.It Cd line_wrap_on_reply ( Vt boolean )
Line wrap automatically on reply.
.Sy Default : Li true .
.
.It Cd line_wrap_on_spell ( Vt boolean )
Line wrap automatically on spell check.
.Sy Default : Li true .
.
.It Cd line_wrap_on_send ( Vt boolean )
Line wrap automatically on send.
.Sy Default : Li true .
.
.It Cd preserve_mimetype ( Vt boolean )
Send message Content-Type through to browser. If 
.Li false , No Content-Type is replaced with
.Ql application/octet-stream
which should force download to local disk, bypassing any automatic
processing of bodyparts by the User-Agent. Unclear at the moment
whether we need to do this, or whether this should be done selectively
based on the User-Agent.
.Sy Default : Li true .
.
.It Cd use_sent_mail ( Vt boolean )
.No Make the Dq Save copy
checkbox on the compose screen checked default.
.Sy Default : Li true .
.
.It Cd use_mark_persist ( Vt boolean )
Use persistent mark for aggregate operations.
.Sy Default : Li false .
.
.It Cd use_search_zoom ( Vt boolean )
Zoom automatically after sucessful search
.Sy Default : Li true .
.
.It Cd use_agg_unmark ( Vt boolean )
Unmark messages after sucessful aggregate operation.
.Sy Default : Li true .
.
.It Cd use_icons ( Vt boolean )
Use icons: may be overriden by value of User-Agent.
.Sy Default : Li true .
.
.It Cd use_welcome ( Vt boolean )
Enable welcome screen .
.Sy Default : Li true .
.
.It Cd use_tail_banner ( Vt boolean )
Duplicate banner icons (toolbar) at the bottom of the Message screen.
.Sy Default : Li true .
.El
.
.Ss Hidden preferences
.
The following options are internally handled as user preferences, but
the Preferences screen no longer provides any means for changing them.
.
.Bl -tag -width Ds
.It Cd use_cookie ( Vt boolean )
Use HTTP cookie for Session-ID, if the browser supports cookies
If disabled, or user rejects the cookie, then the session-ID is stored in the URL.
.Sy Default : Li true .
.
.It Cd use_substitution ( Vt boolean )
Use page substiution rather than HTTP redirects. Faster, but the URLs
that are generated are less predictable.  Page substitution and browser
history mechanism don't coexist well at the moment (Prayer would need to
cache final page value for each substiution event).
.Pp
.Sy Default : Li true .
.
.It Cd use_http_1_1 ( Vt boolean )
Allow HTTP/1.1, if the browser supports it.
.Sy Default : Li true .
.
.It Cd use_pipelining ( Vt boolean )
Allow HTTP/1.1 pipelining, if the browser supports it.
.Sy Default : Li true .
.
.It Cd use_persist ( Vt boolean )
Allow persistent HTTP/1.1 and HTTP/1.0 persistent connections,
if the browser supports them.
.Sy Default : Li true .
.
.It Cd use_short ( Vt boolean )
Allow short URLs, if the browser supports them.
.Sy Default : Li true .
.
.It Cd use_gzip ( Vt boolean )
Allow gzip compression, if the browser supports it.
.Sy Default : Li true .
.
.El
.
.Sh SEE ALSO
.
.Xr prayer 8 ,
.Xr prayer-session 8
.
.Sh AUTHORS
.
This manual page was put together by
.An "Magnus Holmgren" <holmgren@debian.org>
using documentation written by
.An "David Carter" <dpc22@cam.ac.uk> .