Provided by: prayer_1.3.5-dfsg1-8build2_amd64 bug

NAME — main Prayer configuration file

DESCRIPTION is the configuration file of prayer(8) and prayer-session(8).


     For the most part, 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:

     string  No particular restrictions.

     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.

             The following forms are interpreted as true: ‘true’, ‘t’, and ‘1’.  The following
             forms are interpreted as false: ‘false’, ‘nil’, ‘0’.  Capitalisation does not

     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 · 1024.

     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 · 60, or ‘d’,
             for a multiple of 24 · 60 · 60.

     perm    A file permission mode; an octal number of exactly four digits, where the first
             digit must be 0.


     prefix (string), var_prefix (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 path in the rest
             of the file.

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

     prayer_user (string), prayer_uid (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 (string), prayer_gid (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 (boolean)
             Run prayer as background process. If true, prayer will return as soon as valid
             configuration is found.  Default: true

     file_perms (perm)
             Create mode for new files.  Default: 0640 if prayer_uid or prayer_user is set,
             otherwise 0644.

     directory_perms (perm)
             Create mode for new directories.  Default: 0750 if prayer_uid or prayer_user is set,
             otherwise 0755.

     check_directory_perms (boolean)
             Check existing directories under ${var_prefix}?

   Mail server settings
     imapd_server (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.
                     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 (path)
             CDB lookup map overriding default imapd_server location. For information on CDB, see

     prefs_folder_name (string)
             Name of Prayer user preferences folder on IMAP server.

     use_namespace (boolean)
             Use IMAP NAMESPACE command to find personal_hierarchy and hiersep.  Default: true.

     personal_hierarchy (string)
             If not supplied by NAMESPACE.  Default: "".

     hiersep (string)
             If not supplied by NAMESPACE.  Default: "/".

     dualuse (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 (string)
             Talk to Cyrus timsieved using MANAGESIEVE protocol. Syntax is similar to
             imapd_server, except the only recognised flag is /ssl.

     sieved_user_map (path)
             Can be used to provide individualised imapd_server settings in the form of a CDB

     sieved_timeout (time)
             Default timsieved timeout is 10 minutes

   Mail domain configuration
             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 (string)
             Domain used in the return address given to sendmail(8).  Default: the default

     filter_domain_pattern (string)
             A filter pattern which is equivalent to, or at least approximates the list of local
             domains.  Default: the default domain.

     hostname (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 (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: is an alias for webmail[123]
             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 (boolean)
             suppresses the From address option from the Preferences and Roles screens.  Default:

     lookup_rpasswd (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 (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), Prayer
             does not search these first two CDB files, but skips directly to the second stage of
             looking up user information.

     lookup_username (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

             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 (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 (string)
             Name or address of LDAP server.

     ldap_base_dn (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:
                cn (“registered name”)
                ou (“affiliation”)

     ldap_timeout (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 (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 (path)
             Locatation of SSL certificate file (only used if SSL ports defined).  Required if we
             are going to provide SSL services.

     ssl_privatekey_file (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 (time)
             Master server will regenerate shared RSA key at this interval.  Default: 15m.

     ssl_rsakey_freshen (time)
             RSA key remains fresh in child process for this long after first actual use.
             Default: 15m.

     ssl_session_timeout (time)
             SSL session cache TTL.  Default: 0 (SSL session cache not used). prayer-ssl-prune(8)
             should be run periodically to purge any stale session data from the DBD database.

     egd_socket (path)
             Path to entropy gathering daemon socket. If provided, it will be used in place of or
             in addition to /dev/urandom

     contact_email (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 (boolean)
             Dump core on fatal() error.  Default: false.

     log_debug (boolean)
             Enable somewhat more verbose logging, mainly in relation to SSL.  Default: false.

     fix_client_ipaddr (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 (string), gzip_deny_nets (string)
             prayer-session(8) 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 (string)
             A network list in the same format as gzip_allow_nets above. To avoid delay when a
             user logs in, prayer-session(8) only performs a reverse lookup of the remote address
             if matches this list.  Default: empty; no reverse lookup are performed.

     limit_vm (number)
             Virtual memory limit imposed on each process to stop runaway process killing system.
             See setrlimit(2).  Default: no limit.

     http_max_method_size (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

     http_max_hdr_size (number)
             Maximum for headers associated with this request.

     http_max_body_size (number)
             Maximum for HTTP payload. This is the most significant one in normal use.

     draft_att_single_max (number)
             Maximum size of a single attachment when composing a mail.  Default: 0 (unlimited).

     draft_att_total_max (number)
             Maximum size of all attachments.  Default: 0 (unlimited).

     http_min_servers (number)
             Minimum number of preforked 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 http_max_servers.  Default: 4.

     http_max_servers (number)
             Maximum number of preforked prayer(8) HTTP servers (active and idle). The master
             process does not, 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 (number)
             Maximum number of connections that each frontend server will process.  Default: 0
             (no limit).

     http_timeout_idle (time)
             Timeout for (dirty) spare server waiting for another HTTP connection.  Default: 30s.

     http_timeout_icons (time)
             Timeout for HTTP connection that last served static content.  Default: 10s.

     http_timeout_session (time)
             Timeout for HTTP connection that last served a session URL or has not served
             anything yet.  Default: 60s.

     http_cookie_use_port (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 (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

   Session specific configuration
     session_idle_time (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 (time)
             Session terminates after this much idle time.  ‘0’ means session never times out.
             Default: 4h.

     session_timeout_compose (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 (time)
             Ping INBOX, Other, and Draft streams at this interval.  Default: 5m.

     stream_checkpoint (boolean)
             Use CHECKPOINT instead of PING to “ping” streams. Default: true.

     stream_misc_timeout (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 (time)
             stat(2) log files at this interval to see if target file has been renamed or
             removed.  ‘0s’ means stat() log file every time something is logged.  Default: 5m.

     db_ping_interval (time)
             Interval at which to re-read CDB files containing the local domain.  Default: 30m.

     recips_max_msg (number)
             Maximum number of recipients per message.  Default: 0 (unlimited).

     recips_max_session (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 (path)
             Create empty file named user in this directory to disable recips_max_session for
             that user.

     sending_block_dir (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 (string)
             Used in the <title> and heading of the login page Default: "Webmail Service Login".

     login_service_name (string)
             Used in the <title> and elsewhere to refer to the webmail system after the user has
             logged in. Default: "Prayer".

     login_template (string)
             Template to use on the login screen.

     login_insert1_path (path)
             Optional file to include in login page template (as $login_insert1).

     login_insert2_path (path)
             Optional file to include in login page template (as $login_insert2).

     motd_path (path)
             File to use as the part of the login page immediately following the login form.

     ssl_encouraged (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 (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 (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 (number)
             The maximum number of characters to show from addresses on the mailbox list screen.
             Default: 30.

     list_subject_maxlen (number)
             The maximum number of characters to show from the subject on the mailbox list
             screen.  Default: 30.

     change_max_folders (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 (path)
             Path to uncompiled template sets (directories).  Default: "../templates" (relative
             to tmp_dir).

     template_set (string)
             Template set to use.  Default: "xhtml_strict".

     template_use_compiled (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.


                   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 %Color value. Remember that strings containing hash marks
             need to be quoted.

     theme_default_main (string)
             The name of the default theme.

     theme_default_main (string)
             The name of the default theme in help mode.

             Ispell languages that we want to support, with some descriptive text for the
             preferences screen. Syntax:

                   use_ispell_language wordlist description


                   use_ispell_language british "British English"

   Paths etc.
     aspell_path (path)
             Location of Aspell Binary (takes precedence over ispell_path).

     bin_dir (path)
             Location of Prayer binaries (prayer(8) and prayer-session(8)).  Default: none. Must
             be set.

     icon_dir (path)
             Location of icon files.  Default: none. Must be set.

     ispell_path (path)
             Location of Ispell Binary (backwards compatibility only).

     log_dir (path)
             Location of log files.  Default: none. Must be set.

     pid_dir (path)
             Location for PID files of prayer and prayer-session master processes.  Default:
             none. Must be set.

     sendmail_path (path)
             Location of sendmail binary or drop in replacement such as Exim.  Default:

     socket_dir (path)
             Location for unix domain sockets which connect (prayer(8) to prayer-session(8)).

     socket_split_dir (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) tries both variants. In effect, this setting merely controls where
             prayer-session(8) creates the socket files. Default: false.

     init_socket_name (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 (path)
             Location of the SSL session cache database.  Default: none. Must be set, even if the
             SSL session cache is disabled.

     static_dir (path)
             Location of other static files (CSS).  Default: none. If unset, Prayer will not
             serve CSS files.

     tmp_dir (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 (boolean)
             Confirmation dialogue when user logs out.  Default: true.

     confirm_expunge (boolean)
             Confirmation dialogue when user hits expunge.  Default: false.

     confirm_rm (boolean)
             Confirmation dialogue when user deletes mail folder or directory.  Default: true.

     default_domain (string)
             Default domain for outgoing mail. Defaults to hostname setting.

     expunge_on_exit (boolean)
             Expunge deleted messages from inbox automatically on logout.  Default: false.

     html_inline (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:

     html_remote_images (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 (boolean)
             Same as above for text/* bodyparts which start "<HTML>" (case-independent!)  Does
             anyone other than spammers actually use this?  Default: true.

     ispell_language (string)
             Language for ispell.  Default: "british".

     msgs_per_page (number)
             Number of messages per screen on message list screen.  Default: 12.

     msgs_per_page_max (number)
             Maximum value that users are allowed to set msgs_per_page to. Default: 50.

     msgs_per_page_min (number)
             Minimum value that users are allowed to set msgs_per_page to. Default: 4.

     abook_per_page (number)
             Number of addressbook entries per page on address book list screen.  Default: 12.

     abook_per_page_max (number)
             Maximum value that users are allowed to set abook_per_page to. Default: 50.

     abook_per_page_min (number)
             Minimum value that users are allowed to set abook_per_page to. Default: 4.

     maildir (string)
             Mail directory in user's account.  Default: "".  Typically needed with uw-imap.
             Typically not needed with e.g. Dovecot or Courier.

     suppress_dotfiles (boolean)
             Supress dotfiles from directory listing.  Default: true.

     postponed_folder (string)
             Name of the folder where messages to be sent later, a.k.a. drafts, are stored.
             Default: "postponed-msgs".

     sent_mail_folder (string)
             Name of folder for sent mail.  Default: "sent-mail".

     small_cols (number)
             Width of small compose textarea in columns.  Default: 80.

     small_rows (number)
             Height of small compose textarea in lines.  Default: 18.

     large_cols (number)
             Width of large compose textarea in columns.  Default: 80.

     large_rows (number)
             Height of large compose textarea in lines.  Default: 32.

     sort_mode (string)
             Default Sort mode for mailbox list. One of ARRIVAL, DATE, FROM, TO, CC, SIZE,
             SUBJECT, REFERENCES, ORDEREDSUBJECT.  Default: ARRIVAL is most efficient, and

     sort_reverse (boolean)
             Favour reverse sort rather than normal sort order?  Default: false.

     abook_sort_mode (string)
             Default Sort mode for addressbook list. One of: ORDERED, ALIAS, NAME, COMMENT,
             ADDRESS.  Default: ORDERED.

     abook_sort_reverse (boolean)
             Favour reverse sort rather than normal sort order?  Default: false.

     line_wrap_len (number)
             Wrap lines at this many characters.  Default: 76.

     line_wrap_advanced (boolean)
             Enable advanced line wrap options?  Default: false.

     line_wrap_on_reply (boolean)
             Line wrap automatically on reply.  Default: true.

     line_wrap_on_spell (boolean)
             Line wrap automatically on spell check.  Default: true.

     line_wrap_on_send (boolean)
             Line wrap automatically on send.  Default: true.

     preserve_mimetype (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 (boolean)
             Make the “Save copy” checkbox on the compose screen checked default.  Default: true.

     use_mark_persist (boolean)
             Use persistent mark for aggregate operations.  Default: false.

     use_search_zoom (boolean)
             Zoom automatically after sucessful search Default: true.

     use_agg_unmark (boolean)
             Unmark messages after sucessful aggregate operation.  Default: true.

     use_icons (boolean)
             Use icons: may be overriden by value of User-Agent.  Default: true.

     use_welcome (boolean)
             Enable welcome screen .  Default: true.

     use_tail_banner (boolean)
             Duplicate banner icons (toolbar) at the bottom of the Message screen.  Default:

   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 (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 (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 (boolean)
             Allow HTTP/1.1, if the browser supports it.  Default: true.

     use_pipelining (boolean)
             Allow HTTP/1.1 pipelining, if the browser supports it.  Default: true.

     use_persist (boolean)
             Allow persistent HTTP/1.1 and HTTP/1.0 persistent connections, if the browser
             supports them.  Default: true.

     use_short (boolean)
             Allow short URLs, if the browser supports them.  Default: true.

     use_gzip (boolean)
             Allow gzip compression, if the browser supports it.  Default: true.


     prayer(8), prayer-session(8)


     This manual page was put together by Magnus Holmgren <> using
     documentation written by
     David Carter <>.