WebSVN - Diff - Rev 93 and 170 - /trunk/debian/README.Debian


prayer for Debian
-----------------

The Debian version of Prayer is built with SSL support with session
cache using the latest libdb, gzip Content-Transfer-Encoding, LDAP,
and System V mutex support. The initial Debian release, which was only
uloaded to the experimental distribution, was heavily patched to add
UTF-8 and IPv6 support among other things. All that has been
incorporated and improved by upstream in 1.1.0. The remaining patches
concern changes to the default configuration as detailed below, or fix
bugs. You can always find information about patches in
changelog.Debian.gz.

To enable Prayer, run update-rd.c prayer enable. But before you do
 
that you should go through /etc/prayer/prayer.cf and adapt it to your
needs. In particular, if you already run a web server on this machine
you need to change use_http_port (and use_https_port) to something
else.

Debian-specific configuration defaults:

 * Static files (templates, icons, CSS files) are installed in
   /usr/share/prayer in accordance with policy. The prefix option
   points there, while var_prefix, the location of pid files
   (pid_dir), sockets (socket_dir), the SSL session cache
   (ssl_session_dir), and temporary storage of uploaded attachments
   (tmp_dir), is /var/run/prayer and subdirectories.  Log files are
   written to /var/log/prayer (log_dir).

 * Prayer by default runs as user prayer (created on install) and
   group nogroup. The prayer user is added to the ssl-cert group on
   installation, so that it can access keys in /etc/ssl/private.

 * ssl_cert_file and ssl_privatekey_file point to the "snake oil"
   certificate and key created by the ssl-cert package, so that you
   only have to uncomment use_https_port to enable encryption. For a
   production server you should of course install a real certificate.

 * Support for SSL session caching is compiled in, but caching is
   disabled by default, as it probably doesn't make that much a
   difference on modern hardware. To enable it, uncomment the
   ssl_session_timeout setting in prayer.cf. You should also arrange
   for prayer-ssl-prune to be run periodically, for example by placing
   a symlink to it in /etc/cron.hourly or /etc/cron.daily.

 * The default IMAP folders for sent mail (sent_mail_folder) and
   drafts (postponed_folder) are "Sent" and "Drafts", respectively,
   the default for Mozilla Thunderbird and others (although many IMAP
   clients unfortunately use localized folder names).

 * socket_split_dir is off by default to reduce complexity when
   testing. You will probably only need it if you have lots of
   simultaneous users and a file system without directory indexes.

Customizing templates:

To use customized templates you must set template_use_compiled to
FALSE in prayer.cf. Then copy the template (.t file) you wish to
customize from /usr/share/prayer/templates to the corresponding
location under /etc/prayer/templates and edit it there. Prayer will
still use the compiled-in versions of the remaining templates, thanks
to a small patch.

Quirks:

 * If your IMAP server supports STARTTLS, then Prayer (actually the
   libc-client IMAP client library) will use it automatically. To
   disable, append "/notls" to the IMAP server name(s) specified with
   imapd_server. To force TLS, append "/tls". Make sure that the
   server name you specify for imapd_server in prayer.cf matches the
   Common Name in the SSL certificate; otherwise libc-client will
   refuse to accept it. To disable that check, use "/novalidate-cert".
   Other switches you can append are listed in the file naming.txt.gz
   in the documentation directory of the C-client library.

 * If your IMAP server is Dovecot (or any of a number of others,
   probably), then you must change prefs_folder_name to something not
   containing a dot. Unfortunately this means that the preference
   folder will be fully visible.

 * Prayer doesn't handle signals gracefully yet, which means that it
   will leave SysV semaphores lying around when it is stopped or
   restarted.  You can use ipcs to find them and ipcrm to delete them.

 * While Prayer does its best to remove potentially harmful tags from
   HTML email, it doesn't try to convert it to XHTML. This means that
   Prayer's output is conformant XHTML only when not viewing HTML
   mail.

 * Prayer deletes mail the IMAP way, which is by marking messages as
   deleted and leaving them in their folders. Prayer always lists
   deleted messages (with a special icon) and expunges (deletes
   permanently) deleted messages only when explicitly requested.
   Before that they can be undeleted at any time by "unmarking" them.

   Most mail client software deletes mail by moving it to a "trash"
   folder, which in reality means creating a copy in the trash folder
   and marking the original deleted. Messages that are marked as
   deleted are usually never listed, cannot be unmarked, and are often
   automatically expunged. These two approaches are rather
   incompatible, but some software can take either.

 -- Magnus Holmgren <holmgren@debian.org>, Sat, 27 Oct 2018 21:26:25 +0200


Subversion Repositories

(root)/trunk/debian/README.Debian @ 140 - Rev 93 → 170

Rev 93		Rev 170
1	prayer for Debian	1	prayer for Debian
2	-----------------	2	-----------------
3		3
4	The Debian version of Prayer is built with SSL support with session	4	The Debian version of Prayer is built with SSL support with session
5	cache using the latest libdb, gzip Content-Transfer-Encoding, LDAP,	5	cache using the latest libdb, gzip Content-Transfer-Encoding, LDAP,
6	and System V mutex support. The initial Debian release, which was only	6	and System V mutex support. The initial Debian release, which was only
7	uloaded to the experimental distribution, was heavily patched to add	7	uloaded to the experimental distribution, was heavily patched to add
8	UTF-8 and IPv6 support among other things. All that has been	8	UTF-8 and IPv6 support among other things. All that has been
9	incorporated and improved by upstream in 1.1.0. The remaining patches	9	incorporated and improved by upstream in 1.1.0. The remaining patches
10	concern changes to the default configuration as detailed below, or fix	10	concern changes to the default configuration as detailed below, or fix
11	bugs. You can always find information about patches in	11	bugs. You can always find information about patches in
12	changelog.Debian.gz.	12	changelog.Debian.gz.
13		13
14	To enable Prayer, you must edit /etc/default/prayer and change	14	To enable Prayer, run update-rd.c prayer enable. But before you do
15	ENABLED=0 to ENABLED=1. But before you do that you should go through	-
16	/etc/prayer/prayer.cf and adapt it to your needs. In particular, if	15	that you should go through /etc/prayer/prayer.cf and adapt it to your
17	you already run a web server on this machine you need to change	16	needs. In particular, if you already run a web server on this machine
18	use_http_port (and use_https_port) to something else.	17	you need to change use_http_port (and use_https_port) to something
-		18	else.
19		19
20	Debian-specific configuration defaults:	20	Debian-specific configuration defaults:
21		21
22	* Static files (templates, icons, CSS files) are installed in	22	* Static files (templates, icons, CSS files) are installed in
23	/usr/share/prayer in accordance with policy. The prefix option	23	/usr/share/prayer in accordance with policy. The prefix option
24	points there, while var_prefix, the location of pid files	24	points there, while var_prefix, the location of pid files
25	(pid_dir), sockets (socket_dir), the SSL session cache	25	(pid_dir), sockets (socket_dir), the SSL session cache
26	(ssl_session_dir), and temporary storage of uploaded attachments	26	(ssl_session_dir), and temporary storage of uploaded attachments
27	(tmp_dir), is /var/run/prayer and subdirectories. Log files are	27	(tmp_dir), is /var/run/prayer and subdirectories. Log files are
28	written to /var/log/prayer (log_dir).	28	written to /var/log/prayer (log_dir).
29		29
30	* Prayer by default runs as user prayer (created on install) and	30	* Prayer by default runs as user prayer (created on install) and
31	group nogroup. The prayer user is added to the ssl-cert group on	31	group nogroup. The prayer user is added to the ssl-cert group on
32	installation, so that it can access keys in /etc/ssl/private.	32	installation, so that it can access keys in /etc/ssl/private.
33		33
34	* ssl_cert_file and ssl_privatekey_file point to the "snake oil"	34	* ssl_cert_file and ssl_privatekey_file point to the "snake oil"
35	certificate and key created by the ssl-cert package, so that you	35	certificate and key created by the ssl-cert package, so that you
36	only have to uncomment use_https_port to enable encryption. For a	36	only have to uncomment use_https_port to enable encryption. For a
37	production server you should of course install a real certificate.	37	production server you should of course install a real certificate.
38		38
39	* Support for SSL session caching is compiled in, but caching is	39	* Support for SSL session caching is compiled in, but caching is
40	disabled by default, as it probably doesn't make that much a	40	disabled by default, as it probably doesn't make that much a
41	difference on modern hardware. To enable it, uncomment the	41	difference on modern hardware. To enable it, uncomment the
42	ssl_session_timeout setting in prayer.cf. You should also arrange	42	ssl_session_timeout setting in prayer.cf. You should also arrange
43	for prayer-ssl-prune to be run periodically, for example by placing	43	for prayer-ssl-prune to be run periodically, for example by placing
44	a symlink to it in /etc/cron.hourly or /etc/cron.daily.	44	a symlink to it in /etc/cron.hourly or /etc/cron.daily.
45		45
46	* The default IMAP folders for sent mail (sent_mail_folder) and	46	* The default IMAP folders for sent mail (sent_mail_folder) and
47	drafts (postponed_folder) are "Sent" and "Drafts", respectively,	47	drafts (postponed_folder) are "Sent" and "Drafts", respectively,
48	the default for Mozilla Thunderbird and others (although many IMAP	48	the default for Mozilla Thunderbird and others (although many IMAP
49	clients unfortunately use localized folder names).	49	clients unfortunately use localized folder names).
50		50
51	* socket_split_dir is off by default to reduce complexity when	51	* socket_split_dir is off by default to reduce complexity when
52	testing. You will probably only need it if you have lots of	52	testing. You will probably only need it if you have lots of
53	simultaneous users and a file system without directory indexes.	53	simultaneous users and a file system without directory indexes.
54		54
55	Customizing templates:	55	Customizing templates:
56		56
57	To use customized templates you must set template_use_compiled to	57	To use customized templates you must set template_use_compiled to
58	FALSE in prayer.cf. Then copy the template (.t file) you wish to	58	FALSE in prayer.cf. Then copy the template (.t file) you wish to
59	customize from /usr/share/prayer/templates to the corresponding	59	customize from /usr/share/prayer/templates to the corresponding
60	location under /etc/prayer/templates and edit it there. Prayer will	60	location under /etc/prayer/templates and edit it there. Prayer will
61	still use the compiled-in versions of the remaining templates, thanks	61	still use the compiled-in versions of the remaining templates, thanks
62	to a small patch.	62	to a small patch.
63		63
64	Quirks:	64	Quirks:
65		65
66	* If your IMAP server supports STARTTLS, then Prayer (actually the	66	* If your IMAP server supports STARTTLS, then Prayer (actually the
67	libc-client IMAP client library) will use it automatically. To	67	libc-client IMAP client library) will use it automatically. To
68	disable, append "/notls" to the IMAP server name(s) specified with	68	disable, append "/notls" to the IMAP server name(s) specified with
69	imapd_server. To force TLS, append "/tls". Make sure that the	69	imapd_server. To force TLS, append "/tls". Make sure that the
70	server name you specify for imapd_server in prayer.cf matches the	70	server name you specify for imapd_server in prayer.cf matches the
71	Common Name in the SSL certificate; otherwise libc-client will	71	Common Name in the SSL certificate; otherwise libc-client will
72	refuse to accept it. To disable that check, use "/novalidate-cert".	72	refuse to accept it. To disable that check, use "/novalidate-cert".
73	Other switches you can append are listed in the file naming.txt.gz	73	Other switches you can append are listed in the file naming.txt.gz
74	in the documentation directory of the C-client library.	74	in the documentation directory of the C-client library.
75		75
76	* If your IMAP server is Dovecot (or any of a number of others,	76	* If your IMAP server is Dovecot (or any of a number of others,
77	probably), then you must change prefs_folder_name to something not	77	probably), then you must change prefs_folder_name to something not
78	containing a dot. Unfortunately this means that the preference	78	containing a dot. Unfortunately this means that the preference
79	folder will be fully visible.	79	folder will be fully visible.
80		80
81	* Prayer doesn't handle signals gracefully yet, which means that it	81	* Prayer doesn't handle signals gracefully yet, which means that it
82	will leave SysV semaphores lying around when it is stopped or	82	will leave SysV semaphores lying around when it is stopped or
83	restarted. You can use ipcs to find them and ipcrm to delete them.	83	restarted. You can use ipcs to find them and ipcrm to delete them.
84		84
85	* While Prayer does its best to remove potentially harmful tags from	85	* While Prayer does its best to remove potentially harmful tags from
86	HTML email, it doesn't try to convert it to XHTML. This means that	86	HTML email, it doesn't try to convert it to XHTML. This means that
87	Prayer's output is conformant XHTML only when not viewing HTML	87	Prayer's output is conformant XHTML only when not viewing HTML
88	mail.	88	mail.
89		89
90	* Prayer deletes mail the IMAP way, which is by marking messages as	90	* Prayer deletes mail the IMAP way, which is by marking messages as
91	deleted and leaving them in their folders. Prayer always lists	91	deleted and leaving them in their folders. Prayer always lists
92	deleted messages (with a special icon) and expunges (deletes	92	deleted messages (with a special icon) and expunges (deletes
93	permanently) deleted messages only when explicitly requested.	93	permanently) deleted messages only when explicitly requested.
94	Before that they can be undeleted at any time by "unmarking" them.	94	Before that they can be undeleted at any time by "unmarking" them.
95		95
96	Most mail client software deletes mail by moving it to a "trash"	96	Most mail client software deletes mail by moving it to a "trash"
97	folder, which in reality means creating a copy in the trash folder	97	folder, which in reality means creating a copy in the trash folder
98	and marking the original deleted. Messages that are marked as	98	and marking the original deleted. Messages that are marked as
99	deleted are usually never listed, cannot be unmarked, and are often	99	deleted are usually never listed, cannot be unmarked, and are often
100	automatically expunged. These two approaches are rather	100	automatically expunged. These two approaches are rather
101	incompatible, but some software can take either.	101	incompatible, but some software can take either.
102		102
103	-- Magnus Holmgren <holmgren@debian.org>, Wed, 30 Sep 2009 22:57:19 +0200	103	-- Magnus Holmgren <holmgren@debian.org>, Sat, 27 Oct 2018 21:26:25 +0200
104		104