prayer.cf(5) main Prayer configuration file

DESCRIPTION

prayer.cf is the configuration file of prayer(8) and prayer-session8.

SYNTAX

For the most part, prayer.cf consists of option = 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 `#' character. Otherwise, everything following it is treated as a comment. Any line can be folded using a `\' character at the end of the line; any linear white space at the beginning of the next line is removed.

Simple options can be of the following types:

Vt string
No particular restrictions.
Vt path
A file or directory name. The configuration parser expands occurences of a few macros in settings of this type. See prefix and var_prefix below.
Vt boolean
The following forms are interpreted as true `true' , `t' , and `1' The following forms are interpreted as false `false' , `nil' , `0' Capitalisation does not matter.
Vt number
An integer number (sequence of digits 0-9), optionally immediately followed by a single letter `K' , causing the number to be multiplied by 1024, or `M' multiplying it by 1024 pc 1024.
Vt time
An integer number (sequence of digits 0-9) of seconds, optionally immediately followed by a single case-insignificant letter `s' , which has no effect, `m' , causing the number to be multiplied by 60, `h' , multiplying it by 60 pc 60, or `d' , for a multiple of 24 pc 60 pc 60.
Vt perm
A file permission mode; an octal number of exactly four digits, where the first digit must be 0.

OPTIONS

prefix Vt ( string ) , var_prefix Vt ( string
The values of these options can be referred to as $prefix (or ${prefix} ) and $var_prefix (or ${var_prefix} ) respectively, in settings of type Vt path in the rest of the file.

Default : none. Need to be set only if referenced later.

prayer_user Vt ( string ) , prayer_uid Vt ( number
User name or ID to setuid(2) to if started as root. Either, but not both, must be set and must not specify uid 0 Default none.
prayer_group Vt ( string ) , prayer_gid Vt ( number
Group name or ID to setgid(2) to if we start off as root. In addition, prayer calls initgroups(3) if prayer_user is set. Default none.
prayer_background Vt ( boolean
Run prayer as background process. If true, prayer will return as soon as valid configuration is found. Default : true
file_perms Vt ( perm
Create mode for new files. Default : 0640 if prayer_uid or prayer_user is set, otherwise 0644
directory_perms Vt ( perm
Create mode for new directories. Default : 0750 if prayer_uid or prayer_user is set, otherwise 0755
check_directory_perms Vt ( boolean
Check existing directories under ${var_prefix}

Mail server settings

imapd_server Vt ( string
Specifies the default IMAP server(s) using libc-client syntax:

Multiple server specifications can be listed, separated by commas. Common flags are:

/ssl
Use SSL-on-connect (on port 993 by default).
/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.
/notls
Don't issue STARTTLS even if the server supports it. Recommended if the server is localhost
/novalidate-cert
Don't check the integrity of the server certificate.

For the full list of flags, see naming.txt.gz in the current libc-client package.

imapd_user_map Vt ( path
CDB lookup map overriding default imapd_server location. For information on CDB, see

prefs_folder_name Vt ( string
Name of Prayer user preferences folder on IMAP server.
use_namespace ( Vt boolean
Use IMAP NAMESPACE command to find personal_hierarchy and hiersep Default : true
personal_hierarchy ( Vt string
If not supplied by NAMESPACE. Default :
hiersep ( Vt string
If not supplied by NAMESPACE. Default : /
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 false on a server which supports it, but people will be unable to create children of newly created mailboxes without refreshing the view.

Default : false

sieved_server Vt ( string
Talk to Cyrus timsieved using MANAGESIEVE protocol. Syntax is similar to imapd_server except the only recognised flag is /ssl
sieved_user_map Vt ( path
Can be used to provide individualised imapd_server settings in the form of a CDB file.
sieved_timeout Vt ( time
Default timsieved timeout is 10 minutes

Mail domain configuration

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:
local_domain domain [map
]

Without map , local_domain simply defines a domain which will appear on the list visible to user preferences. With 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.

Default : A single entry which corresponds to default_domain

return_path_domain Vt ( string
Domain used in the return address given to sendmail(8). Default : the default domain.
filter_domain_pattern Vt ( string
A filter pattern which is equivalent to, or at least approximates the list of local domains. Default : the default domain.
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 gethostname(2) and 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 `__UNDEFINED__' here means the startup script or command line must provide a hostname using a --config-option override or via the environment variable PRAYER_HOSTNAME This is just a safeguard for systems which use DNS round robining to distribute load across a number of machines.
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.

Default : none

fix_from_address ( Vt boolean
suppresses the From address option from the Preferences and Roles screens. Default : false
lookup_rpasswd ( Vt path
Path to a CDB file that maps arbitrary search keys to colon- or comma-separated lists of user names. Note : Keys must be lowercase Prayer converts search strings to lowercase in order to provide case-insensitive lookup.
lookup_rusername ( Vt path
Path to a second CDB file that maps arbitrary search keys to colon- or comma-separated lists of user names.

If the user enters a valid and existing username according to getpwnam(3),PrayerdoesnotsearchthesefirsttwoCDBfiles, but skips directly to the second stage of looking up user information.

lookup_username ( Vt path
Path to a CDB file that maps usernames to records consisting of the user's ``registered name'' and his/her affiliation (department), separated by a vertical bar `(' | ) . Additionally, if a second vertical bar follows, the account is regarded as cancelled.

When presenting the search results, the usernames found are combined with the 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.

lookup_fullname ( Vt path
Path to a CDB file that maps usernames to ``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

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.

ldap_server ( Vt string
Name or address of LDAP server.
ldap_base_dn ( Vt string
Base DN to search. After binding anonymously, Prayer performs a one-level-scope search for entries with surname or mail attributes containing the search string. The following attributes are fetched and presented:

  • uid
  • displayName
  • cn ``( registered name''
  • ou ``( affiliation''
  • mail
  • telephoneNumber

ldap_timeout ( Vt time
Search timeout. Default : 30s

HTTP and other frontend settings

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 use_http_port and use_https_port directives, with one port on each line. Syntax:
use_http_port [interface : port
]
use_https_port [interface : port
]

interface can be an IP (v4 or v6) address or a hostname. If provided, it is passed to getaddrinfo(3) for resolution, and the first resulting address is used to bind to. Otherwise, prayer(8) binds to port on all interfaces.

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.

Should be rarely required now that Prayer automatically derives an appropriate port if none is provided here.

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.
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.
ssl_rsakey_lifespan Vt ( time
Master server will regenerate shared RSA key at this interval. Default : 15m
ssl_rsakey_freshen Vt ( time
RSA key remains fresh in child process for this long after first actual use. Default : 15m
ssl_session_timeout Vt ( time
SSL session cache TTL. Default : 0 (SSL session cache not used). prayer-ssl-prune8shouldberunperiodicallytopurgeanystalesession data from the DBD database.
egd_socket Vt ( path
Path to entropy gathering daemon socket. If provided, it will be used in place of or in addition to /dev/urandom
contact_email Vt ( string
System administrator email address. This setting is currently not used. If you want to display support information to your users, customise the templates.
fatal_dump_core Vt ( boolean
Dump core on Fn fatal error. Default : false.
log_debug Vt ( boolean
Enable somewhat more verbose logging, mainly in relation to SSL. Default : false.
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. Default : false.
gzip_allow_nets Vt ( string ) , gzip_deny_nets Vt ( string
prayer-session8 gzip-compresses pages sent to clients if:

  1. gzip compression enabled at compile time,
  2. use_gzip is set in user preferences,
  3. User agent is known to support Content-Encoding: gzip,
  4. User agent asks for Content-Encoding: gzip or x-gzip,
  5. IP address of client appears in gzip_allow_nets or IP address of client does not appear in gzip_deny_nets

The format of these options is a sequence of ipaddr [/ masklen ] items, separated by colons and whitespace (to allow for IPv6 addresses to be parsed easily). If masklen is omitted, the item is interpreted as a full host address.

log_name_nets Vt ( string
A network list in the same format as gzip_allow_nets above. To avoid delay when a user logs in, prayer-session8 only performs a reverse lookup of the remote address if matches this list. Default : empty; no reverse lookup are performed.
limit_vm Vt ( number
Virtual memory limit imposed on each process to stop runaway process killing system. See setrlimit(2). Default : no limit.
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.

This sets the maximum size of the initial line of an HTTP request. Default : no limit.

http_max_hdr_size Vt ( number
Maximum for headers associated with this request.
http_max_body_size Vt ( number
Maximum for HTTP payload. This is the most significant one in normal use.
draft_att_single_max ( Vt number
Maximum size of a single attachment when composing a mail. Default : 0 (unlimited).
draft_att_total_max ( Vt number
Maximum size of all attachments. Default : 0 (unlimited).
http_min_servers Vt ( number
Minimum number of preforked prayer(8)HTTPservers.Themasterprocessforksnewslaveprocesses whenever the number of idle slaves falls below this number, unless the total number of slaves would exceed http_max_servers Default : 4.
http_max_servers Vt ( number
Maximum number of preforked prayer(8)HTTPservers(activeandidle).Themasterprocessdoesnot, however, enforce any maximum number of idle slave processes; they have to terminate voluntarily by timing out or serving the maximum number of connections. Default : 64
http_max_connections Vt ( number
Maximum number of connections that each frontend server will process. Default : 0 (no limit).
http_timeout_idle Vt ( time
Timeout for (dirty) spare server waiting for another HTTP connection. Default : 30s
http_timeout_icons Vt ( time
Timeout for HTTP connection that last served static content. Default : 10s
http_timeout_session Vt ( time
Timeout for HTTP connection that last served a session URL or has not served anything yet. Default : 60s
http_cookie_use_port Vt ( boolean
Present HTTP cookies to browser as ``username:port=value '' rather than ``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.
icon_expire_timeout Vt ( time
The amount of time in the future to set the HTTP Expires: field for static content. Default : 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).

Session specific configuration

session_idle_time Vt ( time
Session switches to idle mode after this much time: connections to IMAP and accountd servers are shut down. Default : 0 (idle mode disabled).
session_timeout Vt ( time
Session terminates after this much idle time. `0' means session never times out. Default : 4h
session_timeout_compose Vt ( time
Session terminates after this much idle time instead when the last command was `compose' or `sieve' It should probably not be set lower than session_timeout Default : 0 (always use the same timeout).
stream_ping_interval Vt ( time
Ping INBOX, Other, and Draft streams at this interval. Default : 5m
stream_checkpoint Vt ( boolean
Use CHECKPOINT instead of PING to "ping" streams. Default : true
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. Default : 0 (disabled).
log_ping_interval Vt ( time
stat(2)logfilesatthisintervaltoseeiftargetfilehasbeen renamed or removed. `0s'

means stat() log file every time something is logged. Default : 5m

db_ping_interval Vt ( time
Interval at which to re-read CDB files containing the local domain. Default : 30m
recips_max_msg Vt ( number
Maximum number of recipients per message. Default : 0 (unlimited).
recips_max_session Vt ( number
Maximum number of recipients per session. Automatically creates file in sending_block_dir if limit reached and that is defined. Default : 0 (unlimited).
sending_allow_dir Vt ( path
Create empty file named user in this directory to disable recips_max_session for that user.
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).

Display specific configuration

login_banner Vt ( string
Used in the <title> and heading of the login page Default : Webmail Service Login
login_service_name Vt ( string
Used in the <title> and elsewhere to refer to the webmail system after the user has logged in. Default : Prayer
login_template Vt ( string
Template to use on the login screen.
login_insert1_path Vt ( path
Optional file to include in login page template (as $login_insert1).
login_insert2_path Vt ( path
Optional file to include in login page template (as $login_insert2).
motd_path Vt ( path
File to use as the part of the login page immediately following the login form.
ssl_encouraged ( Vt boolean
If the user connects over unencrypted HTTP, do not show the login form on the start ( / ) page. A link to /login , where the form is still displayed, is still provided. Default : false . Ignored if ssl_redirect or ssl_required is true
ssl_redirect ( Vt boolean
If the user connects over unencrypted HTTP, return a `302' redirect to the default SSL port. Only the start ( / ) page is redirected and it may be possible to switch between http and https after loggin in, subject to cookie rules.

Default : false

ssl_required ( Vt boolean
Return a `403' Forbidden error if the user tries to access anything over unencrypted HTTP. ssl_redirect still has effect, however.
list_addr_maxlen Vt ( number
The maximum number of characters to show from addresses on the mailbox list screen. Default : 30
list_subject_maxlen Vt ( number
The maximum number of characters to show from the subject on the mailbox list screen. Default : 30
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.

Default : 20

template_path ( Vt path
Path to uncompiled template sets (directories). Default : ../templates (relative to tmp_dir )
template_set ( Vt string
Template set to use. Default : xhtml_strict
template_use_compiled ( Vt boolean
Use the compiled-in templates, ignoring template_path Default : true
theme
Define themes and their colors. Semi-deprecated ; Colours set with this directive are only used by the xhtml_transitional template set. The xhtml_strict template set, as well as the login screen, use CSS instead. It is still necessary to tell Prayer which themes are available, however.

Syntax:

theme name description description



theme name element colour

theme name element colour
...

description is the label shown in the theme dropdown lists on the General Preferences page.

element is one of fgcolor , fgcolor_link , bgcolor , bgcolor_banner , bgcolor_row1 , bgcolor_row2 bgcolor_status , bgcolor_status_none , fgcolor_quote1 , fgcolor_quote2 fgcolor_quote3 , and 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.

colour is any valid HTML Vt %Color value. Remember that strings containing hash marks need to be quoted.

theme_default_main ( Vt string
The name of the default theme.
theme_default_main ( Vt string
The name of the default theme in help mode.
use_ispell_language
Ispell languages that we want to support, with some descriptive text for the preferences screen. Syntax:
use_ispell_language wordlist description


Example:

use_ispell_language british Qq British English

Paths etc.

aspell_path ( Vt path
Location of Aspell Binary (takes precedence over ispell_path )
bin_dir ( Vt path
Location of Prayer binaries (prayer8and prayer-session8). Default : none. Must be set.
icon_dir ( Vt path
Location of icon files. Default : none. Must be set.
ispell_path ( Vt path
Location of Ispell Binary (backwards compatibility only).
log_dir ( Vt path
Location of log files. Default : none. Must be set.
pid_dir ( Vt path
Location for PID files of prayer and prayer-session master processes. Default : none. Must be set.
sendmail_path ( Vt path
Location of sendmail binary or drop in replacement such as Exim. Default : /usr/lib/sendmail
socket_dir ( Vt path
Location for unix domain sockets which connect (prayer8to prayer-session8).
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 prayer(8)triesbothvariants.Ineffect,thissettingmerelycontrolswhere prayer-session8createsthesocketfiles. Default : false
init_socket_name ( Vt string
Name of Unix domain socket (in socket_dir ) used for initial handshake between prayer and prayer-session processes when a user logs in. Default : none. Must be set.
ssl_session_dir ( Vt path
Location of the SSL session cache database. Default : none. Must be set , even if the SSL session cache is disabled.
static_dir ( Vt path
Location of other static files (CSS). Default : none. If unset, Prayer will not serve CSS files.
tmp_dir ( Vt path
As the directory both daemons 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. Default : none. Must be set.

Defaults for user preferences

confirm_logout ( Vt boolean
Confirmation dialogue when user logs out. Default : true
confirm_expunge ( Vt boolean
Confirmation dialogue when user hits expunge. Default : false
confirm_rm ( Vt boolean
Confirmation dialogue when user deletes mail folder or directory. Default : true
default_domain Vt ( string
Default domain for outgoing mail. Defaults to hostname setting.
expunge_on_exit ( Vt boolean
Expunge deleted messages from inbox automatically on logout. Default : false
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 Default : true
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. Default : false
html_inline_auto ( Vt boolean
Same as above for text/* bodyparts which start "<HTML>" (case-independent!) Does anyone other than spammers actually use this? Default : true
ispell_language ( Vt string
Language for ispell. Default : british
msgs_per_page ( Vt number
Number of messages per screen on message list screen. Default : 12
msgs_per_page_max ( Vt number
Maximum value that users are allowed to set msgs_per_page to. Default : 50
msgs_per_page_min ( Vt number
Minimum value that users are allowed to set msgs_per_page to. Default : 4
abook_per_page ( Vt number
Number of addressbook entries per page on address book list screen. Default : 12
abook_per_page_max ( Vt number
Maximum value that users are allowed to set abook_per_page to. Default : 50
abook_per_page_min ( Vt number
Minimum value that users are allowed to set abook_per_page to. Default : 4
maildir ( Vt string
Mail directory in user's account. Default : Typically needed with uw-imap. Typically not needed with e.g. Dovecot or Courier.
suppress_dotfiles ( Vt boolean
Supress dotfiles from directory listing. Default : true
postponed_folder ( Vt string
Name of the folder where messages to be sent later, a.k.a. drafts, are stored. Default : postponed-msgs
sent_mail_folder ( Vt string
Name of folder for sent mail. Default : sent-mail
small_cols ( Vt number
Width of small compose textarea in columns. Default : 80
small_rows ( Vt number
Height of small compose textarea in lines. Default : 18
large_cols ( Vt number
Width of large compose textarea in columns. Default : 80
large_rows ( Vt number
Height of large compose textarea in lines. Default : 32
sort_mode ( Vt string
Default Sort mode for mailbox list. One of ARRIVAL , DATE , FROM , TO , CC , SIZE , SUBJECT , REFERENCES , ORDEREDSUBJECT Default : ARRIVAL is most efficient, and recommended.
sort_reverse ( Vt boolean
Favour reverse sort rather than normal sort order? Default : false
abook_sort_mode ( Vt string
Default Sort mode for addressbook list. One of: ORDERED , ALIAS , NAME , COMMENT , ADDRESS Default : ORDERED
abook_sort_reverse ( Vt boolean
Favour reverse sort rather than normal sort order? Default : false
line_wrap_len ( Vt number
Wrap lines at this many characters. Default : 76
line_wrap_advanced ( Vt boolean
Enable advanced line wrap options? Default : false
line_wrap_on_reply ( Vt boolean
Line wrap automatically on reply. Default : true
line_wrap_on_spell ( Vt boolean
Line wrap automatically on spell check. Default : true
line_wrap_on_send ( Vt boolean
Line wrap automatically on send. Default : true
preserve_mimetype ( Vt boolean
Send message Content-Type through to browser. If false , Content-Type is replaced with `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. Default : true
use_sent_mail ( Vt boolean
Make the ``Save copy'' checkbox on the compose screen checked default. Default : true
use_mark_persist ( Vt boolean
Use persistent mark for aggregate operations. Default : false
use_search_zoom ( Vt boolean
Zoom automatically after sucessful search Default : true
use_agg_unmark ( Vt boolean
Unmark messages after sucessful aggregate operation. Default : true
use_icons ( Vt boolean
Use icons: may be overriden by value of User-Agent. Default : true
use_welcome ( Vt boolean
Enable welcome screen . Default : true
use_tail_banner ( Vt boolean
Duplicate banner icons (toolbar) at the bottom of the Message screen. Default : true

Hidden preferences

The following options are internally handled as user preferences, but the Preferences screen no longer provides any means for changing them.

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. Default : true
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).

Default : true

use_http_1_1 ( Vt boolean
Allow HTTP/1.1, if the browser supports it. Default : true
use_pipelining ( Vt boolean
Allow HTTP/1.1 pipelining, if the browser supports it. Default : true
use_persist ( Vt boolean
Allow persistent HTTP/1.1 and HTTP/1.0 persistent connections, if the browser supports them. Default : true
use_short ( Vt boolean
Allow short URLs, if the browser supports them. Default : true
use_gzip ( Vt boolean
Allow gzip compression, if the browser supports it. Default : true

AUTHORS

This manual page was put together by An Magnus Holmgren <[email protected]> using documentation written by An David Carter <[email protected]> .