Subversion Repositories

?revision_form?Rev ?revision_input??revision_submit??revision_endform?

Rev 61 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
61 magnus 1
.\" -*- nroff -*-
2
.Dd 17 August 2008
3
.Os "The Prayer Webmail Interface"
4
.ds volume-operating-system
5
.Dt PRAYER.CF 5
6
.Sh NAME
7
.Nm prayer.cf
8
.Nd main Prayer configuration file
9
.
10
.Sh DESCRIPTION
11
.
12
.Pa prayer.cf
13
is the configuration file of
14
.Xr prayer 8
15
and
16
.Xr prayer-session 8 .
17
.
18
.Sh SYNTAX
19
For the most part, prayer.cf consists of
20
.Ar option No = Ar value
21
pairs, but some configuration items are more complex. All values may
22
be enclosed in double quotes, which are stripped. Quotes must be used
23
if a value contains a
24
.Ql #
25
character. Otherwise, everything following it is treated as a comment.
26
Any line can be folded using a
27
.Ql \(rs
28
character at the end of the line; any linear white space at the beginning
29
of the next line is removed.
30
.Pp
31
Simple options can be of the following types:
32
.Bl -tag
33
.
34
.It Vt string
35
No particular restrictions.
36
.It Vt path
37
A file or directory name. The configuration parser expands occurences of a few macros
38
in settings of this type. See
39
.Cd prefix
40
.No and Cd var_prefix
41
below.
42
.It Vt boolean
43
The following forms are interpreted as
44
.Sy true :
45
.Ql true ,
46
.Ql t ,
47
and
48
.Ql 1 .
49
The following forms are interpreted as
50
.Sy false :
51
.Ql false ,
52
.Ql nil ,
53
.Ql 0 .
54
Capitalisation does not matter.
55
.
56
.It Vt number
57
An integer number (sequence of digits 0-9), optionally immediately followed by a single letter
58
.Ql K ,
59
causing the number to be multiplied by 1024, or
60
.Ql M
61
multiplying it by 1024 \(pc 1024.
62
.
63
.It Vt time
64
An integer number (sequence of digits 0-9) of seconds, optionally immediately
65
followed by a single case-insignificant letter
66
.Ql s ,
67
which has no effect,
68
.Ql m ,
69
causing the number to be multiplied by 60,
70
.Ql h ,
71
multiplying it by 60 \(pc 60, or
72
.Ql d ,
73
for a multiple of 24 \(pc 60 \(pc 60.
74
.It Vt perm
75
A file permission mode; an octal number of exactly four digits, where the first digit must be 0.
76
.El
77
.
78
.Sh OPTIONS
79
.
80
.Bl -tag -width Ds
81
.
82
.It Cd prefix Vt ( string ) , Cd var_prefix Vt ( string )
83
The values of these options can be referred to as
84
.Li $prefix
85
(or
86
.Li ${prefix} ) ,
87
and
88
.Li $var_prefix
89
(or
90
.Li ${var_prefix} ) ,
91
respectively, in settings of type
92
.Vt path
93
in the rest of the file.
94
.Pp
95
.Sy Default : No none. Need to be set only if referenced later.
96
.
97
.It Cd prayer_user Vt ( string ) , Cd prayer_uid Vt ( number )
98
User name or ID to
99
.Xr setuid 2
100
to if started as root. Either, but not both, must be set and must not specify
101
.Li uid 0 .
102
.Sy Default :
103
none.
104
.
105
.It Cd prayer_group Vt ( string ) , Cd prayer_gid Vt ( number )
106
Group name or ID to
107
.Xr setgid 2
108
to if we start off as root. In addition, prayer calls
109
.Xr initgroups 3
110
if
111
.Cd prayer_user
112
is set.
113
.Sy Default :
114
none.
115
.
116
.It Cd prayer_background Vt ( boolean )
117
Run prayer as background process. If true, prayer will return as soon
118
as valid configuration is found.
119
.Sy Default : Li true
120
.
121
.It Cd file_perms Vt ( perm )
122
Create mode for new files.
123
.Sy Default : Li 0640 No if Cd prayer_uid No or Cd prayer_user No is set, otherwise Li 0644 .
124
.
125
.It Cd directory_perms Vt ( perm )
126
Create mode for new directories.
127
.Sy Default : Li 0750 No if Cd prayer_uid No or Cd prayer_user No is set, otherwise Li 0755 .
128
.
129
.It Cd check_directory_perms Vt ( boolean )
130
Check existing directories under
131
.Li ${var_prefix} ?
132
.El
133
.
134
.Ss Mail server settings
135
.
136
.Bl -tag -width Ds
137
.It Cd imapd_server Vt ( string )
138
Specifies the default IMAP server(s) using libc-client syntax:
139
.Bd -literal -offset indent
140
.Sm Ar host Oo : Ar port Oc Op / Ar flag Oo / Ar flag Oc Ar ...
141
.Sm on
142
.Ed
143
.Pp
144
Multiple server specifications can be listed, separated by commas. Common flags are:
145
.Bl -tag -compact
146
.It Li /ssl
147
Use SSL-on-connect (on port 993 by default).
148
.It Li /tls
149
Force use of TLS (using STARTTLS on the normal IMAP port) to encrypt the
150
session. Recommended if the server is remote, since otherwise a
151
downgrade attack is possible.
152
.It Li /notls
153
Don't issue STARTTLS even if the server supports it. Recommended if
154
the server is
155
.Li localhost .
156
.It Li /novalidate-cert
157
Don't check the integrity of the server certificate.
158
.El
159
For the full list of flags, see naming.txt.gz in the current
160
libc-client package.
161
.
162
.It Cd imapd_user_map Vt ( path )
163
CDB lookup map overriding default imapd_server location. For information on CDB, see
164
.Bl -bullet -compact
165
.It
166
http://cr.yp.to/cdb.html
167
.It
168
http://en.wikipedia.org/wiki/Constant_Data_Base
169
.El
170
.
171
.It Cd prefs_folder_name Vt ( string )
172
Name of Prayer user preferences folder on IMAP server.
173
.
174
.It Cd use_namespace ( Vt boolean )
175
Use IMAP NAMESPACE command to find
176
.Cd personal_hierarchy No and Cd hiersep .
177
.Sy Default : Li true .
178
.
179
.It Cd personal_hierarchy ( Vt string )
180
If not supplied by NAMESPACE.
181
.Sy Default : Li """""" .
182
.
183
.It Cd hiersep ( Vt string )
184
If not supplied by NAMESPACE.
185
.Sy Default : Li """/""" .
186
.
187
.It Cd dualuse ( Vt boolean )
188
Hint to Prayer that new mailboxes are dual use (i.e. can contain both
189
mail and inferior mailboxes). Things will mostly work if dualuse set to
190
.Li false No on a server which supports it, but people will be
191
unable to create children of newly created mailboxes without
192
refreshing the view.
193
.Pp
194
.Sy Default : Li false .
195
.
196
.It Cd sieved_server Vt ( string )
197
Talk to Cyrus timsieved using MANAGESIEVE protocol. Syntax is similar to
198
.Cd imapd_server ,
199
except the only recognised flag is
200
.Li /ssl .
201
.
202
.It Cd sieved_user_map Vt ( path )
203
Can be used to provide individualised imapd_server settings in the form of a CDB file.
204
.
205
.It Cd sieved_timeout Vt ( time )
206
Default timsieved timeout is 10 minutes
207
.El
208
.
209
.Ss Mail domain configuration
210
.
211
.Bl -tag -width Ds
212
.
213
.It Cd local_domain
214
Define a valid local domain, and optionally the valid local parts in that domain.
215
This is a special directive that can appear multiple times and does not use an equals sign:
216
.Bd -unfilled
217
.Cd local_domain Ar domain Op Ar map
218
.Ed
219
.Pp
220
.No Without Ar map , Cd local_domain
221
simply defines a domain which will appear on the list visible to user
222
preferences. With
223
.Ar map ,
224
it also defines a list a CDB map file which defines valid entries in
225
that domain; used for personal name expansion and checking for valid
226
addresses: The keys are the valid local parts and the values are the
227
corresponding full names of the users.
228
.Pp
229
.Sy Default : No A single entry which corresponds to
230
.Cd default_domain .
231
.
232
.It Cd return_path_domain Vt ( string )
233
Domain used in the return address given to
234
.Xr sendmail 8 .
235
.Sy Default : No the default domain.
236
.
237
.It Cd filter_domain_pattern Vt ( string )
238
A filter pattern which is equivalent to, or at least approximates the
239
list of local domains.
240
.Sy Default : No the default domain.
241
.
242
.It Cd hostname Vt ( string )
243
Hostname is the canonical name for this particular system, used in
244
session and icon URLs which are generated by Prayer. This is derived
245
automatically using
246
.Xr gethostname 2
247
.No and Xr gethostbyname 3
248
if no value is provided. However, there are situations, especially
249
involving SSL certificates, where the default hostname may not be
250
appropriate. The special value
251
.Ql __UNDEFINED__
252
here means the startup script or command line must provide a hostname
253
using a
254
.Fl -config-option
255
override or via the environment variable
256
.Ev PRAYER_HOSTNAME .
257
This is just a safeguard for systems which use DNS round robining to
258
distribute load across a number of machines.
259
.
260
.It Cd hostname_service Vt ( string )
261
Host name common for all Prayer installations part of the same webmail
262
service. (Only) useful for large installations using DNS round robin
263
for load balancing (example: webmail.hermes.cam.ac.uk is an alias for
264
webmail[123].hermes.cam.ac.uk). This setting is used for two things:
265
The user is redirected to this hostname after logging out, and HTTP
266
requests are sanity checked against it in addition to the canonical
267
hostname.
268
.Pp
269
.Sy Default : No none
270
.
271
.It Cd fix_from_address ( Vt boolean )
272
suppresses the From address option from the Preferences and Roles
273
screens.
274
.Sy Default : Li false .
275
.
276
.It Cd lookup_rpasswd ( Vt path )
277
Path to a CDB file that maps arbitrary search keys to colon- or
278
comma-separated lists of user names.
279
.Sy Note : No Keys must be Em lowercase ;
280
Prayer converts search strings to lowercase in order to provide
281
case-insensitive lookup.
282
.
283
.It Cd lookup_rusername ( Vt path )
284
Path to a second CDB file that maps arbitrary search keys to colon- or
285
comma-separated lists of user names.
286
.Pp
287
If the user enters a valid and existing username according to
288
.Xr getpwnam 3 , Prayer does not search these first two CDB files,
289
but skips directly to the second stage of looking up user information.
290
.
291
.It Cd lookup_username ( Vt path )
292
Path to a CDB file that maps usernames to records consisting of the user's
293
.Dq registered name
294
and his/her affiliation (department), separated by a vertical bar
295
.Ql ( "|" ) .
296
Additionally, if a second vertical bar follows, the account is
297
regarded as cancelled.
298
.Pp
299
When presenting the search results, the usernames found are combined with the
300
.Cd default_domain
301
to form email addresses. It is not possible at this time to let users
302
search for addresses in more than one domain using this facility.
303
.
304
.It Cd lookup_fullname ( Vt path )
305
Path to a CDB file that maps usernames to
306
.Dq display names ,
307
possibly provided by the users themselves in some way. The display name
308
of a user is used together with the email address in recipient fields
309
.Pp
310
Note that all four lookup options must be set to valid CDB files for
311
the local lookup to work, but more than one option may conceivably
312
point to the same file.
313
.
314
.It Cd ldap_server ( Vt string )
315
Name or address of LDAP server.
316
.
317
.It Cd ldap_base_dn ( Vt string )
318
Base DN to search. After binding anonymously, Prayer performs a
319
one-level-scope search for entries with
320
.Li surname No or Li mail No attributes containing the search string.
321
The following attributes are fetched and presented:
322
.Bl -bullet -compact
323
.It
324
.Li uid
325
.It
326
.Li displayName
327
.It
328
.Li cn Dq ( registered name )
329
.It
330
.Li ou Dq ( affiliation )
331
.It
332
.Li mail
333
.It
334
.Li telephoneNumber
335
.El
336
.
337
.It Cd ldap_timeout ( Vt time )
338
Search timeout.
339
.Sy Default : Li 30s .
340
.El
341
.
342
.Ss HTTP and other frontend settings
343
.
344
.Bl -tag -width Ds
345
.
346
.It Cd use_http_port , use_https_port
347
Define a single HTTP[S] port to bind to.  You can define an arbitary list
348
of ports of both kinds by using a series of separate
349
.Cd use_http_port No and Cd use_https_port
350
directives, with one port on each line. Syntax:
351
.Bd -literal -offset indent
352
.Cd use_http_port Oo Ar interface : Oc Ns Ar port
353
.Cd use_https_port Oo Ar interface : Oc Ns Ar port
354
.Ed
355
.Pp
356
.Ar interface
357
can be an IP (v4 or v6) address or a hostname. If provided, it is passed to
358
.Xr getaddrinfo 3
359
for resolution, and the first resulting address is used to bind to. Otherwise,
360
.Xr prayer 8
361
.No binds to Ar port No on all interfaces.
362
.
363
.It Cd ssl_default_port Vt ( number )
364
Prayer will put a warning on the login page for HTTP connections if
365
both HTTP and HTTPS sessions are available. This will provide a link
366
to the SSL version of the service, defaulting to port 443 or failing
367
that the first defined HTTPS port. ssl_default_port overrides the
368
built in logic.
369
.Pp
370
Should be rarely required now that Prayer automatically derives an
371
appropriate port if none is provided here.
372
.
373
.It Cd ssl_cert_file Vt ( path )
374
Locatation of SSL certificate file (only used if SSL ports defined).
375
Required if we are going to provide SSL services.
376
.
377
.It Cd ssl_privatekey_file Vt ( path )
378
Location of SSL private key file (only used if SSL ports defined).
379
Required if we are going to provide SSL services.
380
.
381
.It Cd ssl_rsakey_lifespan Vt ( time )
382
Master server will regenerate shared RSA key at this interval.
383
.Sy Default : Li 15m .
384
.
385
.It Cd ssl_rsakey_freshen Vt ( time )
386
RSA key remains fresh in child process for this long after first actual use.
387
.Sy Default : Li 15m .
388
.
389
.It Cd ssl_session_timeout Vt ( time )
390
SSL session cache TTL.
391
.Sy Default : Li 0 No (SSL session cache not used).
392
.Xr prayer-ssl-prune 8 should be run periodically to purge any stale session
393
data from the DBD database.
394
.
395
.It Cd egd_socket Vt ( path )
396
Path to entropy gathering daemon socket. If provided, it will be used in place of
397
or in addition to
398
.Pa /dev/urandom
399
.
400
.It Cd contact_email Vt ( string )
401
System administrator email address.
402
.Sy This setting is currently not used.
403
If you want to display support information to your users, customise the templates.
404
.
405
.It Cd fatal_dump_core Vt ( boolean )
406
Dump core on
407
.Fn fatal
408
error.
409
.Sy Default : No false.
410
.
411
.It Cd log_debug Vt ( boolean )
412
Enable somewhat more verbose logging, mainly in relation to SSL.
413
.Sy Default : No false.
414
.
415
.It Cd fix_client_ipaddr Vt ( boolean )
416
Client must connect from consistent IP addresses. May be useful as
417
a security measure in LAN environments. Painful for dialup users
418
whose connections may drop out.
419
.Sy Default : No false.
420
.
421
.It Cd gzip_allow_nets Vt ( string ) , Cd gzip_deny_nets Vt ( string )
422
.Xr prayer-session 8
423
gzip-compresses pages sent to clients if:
424
.Bl -enum -compact
425
.It
426
gzip compression enabled at compile time,
427
.It
428
.Cd use_gzip No is set in user preferences,
429
.It
430
User agent is known to support Content-Encoding: gzip,
431
.It
432
User agent asks for Content-Encoding: gzip or x-gzip,
433
.It
434
IP address of client appears in
435
.Cd gzip_allow_nets
436
.Em or No IP address of client does Em not No appear in Cd gzip_deny_nets .
437
.El
438
.Pp
439
The format of these options is a sequence of
440
.Ar ipaddr Ns Op / Ns Ar masklen
441
items, separated by colons
442
.Em and No whitespace (to allow for IPv6 addresses to be parsed easily). If
443
.Ar masklen No is omitted, the item is interpreted as a full host address.
444
.
445
.It Cd log_name_nets Vt ( string )
446
A network list in the same format as
447
.Cd gzip_allow_nets
448
above. To avoid delay when a user logs in,
449
.Xr prayer-session 8
450
only performs a reverse lookup of the remote address if matches this list.
451
.Sy Default : No empty; no reverse lookup are performed.
452
.
453
.It Cd limit_vm Vt ( number )
454
Virtual memory limit imposed on each process to stop runaway process killing system. See
455
.Xr setrlimit 2 .
456
.Sy Default : No no limit.
457
.
458
.It Cd http_max_method_size Vt ( number )
459
Prayer should in theory be able to cope with input of arbitrary
460
size. In practice however, the incoming request has to be stored
461
somewhere and without limits an attacker may exhaust available memory,
462
causing a denial of service attack.
463
.Pp
464
This sets the maximum size of the initial line of an HTTP request.
465
.Sy Default : No no limit.
466
.
467
.It Cd http_max_hdr_size Vt ( number )
468
Maximum for headers associated with this request.
469
.
470
.It Cd http_max_body_size Vt ( number )
471
Maximum for HTTP payload. This is the most significant one in normal use.
472
.
473
.It Cd draft_att_single_max ( Vt number )
474
Maximum size of a single attachment when composing a mail.
475
.Sy Default : Li 0 No (unlimited).
476
.
477
.It Cd draft_att_total_max ( Vt number )
478
Maximum size of all attachments.
479
.Sy Default : Li 0 No (unlimited).
480
.
481
.It Cd http_min_servers Vt ( number )
482
Minimum number of preforked
483
.Xr prayer 8 HTTP servers. The master process forks new slave processes
484
whenever the number of idle slaves falls below this number, unless the
485
total number of slaves would exceed
486
.Cd http_max_servers .
487
.Sy Default : Li 4.
488
.
489
.It Cd http_max_servers Vt ( number )
490
Maximum number of preforked
491
.Xr prayer 8 HTTP servers (active and idle). The master process does not,
492
however, enforce any maximum number of
493
.Em idle No slave processes; they have to terminate voluntarily by timing out
494
or serving the maximum number of connections.
495
.Sy Default : Li 64 .
496
.
497
.It Cd http_max_connections Vt ( number )
498
Maximum number of connections that each frontend server will process.
499
.Sy Default : Li 0 No (no limit).
500
.
501
.It Cd http_timeout_idle Vt ( time )
502
Timeout for (dirty) spare server waiting for another HTTP connection.
503
.Sy Default : Li 30s .
504
.
505
.It Cd http_timeout_icons Vt ( time )
506
Timeout for HTTP connection that last served static content.
507
.Sy Default : Li 10s .
508
.
509
.It Cd http_timeout_session Vt ( time )
510
Timeout for HTTP connection that last served a session URL or has not served anything yet.
511
.Sy Default : Li 60s .
512
.
513
.It Cd http_cookie_use_port Vt ( boolean )
514
Present HTTP cookies to browser as
515
.Dq Li username:port=value
516
rather than
517
.Dq Li username=value .
518
Allows simultaneous login sessions from a single client browser.
519
However can leave a trail of cookies behind. Probably don't want this
520
in the long term, it's here for experimentation purposes only at the
521
moment.
522
.
523
.It Cd icon_expire_timeout Vt ( time )
524
The amount of time in the future to set the HTTP
525
.Li Expires: No field for static content.
526
.Sy Default : Li 7d .
527
(In contrast sessions URLs expire immediately: Browsers really
528
shouldn't be trying to cache this stuff, especially when it is coming
529
in over HTTPS).
530
.El
531
.
532
.Ss Session specific configuration
533
.
534
.Bl -tag -width Ds
535
.
536
.It Cd session_idle_time Vt ( time )
537
Session switches to idle mode after this much time: connections to
538
IMAP and accountd servers are shut down.
539
.Sy Default : Li 0 No (idle mode disabled).
540
.
541
.It Cd session_timeout Vt ( time )
542
Session terminates after this much idle time.
543
.Ql 0
544
means session never times out.
545
.Sy Default : Li 4h .
546
.
547
.It Cd session_timeout_compose Vt ( time )
548
Session terminates after this much idle time instead when the last command was
549
.Ql compose
550
.No or Ql sieve .
551
It should probably not be set lower than
552
.Cd session_timeout .
553
.Sy Default : Li 0 No (always use the same timeout).
554
.
555
.It Cd stream_ping_interval Vt ( time )
556
Ping INBOX, Other, and Draft streams at this interval.
557
.Sy Default : Li 5m .
558
.
559
.It Cd stream_checkpoint Vt ( boolean )
560
.No Use Li CHECKPOINT No instead of Li PING Li to \(lqping\(rq streams.
561
.Sy Default : Li true .
562
.
563
.It Cd stream_misc_timeout Vt ( time )
564
Shut down Postponed, Preferences and Transfer streams entirely
565
after this much idle time, but only if idle mode doesn't beat us to it.
566
.Sy Default : Li 0 No (disabled).
567
.
568
.It Cd log_ping_interval Vt ( time )
569
.Xr stat 2 log files at this interval to see if target file has been
570
renamed or removed.
571
.Ql 0s
572
means stat() log file every time something is logged.
573
.Sy Default : Li 5m .
574
.
575
.It Cd db_ping_interval Vt ( time )
576
Interval at which to re-read CDB files containing the local domain.
577
.Sy Default : Li 30m .
578
.El
579
.
580
.Ss Display specific configuration
581
.
582
.Bl -tag -width Ds
583
.It Cd login_banner Vt ( string )
584
Used in the
585
.Li <title>
586
and heading of the login page, unless
587
.Cd login_prefix_path
588
specifies a custom first HTML part.
589
.Sy Default : Li """Webmail Service Login""" .
590
.
591
.It Cd login_service_name Vt ( string )
592
Used in the
593
.Li <title> No and elsewhere to refer to the webmail system
594
.Em after No the user has logged in.
595
.Sy Default : Li """Prayer""" .
596
.
597
.It Cd login_prefix_path Vt ( path )
598
File to use as the part of the login page before the login
599
form. Should include everything including DOCTYPE and <html> tag.  If
600
unset, Prayer constructs a fairly safe and boring login page
601
consisting of the
602
.Cd login_banner .
603
on the background colour of the default main theme.
604
.
605
.It Cd motd_path Vt ( path )
606
File to use as the part of the login page immediately following the login form.
607
.
608
.It Cd login_suffix_path Vt ( path )
609
File to use as the last part of the login page. If unset, Prayer simply outputs
610
.Dq Li </body></html> .
611
.
612
.It Cd ssl_encouraged ( Vt boolean )
613
If the user connects over unencrypted HTTP, do not show the login form on the start
614
.Pa ( / ) No page. A link to Pa /login , No where the form is still displayed, is still provided.
615
.Sy Default : Li false . No Ignored if Cd ssl_redirect No or Cd ssl_required No is Li true .
616
.
617
.It Cd ssl_redirect ( Vt boolean )
618
If the user connects over unencrypted HTTP, return a
619
.Ql 302
620
redirect to the default SSL port. Only the start
621
.Pa ( / ) No page is redirected and it may be possible to switch between http and
622
https after loggin in, subject to cookie rules.
623
.Pp
624
.Sy Default : Li false .
625
.
626
.It Cd ssl_required ( Vt boolean )
627
Return a
628
.Ql 403 Forbidden
629
error if the user tries to access anything over unencrypted HTTP.
630
.Cd ssl_redirect No still has effect, however.
631
.
632
.It Cd list_addr_maxlen Vt ( number )
633
The maximum number of characters to show from addresses on the mailbox list screen.
634
.Sy Default : Li 30 .
635
.
636
.It Cd list_subject_maxlen Vt ( number )
637
The maximum number of characters to show from the subject on the mailbox list screen.
638
.Sy Default : Li 30 .
639
.
640
.It Cd change_max_folders ( Vt number )
641
The maximum number of folders allowed in the quick folder change
642
dropdown list. If there would be too many folders, the quick list is
643
disabled altogether. Only folders that are expanded in the folder view
644
are included.
645
.Pp
646
.Sy Default : Li 20 .
647
.
648
.It Cd template_path ( Vt path )
649
Path to uncompiled template sets (directories).
650
.Sy Default : Li """../templates""" No (relative to
651
.Cd tmp_dir ) .
652
.
653
.It Cd template_set ( Vt string )
654
Template set to use.
655
.Sy Default : Li """xhtml_strict""" .
656
.
657
.It Cd template_use_compiled ( Vt boolean )
658
Use the compiled-in templates, ignoring
659
.Cd template_path .
660
.Sy Default : Li true .
661
.Pp
662
As a Debian extension,
663
.Xr prayer-session 8
664
will fall back to the compiled-in template version of any template
665
that it cannot find in the template directory. This enables
666
customization of some templates without having to compile all of them
667
at run time, although attempting to open each template still incurs a
668
certain penalty.
669
.
670
.It Cd theme
671
Define themes and their colors.
672
.Em Semi-deprecated ; No Colours set with this directive are only used by the
673
.Li xhtml_transitional No template set. The
674
.Li xhtml_strict No template set, as well as the login screen, use CSS instead.
675
It is still necessary to tell Prayer which themes are available, however.
676
.Pp
677
Syntax:
678
.Bd -literal -offset indent
679
.Cd theme Ar name Li description Ar description
680
.Cd theme Ar name element colour
681
.Cd theme Ar name element colour
682
\&...
683
.Ed
684
.Pp
685
.Ar description No is the label shown in the theme dropdown lists on the
686
General Preferences page.
687
.Pp
688
.Ar element No is one of
689
.Li fgcolor , fgcolor_link , bgcolor , bgcolor_banner , bgcolor_row1 , bgcolor_row2 ,
690
.Li bgcolor_status , bgcolor_status_none , fgcolor_quote1 , fgcolor_quote2 ,
691
.Li fgcolor_quote3 , No and Li fgcolor_quote4 .
692
The first three are not used by any standard template set, but are
693
available.  Please study the templates to understand how the rest are
694
used.
695
.Pp
696
.Ar colour No is any valid HTML Vt %Color No value.
697
Remember that strings containing hash marks need to be quoted.
698
.It Cd theme_default_main ( Vt string )
699
.No The Ar name No of the default theme.
700
.
701
.It Cd theme_default_main ( Vt string )
702
.No The Ar name No of the default theme in help mode.
703
.
704
.It Cd use_ispell_language
705
Ispell languages that we want to support, with some descriptive text
706
for the preferences screen. Syntax:
707
.Bd -literal -offset indent
708
.Cd use_ispell_language Ar wordlist Ar description
709
.Ed
710
.Pp
711
Example:
712
.Bd -literal -offset indent
713
.Li use_ispell_language british Qq British English
714
.Ed
715
.El
716
.
717
.Ss Paths etc.
718
.
719
.Bl -tag -width Ds
720
.
721
.It Cd aspell_path ( Vt path )
722
Location of Aspell Binary (takes precedence over
723
.Cd ispell_path ) .
724
.
725
.It Cd bin_dir ( Vt path )
726
Location of Prayer binaries
727
.Xr ( prayer 8 and
728
.Xr prayer-session 8 ) .
729
.Sy Default : No none. Sy Must be set.
730
.
731
.It Cd icon_dir ( Vt path )
732
Location of icon files.
733
.Sy Default : No none. Sy Must be set.
734
.
735
.It Cd ispell_path ( Vt path )
736
Location of Ispell Binary (backwards compatibility only).
737
.
738
.It Cd log_dir ( Vt path )
739
Location of log files.
740
.Sy Default : No none. Sy Must be set.
741
.
742
.It Cd pid_dir ( Vt path )
743
Location for PID files of prayer and prayer-session master processes.
744
.Sy Default : No none. Sy Must be set.
745
.
746
.It Cd sendmail_path ( Vt path )
747
Location of sendmail binary or drop in replacement such as Exim.
748
.Sy Default : Pa /usr/lib/sendmail .
749
.
750
.It Cd socket_dir ( Vt path )
751
Location for unix domain sockets which connect
752
.Xr ( prayer 8 to
753
.Xr prayer-session 8 ) .
754
.
755
.It Cd socket_split_dir ( Vt boolean )
756
Split socket directory into 64 subdirs keyed on first letter of
757
sessionID. It is possible to switch back and forth without moving
758
sockets or killing sessions, since
759
.Xr prayer 8 tries both variants. \&In effect, this setting merely controls where
760
.Xr prayer-session 8 creates the socket files.
761
.Sy Default : Li false .
762
.
763
.It Cd init_socket_name ( Vt string )
764
Name of Unix domain socket (in
765
.Cd socket_dir ) No used for initial handshake
766
between prayer and prayer-session processes when a user logs in.
767
.Sy Default : No none. Sy Must be set.
768
.
769
.It Cd ssl_session_dir ( Vt path )
770
Location of the SSL session cache database.
771
.Sy Default : No none. Sy Must be set , No even if the SSL session cache is disabled.
772
.
773
.It Cd static_dir ( Vt path )
774
Location of other static files (CSS).
775
.Sy Default : No none. If unset, Prayer will not serve CSS files.
776
.
777
.It Cd tmp_dir ( Vt path )
778
As the directory both daemons
779
.Xr chdir 2
780
to at startup, it is where temporary files, such as attachments and
781
folders in transist during upload and download operations, are
782
written. Core files also end up here.
783
.Sy Default : No none. Sy Must be set.
784
.El
785
.
786
.Ss Defaults for user preferences
787
.
788
.Bl -tag -width Ds
789
.
790
.It Cd confirm_logout ( Vt boolean )
791
Confirmation dialogue when user logs out.
792
.Sy Default : Li true .
793
.
794
.It Cd confirm_expunge ( Vt boolean )
795
Confirmation dialogue when user hits expunge.
796
.Sy Default : Li false .
797
.
798
.It Cd confirm_rm ( Vt boolean )
799
Confirmation dialogue when user deletes mail folder or directory.
800
.Sy Default : Li true .
801
.
802
.It Cd default_domain Vt ( string )
803
Default domain for outgoing mail. Defaults to
804
.Cd hostname No setting.
805
.
806
.It Cd html_inline ( Vt boolean )
807
Show text/html bodyparts inline. Content is scrubbed to remove
808
dangerous tags; see documentation for more details.
809
.Sy Default : Li true .
810
.
811
.It Cd html_inline_auto ( Vt boolean )
812
Same as above for text/* bodyparts which start "<HTML>" (case-independent!)
813
Does anyone other than spammers actually use this?
814
.Sy Default : Li true .
815
.
816
.It Cd ispell_language ( Vt string )
817
Language for ispell.
818
.Sy Default : Li """british""" .
819
.
820
.It Cd msgs_per_page ( Vt number )
821
Number of messages per screen on message list screen.
822
.Sy Default : Li 12 .
823
.
824
.It Cd msgs_per_page_max ( Vt number )
825
Maximum value that users are allowed to set
826
.Cd msgs_per_page No to.
827
.Sy Default : Li 50 .
828
.
829
.It Cd msgs_per_page_min ( Vt number )
830
Minimum value that users are allowed to set
831
.Cd msgs_per_page No to.
832
.Sy Default : Li 4 .
833
.
834
.It Cd abook_per_page ( Vt number )
835
Number of addressbook entries per page on address book list screen.
836
.Sy Default : Li 12 .
837
.
838
.It Cd abook_per_page_max ( Vt number )
839
Maximum value that users are allowed to set
840
.Cd abook_per_page No to.
841
.Sy Default : Li 50 .
842
.
843
.It Cd abook_per_page_min ( Vt number )
844
Minimum value that users are allowed to set
845
.Cd abook_per_page No to.
846
.Sy Default : Li 4 .
847
.
848
.It Cd maildir ( Vt string )
849
Mail directory in user's account.
850
.Sy Default : Li """""" .
851
Typically needed with uw-imap. Typically not needed with e.g. Dovecot or Courier.
852
.
853
.It Cd suppress_dotfiles ( Vt boolean )
854
Supress dotfiles from directory listing.
855
.Sy Default : Li true .
856
.
857
.It Cd postponed_folder ( Vt string )
858
Name of the folder where messages to be sent later, a.k.a. drafts, are stored.
859
.Sy Default : Li """postponed-msgs""" .
860
.
861
.It Cd sent_mail_folder ( Vt string )
862
Name of folder for sent mail.
863
.Sy Default : Li """sent-mail""" .
864
.
865
.It Cd small_cols ( Vt number )
866
Width of small compose textarea in columns.
867
.Sy Default : Li 80 .
868
.
869
.It Cd small_rows ( Vt number )
870
Height of small compose textarea in lines.
871
.Sy Default : Li 18 .
872
.
873
.It Cd large_cols ( Vt number )
874
Width of large compose textarea in columns.
875
.Sy Default : Li 80 .
876
.
877
.It Cd large_rows ( Vt number )
878
Height of large compose textarea in lines.
879
.Sy Default : Li 32 .
880
.
881
.It Cd sort_mode ( Vt string )
882
Default Sort mode for mailbox list. One of
883
.Li ARRIVAL , DATE , FROM , TO , CC , SIZE , SUBJECT , REFERENCES , ORDEREDSUBJECT .
884
.Sy Default : Li ARRIVAL No is most efficient, and recommended.
885
.
886
.It Cd sort_reverse ( Vt boolean )
887
Favour reverse sort rather than normal sort order?
888
.Sy Default : Li false .
889
.
890
.It Cd abook_sort_mode ( Vt string )
891
Default Sort mode for addressbook list. One of:
892
.Li ORDERED , ALIAS , NAME , COMMENT , ADDRESS .
893
.Sy Default : Li ORDERED .
894
.
895
.It Cd abook_sort_reverse ( Vt boolean )
896
Favour reverse sort rather than normal sort order?
897
.Sy Default : Li false .
898
.
899
.It Cd line_wrap_len ( Vt number )
900
Wrap lines at this many characters.
901
.Sy Default : Li 76 .
902
.
903
.It Cd line_wrap_advanced ( Vt boolean )
904
Enable advanced line wrap options?
905
.Sy Default : Li false .
906
.
907
.It Cd line_wrap_on_reply ( Vt boolean )
908
Line wrap automatically on reply.
909
.Sy Default : Li true .
910
.
911
.It Cd line_wrap_on_spell ( Vt boolean )
912
Line wrap automatically on spell check.
913
.Sy Default : Li true .
914
.
915
.It Cd line_wrap_on_send ( Vt boolean )
916
Line wrap automatically on send.
917
.Sy Default : Li true .
918
.
919
.It Cd preserve_mimetype ( Vt boolean )
920
Send message Content-Type through to browser. If
921
.Li false , No Content-Type is replaced with
922
.Ql application/octet-stream
923
which should force download to local disk, bypassing any automatic
924
processing of bodyparts by the User-Agent. Unclear at the moment
925
whether we need to do this, or whether this should be done selectively
926
based on the User-Agent.
927
.Sy Default : Li true .
928
.
929
.It Cd use_sent_mail ( Vt boolean )
930
.No Make the Dq Save copy
931
checkbox on the compose screen checked default.
932
.Sy Default : Li true .
933
.
934
.It Cd use_mark_persist ( Vt boolean )
935
Use persistent mark for aggregate operations.
936
.Sy Default : Li false .
937
.
938
.It Cd use_search_zoom ( Vt boolean )
939
Zoom automatically after sucessful search
940
.Sy Default : Li true .
941
.
942
.It Cd use_agg_unmark ( Vt boolean )
943
Unmark messages after sucessful aggregate operation.
944
.Sy Default : Li true .
945
.
946
.It Cd use_icons ( Vt boolean )
947
Use icons: may be overriden by value of User-Agent.
948
.Sy Default : Li true .
949
.
950
.It Cd use_welcome ( Vt boolean )
951
Enable welcome screen .
952
.Sy Default : Li true .
953
.
954
.It Cd use_tail_banner ( Vt boolean )
955
Duplicate banner icons (toolbar) at the bottom of the Message screen.
956
.Sy Default : Li true .
957
.El
958
.
959
.Ss Hidden preferences
960
.
961
The following options are internally handled as user preferences, but
962
the Preferences screen no longer provides any means for changing them.
963
.
964
.Bl -tag -width Ds
965
.It Cd use_cookie ( Vt boolean )
966
Use HTTP cookie for Session-ID, if the browser supports cookies
967
If disabled, or user rejects the cookie, then the session-ID is stored in the URL.
968
.Sy Default : Li true .
969
.
970
.It Cd use_substitution ( Vt boolean )
971
Use page substiution rather than HTTP redirects. Faster, but the URLs
972
that are generated are less predictable.  Page substitution and browser
973
history mechanism don't coexist well at the moment (Prayer would need to
974
cache final page value for each substiution event).
975
.Pp
976
.Sy Default : Li true .
977
.
978
.It Cd use_http_1_1 ( Vt boolean )
979
Allow HTTP/1.1, if the browser supports it.
980
.Sy Default : Li true .
981
.
982
.It Cd use_pipelining ( Vt boolean )
983
Allow HTTP/1.1 pipelining, if the browser supports it.
984
.Sy Default : Li true .
985
.
986
.It Cd use_embed_http ( Vt boolean )
987
Allow HTTP links embedded in HTTPS responses, if the browser supports it.
988
.Sy Default : Li true .
989
.
990
.It Cd use_persist ( Vt boolean )
991
Allow persistent HTTP/1.1 and HTTP/1.0 persistent connections,
992
if the browser supports them.
993
.Sy Default : Li true .
994
.
995
.It Cd use_short ( Vt boolean )
996
Allow short URLs, if the browser supports them.
997
.Sy Default : Li true .
998
.
999
.It Cd use_gzip ( Vt boolean )
1000
Allow gzip compression, if the browser supports it.
1001
.Sy Default : Li true .
1002
.
1003
.El
1004
.
1005
.Sh SEE ALSO
1006
.
1007
.Xr prayer 8 ,
1008
.Xr prayer-session 8
1009
.
1010
.Sh AUTHORS
1011
.
1012
This manual page was put together by
1013
.An "Magnus Holmgren" <holmgren@debian.org>
1014
using documentation written by
1015
.An "David Carter" <dpc22@cam.ac.uk> .