"Fossies" - the Fresh Open Source Software Archive 
Member "courier-1.2.2/INSTALL" (19 Feb 2023, 202014 Bytes) of package /linux/misc/courier-1.2.2.tar.bz2:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the last
Fossies "Diffs" side-by-side code changes report for "INSTALL":
1.1.11_vs_1.2.0.
1 NOTE: a more readable HTML version of this INSTALL document can be found
2 in courier/doc/install.html.
3
4 Installation
5
6 Building rpm and deb packages
7
8 These are not the same packages as the ones from various distributions'
9 repositories. These packages carry a higher internal revision level in
10 order to prevent them from getting upgraded by the distribution packaging.
11 These packages exist in order to have a convenient way of updating after a
12 release without waiting for the distribution's package to get built.
13
14 NOTE: If a distribution package is already installed it should be removed
15 completely before switching to the upstream version (dnf remove or apt
16 purge). Preserve any existing configuration files, beforehand, in order to
17 restore it after switching packages. This applies to all Courier packages.
18 A switch to this courier package requires switching the courier-unicode
19 and courier-authlib packages too.
20
21 NOTE: These packages use their own, generic, installation layout that may
22 deviate slightly from the package installation conventions preferred by
23 the distributions:
24
25 • The main "courier" package. This installs the main mail server that
26 starts locally but does not listen on the smtp port until the
27 appropriate esmtpd configuration files enable the smtp port
28 listener(s).
29
30 • The "courier-maildrop" package. This package installs the maildrop
31 mail filter.
32
33 • The "courier-imapd" and "courier-pop3d" packages. Installing them
34 results in the IMAP and the POP3 server getting started and listening
35 on the respective ports, and a self-signed SSL certificate gets
36 automatically generated, for testing purposes, until it gets replaced
37 by your real one.
38
39 • The "courier-webmail" package. This package installs the sqwebmail
40 webmail server.
41
42 • The "courier-mlm" package. This package installs the couriermlm
43 mailing list manager.
44
45 • The "courier-mlm-web" package. This package installs couriermlm's
46 web-based gateway.
47
48 • The "courier-webadmin" package. This installs the webadmin module, for
49 a basic browser-based configuration module. The "courier-ldap" module
50 installs the LDAP-based alias daemon and the webadmin page for
51 configuring it. The "courier-mysql" and "courier-pgsql" packages
52 install webadmin pages for configuring mysql and postgres-based
53 account authentication. The "courier-fax" package installs webadmin
54 pages and scripts for integrating with the mgetty+sendfax gateway.
55
56 • deb only: the "-apache2" deb packages install apache2 configuration
57 files that enable each corresponding module.
58
59 The main "courier" package starts all modules, whichever modules are
60 installed. Depending on the distribution installing the main "courier"
61 package may or may not automatically start it. Installing or uninstalling
62 an additional package with a service may or may not result in an
63 appropriate restart.
64
65 rpm
66
67 Run dnf install rpm-build if it's not installed already, then:
68
69 rpmbuild -ta courier-version.tar.bz2
70
71 If this fails due to any missing dependencies, install them. This will
72 eventually create source and binary RPM packages. This works for all
73 Courier packages.
74
75 Changing the options that the RPMs are built with
76
77 Building the RPMs directly from the source tarball uses the default
78 options programmed into the tarball. Sometimes you may want to use
79 different options. For example, you might want to enable fixes for certain
80 bugs in some IMAP clients. Use the following procedure to build the RPMs
81 with different options:
82
83 • First, build the RPM packages using the default options.
84 • In addition to binary RPM packages, rpmbuild will create a source RPM
85 package (filename.src.rpm)
86 • Install the source RPM package: rpm -i courier-version.src.rpm.
87 • The contents of the source RPM package get installed into your rpm
88 build directory, which is usually $HOME/rpm/package.
89 • Edit the .spec file, modifying the default configuration. You will
90 need to have some understanding of how RPM spec files work, then use
91 the modified spec file to build your custom package: rpmbuild -ba
92 filename.spec
93
94 Building DEB packages
95
96 Create an empty directory and copy/move the tarball into it:
97
98 $ mkdir tmp
99 $ mv courier-VERSION.tar.bz2 tmp
100 $ cd tmp
101
102 Unpack the tarball and cd into the unpacked subdirectory:
103
104 $ tar xvf courier-VERSION.tar.bz2
105 $ cd courier-VERSION
106
107 Run the courier-debuild script, which is a wrapper for debuild, and
108 forwards its parameters to it:
109
110 $ courier-debuild -us -uc
111
112 NOTE: the above steps must be followed strictly. The courier-debuild
113 script expects the distributed tarball in its parent directory.
114
115 This eventually produces a deb subdirectory with .deb packages that can be
116 installed with "dpkg -i".
117
118 Maintainer Mode (see README in the git repository to set up)
119
120 make rpm or make deb, as appropriate, will:
121
122 1. Increment an internal release number.
123
124 2. Run make dist.
125
126 3. Proceed and build a new release, creating the native packages in the
127 rpm or deb subdirectory.
128
129 Manual installation
130
131 > ═════════════════════════════════════════════════════════════════════════
132
133 > NOTE:
134
135 > This documentation describes manual installation of the Courier mail
136 > server. This is a somewhat involved process that may overwhelm people
137 > that do not have prior experience with installing large software
138 > packages. Many distributions have a separately-maintained,
139 > preconfigured, ready-to-install packages that can be loaded with much
140 > less investment of time. Installing a pre-built package would probably
141 > be the best approach in this case.
142
143 > Should you choose to install a platform-specific prebuilt package, you
144 > should carefully read any custom documentation files that are included
145 > in the package. Most platform-specific packages provide custom,
146 > non-default configuration settings that are optimized for that
147 > platform's unique policies. Feedback about platform-specific precompiled
148 > packages should be copied to the development group that maintains the
149 > package, in additional to the platform-neutral courier-users mailing
150 > list.
151
152 > ═════════════════════════════════════════════════════════════════════════
153
154 Read this document in its entirety before entering a single command.
155 Installing the Courier mail server for the first time will take a while.
156 If possible, consider looking around for anyone who has already packaged
157 the Courier mail server for your operating system, and save yourself the
158 hassle.
159
160 Fortunately, it gets easier with each subsequent installation. The Courier
161 mail server is a complicated piece of software. Most problems people will
162 have are likely to be with the configuring and installing it correctly.
163 Designing complex software that compiles and installs on a wide variety of
164 POSIX systems is not a trivial task.
165
166 The Courier mail server's configuration and installation scripts are very
167 flexible in setting up installation directories for each logical set of
168 files - configuration files, binaries, scripts, the mail queue, and more.
169 If you begin by installing someone else's package, instead of installing
170 everything yourself, you should take careful notes where things are
171 installed. If you later decide to roll your own package, you will either
172 need to use a COMPLETELY IDENTICAL configuration, or take care to back up
173 your old configuration, and then restore it after the upgrade. The
174 following documentation refers to the default location of various
175 configuration files (and other files as well). If you choose to install
176 some files in a non-default location (either by yourself, or by using
177 someone else's package), you will need to take this into account while
178 reading the following documentation.
179
180 This cannot be emphasized enough: the configuration defaults are very
181 generic; the goal is to have the default configuration settings work for
182 almost everyone. In every case using at least a couple of non-default
183 parameters will make the Courier mail server work better on your system.
184 You should anticipate going through several trial-and-error installs,
185 tweaking the options to see what works better for you.
186
187 NOTE: older versions of the linuxconf configuration tool are hardwired for
188 sendmail. They like to change the permission of the sendmail wrapper to
189 match the permissions they think the real sendmail should have. Older
190 versions of linuxconf also have a tendency to create the /var/spool/mqueue
191 directory, even if sendmail is not installed.
192
193 Table Of Contents
194
195 The following table of contents might look intimidating at first, but some
196 sections are marked "optional". These sections are not required for a
197 basic installation as a simple ESMTP server.
198
199 • Upgrading an existing installation
200 • Overview
201 • Preparing for installation
202 • OPTIONAL: Install the Socks 5 client toolkit
203 • Run configure
204 • IPv6
205 • Compile and run make check
206 • Installation
207 • Install configuration files
208 • Adjust system paranoia level
209 • Post-installation setup
210 • Post-installation checks
211 • OPTIONAL: Configure webadmin
212 • Create system aliases
213 • Create smtp access list
214 • Backscatter suppression
215 • Miscellaneous configuration
216 • Define local domains
217 • OPTIONAL: Configure UUCP
218 • OPTIONAL: Configure LDAP aliasing
219 • OPTIONAL: Enable standard mail filters
220 • OPTIONAL: Configure custom mail filtering
221 • Create a list of domains to accept mail for
222 • Starting and stopping the Courier mail server
223 • Run the Courier mail server in parallel to your mail server
224 • OPTIONAL: Configure ESMTP authentication and SSL
225 • OPTIONAL: Configure ESMTP smarthosting
226 • OPTIONAL: Configure the SECURITY ESMTP extension
227 • OPTIONAL: Configure the Sender Policy Framework
228 • OPTIONAL: Configure the IMAP server
229 • OPTIONAL: Configure IMAP shared folders
230 • OPTIONAL: Configure IMAP over SSL
231 • OPTIONAL: Certificate Authentication
232 • OPTIONAL: Sending mail via an IMAP connection
233 • OPTIONAL: Configure IMAP realtime folder status updates
234 • OPTIONAL: Configure SMAP
235 • OPTIONAL: Configure the POP3 server
236 • OPTIONAL: Configure POP3 over SSL
237 • OPTIONAL: Configure the IMAP/POP3 aggregator proxy
238 • OPTIONAL: Configure the webmail server
239 • OPTIONAL: Configure webmail calendaring
240 • OPTIONAL: Configure mail filtering for the webmail server
241 • OPTIONAL: Changing mail account passwords using the webmail server
242 • OPTIONAL: Configure autoreplies for the webmail server
243 • OPTIONAL: Configure encryption for the webmail server
244 • OPTIONAL: Install automatically-appended footer text for webmail
245 messages
246 • OPTIONAL: Quota support
247 • OPTIONAL: Account OPTIONS
248 • OPTIONAL: Configure outbound faxing
249 • OPTIONAL: Configure inbound faxing
250 • OPTIONAL: Install the Courier mail server log analyzer
251 • OPTIONAL: Configure Courier IP address-specific settings for servers
252 with multiple IP addresses
253 • OPTIONAL: Configure hostname-dependent configuration
254 • Decommission your existing mail server
255 • Sample init script
256
257 Upgrading an existing installation
258
259 Upgrading from the Courier mail server 1.0.16 or earlier
260
261 The IMAP server switched to using the inotify kernel API directly instead
262 of the legacy FAM/Gamin daemon. When using virtual mail accounts it will
263 be necessary to increase the kernel's configured limit on the maximum
264 number of inotify file descriptors, see the IMAP server configuration
265 notes, below.
266
267 Upgrading from the Courier mail server 0.73.1, or earlier
268
269 The unicode library in Courier is now a separate package. Download the
270 Courier Unicode Library before updating to 0.74, or later.
271
272 Upgrading from the Courier mail server 0.72, or earlier
273
274 Version 0.73 removes the TLS_DHCERTFILE parameter from esmtpd, esmtpd-ssl,
275 imap, and pop3d configuration files. DH parameters, and DH parameters
276 only, get read from the new TLS_DHPARAMS file (and the other functionaly
277 of TLS_DHCERTFILE, for DSA certificates, is merged into TLS_CERTFILE).
278 After upgrading, run the mkdhparams script to create a new TLS_DHPARAMS
279 file.
280
281 Upgrading from the Courier mail server 0.66.3, or earlier
282
283 In 0.67, the IMAP server resets the epoch for an internal sequence number
284 generator for new mailboxes. This is an internal attribute of individual
285 IMAP folders, that's defined by the IMAP specification. Each folder in a
286 mailbox carries an individual sequence number, it is defined as a 32 bit
287 integer value, and required to be a monotonically increasing value. and
288 RFC 2060 recommended that "... a good value to use for the unique
289 identifier validity value is a 32-bit representation of the creation
290 date/time of the mailbox."
291
292 On modern platforms, the system time is now a 64 bit value (even on the
293 remaining 32 bit platforms). With Y2038K on the horizon, it's time to
294 reset the epoch (the new epoch, for anyone who cares, runs until the year
295 2069). The upgrade impact on existing systems is as follows.
296
297 There is no impact on existing folders in existing mailboxes. New folders
298 will have their internal sequence number in the new epoch.
299
300 One potential issue exists if a folder gets deleted by the IMAP client,
301 and then recreated later. The new folder will now get a lower sequence
302 number. Although this is technically not allowed, it's unlikely to cause
303 problems with most IMAP clients. If the same IMAP client deletes and
304 recreated the mailbox, the client should be completely up to speed. If,
305 however, there's an IMAP client that accesses the same folder, and some
306 other IMAP client deletes and recreates the same folder, this might cause
307 confusion. Most IMAP clients are likely to recover automatically; most
308 IMAP clients only care that the new sequence number they see is different
309 from the previous one, in order to trigger a full resynchronization with
310 the server. In case an IMAP client fails to resynchronize, the remedy is
311 to remove the IMAP account configuration from the client, and add it back
312 in.
313
314 Copying a mailbox by directly copying the files in maildirs preserves each
315 folder's epoch. However if a mailbox gets migrated by copying its contents
316 over IMAP, the folders on the destination IMAP server will not necessarily
317 have a monotonically higher value -- neither does IMAP guarantee that
318 different IMAP servers must be in agreement with each other on the subject
319 of sequence numbers -- and if IMAP clients are repointed to a new server
320 they may experience problems opening existing mailboxes. To remedy this
321 situation it will be necessary to completely remove and then reconfigure
322 the IMAP account, in the IMAP client. Again, verbatim copying of maildirs
323 has no issues.
324
325 A marginal situation exists where if a server completely runs of disk
326 space, or if there's a hardware failure, and the IMAP server is unable to
327 retrieve or save an existing folder's sequence number, and must now start
328 afresh and generate a new one, the IMAP server running on a new epoch will
329 recover with a lower sequence than the one that existed before. The
330 rememdy is the same: remove the IMAP account configuration from the
331 client, and then recreate it.
332
333 Upgrading from the Courier mail server 0.63.0, or earlier
334
335 There's a new setting, SYSLOCALE, in the courierd configuration file,
336 which initializes the environment from the default system locale. The
337 configuration script heuristically searches for a list of known locale
338 initialization scripts on various platforms, if found.
339
340 If your platform's locale configuration script's name is not known to the
341 configuration script, manually specify your default system locale in this
342 configuration setting.
343
344 Upgrading from the Courier mail server 0.55.1, or earlier
345
346 The webmlmd tool has been significantly enhanced, with a new
347 administration screen that consists of three new template files:
348 style.css.tmpl, webmlmlistadmin.tmpl.html, and
349 webmlmlistadminpw.html.html. These three template files must be installed
350 in each mailing list directory. You may copy them manually, or use the
351 couriermlm update command. couriermlm update overwrites all your
352 list-specific customizations, so make backups first!
353
354 Upgrading from the Courier mail server 0.54.2, or earlier
355
356 The logic for outbound authenticated SMTP has changed. This is when the
357 Courier mail server sends outbound mail through a smarthost that requires
358 authentication.
359
360 The specified smarthost's name is still looked up in DNS, as before. When
361 smtp.example.com is specified as the smarthost's name, The Courier mail
362 server looks up any MX or A records for smtp.example.com. A connection
363 gets established to a server whose name may be different than the original
364 DNS hostname, if it gets redirected via an MX or a CNAME record.
365
366 In earlier versions of the Courier mail server, the smarthost's userid and
367 password must be listed using the resulting server's physical, resolved
368 name. Starting with version 0.55, the smarthost's original DNS name must
369 be listed instead. In all cases now, the name of the server listed in
370 esmtpauthclient will now match the name specified in esmtproutes.
371
372 After updating to 0.55, the contents of the esmtpauthclient configuration
373 file may need updating.
374
375 IMPORTANT: After updating to 0.55, all existing couriermlm mailing list
376 directories must be updated with new configuration files. See the "update"
377 command in the "MANUAL COMMANDS" section of the couriermlm(1) manual page.
378 If you run many mailing lists, you are strongly advised to install the new
379 version of the Courier mail server on another machine and become
380 re-acquainted with couriermlm's configuration. In an emergency, make a
381 backup copy of the couriermlm command from your existing version of the
382 Courier mail server, before installing this update.
383
384 Upgrading from the Courier mail server 0.51, or earlier
385
386 Version 2.0 of maildrop, in the Courier mail server 0.52, introduces a new
387 pattern matching engine that uses the PCRE library, that uses a completely
388 different syntax. However, very few changes should be required to upgrade
389 existing maildrop recipes to the new syntax.
390
391 After upgrading from the Courier mail server 0.51, or earlier, review the
392 maildropfilter manual page which has been revised to document the new
393 pattern matching syntax. The legacy pattern matching engine is still
394 available by setting MAILDROP_OLD_REGEXP to 1. See also the "Conversion of
395 maildrop 1.x pattern to 2.0" section in the manual page, for more
396 information.
397
398 Upgrading from the Courier mail server 0.49.0, or earlier
399
400 couriermlm's default configuration now treats both the userid and the
401 domain portion of E-mail addresses as case-insensitive.
402
403 Any existing mailing list that has subscribers whose E-mail addresses
404 contain uppercase addresses must explicitly set the new CASESENSITIVE=1
405 list option, using the couriermlm command, otherwise those subscribers
406 will have problems unsubscribing or posting messages to the list.
407
408 Upgrading from the Courier mail server 0.48.2, or earlier
409
410 The Courier mail server's default configuration now includes backscatter
411 suppression. Review Backscatter suppression, below, for any needed
412 configuration changes.
413
414 Upgrading from the Courier mail server 0.47, or earlier
415
416 Beginning with 0.48, the authentication library that used to be a part of
417 the Courier mail server's source has been spun off into a standalone
418 authentication library.
419
420 You must download and install the Courier mail server authentication
421 library from http://www.courier-mta.org/authlib/ before upgrading. Review
422 the documentation in the courier-authlib package for more information.
423
424 As part of installing courier-authlib, the configuration files in the
425 Courier mail server's configuration directory that relate to
426 authentication will be copied to courier-authlib's configuration
427 directory. The files are: authdaemonrc, authmysqlrc, authpgsqlrc,
428 authldaprc, and userdb (together with the .dist versions). This works only
429 as long as the Courier mail server was installed in one of the known
430 default installation directories. The documentation in courier-authlib
431 explains what to do if the existing version of the Courier mail server is
432 installed in a non-default location.
433
434 In any case, after upgrading to 0.48 these configuration files in the
435 Courier mail server's configuration directory will no longer be used. To
436 avoid future confusion the old copies of these configuration files
437 (including the .dist files), should be removed from the Courier mail
438 server's configuration directory. They now live in the Courier mail
439 server-authlib's configuration directory (/usr/local/etc/authlib, or
440 whatever was specified to the Courier mail server-authlib's configure
441 script).
442
443 Upgrading from the Courier mail server 0.45.4 or earlier
444
445 The command to start the webmail server daemon has changed. The system
446 startup script must be modified to run the new command:
447 "/usr/lib/courier/sbin/webmaild start". Additionally, this scripts also
448 starts pcpd, if required. It is no longer necessary to start pcpd by hand.
449
450 Upgrading from the Courier mail server 0.44.0 or earlier
451
452 Version 0.44.1 introduced an updated webmail implementation. The suid
453 cgi-bin binary has been replaced by a combination of a stub and a daemon
454 process. After upgrading to 0.44.1 you will need to modify your system
455 startup script to run /usr/lib/courier/libexec/courier/sqwebmaild start.
456 See below for more information.
457
458 Upgrading from the Courier mail server 0.42.2 or earlier
459
460 After upgrading from the Courier mail server 0.42.2, or earlier, any
461 existing mail in POP3 mailboxes may show up as new mail, by some mail
462 clients. This is a one-time event.
463
464 Upgrading from the Courier mail server 0.42.0 or earlier
465
466 Version 0.43 introduced some functional changes to the LDAP, MySQL, and
467 PostgreSQL authentication modules. A new DEFAULTDELIVERY setting is added
468 to each module, incorporating some functionality previously done by the
469 MAILDIR setting. Previously, MAILDIR served two purposes: 1) define the
470 default location to the primary mailbox, relative to the account's home
471 directory, 2) provide default mail delivery instructions, overriding
472 DEFAULTDELIVERY in the courierd configuration file.
473
474 Starting with this version, MAILDIR only specifies the default location
475 for the primary mailbox, and this setting is now used only by the POP3,
476 IMAP, and Webmail servers. The new DEFAULTDELIVERY setting specifies the
477 default mail delivery instructions. Sites that previously used MAILDIR may
478 now need to copy its setting to DEFAULTDELIVERY.
479
480 Upgrading from the Courier mail server 0.34.1 or earlier
481
482 Version 0.35 introduced the ability to update system passwords from the
483 webmail server. If you are using the authuserdb authentication module,
484 rerun the makeuserdb script after upgrading to 0.35 or later.
485
486 Prior to 0.35, the default configuration of the webmail server maintained
487 a separate webmail password file. The webmail server did not have the
488 logic to update system login passwords, the approach was to copy system
489 login passwords into a webmail password file. Changing the webmail
490 password involved simply updating the webmail password file, and life was
491 good.
492
493 In 0.35, logic was added to update the real system password file, and the
494 eliminate the webmail password file. After upgrading in 0.35, it will
495 probably be necessary to reset all mail account passwords on existing
496 accounts, since the webmail password file is not being used any more, and
497 most people have probably changed their webmail passwords.
498
499 As the result of the password change, the default configuration script
500 will now always build the authdaemond authentication module by default.
501 Previously, authdaemond was built by default only if LDAP or MySQL support
502 was necessary.
503
504 Upgrading from the Courier mail server 0.29.1 or earlier
505
506 Version 0.30 changed the format of most configuration files. The new
507 configuration file format allows configuration files to be automatically
508 upgraded. The automatic upgrade feature requires that both the old and the
509 new installation have preformatted configuration files. Therefore, when
510 upgrading from version 0.29.1 or earlier, use the following procedure to
511 upgrade the existing configuration files.
512
513 All configuration files are installed in the same directory, "sysconfdir".
514 sysconfdir is a configurable parameter, it's usually /usr/lib/courier/etc.
515 sysconfdir is /etc/courier in the RPM and the DEB version of the Courier
516 mail server.
517
518 Back up your existing sysconfdir
519
520 Make a backup copy of your current sysconfdir, then delete the old version
521 of the Courier mail server. "rm -rf /usr/lib/courier" will do nicely. All
522 the possible configurable settings are in sysconfdir, everything else can
523 simply go.
524
525 Back up your existing sysconfdir
526
527 Make a backup copy of your current sysconfdir. The upgrade process
528 reinstalls several default configuration files; specifically
529 sysconfdir/aliases/system and sysconfdir/smtpaccess/default. Any additions
530 to these files will normally be lost in the upgrade, and can be restored
531 from the backup afterwards. Don't forget to rerun makealiases and
532 makesmtpaccess.
533
534 Install the new version
535
536 Follow the installation procedure in the next section (including the make
537 install-configure). The following configuration files are now preformatted
538 for automatic installation:
539
540 ldapaddressbook
541 esmtpd
542 esmtpd-msa
543 courierd
544 pop3d
545 pop3d-ssl
546 imapd
547 imapd-ssl
548 ldapaliasrc
549 authldaprc
550 authmysqlrc
551 authpgsqlrc
552 authdaemonrc
553
554 NOTE: depending upon your configuration, you may not actually have every
555 one of these files installed, so just disregard the ones that are not
556 present. Manually edit filename, and retype any custom modifications from
557 the backup copy of the configuration file. This is a hassle, but it only
558 needs to be done once. Future upgrades will be 99% automatic.
559
560 Any custom configuration changes are generally confined to these
561 configuration files only. Very rarely are any configuration changes made
562 to the remaining configuration files. If necessary, they can simply be
563 restored from the backup copy made in the previous step. Something to keep
564 in mind is that future versions may add additional complexity to other
565 configuration files, resulting in additional configuration files being
566 reformatted for automatic upgrading.
567
568 Overview
569
570 You will need the following software in order to compile and install the
571 Courier mail server:
572
573 1. The Courier Unicode Library
574
575 The courier-unicode package must be installed and configured prior to
576 installing the Courier mail server. Download the courier-unicode
577 package from http://www.courier-mta.org/unicode/.
578
579 2. The Courier mail server Authentication Library
580
581 The courier-authlib package must be installed and configured prior to
582 installing the Courier mail server. Download the courier-authlib
583 package from http://www.courier-mta.org/authlib/.
584
585 3. A C++ compiler
586
587 The Courier mail server is primarily developed and built with gcc.
588 Other C++ compiler may or may not work. Solaris's C++ compiler is
589 reported to work without any problems. There are some issues with
590 AIX's xlC compiler, which mostly has to do with the C++ libraries and
591 header files. IBM has released a GNU/Linux development toolkit for
592 AIX, which may help in getting the Courier mail server to compile.
593
594 4. PCRE
595
596 The PCRE2 library (http:/www.pcre.org) is required.
597
598 5. wget
599
600 The wget command must be installed.
601
602 6. GNU IDN library
603
604 This library (http://www.gnu.org/software/libidn/) implements support
605 for internationalized domain names.
606
607 7. GNU make
608
609 On the BSD platform family GNU make is usually installed as gmake.
610 Simply replace 'make' with 'gmake' in the following instructions. GNU
611 make is REQUIRED. Use anything else at your own risk.
612
613 8. Perl 5
614
615 A recent version of Perl needs to be installed.
616
617 9. GDBM or Berkeley DB library
618
619 Either library must be installed.
620
621 10. OpenSSL or GnuTLS
622
623 Support for SSL/TLS requires OpenSSL/GnuTLS. All features that require
624 SSL/TLS are disabled unless OpenSSL or GnuTLS is installed.
625
626 11. OpenLDAP
627
628 Support for LDAP directory services requires OpenLDAP client libraries
629 to be installed. If OpenLDAP is not installed LDAP directory features
630 are disabled. Sometimes there's some confusion when commercial LDAP
631 servers are used, which come with their own development toolkits,
632 which use a different API than OpenLDAP. Even if a commercial LDAP
633 server is used to provide LDAP services, OpenLDAP is still required to
634 enable LDAP services in the Courier mail server. Also, note that you
635 need OpenLDAP development libraries and files. On most systems, the
636 development files are packaged separately, in addition to the runtime
637 OpenLDAP libraries. Make sure that you have not just the runtime
638 OpenLDAP libraries installed, but the development libraries as well.
639
640 Most of the LDAP support code is already provided by the Courier mail
641 server authentication library. Some LDAP features, such as LDAP-based
642 mail aliases, are implemented in the Courier mail server directly.
643 OpenLDAP client libraries must be installed. If OpenLDAP is not
644 installed, LDAP directory features are disabled.
645
646 12. mgetty+sendfax, groff or troff (not tested), ghostscript, and NetPBM
647
648 This optional software is required to send E-mail messages via fax.
649 The Courier mail server will compile and install without this
650 software, but you will not be able to send faxes. All packages must be
651 installed prior to installing the Courier mail server, and binaries
652 from all packages must be installed in the default PATH before running
653 the Courier mail server's configure script.
654
655 mgetty+sendfax, ghostscript, and groff, are required for basic fax
656 support, which supports faxing of plain text, Postscript, and
657 PDF-formatted content. It's probably possible to use the original UNIX
658 troff instead of groff, but this has not been tested. Installing
659 NetPBM adds the ability to fax GIF, JPEG, and PNG images.
660
661 The typical sequence of commands to install the Courier mail server is as
662 follows. Read the following section before running these commands:
663
664 ./configure [options]
665 make
666 make check # Optional -- see below
667 make install
668 make install-configure
669
670 These commands are described in greater detail in the following sections.
671
672 ══════════════════════════════════════════════════════════════════════════
673
674 > If you're using gmake (the make on GNU/Linux, and gmake everywhere
675 > else), and you are compiling the Courier mail server on a workstation
676 > with multiple CPUs and plenty of memory, set the following environment
677 > variable:
678
679 MAKEFLAGS="-j 4"; export MAKEFLAGS # Bourne or Korn shell
680
681 > or:
682
683 setenv MAKEFLAGS="-j 4" # The C shell
684
685 > This must be done before running the configure script. This works only
686 > with gmake.
687
688 ══════════════════════════════════════════════════════════════════════════
689
690 > The Courier mail server will not work on a Linux kernel that's been
691 > patched with the Openwall security patch in its default configuration.
692 > The current version of the Openwall patch has a non-default option that
693 > turns off the portion of the Openwall patch which prevents the Courier
694 > mail server from running.
695
696 > NOTE: Linux-Mandrake includes the Openwall patch in the alternative
697 > "secure" kernel package. The Courier mail server will not run on
698 > Linux-Mandrake under the alternative "secure" kernel. This package must
699 > be removed and the standard kernel package must be installed.
700
701 ══════════════════════════════════════════════════════════════════════════
702
703 Preparing for installation
704
705 The first step consists of gathering some information about your existing
706 mail system. Before proceeding, you will need to identify and resolve the
707 following issues:
708
709 • Maildirs or mailbox files
710
711 The Courier mail server can be used as a simple mail relay -- which does
712 not store any mail locally but is merely a gateway between internal and
713 external mail systems. The Courier mail server can also be used as a
714 traditional mail server, accepting and storing messages in individual
715 mailboxes that are accessible via POP3, IMAP, or webmail.
716
717 The Courier mail server defaults to storing mail in maildirs, not
718 traditional flat file mailbox files. Maildirs require less I/O and CPU
719 resources; they do not use locking; and multiple clients can read and
720 write from maildirs simultaneously. Maildirs scale very well to servers
721 with multiple CPUs. Some benchmark numbers on maildirs are available from
722 http://www.courier-mta.org/mbox-vs-maildir/.
723
724 Additionally, The Courier mail server's integrated POP3, IMAP, and
725 HTTP/webmail servers support maildir mailboxes only. They do not support
726 mailbox files.
727
728 If you have an existing mail server in service, chances are that your
729 current mail server delivers mail to mailbox files. You should consider
730 migrating and converting to maildirs, but this will require that you also
731 upgrade your POP3 server, your IMAP server, and all your other mail
732 clients to software that supports maildirs. Fortunately, The Courier mail
733 server already includes a fully integrated POP3 and IMAP server.
734
735 Still, if circumstances absolutely require for you to stick with mailbox
736 files, The Courier mail server has limited compatibility support for
737 delivering mail to mailbox files, but you have more homework to do:
738
739 • What locking mechanism is used on mailbox files
740
741 If you decide to stick with mailbox files, you must know - of course -
742 where your mailboxes are located, and what locking mechanism is being used
743 by your mail software. Mailbox files require some form of locking, because
744 only one application can access the mailbox file at the same time.
745 Unfortunately, different operating systems use different locking methods.
746 There are several possible locking strategies that can be used: so-called
747 "dot-locks", or one of three possible kinds of file locking calls. You
748 will need to consult the documentation for your existing mail software to
749 determine what locking mechanisms you should use.
750
751 In most cases, mailbox files are located in a separate partition, usually
752 the directory /var/spool/mail. In some instances, mailbox files may be
753 kept in the home directory of each individual account, and the mail is
754 delivered to either $HOME/Mailbox, or $HOME/INBOX. Again, you will have to
755 figure this out by yourself.
756
757 The Courier mail server can deliver mail to mailbox files only if the
758 default mailbox file is in the home directory of each individual account,
759 and if you use file locking. The Courier mail server does not support
760 dot-locks, and the Courier mail server does not support a separate mail
761 directory for mailbox files. Mailbox files must be located in the home
762 directory of each individual account.
763
764 The Courier mail server can use a recipient database (userdb) that can
765 specify a non-default location for a recipient's mailbox. In theory, it is
766 possible to point each account to its individual mailbox in
767 /var/spool/mail, or somewhere else. However, that's a tedious task that
768 must be done manually for each account, and is likely to be a major
769 maintenance issue.
770
771 A better solution is to use a separate local mail delivery agent. Your
772 existing mail system is very likely to include a separate local mail
773 delivery agent. If you already use a mail delivery agent such as procmail,
774 you probably already have it set to use the correct locking mechanism for
775 mailbox files, and it already knows where the mailbox files are. The
776 Courier mail server will be happy to hand off all local mail to procmail,
777 or anything else for the actual delivery.
778
779 The Courier mail server source distribution includes the maildrop mail
780 delivery agent which has some additional file locking options, however
781 you'll have less problems if you stick with procmail in the beginning, and
782 switch to maildrop after you've gained some experience configuring and
783 installing the Courier mail server.
784
785 • Create the courier user and group IDs
786
787 You should create a new userid and groupid named "courier". That's
788 optional, but highly recommended. If this is not done, The Courier mail
789 server will install as user/group daemon (or some other suitable
790 user/group id). Only two of the Courier mail server's daemon processes run
791 as a superuser (and one of them is perpetually waiting for a non-superuser
792 daemon process to terminate, in order to restart it). Everything else runs
793 as a non-superuser process. Ideally, you should reserve a separate user
794 and group ID for the Courier mail server's use only, so a compromised mail
795 system cannot be used to compromise the rest of the system. If push comes
796 to shove, you can set up the Courier mail server to use a well-defined
797 existing user and group ID, such as daemon.
798
799 • Define the installation directory
800
801 The Courier mail server, by default, installs in /usr/lib/courier.
802 Everything goes in there: binaries, scripts, configuration files, and
803 manual pages. You will have to configure your man command to look for
804 manual pages in /usr/lib/courier/man by adding this directory to the
805 MANPATH environment variable. You will also need to add
806 /usr/lib/courier/bin and /usr/lib/courier/sbin (for the root user only) to
807 the default PATH. The Courier mail server's RPM and DEB packages install a
808 script that automatically implements that.
809
810 Note that this installation layout is nothing more than a basic default,
811 chosen because this simple arrangement works for everyone. The
812 installation layout can be easily changed. For example, binaries can go to
813 /usr/local/bin, and configuration files to /usr/local/etc. But keep in
814 mind that the Courier mail server consists of several hundred individual
815 files (at the last count), so if you install the Courier mail server
816 somewhere else it might be very cumbersome to keep track of where
817 everything went, and it will lead to almost guaranteed problems later,
818 when you upgrade.
819
820 You should try to use some kind of a packaging system in order to keep
821 track of your the Courier mail server installation. Once you choose a
822 packaging system, you should stick to it. If you switch to a different
823 packaging system you should take extreme care to remove your previous
824 package, and install your new package. Extreme configuration flexibility
825 means that different packages will install in different places, and even
826 have different file ownerships!
827
828 For example, The Courier mail server's source code tarball can be built
829 into a binary RPM package. The binary RPM package installs configuration
830 files in /etc/courier, the mail queue in /var/spool/courier, and
831 everything else in /usr/lib/courier. If you install this package, and
832 later decide to either create your own package or use someone else's, you
833 will have to make sure to use the same settings, or remove this package
834 completely, before installing your new package. I mean it when I say
835 "remove my package completely". That includes the mail queue containing
836 any unsent messages. The Courier mail server will not function if it's
837 reinstalled using a different user/group ID, or if you use a different
838 value for any other option.
839
840 • Conclusion
841
842 Once these issues are squared away, you are ready to configure and install
843 the Courier mail server.
844
845 OPTIONAL: Install the Socks 5 client toolkit
846
847 The Courier mail server has the ability to send outgoing SMTP mail through
848 a Socks 5 proxy. The Socks 5 proxy option requires a separate module, the
849 Socks 5 client/server proxy to be installed before installing the Courier
850 mail server. Download the Socks 5 proxy client library from
851 http://www.courier-mta.org/download.html#sox and follow its installation
852 instructions.
853
854 > NOTE: Be sure to read the README, NEWS, and INSTALL files in the Courier
855 > mail server Socks 5 library toolkit, before attempting to install it for
856 > the first time (unless using the RPM or DEB build method).
857
858 Socks proxying must be implemented in relatively low-level manner, and may
859 not work on all operating systems. This is why it is packaged separately,
860 in case that it doesn't work. The configure script, described in the
861 following section, enables Socks 5 support automatically if the Courier
862 mail server Socks 5 proxy client library is already installed. To make
863 sure that the library is installed correctly, specify the "--with-socks"
864 option to the following configure script. This option aborts the configure
865 script if it does not detect the Courier mail server Socks 5 proxy client
866 library.
867
868 Run configure
869
870 After you are squared away with the preliminaries, run the configure
871 script:
872
873 ./configure [ options ]
874
875 > NOTE
876
877 > You MUST run the configure script as normal user, not root. Did you
878 > extract the tarball as root? It won't work. Delete everything you have
879 > just extracted, as root. Log in as a normal user. Extract the source
880 > code as a normal user, then run configure. You will do everything as a
881 > normal user, except for the final step of installing the compiled
882 > software. When you're ready to do a make install, later, su yourself to
883 > root, and run make install.
884
885 The configure script can take a while to complete. There will be more then
886 thirty separate configuration scripts that will be executed by this
887 command. To an untrained eye it may seem that the same configuration
888 script is stuck in a loop; that's because all these configuration scripts
889 share a lot of code. It may take as much as 15-20 minutes for configure to
890 finish on a slow machine - even more.
891
892 You must have the uux command in your default search path if you intend to
893 use the Courier mail server to relay mail via UUCP. You may need to modify
894 your PATH environment variable to include the directory containing uux.
895
896 gcc/egcs is officially blessed for building the Courier mail server. In
897 most cases there's no need to tweak any compiler-specific settings. Note
898 that there currently may be some unresolved issues with gcc 2.96. gcc 2.91
899 has been tested and known to work. Occasionally some of your system
900 libraries may be stuck in some oddball directory that is not searched by
901 default. Non-standard options for the compiler or linker can be set by
902 putting them into environment variables. This must be done before running
903 the configurescript:
904
905 • CFLAGS
906
907 Additional flags for the C compiler.
908
909 • CXXFLAGS
910
911 Additional flags for the C++ compiler.
912
913 • LDFLAGS
914
915 Additional flags for the linker.
916
917 • LDADD
918
919 Additional libraries to link with. NOTE - everything will be linked
920 with these libraries.
921
922 The complete reference to all configure script options is provided below.
923 The most important options are:
924
925 • --prefix=pathname
926
927 Install the Courier mail server in pathname, instead of the default
928 location of /usr/lib/courier. Note - the examples in the rest of this
929 text assumes this is where you will install the Courier mail server.
930 Do not attempt to install the Courier mail server in a directory whose
931 name contains spaces or punctuation marks. Periods or dashes are fine,
932 but refrain the temptation to use other, exotic, punctuation.
933
934 • --with-db=db or --with-db=gdbm
935
936 The Courier mail server requires either the GDBM or the DB database
937 library. GDBM is used if both are present. This option forces the
938 selection of the database library.
939
940 • --with-locking-method=function
941
942 Select a file locking function. Available functions are: fcntl, lockf,
943 and flock. Not every function is available on every platform. If this
944 option is not present, configure tries each one, and takes the first
945 one that works. You can select a specific locking function by using
946 this option. This affects both the locking used for delivering mail to
947 mailbox files, and for other kinds of locking that the Courier mail
948 server uses internally.
949
950 • --enable-mimecharset=charset
951
952 Specify the default character set the Courier mail server uses when
953 adding MIME headers to a message. If not specified, us-ascii is used.
954
955 • --without-tcpddns
956
957 Use this option if you are running a small network without access to a
958 DNS server. This option will cause couriertcpd to use the system
959 resolver's gethostby functions instead of issuing DNS queries. Also:
960 you must initialize the esmtproutes control file with the IP addresses
961 of all your servers.
962
963 configure reference
964
965 Here's a comprehensive list of options for the configure script. They are
966 presented in no particular order. In almost all cases, the configure
967 script will automatically figure out the correct values, but sometimes it
968 is necessary to specify them explicitly. If you ever have a need to
969 manually specify any configuration option, try to determine whether you
970 need it because of a particular unique case that involves your server
971 only, or whether it affects any server running your hardware, or system.
972 In the later case, try to investigate if it's possible for configure to be
973 a bit smarter and make the right decision.
974
975 • --prefix=pathname
976
977 Install the Courier mail server in pathname, instead of the default
978 location of /usr/lib/courier. Note - the examples in the rest of this
979 text assumes this is where you will install the Courier mail server.
980
981 • --exec-prefix=pathname
982
983 Specify where the Courier mail server's machine-executable binaries
984 should be installed. This defaults to the same directory as given by
985 the --prefix option. There will be three subdirectories created
986 underneath exec-prefix: bin - user-executable binaries; sbin -
987 superuser-only binaries; libexec - other binaries that are not
988 directly invoked from the command line, but are started by other
989 Courier mail server commands.
990
991 • --bindir=pathname, --sbindir=pathname, --libexecdir=pathname
992
993 These options override the default value for the corresponding
994 subdirectory underneath --exec-prefix (see above). The bindir
995 directory contains programs that can be executed by anyone. sbindir
996 contains programs that can only be executed by the superuser.
997 libexecdir contains programs and libraries that cannot be directly
998 executed from the command line. The default locations are the bin,
999 sbin, and libexec subdirectories underneath the directory specified by
1000 exec_prefix.
1001
1002 • --datadir=pathname
1003
1004 Specify the directory where miscellaneous shell scripts, Perl scripts,
1005 and data files will be installed. This option defaults to the
1006 subdirectory "share" in the directory specified by the --prefix
1007 option.
1008
1009 • --sysconfdir=pathname
1010
1011 Specifies the directory where the Courier mail server's configuration
1012 files are installed. This option defaults to the subdirectory "etc" in
1013 the directory specified by the --prefix option.
1014
1015 • --localstatedir=pathname
1016
1017 Specify the directory that will hold the mail queue, and other
1018 temporary data. This option defaults to the subdirectory "var" in the
1019 directory specified by the --prefix option.
1020
1021 • --without-ipv6
1022
1023 Do not compile IPv6 support. IPv6 support, if available is normally
1024 automatically detected and enabled. Use --without-ipv6 to disable it.
1025 IPv6 implementations on various platforms is still in flux, and IPv6
1026 support will not be enabled if the detection logic fails. Use
1027 --with-ipv6 in order to fail the configuration stage if IPv6 is not
1028 detected, instead of silently continuing with IPv4 support only. See
1029 "IPv6" below for more information.
1030
1031 • --with-db=db or --with-db=gdbm
1032
1033 The Courier mail server requires either the GDBM or the DB database
1034 library. GDBM is used if both are present. This option forces the
1035 selection of the database library.
1036
1037 • --with-locking-method=function
1038
1039 Select a file locking function. Available functions are: fcntl, lockf,
1040 and flock. Not every function is available on every platform. If this
1041 option is not present, configure will choose the first locking
1042 function that's available. You can select a specific locking function
1043 by using this option. This affects both the locking used for
1044 delivering mail to mailbox files, and for other kinds of locking that
1045 the Courier mail server uses internally.
1046
1047 • --enable-mimecharset=charset
1048
1049 Specify the default character set the Courier mail server uses when
1050 adding MIME headers to a message. If not specified, us-ascii will be
1051 used.
1052
1053 • --without-tcpddns
1054
1055 \Use this option if you are running a small network without access to
1056 a DNS server. This option will cause couriertcpd to use the system
1057 resolver's gethostby functions instead of issuing DNS queries. Also:
1058 you will have to initialize the smtproutes control file with the IP
1059 addresses of all your servers.
1060
1061 • --without-explicitsync
1062
1063 Normally the Courier mail server will automatically sync, or flush out
1064 all file buffers to disk, at certain key points in order to try to
1065 minimize the extent the mail queue can get corrupted if the system
1066 crashes. If the mail queue is installed on a reliable disk array or a
1067 network file server, this may not be necessary, and will only serve to
1068 slow down the mail delivery. Use this option to turn off syncing.
1069
1070 • --with-dirsync
1071
1072 Also explicitly sync the parent directory. There's a school of thought
1073 which believes that the Linux ext2 filesystem requires the parent
1074 directory to also be synced, in addition to the new message file
1075 that's just been written to disk. There's another school of thought
1076 that thinks that this issue is completely blown out of proportion, and
1077 is really nothing more than a tempest in a teapot. However -- to
1078 accomodate the former school of thought -- this option adds a little
1079 bit of extra code to sync the parent directory.
1080
1081 • --with-shellpath=path
1082
1083 Specify the contents of the PATH environment variable that is
1084 inherited by custom programs started by the Courier mail server to
1085 deliver messages. If not specified, PATH will be set to
1086 /bin:/usr/bin:/usr/local/bin.
1087
1088 • --disable-local-extensions
1089
1090 Normally, in addition to accepting mail that's addressed to
1091 <user@domain.com>, The Courier mail server can accept mail that's
1092 addressed to <user-xxx@domain.com>, for arbitrary values of xxx. In
1093 order for that to happen the user has to create a special file with
1094 delivery instructions. See the dot-courier(5) manual page for more
1095 information. This option disables this feature.
1096
1097 • --with-paranoid-smtpext
1098
1099 Be paranoid when negotiating the Courier mail server-specific ESMTP
1100 extensions with remote servers. The Courier mail server defines and
1101 implements certain experimental ESMTP extensions: XVERP and XEXDATA.
1102 Problems may result in the event that someone else uses the same name
1103 to implement some other extension. If this option is specified, The
1104 Courier mail server's ESMTP server will also advertise a dummy ESMTP
1105 capability called XCOURIEREXTENSIONS, and will not recognize any the
1106 Courier mail server-specific extensions unless the remote mail server
1107 also advertises this dummy ESMTP capability.
1108
1109 • --enable-workarounds-for-imap-client-bugs
1110
1111 There are several confirmed bugs in some IMAP clients that do not
1112 properly implement the IMAP4rev1 protocol. This option enables some
1113 workarounds for those buggy IMAP clients. NOTE: make check will fail
1114 if this option is used. You should first configure without this
1115 option, and if all post-configuration tests succeed, rerun configure
1116 with this option and recompile.
1117
1118 • --with-qdircount=n
1119
1120 Set n to be the number of mail queue subdirectories. In order to
1121 improve the speed of access to the mail queue, messages are stored in
1122 subdirectories, hashed by the message queue number. n specifies how
1123 many subdirectories will be created. If this option is not specified,
1124 100 subdirectories will be used. WARNING: once you've installed the
1125 Courier mail server once, if you decide to reconfigure and reinstall,
1126 you MUST use the same subdirectory count (by default, or explicitly),
1127 otherwise you'll end up with a big mess on your hands if you have ANY
1128 messages in the mail queue. If you need to change this option, wait
1129 for all messages in the queue to be flushed out, and reinstall with an
1130 empty mail queue.
1131
1132 • --with-random=/dev/path, --without-random
1133
1134 Sometimes the Courier mail server sometimes needs a good source of
1135 random noise. If configure finds /dev/urandom, it will use that. If
1136 your random device is named otherwise, specify it using this option.
1137 If you don't want to use a random device, specify --without-random,
1138 and the Courier mail server will generate some noise on its own. The
1139 Courier mail server will generate noise based on the output of a
1140 random ps command, and several other, hopefully unpredictable,
1141 sources.
1142
1143 • --with-gnutls - Use the GnuTLS library even if the OpenSSL library is
1144 also installed. The Courier mail server automatically uses whichever
1145 one is available. The OpenSSL library is selected if both are present.
1146 Use this option to override and select GnuTLS instead.
1147 • --without-certdb
1148
1149 Do not install a default set of trusted X.509 root CA certs (in order
1150 to validate the remote server's X.509 certificate). See "Configure
1151 ESMTP authentication and SSL" for more information.
1152
1153 • --with-certdb=pathname
1154
1155 Do not install the default set, but put pathname as the default
1156 location of the root CA database, into the configuration file. This is
1157 a convenient option to have the Courier mail server use an external,
1158 previously installed, root CA database.
1159
1160 • --with-certsdir=pathname
1161
1162 Set up configuration files and scripts that reference the server's SSL
1163 certificates to use the pathname directory, instead of the directory
1164 specified by the --datadir option. Scripts that create temporary
1165 self-signed certificates to be used for testing (mkimapdcert,
1166 mkpop3dcert, et. al.) install the generated certificate in this
1167 directory, and it's referenced from the corresponding configuration
1168 files.
1169
1170 • --with-waitfunc=wait, --with-waitfunc=wait3
1171
1172 Specify the system call to use to asynchronously reap child processes.
1173 This is a sticky one, because the behavior of the wait and wait3
1174 system calls varies greatly depending on the level of each individual
1175 system's POSIX compliance. The configure script will attempt to
1176 compile and run some test programs in order to attempt to figure out
1177 which system call actually works. If the configure script fails, or if
1178 it selects a wrong function (which will be evident when mail delivery
1179 stops, and you have a bunch of zombies that are not being reaped), you
1180 might have to manually specify it using either option. In that case,
1181 however, you should also examine the test programs, investigate what
1182 went wrong, and patch the test programs to give a correct result for
1183 your system.
1184
1185 • --without-ispell, --with-ispell=program
1186
1187 The Courier mail server's webmail server can use spell checking, if
1188 the ispell program is available (aspell can be used too). If configure
1189 finds ispell, spell checking is enabled. Use --without-ispell to
1190 forcefully disable spell checking. If ispell is not in the current
1191 search path, use --with-ispell=program to explicitly set the location
1192 of ispell. See "Configure the webmail server" for more information on
1193 ispell or aspell.
1194
1195 • --enable-imageurl=/url
1196
1197 Use /url/ as the URL to the static images displayed by the webmail
1198 server. HTML pages are dynamically generated by the webmail server
1199 CGI, but they also include some static icons. The webmail CGI will use
1200 /url as the URL to the directory containing the static images. The
1201 default URL is "/webmail", which means that the static images must be
1202 installed in the <DocumentRoot>/webmail directory. This is a manual
1203 process that is described in more detail in the "Configure the webmail
1204 server" section, below.
1205
1206 • --enable-https, --enable-https=login, --enable-https=auto
1207
1208 If you have an SSL-enabled web server, use the --enable-https option
1209 in order to configure webmail access for SSL. Use --enable-https=login
1210 in order to use SSL only when logging in, to send the password. Use
1211 --enable-https=auto to generate relative URLs, so that users can
1212 connect with either http or https and their session will remain that
1213 way.
1214
1215 --enable-https=login and --enable-https=auto require that your http
1216 and https URLs that refer to the webmail CGI be identical (which is
1217 the usual default).
1218
1219 --enable-https=auto is the default. Use --disable-https if you need to
1220 completely disable https, for some reason.
1221
1222 • --enable-hardtimeout=7200
1223
1224 set the hard timeout for webmail sessions (in seconds). The default is
1225 2 hours. webmail sessions are unequivocally logged out after the
1226 indicated time interval.
1227
1228 • --enable-softtimeout=1200
1229
1230 set the inactivity timeout for webmail sessions (in seconds). The
1231 default is 20 minutes. webmail sessions are logged out if there's no
1232 activity for the indicated time interval.
1233
1234 • --with-defaultlang=lang
1235
1236 reserved for future use.
1237
1238 • --enable-mimetypes=file:file:file
1239
1240 this is a colon-separated list of all of your mime.types files. The
1241 mime.types configuration files are used to map file extension to their
1242 corresponding MIME content types. The configuration script will look
1243 in several directories where mime.types usually exists. You can use
1244 this option to explicitly specify a list of mime.types files to be
1245 used, instead of the default.
1246
1247 • --enable-bannerprog=pathname
1248
1249 advanced option that sets a banner program that the webmail server
1250 will execute. This program should print HTML, on standard output, to
1251 generate a typical banner.
1252
1253 • --with-maxargsize=bytes,--with-maxformargsize=bytes
1254
1255 Sets an upper limit on the size of CGI arguments for the webmail
1256 server. Normally there's no reason to modify the defaults (500,000 and
1257 2,000,000 bytes). The latter is generally the maximum allowed size of
1258 an attachment. The former is generally the maximum allowed size of the
1259 typed message. These settings can also be adjusted at runtime. See
1260 Maximum message size, below.
1261
1262 • --with-maxmsgsize=bytes
1263
1264 Sets the upper limit of messages composed in the webmail server, the
1265 main text and all the attachments. This setting can also be adjusted
1266 at runtime. See Maximum message size, below.
1267
1268 • --with-cachedir=dir, --with-cacheowner=userid
1269
1270 The webmail server uses a cache of currently active logins. The
1271 webmail server binary, is executed for each and every HTTP request,
1272 and the user's maildir needs to be quickly located each time. Because
1273 hitting the authentication module can be expensive (think
1274 MySQL/PostgreSQL/LDAP query for every HTTP request!) the webmail
1275 server will cache this information in order to avoid having your
1276 authentication server brought down to its knees. By default, the
1277 directory /usr/lib/courier/var/webmail-logincache will be used, owned
1278 by the bin user. These options can be used to specify a different
1279 location for the webmail login cache directory.
1280
1281 If you'll be using the webmail server, you MUST add an hourly cron job
1282 to run the /usr/lib/courier/share/sqwebmail/cleancache.pl script which
1283 deletes expired cache records from the cache directory. Add the
1284 following command to be executed from cron at least once an hour:
1285
1286 su -c "/usr/lib/courier/share/sqwebmail/cleancache.pl" bin
1287
1288 (This assumes that your cache directory is owned by the bin user).
1289 There's no need to set up this cron job if the webmail server is not
1290 used. NOTE: your su command may use different options or syntax, check
1291 the su manual page to confirm the correct syntax.
1292
1293 • --without-gzip
1294
1295 if the configuration script finds the gzip utility, the webmail server
1296 will automatically use gzip compression for some large web pages (if
1297 the client browser supports gzip compression). Use this option to turn
1298 off gzip compression.
1299
1300 • --disable-autorenamesent
1301
1302 do not rename the Sent folder every month. This option can also be
1303 controlled by the SQWEBMAIL_AUTORENAMESENT environment variable (which
1304 can be set in Apache's httpd.conf, for example). This setting gives
1305 the initial configuration, that can be individually adjusted in the
1306 Preferences screen.
1307
1308 • --with-calendarpurge=N
1309
1310 if calendaring is enabled, purge expired calendar events after N days
1311 (default: 30).
1312
1313 • --with-trashquota
1314
1315 include deleted messages, and the Trash folder, in the estimated quota
1316 usage for maildirs. Quotas are optional, see the file
1317 maildir/README.maildirquota.html for more information. The default
1318 configuration does not count messages marked as deleted (but not yet
1319 expunged) and the contents of the Trash folder (which are
1320 automatically purged by the server) against the quota usage. NOTE - if
1321 this option is used, make check WILL FAIL. You should first configure
1322 the Courier mail server without this option, run make check, then
1323 reconfigure the Courier mail server with this option.
1324
1325 IPv6
1326
1327 IPv6 support in the Courier mail server means basically the following:
1328
1329 • ESMTP, IMAP, and POP3 servers will create an IPv6 socket and accept
1330 IPv6 connections.
1331 • The ESMTP client will attempt to resolve AAAA records in addition to A
1332 records.
1333 • Headers in incoming mail will log IPv6 addresses, instead of IPv4
1334 addresses. Delivery Status Notifications and log files will also
1335 reflect IPv6 addresses.
1336
1337 IPv6 implementations are required to accept IPv4 connections on IPv6
1338 sockets, so IPv6 sockets should be able to receive both IPv4 and IPv6
1339 connections. In the event that your IPv6 implementation is not stable, or
1340 is partially incomplete, IPv6 support in the Courier mail server should be
1341 disabled.
1342
1343 The configuration script will attempt to detect whether IPv6 structures
1344 and functions are available, and automatically enable IPv6 support if they
1345 are found. The --without-ipv6 option disables IPv6 support, which may be
1346 desired for the following reasons:
1347
1348 • The IPv6 implementation on your platform is incomplete.
1349 • The IPv6 implementation on your platform is actually not available,
1350 despite the presence of IPv6 structures and functions. Most GNU/Linux
1351 distributions ship without IPv6 support enabled in the default kernel
1352 build. The Courier mail server automatically falls back to creating an
1353 IPv4 socket, if it can't create an IPv6 socket, so things should
1354 continue to work in that case. However, each such attempt is likely to
1355 result in an error message logged to /var/log/messages -- modprobe is
1356 whining that it can't find an IPv6 module to load. On systems that
1357 handle a large amount of traffic the log files can fill up rather
1358 quickly.
1359 • Implementing IPv6 can increase the amount of DNS traffic, even if
1360 there is no IPv6 support in the kernel. Even if the Courier mail
1361 server falls back to IPv4 sockets, it will continue to resolve IPv6
1362 addresses, resulting in some extra DNS queries. There won't be a lot
1363 of extra DNS queries, but there will be some. Also, there are still
1364 some DNS servers that cannot correctly handle IPv6 queries, and
1365 attempts to deliver mail to these domains will fail despite the
1366 presence of valid IPv4 records.
1367
1368 IPv6 support is still a bit spotty in some places. If the configuration
1369 checks fail, IPv6 support will be quietly suppressed. If you expect IPv6
1370 support to be present, the --with-ipv6 flag can be used to abort
1371 configuration if IPv6 support was not detected.
1372
1373 Compile and run make check
1374
1375 make
1376 make check
1377
1378 If the configure script ran without errors, run make to build the Courier
1379 mail server. If make completes succesfully, run make check. make check
1380 runs some simple internal tests. It is not feasible to run a complete
1381 check of the Courier mail server's behavior, but make check does
1382 automatically run some tests on several modules.
1383
1384 If make check fails, you need to do some detective work. Investigate the
1385 source of the failure. It is possible that the issue can be resolved by
1386 specifying different options to the configure script, in which case you
1387 have to go back and rerun the configure script again.
1388
1389 Installation
1390
1391 su yourself to root, if you want to do a live install, then run make
1392 install or make install-strip to install the Courier mail server. If you
1393 use the GNU version of make, and you would like to see which files the
1394 Courier mail server installs and where, don't su yourself to root, but set
1395 the make variable named DESTDIR. For example:
1396
1397 make install DESTDIR=/var/tmp/courier-inst
1398
1399 The contents of DESTDIR are prepended to the name of every file installed,
1400 so if --prefix was set to /usr/lib/courier, the files will be installed in
1401 /var/tmp/courier-inst/usr/lib/courier. This only works if you use GNU
1402 make.
1403
1404 NOTE: you must make sure that your umask is 022 before you run make
1405 install.
1406
1407 If executed by root, make install automatically sets the correct ownership
1408 on the installed files. Non-root make installs do not set the ownership,
1409 but still set correct permissions. This feature is mainly for use by
1410 people who are rolling the Courier mail server into a prebuilt package,
1411 since this allows them to build the package as a normal user, not root. In
1412 this situation the command make install-perms will be very useful. This
1413 command creates a file called permissions.dat. This file contains a
1414 complete listing of everything that will be installed, and what the
1415 correct permissions are on every file.
1416
1417 make install installs the Courier mail server binaries with debugging
1418 data, which is probably a good idea to do while the Courier mail server is
1419 in development. Use makeinstall-strip to install binaries without
1420 debugging data. Some systems have a broken install utility, so make
1421 install-strip may fail.
1422
1423 Install configuration files
1424
1425 The following command creates and updates configuration files. It must be
1426 executed after running make install:
1427
1428 make install-configure
1429
1430 This command copies each configuration file "filename.dist" to "filename".
1431 The existing filename is backed up as filename.bak. If upgrading from the
1432 Courier mail server 0.30 or later, the previous configuration settings in
1433 filename.bak will be automatically copied to filename, provided that they
1434 are still valid. If a configuration setting may no longer be valid, it
1435 will be reset to its default value. The output of make install-configure
1436 will indicate the status of each configuration setting, therefore it is
1437 advistable to save the output to a file, and examine it:
1438
1439 make install-configure >upgrade.log
1440
1441 Versions prior to 0.30 cannot have their configuration settings
1442 automatically preserved, and must be restored manually from filename.bak.
1443 Do not simply copy filename.bak to filename, this will lose all the
1444 formatting codes that allow automatic upgrades.
1445
1446 PAM configuration
1447
1448 If you use PAM library for authentication, you may need to set up PAM for
1449 authenticating POP3 logins, IMAP logins, webmail logins, and/or ESMTP
1450 authentication. In most cases, all you have to do is install
1451 /usr/lib/courier/etc/pop3d.authpam as /etc/pam.d/pop3,
1452 /usr/lib/courier/etc/imapd.authpam as /etc/pam.d/imap,
1453 /usr/lib/courier/etc/webmail.authpam as /etc/pam.d/webmail, and
1454 /usr/lib/courier/etc/esmtp.authpam as /etc/pam.d/esmtp. However you will
1455 have to consult your PAM documentation, and the manual pages for authpam,
1456 in order to make sure.
1457
1458 Some versions of the PAM library, do not use the /etc/pam.d directory.
1459 Instead they use a single configuration file /etc/pam.conf. Here's an
1460 example of what needs to be added to /etc/pam.conf on FreeBSD 4.0. NOTE:
1461 other platforms may need something similar:
1462
1463 imap auth required pam_unix.so try_first_pass
1464 imap account required pam_unix.so
1465 imap session required pam_permit.so
1466 pop3 auth required pam_unix.so try_first_pass
1467 pop3 account required pam_unix.so
1468 pop3 session required pam_permit.so
1469 esmtp auth required pam_unix.so try_first_pass
1470 esmtp account required pam_unix.so
1471 esmtp session required pam_permit.so
1472
1473 Building RPM and DEB packages
1474
1475 NOTE: If an RPM or a DEB package gets built as per this INSTALL file
1476 resulting packages may not install if you have an existing IMAP or an
1477 existing POP3 server installed. The RPM packages will contain these PAM
1478 configuration files, and they will conflict with any PAM configuration
1479 files installed by another IMAP or POP3 server. If you manually installed
1480 an IMAP or a POP3 server without creating a distribution package, the
1481 Courier mail server package will install and the old configuration files
1482 will get silently removed, since they were not installed using rpm or
1483 dpkg.
1484
1485 The Courier mail server includes integrated POP3, IMAP, and webmail
1486 servers, however they only work with maildirs. Decide if you want to keep
1487 using your current server, or switch to the Courier mail server's
1488 IMAP/POP3/webmail servers. If you want to keep your existing servers, back
1489 up the contents of your /etc/pam.d directory before installing the RPM or
1490 the DEB package, install it, then restore the overwritten files. If you
1491 want to switch to the Courier mail server, blow away your current server
1492 before running make install.
1493
1494 Adjust system paranoia level
1495
1496 There are four setuid binaries in the Courier mail server that are owned
1497 by root: sendmail, maildrop, webmail and webadmin. There's also one setgid
1498 binary, sqwebpasswd.
1499
1500 /usr/lib/courier/bin/maildrop is the mail filter. If you do not need mail
1501 filtering, you can remove it. The setuid root privilege is only needed to
1502 implement mail filtering "on the wire", when receiving mail from an
1503 external mail relay (see localmailfilter(7) for more information).
1504 Removing the setuid root bit still allows traditional mail filtering to be
1505 used, after the message is received and delivered to the mailbox.
1506
1507 /usr/lib/courier/libexec/courier/webmail/webmail is the webmail CGI. It is
1508 executed by the web server, and needs to change its userid/groupid, in
1509 order to enter the maildir. If you do not need webmail access, you can
1510 remove it. An alternative is to implement virtual mailboxes, owned by a
1511 non-privileged userid, and change the ownership of the webmail CGI to the
1512 non-privileged user (you will also need to use the --with-cacheowner
1513 option to the configure script since the webmail process must have write
1514 access to the webmail login cache directory).
1515
1516 /usr/lib/courier/libexec/courier/webmail/webadmin is the wrapper for the
1517 web-based administration tool. See below for more information.
1518
1519 /usr/lib/courier/bin/sendmail is the command line mail sender. Its first
1520 order of business is to set its group id to the Courier mail server's
1521 group id, and restore the original userid, dropping root. The reason that
1522 it needs root setuid is to set its real group id, because setting the
1523 setgid bit on the executable is not enough. The setgid bit sets only the
1524 effective group id, and the root setuid bit is required to set both
1525 effective and real group ids. Both real and effective group IDs are needed
1526 in order to be able to implement maildrop mail filtering.
1527
1528 /usr/lib/courier/libexec/courier/sqwebpasswd is described in detail in the
1529 "OPTIONAL: Changing mail account passwords using the webmail server"
1530 section.
1531
1532 Post-installation setup
1533
1534 A first-time the Courier mail server installation may not require the
1535 system startup scripts to be modified to start the Courier mail server at
1536 system boot. Until the system's functionality is verified, the system will
1537 probably continue to use the existing mail server. Still, most the Courier
1538 mail server configurations will require two things to be started before
1539 any part of the system is put to use:
1540
1541 • An hourly cron job needs to be created to run the cleancache.pl
1542 script, which purges expired webmail login cache records. Logging in
1543 to the mail account via the web creates a file in a temporary
1544 directory that caches the login session identity. The output of make
1545 install includes the command that needs to be set up as a cron job by
1546 root. The cron job runs su to change to the userid that owns the login
1547 cache directory, then runs the purge script. The su command on some
1548 system uses a slightly different syntax than what's shown by make
1549 install. It may be necessary to consult the su man page before setting
1550 up the cron job. Run the su command as root, to make sure that its
1551 syntax is correct, before setting up the cron job. The cron job can be
1552 omitted if webmail is not going to be used.
1553 • Run the mkdhparams script to create the DH parameter file. A monthly
1554 job should also be created to run the mkdhparams script, in order to
1555 periodically generate a new set of DH parameters. DH parameters are
1556 used to set up encrypted connections.
1557
1558 Post-installation checks
1559
1560 The following tests should be run to verify that your installation works
1561 properly. These tests are not really comprehensive tests, they only make
1562 sure that the basic functionality is there, and they definitely must be
1563 done the first time you install a version of the Courier mail server on
1564 your system. If you later reinstall the same version on the same platform,
1565 using the same configuration, you don't need to run these installation
1566 checks (but you better be sure that the reinstallation is COMPLETELY
1567 identical to the original install). You might also wish to rerun these
1568 installation checks after upgrading your base operating system.
1569
1570 The following documentation assumes that the Courier mail server is
1571 installed in /usr/lib/courier.
1572
1573 Verify module installation
1574
1575 Run the showmodules utility after all files have been installed, but
1576 before you attempt to start the Courier mail server. The showmodules
1577 utility attempts to load and initialize transport modules that have been
1578 configured, without actually starting up the Courier mail server. Running
1579 showmodules should result in something that looks like this:
1580
1581 showmodules[5060]: Loading STATIC transport module libraries.
1582 showmodules[5060]: Installing i586-gnu-linux [0/0]
1583 showmodules[5060]: Installing local
1584 showmodules[5060]: Installed local
1585 showmodules[5060]: Installing esmtp
1586 showmodules[5060]: Installed esmtp
1587 showmodules[5060]: Installing dsn
1588 showmodules[5060]: Installed dsn
1589 showmodules[5060]: Initializing local
1590 showmodules[5060]: Initializing esmtp
1591 showmodules[5060]: Initializing dsn
1592
1593 Test child process termination
1594
1595 In this test, you will start the Courier mail server, then attempt to
1596 rapidly pump through as many messages as fast as possible, to verify that
1597 asynchronous child process termination handling works. For this test (and
1598 the following tests) you need to use a test account.
1599
1600 Log on to the test account and run maildirmake to create two maildirs:
1601 maildirmake $HOME/test, and maildirmake $HOME/bounces.
1602
1603 Create $HOME/.courier-test-default, containing one line: ./test. Create
1604 $HOME/.courier, containing one line: ./bounces. If you previously selected
1605 .qmail compatibility, you will need to use .qmail-test-default and .qmail,
1606 of course. Keep that in mind as you work through the remaining tests.
1607
1608 Start the Courier mail server as root:
1609
1610 /usr/lib/courier/sbin/courier start
1611
1612 Check your system log files for any error messages. Run the ps command,
1613 and check that you only have the following processes running: courierd
1614 (two processes), courierdsn, courieruucp, courieresmtp, and courierlocal.
1615 You will also have a couple of "logger" processes hanging around, that's
1616 ok too.
1617
1618 One of the two courierd processes will be running as root. The
1619 courierlocal process will also be running as root. All other processes
1620 will be running as the courier (or daemon, or mail) user. courieruucp may
1621 be running as uucp.
1622
1623 Run the perftest1 script, which can be found in the directory containing
1624 the Courier mail server's source code:
1625
1626 sh perftest1 1000 "user-test-1 user-test-2 user-test-3 user-test-4 user-test-5"
1627
1628 Run this script while logged on to the test account. Replace "user" with
1629 the name of your test account. This will send 1000 messages with five
1630 recipients per message. You should end up with exactly 5000 messages in
1631 $HOME/test/new. Count them.
1632
1633 Monitor the system logs. There will be a lot of activity. On my test
1634 system, the system logger usually backs up. The Courier mail server
1635 generates log messages faster than the logger can record them. When all
1636 the activity stops, count how many files you have in $HOME/test/new. For
1637 extra credit, total up the Delivered-To: headers in all the messages,
1638 there should be 1000 headers for each one of the five addresses.
1639
1640 If you did not get 5000 messages, and mailq comes up empty, check
1641 $HOME/bounces/new. If you're lucky, the rest bounced. That's still a
1642 problem, but the bounces will help you to investigate things further.
1643
1644 If you did not get 5000 messages, and mailq shows some messages remaining
1645 in the queue, and ps shows some dead zombie processes that are not being
1646 reaped, this means that asynchronous process termination is not working.
1647 You will need to examine your configuration to see whether configure
1648 selected the wait or the wait3 function. Unpack the source code again and
1649 rerun configure. This time use the --with-waitfunc option to choose the
1650 other wait function, manually. Recompile, reinstall, and rerun this test.
1651
1652 If you did get all the messages, go through your syslog for extra-extra
1653 credit. grep it for the word "defer" to see if any messages required
1654 multiple delivery attempts. This shouldn't happen either.
1655
1656 If your hardware has enough juice to pump through 5000 messages in a short
1657 period of time, rerun this test with a larger number of messages. Before
1658 doing that, wipe the Maildirs clean, in order to confirm the message
1659 count, later. The test must run for at least 3-4 minutes in order to get
1660 meaningful results.
1661
1662 User/group ID check
1663
1664 For this test you will need to use or create a regular user test account,
1665 which will be referred to as user. You can use the same test account you
1666 used in the last test, but erase all .courier (or .qmail) files.
1667
1668 In user's home directory, create .courier which contains the following
1669 text:
1670
1671 | /usr/bin/id >ID
1672 | /usr/bin/env >ENV
1673
1674 Make sure that your id and env commands are in /usr/bin. If not, use the
1675 correct path.
1676
1677 Send a single message to user:
1678
1679 echo "To: user" | /usr/lib/courier/bin/sendmail
1680
1681 Thie message will disappear into the never-never land, so don't waste time
1682 looking for it. Just examine, very closely, the contents of the ID and the
1683 ENV files in user's home directory. Double check what user and the group
1684 ids recorded in ID match user's. Pay close attention to any auxiliary
1685 group IDs, make sure that they haven't "leaked" from the root user who
1686 started the Courier mail server.
1687
1688 Also, examine the environment, in ENV. Check the manual page for
1689 dot-courier, ENV should contain only the documented environment variables,
1690 and any environment variables that are defined in the
1691 /usr/lib/courier/etc/courierd file.
1692
1693 OPTIONAL: Configure webadmin
1694
1695 This is a web-based administration tool. webadmin is a web CGI
1696 application. It is necessary to have a local web server installed in order
1697 to use webadmin. Apache will do, but so will any other server with a
1698 complete CGI implementation (PHP is not required). Installing webadmin is
1699 a three step process:
1700
1701 1. Move /usr/lib/courier/libexec/courier/webmail/webadmin to your web
1702 server's SSL cgi-bin directory.
1703
1704 2. Add the following command to your system startup script:
1705
1706 /var/www/cgi-bin/webadmin daemon &
1707
1708 (or the actual cgi-bin directory). Executing the cgi-bin webadmin with
1709 a "daemon" parameter starts the daemon process.
1710
1711 It might be useful to manage webadmin with courierlogger: using
1712 "courierlogger -pid=/usr/lib/courier/var/webadmin.pid -start
1713 .../webadmin daemon" to start webadmin and "courierlogger
1714 -pid=/usr/lib/courier/var/webadmin.pid -stop" to stop it.
1715
1716 3. Execute "make install-webadmin-password". This prompts for a password,
1717 which is saved in the file /usr/lib/courier/etc/webadmin/password.
1718
1719 4. Edit "/usr/lib/courier/etc/webadmin/restartcmd", this file contains
1720 one line, a command that webadmin runs to restart courier. This
1721 defaults to "courier restart". If Courier gets set up to run under
1722 systemd this should be changed to like:
1723
1724 systemctl restart courier.service &
1725
1726 ... or try-restart. It is important to use & to run systemctl in the
1727 background. webadmin uses this as an indication for proper signal
1728 handling setup. webadmin blocks signals when installing an updated
1729 configuration, but commands executed in the background have their
1730 signal handling reset to default. systemd will signal processes to
1731 terminate when restarting them. webadmin's blocked signals permit it
1732 to finish installing any remaining updates. systemctl will wait for
1733 the restart to finish, but it's part of the service that's getting
1734 restarted, so this process needs to run in a background, with default
1735 signal handling so that systemctl itself gets terminated.
1736
1737 5. Edit "/usr/lib/courier/etc/webadmin/restartauthcmd", this file
1738 contains one line, a command that webadmin runs to restart the Courier
1739 authentication library service. This defaults to "authdaemond
1740 restart". If courier-authlib gets set up to run under systemd this
1741 should be changed to an "systemctl restart", or maybe "systemctl
1742 try-restart", for example: systemctl try-restart
1743 courier-authlib.service.
1744
1745 6. The web server SHOULD be configured to run webadmin from the cgi-bin
1746 directory using SSL only. webadmin's authentication is rather simple:
1747 the password is saved in a cookie. Unless SSL is used, the webadmin
1748 password can be intercepted in transit. If SSL is not available, an
1749 acceptable level of security can be achieved by setting up a firewall
1750 that allows web access only from trusted IP addresses, then use a
1751 dedicated webadmin password. This is not perfect, but is generally
1752 adequate. A firewall is a good idea even if SSL is used. This is not
1753 Fort Knox, and webadmin is not going to be publicly accessible, so the
1754 only needed security is to keep everyone out except for authorized IP
1755 addresses.
1756
1757 Note that webadmin, by default, will enforce this restriction: either
1758 SSL, or access from a local IP address. Create an empty file
1759 /usr/lib/courier/etc/webadmin/unsecureok to allow non-SSL webadmin
1760 connections from remote IP addresses. Alternative, the unsecuredok
1761 file may consist of a single line with one or more IP addresses,
1762 separated by spaces. Non-SSL access will get accepted from these IP
1763 addresses only:
1764
1765 echo 192.168.0.9 192.168.0.10 >unsecuredok
1766
1767 webadmin is designed to be self-explanatory. Configuration options are
1768 divided into logical sections. Changes made to configuration options do
1769 not take effect immediately. To apply configuration changes, select
1770 "Install new configuration" from the main menu. To cancel all changes
1771 made, select "Cancel new configuration". Selecting "Install new
1772 configuration" will apply all the changes to the configuration files, and
1773 restart any the Courier mail server modules that must be restarted in
1774 order for the changes to take effect.
1775
1776 If you decide to use webadmin, most of the remaining steps in this INSTALL
1777 document can be done using webadmin's equivalent screens.
1778
1779 Create system aliases
1780
1781 You must now specify which account gets postmaster mail. The Courier mail
1782 server does NOT deliver any mail to root. You must use a non-privileged
1783 for postmaster mail. You will also need to specify where your postmaster
1784 account is. In the following example the same account is used for both,
1785 but you can easily use separate mailboxes.
1786
1787 Let's say that you want postmaster mail to be delivered to the user
1788 "admin".
1789
1790 Create /usr/lib/courier/etc/aliases/system using any text editor. An
1791 example aliases/system file is created by make install, and you can simply
1792 edit what you have there. The default contents of this file are as
1793 follows:
1794
1795 root: postmaster
1796
1797 mailer-daemon: postmaster
1798
1799 MAILER-DAEMON: postmaster
1800
1801 uucp: postmaster
1802
1803 You need to append the following line:
1804
1805 postmaster: admin
1806
1807 These aliases cause all mail addressed to root, postmaster, or
1808 mailer-daemon, to be delivered to admin's account. If you want root's mail
1809 delivered somewhere else, you can replace "root: postmaster", with
1810 something else.
1811
1812 Run the following command as root:
1813
1814 /usr/lib/courier/sbin/makealiases
1815
1816 This command creates /usr/lib/courier/etc/aliases.dat, a database that
1817 contains your new aliases.
1818
1819 Send a test message:
1820
1821 echo "To: postmaster" | /usr/lib/courier/bin/sendmail
1822
1823 Check admin's mailbox, the message should be there.
1824
1825 Let's do it again:
1826
1827 echo "To: postmaster" | /usr/lib/courier/bin/sendmail -Nsuccess
1828
1829 This time, in addition to the blank message, the sending account should
1830 receive a return receipt.
1831
1832 Additional aliases can be either added to this file, or placed in any
1833 other text file in the /usr/lib/courier/etc/aliases directory.
1834
1835 Create smtp access list
1836
1837 You need to define which IP addresses are allowed to relay SMTP mail
1838 through the server. The installation script creates
1839 /usr/lib/courier/etc/smtpaccess/default containing an example of how to
1840 enable relaying for IP address 127.0.0.1, and several reserved netblocks.
1841 You can either append additional entries to this file, or put your
1842 additional entries in any other file in the
1843 /usr/lib/courier/etc/smtpaccess subdirectory. Afterwars, run the following
1844 as root:
1845
1846 /usr/lib/courier/sbin/makesmtpaccess
1847
1848 This command creates the /usr/lib/courier/etc/smtpaccess.dat database that
1849 couriertcpd uses to initialize the environment for courieresmtpd.
1850
1851 You will need to rerun makesmtpaccess in order to rebuild smtpaccess.dat
1852 after any changes in the smtpaccess subdirectory.
1853
1854 The default the Courier mail server configuration applies smtpaccess.dat
1855 to both the regular ESMTP server (port 25), and the message submission
1856 server (port 587). It is possible to set up different access files for
1857 both ports. To do that, edit /usr/lib/courier/etc/esmtpd-msa, and
1858 explicitly set ACCESSFILE to a different file, create that file, and use
1859 the makesmtpaccess-msa command to compile the dedicated port 587 access
1860 database.
1861
1862 > NOTE: Authenticated SMTP is preferred over defining explicit IP address
1863 > ranges. When combined with SSL, authenticated SMTP enables relaying
1864 > privileges to any sender that securely provides a valid login/password,
1865 > from any IP address, instead of only a small range of preauthorized IP
1866 > addresses. The "OPTIONAL: Configure ESMTP authentication and SSL"
1867 > section, later in this installation guide, gives more information on
1868 > enabling authenticated SMTP and SSL-based encryption.
1869
1870 > Furthermore, preauthorized IP address ranges are vulnerable to being a
1871 > source of abusive backscatter E-mail. Using authenticated SMTP together
1872 > with the optional backscatter setting, described in the following
1873 > section, prevents transmission of abusive backscatter bounces to
1874 > external recipients even from trusted senders that have been
1875 > compromised.
1876
1877 Backscatter suppression
1878
1879 > NOTE: It is important to know that the Courier mail server's default
1880 > backscatter configuration means that if the Courier mail server receives
1881 > a message for delivery to a local mailbox, and encounters an error
1882 > during the delivery, the sender may not receive a delivery failure
1883 > notification. The most common reason is an error in a custom mail
1884 > filtering script. The next most common reason is a configuration error
1885 > (the Courier mail server authentication library gives the account's home
1886 > directory, optional non-default mailbox location, the account's system
1887 > userid and groupid; but they differ from the actual files and
1888 > directories (the home directory or the account's mailbox does not exist,
1889 > exists somewhere else, or they're owned by a different userid or
1890 > groupid).
1891
1892 > When installing the Courier mail server for the first time, it is
1893 > usually helpful to termporary turn off the default backscatter filters,
1894 > by setting BOFHSUPPRESSBACKSCATTER to "none", as described below. Remove
1895 > this setting after the Courier mail server is installed and its basic
1896 > functions appear to be working.
1897
1898 The term "backscatter" refers to non-delivery reports sent to a forged
1899 return address. SMTP was created a long time ago, in better times when
1900 everyone trusted each other. Anyone could provide any return address for
1901 any E-mail message.
1902
1903 Times have changed. At the time this documentation is written, most
1904 surveys report that between 75% and 80% of Internet E-mail is junk E-mail
1905 or viruses, with a forged return address.
1906
1907 Backscatter becomes a problem when a mail server does not reject unwanted
1908 mail. The mail server decides that the message is unwanted only after it
1909 is accepted. It generates a non-delivery notice, and sends it to the
1910 original message's return address. Because viruses and junk mail use
1911 random forged return addresses, the unfortunate victim of address forgery
1912 must deal with large amounts of useless non-delivery notices from the
1913 mailbox. Not to mention a bunch of uninformed people who think he is
1914 responsible for sending the virus or the junk mail to them.
1915
1916 There's now a growing consensus that backscatter bounces should be
1917 considered E-mail abuse. The Courier mail server is already very good at
1918 minimizing the amount of backscatter, by the virtue of refusing to receive
1919 any mail to a nonexistent local mailbox. However it's still possible for
1920 the Courier mail server to bounce a received message. Several settings
1921 control how the Courier mail server filters out its own backscatter, and
1922 avoids becoming a nuisance to others.
1923
1924 Two settings are available. The first setting instructs the Courier mail
1925 server to simply discard backscatter bounces. This is the
1926 ESMTP_BLOCKBACKSCATTER setting in the courierd configuration file. This
1927 setting lists the so-called "message sources" which are dropped by the
1928 SMTP client. All messages from any matching source are quietly discarded.
1929 The default setting lists one message source: a code that means "a
1930 delivery status notification for a message received via SMTP from a
1931 non-authenticated source". "Non-authenticated" means a message received
1932 from an IP address that does not have relaying privileges, and did not
1933 authenticate. It's also possible to include authenticated SMTP sources; or
1934 it's possible to disable this setting altogether, instructing the Courier
1935 mail server to deliver all bounces via SMTP, even if they may potentially
1936 be backscatter.
1937
1938 Note that messages received in other ways (such as messages sent via the
1939 sendmail command) are not affected. Their bounces will be sent via SMTP in
1940 all cases (although there exists an undocumented setting to block those
1941 bounces too). Also, bounces are always delivered to local mailboxes, this
1942 setting is ignored for local mail deliveries.
1943
1944 The default setting means that if the Courier mail server receives a
1945 message via SMTP for delivery to a local mailbox, and it bounces for some
1946 reason, the bounce will be discarded.
1947
1948 The Courier mail server is also often used as a smarthost for SMTP
1949 clients. These SMTP clients either connect from trusted IP addresses (IP
1950 addresses that belong to the organization that runs the mail server), or
1951 that succesfully authenticate, using SMTP authenticate. If those messages
1952 bounce, the non-delivery report gets delivered, because the default
1953 setting only drops bounces from non-authenticated source (a connection
1954 from a trusted IP address is always processed as if the sender succesfully
1955 authenticated).
1956
1957 > NOTE: Sometimes the Courier mail server serves as a backup MX for
1958 > another organization. If mail cannot be delivered to the primary MX (it
1959 > rejects the message, or the message times out), the bounce will be
1960 > discarded, because the message was probably received from a
1961 > non-authenticated source.
1962
1963 The second setting minimizes the possibility of generating a bounce, of
1964 any kind, in the first place. The second setting controls the backscatter
1965 suppression list, which is a list of blacklisted E-mail addresses.
1966
1967 When the Courier mail server fails to deliver a message to an address,
1968 this address goes on the suppression list, and the Courier mail server
1969 will refuse to accept any more messages to the same address. If the
1970 delivery failure was a temporary failure, any future messages will also be
1971 turned away with a temporary error. A permanent delivery failure results
1972 in future messages rejected with a permanent error.
1973
1974 Note that the suppression list does not apply to messages already accepted
1975 by the Courier mail server, and which are in its mail queue. The
1976 suppression list is checked when the Courier mail server is receiving a
1977 new message. The Courier mail server automatically clears an address from
1978 the suppression list after two hours. If the original message encountered
1979 a temporary delivery failure, The Courier mail server periodically tries
1980 again to re-deliver the message. If the message continues to encounter a
1981 temporary delivery failure, the clock starts running again, from the
1982 beginning, If a re-delivery attempts succeeds, the address is cleared from
1983 the suppression list, and the Courier mail server will now accept more
1984 messages to the same address, immediately.
1985
1986 If a message keeps encountering temporary delivery failures, the time
1987 before re-delivery attempts gets longer. It's possible that it could take
1988 more than two hours for another delivery attempt, on a busy mail server.
1989 The address then falls off the list, and the Courier mail server will
1990 accept another message to the undeliverable address. This situation is
1991 unavoidable, but is not considered to be a major issue.
1992
1993 The second setting is the BOFHSUPPRESSBACKSCATTER setting, in the bofh
1994 configuration file. See the courier(8) man page for more information. The
1995 default BOFHSUPPRESSBACKSCATTER setting also filters only messages from
1996 non-authenticated SMTP sources against the suppression list.
1997
1998 The suppression list is not updated when problematic messages are manually
1999 removed from the mail queue (using the "courier cancel" command). Even
2000 though the stuck messages are deleted, The Courier mail server will
2001 continue to refuse messages to suppressed addresses, until they time out.
2002 Use the "courier clear" command to manually clear addresses from the
2003 suppression list, if so desired.
2004
2005 > NOTE: A mailbox that exceeded its storage quota results in temporary
2006 > delivery failures. Therefore, when a mailbox fills up, The Courier mail
2007 > server stops accepting any more messages to this mailbox (there might be
2008 > one or two messages already in the mail queue, but that shouldn't be a
2009 > major issue). Mail deliveries will resume when the mailbox goes below
2010 > the quota (although this may take an hour, or two, as explained
2011 > previously). It's possible that an existing version of the Courier mail
2012 > server was originally modified to generate a permanent delivery failure
2013 > for a quota exceeded condition. This change should now be undone, in
2014 > order for backscatter suppression to work properly.
2015
2016 The third setting is the DSNTOAUTHADDR=1 setting in the courierd
2017 configuration file. This setting, when enabled, alters bounce handling of
2018 messages that were received from an authenticated SMTP connection.
2019
2020 Bounces of authenticated messages are processed according to the previous
2021 two settings, except that the bounce message gets sent (if it gets sent at
2022 all) to the authenticated login address, instead of the message's return
2023 address.
2024
2025 > NOTE: This works only if the Courier mail server is configured, via the
2026 > Courier mail server Authentication Library, to validate login IDs that
2027 > consist of a full E-mail address, "user@domain", with the login ID
2028 > corresponding to the mailbox's E-mail address.
2029
2030 Enabling this setting removes the possibility of the Courier mail server
2031 sending abusive backscatter bounces to external recipients, from a
2032 compromised trusted sender, even if the compromised trusted sender uses
2033 authenticated SMTP. Instead of sending the bounces to the forged return
2034 address, they get redirected to the sender's mailbox.
2035
2036 > NOTE: The authenticated address is used for bounces only. When the
2037 > message gets sent to its listed recipients, the message's return address
2038 > gets used, as usual.
2039
2040 > NOTE: Authenticated SMTP must be used for this option to have any
2041 > effect. When relaying privileges are granted to explicit IP address
2042 > ranges (see the preceding "Create smtp access list" section), The
2043 > Courier mail server will not have the sender's authenticated login
2044 > address (unless the sender voluntary authenticates).
2045
2046 Miscellaneous configuration
2047
2048 Review/edit contents of various configuration files in
2049 /usr/lib/courier/etc:
2050
2051 • courierd
2052
2053 this file controls general aspects of the Courier mail server's
2054 message processing. A default file is installed with comments
2055 describing what the various options are. Review the default options,
2056 and make whatever changes you deem appropriate. You will probably need
2057 to make changes to this configuration file in order to select the
2058 correct way to deliver local mail (whether to have the Courier mail
2059 server handle the delivery directly, or whether to run procmail or
2060 maildrop). There are comments in this file that tell you what needs to
2061 be done to have the Courier mail server use a separate local mail
2062 delivery agent, such as procmail, for mail delivery. Read and follow
2063 the instructions there.
2064
2065 • esmtpd
2066
2067 this is an important file that controls the Courier mail server's
2068 ESMTP server. Options in this file include setting the maximum limit
2069 on simultaneous server connections, whether to disable certain
2070 optional SMTP features, whether or not you have a mail filter module
2071 installed, and whether or not DNS-based blacklists or whitelists are
2072 used.
2073
2074 • esmtpd-msa
2075
2076 this file controls the Courier mail server's ESMTP message submission
2077 server (RFC 2476). The settings in this file supplement the settings
2078 in esmtpd. The default startup script first reads esmtpd, then
2079 esmtpd-msa in order to initialize the ESMTP message submission server
2080 on port 587.
2081
2082 • smtpaccess
2083
2084 this configuration file/directory is used to ban explicit IP addresses
2085 from connecting to the ESMTP server at all, or to specify which IP
2086 address ranges are allowed to relay mail through the ESMTP server. The
2087 default file turns on relaying in a couple of reserved IP address
2088 ranges, as an example. The makesmtpaccess command must be executed for
2089 any changes to smtpaccess to take effect.
2090
2091 • pop3d
2092
2093 this file sets various options for the Courier mail server's POP3
2094 server. The Courier mail server's POP3 server can be used only if mail
2095 is stored in Maildirs. You will need to use another POP3 server if you
2096 choose to deliver your mail to legacy mailbox files. A default
2097 configuration file is installed, describing the available options.
2098
2099 • imapd
2100
2101 this file sets various options for the Courier mail server's IMAP
2102 server. The Courier mail server's IMAP server can be used only if mail
2103 is stored in Maildirs. You will need to use another IMAP server if you
2104 choose to deliver your mail to legacy mailbox files. A default
2105 configuration file is installed, describing the available options.
2106
2107 Qmail compatibility mode.
2108
2109 echo "qmail" >/usr/lib/courier/etc/dotextension
2110
2111 Run this command if you are installing the Courier mail server on a system
2112 that's currently running the Qmail mail server. The Courier mail server
2113 will now read .qmail files for delivery instructions, instead of .courier
2114 files. The Courier mail server's .courier files are mostly compatible with
2115 Qmail's .qmail files, but there are some minor differences. Still, most of
2116 your .qmail files should work without too many problems.
2117
2118 Define local domains
2119
2120 The configuration file /usr/lib/courier/etc/locals is a list of all the
2121 domains that are considered local. Mail to any address in any local domain
2122 is handled as a local delivery. If this file does not exist the Courier
2123 mail server will use the contents of the me configuration file, or it will
2124 obtain its machine name from the operating system.
2125
2126 This file contains a list of domains, one per line. In most cases you need
2127 to initialize this file to contain every hostname that has a DNS A, or
2128 AAAA, record pointing to any IP address assigned to this machine,
2129 including "localhost". You will also need to include any domain that lists
2130 this machine as its primary MX relay.
2131
2132 You may also include domain wildcards in locals by prefixing the domain
2133 with a period. For example: ".example.com" will treat any domain
2134 underneath example.com - like a.example.com, b.example.com - as a local
2135 domain. Note that this does not include example.com itself, so you may
2136 need to list it explicitly as well!
2137
2138 NOTE: The makealiases command must be entered after making any changes to
2139 this file.
2140
2141 Create a list of domains to accept mail for
2142
2143 If you would like your server to function as a backup mail relay for other
2144 domains, create /usr/lib/courier/etc/esmtpacceptmailfor. This is a plain
2145 text file, containing a list of domains, one per line. This file lists all
2146 domains your server will accept mail for. NOTE: if you create this file,
2147 you MUST include all your local domains. Usually you can simply append
2148 what you have in /usr/lib/courier/etc/locals. If
2149 /usr/lib/courier/etc/esmtpacceptmailfor does not exist, The Courier mail
2150 server will accept mail only for the machine name listed in
2151 /usr/lib/courier/etc/me, (or the system machine name).
2152
2153 Like /usr/lib/courier/etc/locals, prepending a period to a domain name in
2154 esmtpacceptmailfor will cause the Courier mail server to accept mail for
2155 all subdomains of this domain.
2156
2157 OPTIONAL: Configure UUCP
2158
2159 The Courier mail server is capable of sending and receiving mail via UUCP.
2160 The Courier mail server does not implement UUCP directly, but instead uses
2161 your existing UUCP software to send and receive mail.
2162
2163 The Courier mail server's UUCP functionality has been tested with Taylor
2164 UUCP 1.06. It's likely that some minor tweaking will be necessary to get
2165 the Courier mail server working with other UUCP builds. Give it a shot,
2166 and keep an eye out for problems.
2167
2168 /usr/lib/courier/etc/uucpme
2169
2170 This configuration file must be initialized to list the UUCP node name
2171 that this machine is known as. Currently the Courier mail server does not
2172 support multiple UUCP node aliases for the same machine.
2173
2174 /usr/lib/courier/etc/uucpneighbors
2175
2176 This configuration file contains a list of all the nodes that your machine
2177 talks to via UUCP. Obviously this information will be a duplicate of the
2178 corresponding data in your existing UUCP configuration files, and some
2179 maintenance will be necessary to keep both lists in sync. That is,
2180 unfortunately, unavoidable. The makeuucpneighbors commands turns this
2181 plain text file into a database, which is what the Courier mail server
2182 uses directly. The format of the uucpneighbors configuration file is
2183 described in the makeuucpneighbors(8) manual page.
2184
2185 /usr/lib/courier/etc/uuucprewriteheaders
2186
2187 The Courier mail server automatically rewrites message envelope addresses
2188 from ESMTP to UUCP format. If this file exists, the addresses in the
2189 headers of messages sent to/from UUCP addresses will also be rewritten.
2190
2191 Configure UUCP domain aliases
2192
2193 The Courier mail server can accept mail addressed to <user@example.com>,
2194 and then forward it to uucp!bang!path!user, via UUCP. This is done by
2195 adding a UUCP virtual domain alias to your aliases file, see "Create
2196 system aliases". Append the following entry to your /etc/aliases, then run
2197 the makealiases command:
2198
2199 @example.com: uucp!bang!path!
2200
2201 See the makealiases(8) manual page for more information.
2202
2203 OPTIONAL: Configure LDAP aliasing
2204
2205 In addition to using LDAP for authentication and for managing accounts,
2206 The Courier mail server can use an LDAP directory for routing, or
2207 "aliasing" mail.
2208
2209 The term "aliasing" refers to substituting one or more addresses for
2210 another address. A one-to-one substitution results in the Courier mail
2211 server accepting mail for one address, and delivering the mail to another
2212 address. A one-to-many substitution results in the Courier mail server
2213 accepting mail for one address, and delivering a separate copy of the
2214 message to every address defined by the alias.
2215
2216 The Courier mail server supports a basic form of aliasing using a GDBM or
2217 DB-based database. The makealiases(8) command reads a plain text file
2218 containing the aliasing rules, the creates a GDBM or a DB database. Each
2219 recipient address is looked up in the database, and if an alias is defined
2220 for the recipient address, it is used in place of the original address.
2221 Aliasing can be used against individual addresses, one by one. An extended
2222 form of aliasing maps an entire domain to a single local address, using
2223 dot-courier(5) delivery instruction files.
2224
2225 The Courier mail server can use an LDAP directory instead of a GDBM or a
2226 DB database, to perform essentially the same function. If OpenLDAP is
2227 available at time of installation, the installation script installs the
2228 courierldapaliasd(8) program and a ldapaliasrc configuration file. It will
2229 be necessary to enter appropriate information into ldapaliasrc, and
2230 arrange to run "courierldapaliasd start" at system boot time (it is a
2231 background daemon process that opens persistent connections to the LDAP
2232 server).
2233
2234 Additional instructions for setting up LDAP-based aliasing are found in
2235 the courierldapaliasd(8) manual page.
2236
2237 OPTIONAL: Enable standard mail filters
2238
2239 The Courier mail server includes several options for selectively filtering
2240 mail. In general, The Courier mail server provides several plug-in
2241 interfaces for external mail filters, that can be used to selectively
2242 accept or reject messages.
2243
2244 Please note that running mail filters can have a non-trivial impact on
2245 mail system performance and throughput.
2246
2247 There are three standard mail filtering modules:
2248
2249 • verifyfilter - Verify all E-mail's return addresses, see the
2250 verifyfilter(8) manual page for more information.
2251 • dupfilter - Block duplicate messages, see the dupfilter(8) manual page
2252 for more information.
2253 • ratefilter - Limit the rate of messages per sender see the
2254 ratefilter(8) manual page for more information.
2255
2256 To enable a mail filter, for example:
2257
2258 filterctl start verifyfilter
2259
2260 The filterctl installs the filter, and the courierfilter starts them, see
2261 Starting and stopping the Courier mail server.
2262
2263 OPTIONAL: Configure custom mail filtering
2264
2265 The Courier mail server comes with some sample code that demonstrates how
2266 to write a mail filter. The Courier mail server provides two mail
2267 filtering interfaces:
2268
2269 • Global mail filters
2270
2271 these filters are installed and will be used to filter every incoming
2272 message. Global mail filters are permanently running daemons that
2273 create and listen on a filesystem domain socket. Each new message that
2274 the Courier mail server receives must be acknowledged by every global
2275 mail filter. Note that if global mail filters are installed, but their
2276 daemons are not running, The Courier mail server will not accept any
2277 new messages.
2278
2279 • Local mail filter
2280
2281 this filter can be used when the message is addressed to a local
2282 recipient - when the Courier mail server itself will deliver the
2283 message to a physical mailbox. Local mail filtering is designed to be
2284 primarily used by the maildrop mail filter. With the local mail
2285 filtering installed, individual recipients can create files containing
2286 mail filtering instructions that can selectively accept or reject
2287 individual messages.
2288
2289 See courierfilter(8) for more information on global mail filters.
2290
2291 See maildropfilter(7) for more information on local mail filters.
2292
2293 Miscellaneous UUCP configuration
2294
2295 The Courier mail server sends UUCP mail by running rmail via uux. The
2296 configuration script searches for the uux command in the default search
2297 path. If your uux command is not in a directory that's in your search path
2298 you will have to modify PATH before running configure.
2299
2300 The Courier mail server receives UUCP mail by expecting your UUCP software
2301 to run the rmail command, which is installed in /usr/lib/courier/bin.
2302 (It's actually a soft link to sendmail, but we'll talk about it later).
2303 Your UUCP software probably does not run commands from this directory by
2304 default, so you will have to make the necessary adjustments. You can
2305 always create another soft link in a directory that UUCP searches by
2306 default.
2307
2308 Starting and stopping the Courier mail server
2309
2310 To start the Courier mail server, run the command
2311 /usr/lib/courier/sbin/courier start. To stop the Courier mail server, run
2312 the command /usr/lib/courier/sbin/courier stop. See the courier(8) manual
2313 page for more information.
2314
2315 You should add these commands to your system startup and shutdown scripts.
2316
2317 Note that this command starts and stops the Courier mail server's core
2318 processes only. It does not start any additional daemon processes that you
2319 may need, such as the mail filtering daemon, the ESMTP server daemon, the
2320 POP3 server daemon, or the IMAP server daemon.
2321
2322 The commands courierfilter start, courierfilter stop, esmtpd start, esmtpd
2323 stop, esmtpd-msa start, esmtpd-msa stop, pop3d start, pop3d stop, imapd
2324 start, and imapd stop (all commands are installed in the sbin directory)
2325 are used to start or stop their respective daemons, and they should be
2326 added to your system startup and shutdown scripts, where required. As
2327 described in the relevant manual pages, courierfilter should be the first
2328 daemon process to start, and the last one to terminate. The remaining
2329 daemons may be started in any order.
2330
2331 Run the Courier mail server in parallel to your mail server
2332
2333 You now have several options for migrating from your existing mail server
2334 to the Courier mail server:
2335
2336 • Your existing mail server can continue to handle incoming mail, by
2337 listening on the smtp port. The Courier mail server will be used to
2338 send all outgoing mail. This is accomplished by configuring your mail
2339 software to run /usr/lib/courier/bin/sendmail to send mail, instead of
2340 your current sendmail program.
2341 • The Courier mail server can handle incoming mail by listening on the
2342 smtp port, and your existing mail server can continue to handle all
2343 outgoing mail. You will need to stop your existing mail server from
2344 listening on the smtp port, and run the following command:
2345
2346 /usr/lib/courier/sbin/esmtpd start
2347
2348 from your system start up script. You should also add
2349 /usr/lib/courier/sbin/esmtpd stop to your system shutdown script. Note
2350 that there's a separate script that starts the ESMTP submission server
2351 on port 587 - /usr/lib/courier/sbin/esmtpd-msa, that is used in an
2352 analogous fashion.
2353
2354 OPTIONAL: Configure ESMTP authentication and SSL
2355
2356 The Courier mail server supports authenticated ESMTP in order to grant
2357 ESMTP relaying privileges to remote users. The following steps set up
2358 authenticated ESMTP:
2359
2360 • Edit /usr/lib/courier/etc/esmtpd and initialize the ESMTPAUTH
2361 configuration setting. The configuration file
2362 /usr/lib/courier/etc/esmtpd-msa is used for the ESMTP submission
2363 server on port 587. Setting this variable in esmtpd is sufficient,
2364 because esmtpd-msa merely supplements the settings in esmtpd.
2365 Explicitly initialize this setting in esmtpd-msa only if you wish to
2366 apply it to port 587 only.
2367
2368 ESMTPAUTH is a list of SASL authentication methods to use use.
2369 Currently, The Courier mail server supports LOGIN, PLAIN, CRAM-SHA1
2370 and CRAM-MD5. The list of authentication methods is sometimes
2371 influenced by the installed authentication modules in the Courier mail
2372 server Authentication Library. Not all authentication modules
2373 implement CRAM-MD5/SHA1. The authentication modules that support
2374 CRAM-MD5/SHA1 authentication are: authuserdb, authldap, authmysql, and
2375 authpgsql.
2376
2377 • Your authentication modules may require additional configuration, you
2378 will have to take care of that too. For example, authpam - the PAM
2379 authentication module - requires that you also configure your PAM
2380 library. In this case, you need to configure your PAM library to
2381 support the "esmtp" service. The PAM library configuration details
2382 depend on your particular operating system, and are beyond the scope
2383 of this document. Consult the documentation for your PAM library for
2384 more information.
2385 • Restart the Courier mail server.
2386
2387 ESMTP over TLS/SSL
2388
2389 The Courier mail server also supports ESMTP over TLS/SSL, by using the
2390 ESMTP STARTTLS extension:
2391
2392 • To add SSL support you have to install OpenSSL or GnuTLS before
2393 installing the Courier mail server. Download OpenSSL from
2394 http://www.openssl.org/, or GnuTLS from http://www.gnutls.org.
2395
2396 Follow OpenSSL's or GnuTLS's installation instructions, then build the
2397 Courier mail server.
2398
2399 > NOTE: Most systems already have an available OpenSSL or GnuTLS
2400 > package. Do not build OpenSSL or GnuTLS yourself, if a prebuilt
2401 > package is already available. Just install the prebuilt package.
2402
2403 > NOTE: The development libraries must be installed in addition to the
2404 > runtime package, in order to build the Courier mail server. On most
2405 > systems, the development files (header files, libraries, etc...) are
2406 > provided in a separate "devel" package. The base OpenSSL/GnuTLS
2407 > package is not sufficient to build the Courier mail server, the
2408 > development libraries must be installed.
2409
2410 The OpenSSL library is selected when both OpenSSL and GnuTLS libraries
2411 are found by the configure script. Use the --with-gnutls option to
2412 explicitly select GnuTLS library over OpenSSL.
2413
2414 • STARTTLS is enabled simply by installing an X.509 certificate as
2415 /usr/lib/courier/share/esmtpd.pem. If this file exists, the STARTTLS
2416 ESMTP extension will be automatically advertised. This file must be
2417 owned by the userid the Courier mail server is installed as, and MUST
2418 NOT be world readable!
2419 • Note that SSL requires a signed X.509 certificate. You can generate
2420 your own self-signed certificates with OpenSSL, but mail clients will
2421 display a warning message the first time they connect to the server.
2422 To prevent the warning message, you will need to pay money to have
2423 your certificate signed by a certificate authority. The gory details
2424 of setting up SSL is beyond the scope of this document, and you should
2425 consult the OpenSSL documentation for more information.
2426 • The certificate must be installed as
2427 /usr/lib/courier/share/esmtpd.pem. This file MUST NOT HAVE any group
2428 or world permissions! It must be owned by the Courier mail server
2429 userid (the userid used to install the Courier mail server, usually
2430 courier or daemon).
2431 • In times of extreme desperation the script
2432 /usr/lib/courier/sbin/mkesmtpdcert can be used to generate
2433 /usr/lib/courier/share/esmtpd.pem. This script will silently terminate
2434 if OpenSSL is not installed, or if the esmtpd.pem certificate file
2435 already exists (so it will not be overwritten). This makes it easier
2436 to have this script invoked from a package install script.
2437 • Restart the Courier mail server's ESMTP server after installing the
2438 X.509 certificate.
2439
2440 The Courier mail server will also use TLS/SSL when sending ESMTP mail,
2441 automatically. If the remote mail server support STARTTLS, The Courier
2442 mail server will use it automatically.
2443
2444 SSL/TLS settings for the ESMTP client can be adjusted in the
2445 /usr/lib/courier/etc/courierd configuration file. When sending mail using
2446 SSL, The Courier mail server can optionally verify the remote server's
2447 X.509 certificate. This is done by setting ESMTP_TLS_VERIFY_DOMAIN to 1,
2448 in /usr/lib/courier/etc/courierd.
2449
2450 The configuration script checks for the system's list of trusted
2451 certificate authorities, and initializes TLS_TRUSTCERTS in the courierd
2452 configuration file, during installation. When the Courier connects to a
2453 remote server, setting ESMTP_TLS_VERIFY_DOMAIN to 1 in the courierd
2454 configuration file (usually /usr/lib/courier/etc/courierd or
2455 /etc/courierd) enables certificate verifications. However, many mail
2456 servers on the Internet use self-signed certificates, so this is generally
2457 of little use.
2458
2459 OPTIONAL: Configure ESMTP smarthosting
2460
2461 Initialize the esmtproutes configuration file if all outgoing mail need to
2462 be forwarded to your Internet provider's mail server, or some other
2463 "smarthost". See courier(8) for more information:
2464
2465 : relay.example.com
2466
2467 This forwards all mail to relay.example.com
2468
2469 : relay.example.com,587
2470
2471 This forwards all mail to relay.example.com on port 587.
2472
2473 : relay.example.com,465 /SECURITY=SMTPS
2474
2475 This forwards all mail to relay.example.com on port 465, using encrypted
2476 SMTP.
2477
2478 If the smarthost requires authentication, initialize the esmtpauthclient
2479 configuration file:
2480
2481 relay.example.com,587 john@example.com snerkle
2482
2483 When the Courier mail server connects to relay.example.com on port 587, it
2484 will authentication using the userid of "john@example.com" and password
2485 "snerkle".
2486
2487 OPTIONAL: Configure the SECURITY ESMTP extension
2488
2489 The Courier mail server includes an experimental extension to ESMTP that
2490 can be used to set up secure E-mail delivery between trusted mail relays
2491 over an untrusted network. This is implemented by an experimental ESMTP
2492 extension in the Courier mail server. Therefore, at present time both the
2493 sending and the receiving mail relay must be running the Courier mail
2494 server that's configured to support this extension. The specification for
2495 this ESMTP extension is publicly available. This is a very small extension
2496 of the existing, draft-standard STARTTLS ESMTP extension. The SECURITY
2497 extension should only require minor changes to existing mail servers and
2498 clients that already implement STARTTLS.
2499
2500 Overview
2501
2502 The first necessary step is to read the formal definition of the SECURITY
2503 extension, which can be found on http://www.courier-mta.org. Although the
2504 following instructions do not use any information directly from this
2505 document, it is important to understandi how this mechanism works. This
2506 will be very useful in troubleshooting. This is not called an
2507 "experimental" extension just for the hell of it.
2508
2509 The SECURITY extension builds on top of several existing, proven,
2510 technologies in order to deliver mail with the highest level of security
2511 that can possibly be implemented using the existing technology. The
2512 several steps in implementing the SECURITY extension:
2513
2514 1. Install and configure the STARTTLS ESMTP extension. This extension
2515 uses TLS/SSL encryption for sending mail.
2516 2. Create a private, controlled, X.509 Certificate Authority.
2517 3. Use the private CA to sign X.509 certificates of all mail nodes in the
2518 trusted mail network. This CA's certificate is also installed in every
2519 trusted mail node.
2520
2521 The SECURITY extension is an optional tag that's attached to an E-mail
2522 message. The Courier mail server requires STARTTLS to forward
2523 SECURITY-tagged messages, and the receiving mail nodes must present an
2524 X.509 certificate, signed by the private Certificate Authority, before the
2525 Courier mail server will send the message. The Courier mail server will
2526 refuse to send the message to a mail node that does not support STARTTLS,
2527 or doesn't present a suitable X.509 certificate.
2528
2529 Therefore, in an ideal world, mail clients will simply tag messages with
2530 the SECURITY extension. Obviously, this means that mail clients must be
2531 updated to implement this feature. Until this happens, The Courier mail
2532 server will provide a workaround that automatically tags all messages for
2533 selected domains with the SECURITY extension. This is not a perfect
2534 solution, and it has some minor limitations, which will be mentioned
2535 later.
2536
2537 Install and configure the STARTTLS ESMTP extension
2538
2539 The first step is to implement ESMTP STARTTLS. Use the instructions
2540 elsewhere in this document to activate ESMTP STARTTLS support. The
2541 following instructions use the scripts from OpenSSL 0.9.6, but should also
2542 work with OpenSSL 0.9.5a.
2543
2544 Create a private X.509 Certificate Authority
2545
2546 Create an empty subdirectory:
2547
2548 mkdir /etc/myca
2549 cd /etc/myca
2550
2551 There's a convenient OpenSSL script called CA.pl that you want to copy to
2552 the current directory:
2553
2554 cp /usr/share/ssl/misc/CA.pl .
2555
2556 Your OpenSSL package may have CA.pl installed someplace else. Find it, and
2557 copy it to /etc/myca. The CA.pl needs to be slightly modified before it
2558 can be used. Find the following commands in CA.pl, and change them as
2559 follows:
2560
2561 Replace:
2562
2563 system ("$REQ -new -keyout newreq.pem -out newreq.pem $DAYS");
2564
2565 replace with:
2566
2567 system ("$REQ -new -nodes -keyout newreq.pem -out newreq.pem $DAYS");
2568
2569 Also replace:
2570
2571 system ("$REQ -new -x509 -keyout " .
2572 "${CATOP}/private/$CAKEY -out ${CATOP}/$CACERT $DAYS");
2573
2574 replace with:
2575
2576 system ("$REQ -new -nodes -x509 -keyout " .
2577 "${CATOP}/private/$CAKEY -out ${CATOP}/$CACERT $DAYS");
2578
2579 The CA.pl script creates password-protected certificate keys by default.
2580 Password protected certificates currently do not work with the Courier
2581 mail server. Adding the -nodes parameter turns off password protection.
2582 This means that it is vital to make sure that the trusted mail relays are
2583 properly secured. All the encryption in the world will not be of much use
2584 if the mail relays are running a rootable FTP server (for example).
2585 Anyway, run CA.pl to create a new certificate authority:
2586
2587 ./CA.pl -newca
2588
2589 CA.pl prompts for a basic description of the new CA, then creates the
2590 certificate and the certificate key. The CA's root certificate is saved in
2591 /etc/myca/demoCA/cacert.pem.
2592
2593 Use the private CA to sign X.509 certificates of all trusted mail nodes
2594
2595 This step must be performed to create the X.509 certificates for every
2596 mail node in the trusted secure network. First, a certificate request is
2597 created:
2598
2599 ./CA.pl -newreq
2600
2601 CA.pl prompts for a basic description of the new certificate. Special care
2602 must be paid to the "commonName" setting. "commonName" MUST be set to the
2603 hostname of the trusted mail node, NOT its mail domain. For example, given
2604 the following DNS setup for example.com:
2605
2606 example.com. MX 10 mx1.example.com.
2607 example.com. MX 20 mx2.example.com.
2608
2609 mx1.example.com. A 192.68.0.1
2610 mx2.example.com. A 192.68.1.1
2611
2612 This domain will need two certificates, one with "commonName" set to
2613 "mx1.example.com", and one with "commonName" set to mx2.example.com.
2614
2615 Running ./CA.pl produces a certificate request in the file newreq.pem. Run
2616 the following command to sign it:
2617
2618 ./CA.pl -signreq
2619
2620 This step creates the file newcert.pem that contains a new signed
2621 certificate. The private key from the original certificate request must be
2622 appended to this file, before the certificate can be used. Simply take the
2623 newreq.pem file from the previous step, and append the private key in that
2624 file to newcert.pem. The resulting certificate file should look something
2625 like this:
2626
2627 [ description of the certificate ]
2628
2629 -----BEGIN CERTIFICATE-----
2630
2631 [ binary goo ]
2632
2633 -----END CERTIFICATE-----
2634 -----BEGIN RSA PRIVATE KEY-----
2635
2636 [ binary goo ]
2637
2638 -----END RSA PRIVATE KEY-----
2639
2640 The OpenSSL documentation contains instructions on how to perform the
2641 equivalent procedure with Diffie-Hellman instead of RSA.
2642
2643 Configure trusted mail nodes
2644
2645 Two files must be installed on every trusted mail node.
2646
2647 • The mail node's certificate, the newcert.pem file from the previous
2648 step. The following documentation assumes that this file is installed
2649 as /etc/mycert.pem. This mail node will use this certificate to
2650 authenticate itself to other trusted mail nodes.
2651 • The certificate authority file, cacert.pem. The following
2652 documentation assumes that it's installed as /etc/cacert.pem. The CA's
2653 certificate is used to authenticate other trusted mail nodes.
2654
2655 Edit the /usr/lib/courier/etc/esmtpd configuration file. Set TLS_CERTFILE
2656 to /etc/mycert.pem. The Courier mail server will use TLS_CERTFILE to
2657 authenticate itself to other trusted mail nodes.
2658
2659 Edit the /usr/lib/courier/etc/courierd configuration file. Set
2660 TLS_TRUSTSECURITYCERTS to /etc/cacert.pem. The Courier mail server will
2661 not send ESMTP mail tagged with the SECURITY extension to other mail
2662 relays unless they produce a certificate that's signed by
2663 TLS_TRUSTSECURITYCERTS.
2664
2665 Testing
2666
2667 The following simple steps can be carried out to verify that everything is
2668 working correctly. These examples use two mail nodes called
2669 send.example.com and receive.example.com. The test messages are sent from
2670 send.example.com, and are addressed to receive.example.com. The Courier
2671 mail server must be restarted on both send and receive, after
2672 reconfiguring the machines for each test. It is not strictly necessary to
2673 do this every time, actually, but it's simply easier to do make it a part
2674 of the routine. It is necessary to restart both the main the Courier mail
2675 server daemon processes as well as the separate ESMTP daemon process (on
2676 receive):
2677
2678 courier stop
2679 courier start
2680 esmtpd stop
2681 esmtpd start
2682
2683 1. Temporary get rid of /usr/lib/courier/bin/couriertls wrapper on
2684 receive.example.com. Rename it to couriertls.save. STARTTLS is
2685 automatically disabled if couriertls is missing,
2686 2. Run the following command on send.example.com:
2687
2688 echo "To: postmaster" | /usr/lib/courier/bin/sendmail \
2689 -S STARTTLS postmaster@receive.example.com
2690
2691 This message should bounce back since receive has STARTTLS disabled.
2692
2693 3. Restore couriertls on receive.example.com, but then rename it on
2694 send.example.com. The situation is now reversed, and the test message
2695 should still bounce.
2696 4. Restore couriertls on send.example.com. Edit receive's
2697 /usr/lib/courier/etc/esmtpd file. Comment out the current TLS_CERTFILE
2698 setting (which points to the private CA certificate). Reset
2699 TLS_CERTFILE to /usr/lib/courier/share/esmtpd.pem, which is the
2700 self-signed test certificate created by the mkesmtpdcert script, when
2701 STARTTLS support in the Courier mail server was first set up.
2702
2703 Send a test message WITHOUT the "-S STARTTLS" option. This message
2704 should go through, assuming all the other setting in all configuration
2705 files are the initial defaults. The regular ESMTP STARTTLS extension,
2706 without authentication, will be used the deliver this message. Verify
2707 this by checking the headers in the received message on
2708 receive.example.com.
2709
2710 Send a test message WITH the "-S STARTTLS" option. It should bounce,
2711 even though receive.example.com supports STARTTLS. That's because it
2712 is using an X.509 certificate that's not signed by the private CA
2713 authority.
2714
2715 5. Restore TLS_CERTFILE on receive, and send a test message with the -S
2716 STARTTLS option, which should now go through.
2717
2718 Force SECURITY for selected domains
2719
2720 As demonstrated by the test messages, messages must be tagged with the
2721 SECURITY extension in order for them to be securely transmitted. This must
2722 be done by the sending mail client. Until mail clients support SECURITY
2723 The Courier mail server can automatically add the SECURITY tag to every
2724 message addressed to a domain. This is done by entering the domain in the
2725 esmtproutes configuration file using the following syntax:
2726
2727 receive.example.com: /SECURITY=STARTTLS
2728
2729 Repeat the tests in the previous section, but this time add and delete
2730 this entry in /usr/lib/courier/etc/esmtproutes instead of using the -S
2731 STARTTLS option. The test messages must still bounce or not bounce in the
2732 same way.
2733
2734 Consult the courier(8) manual page for more information on the esmtproutes
2735 configuration file.
2736
2737 Limitations
2738
2739 This setup makes it virtually impossible to intercept mail traffic between
2740 trusted mail nodes. Even if the DNS cache is poisoned to intercept mail to
2741 a hostile mail node, mail will not go through since the attacker will not
2742 have a signed X.509 cert. However, all is lost if the mail nodes
2743 themselves are compromised directly. After securing the compromised node,
2744 everything must be rebuilt. A new CA must be created, and all mail nodes
2745 must now receive new certificates. Once support for certificate revocation
2746 lists is improved, this situation will get somewhat better.
2747
2748 Another possible way to mitigate that possibility is to use a different
2749 certificate authority for every trusted mail node. TLS_TRUSTSECURITYCERTS
2750 can point to a directory, instead of a file. This directory can contain
2751 multiple certificate authorities (hashed by OpenSSL's c_rehash script).
2752 Then, only the compromised mail node's authority certificate needs to be
2753 tossed out, regenerated, and redistributed.
2754
2755 TODO: it may be possible to avoid generating individual certificates, and
2756 distribute self-signed certificate authority certs only, with a
2757 properly-initialized commonName field. This needs to be researched.
2758
2759 There are some minor differences between using -S STARTTLS versus putting
2760 the domain into esmtproutes. If the sending mail node forward mail to this
2761 domain via UUCP, -S STARTTLS will bounce. Since esmtproutes does not apply
2762 to UUCP, putting this domain in esmtproutes will have no effect
2763 whatsoever.
2764
2765 OPTIONAL: Configure the Sender Policy Framework
2766
2767 The Courier mail server can optionally check the return address on all
2768 SMTP mail for the sender's published Sender Policy Framework (SPF). Keep
2769 in mind SPF is an experimental protocol that's still maturing. The Courier
2770 mail server's SPF configuration is set up in the "bofh" configuration
2771 file, and is fully explained in the courier(8) manual page.
2772
2773 OPTIONAL: Configure the IMAP server
2774
2775 The Courier mail server includes an integrated IMAP server. The following
2776 steps set it up:
2777
2778 • If using virtual mail accounts the system limit on the maximum number
2779 of inotify file descriptors, /proc/sys/fs/inotify/max_user_instances,
2780 will likely need to be increased, since all IMAP processes will be
2781 running under the same userid. Rough metric is the maximum number of
2782 concurrent IMAP sessions multiplied by 4. On very large servers it may
2783 also be necessary to increase /proc/sys/fs/inotify/max_user_watches, a
2784 rough metric would be at least 5 times the max_user_instances setting.
2785 • Edit /usr/lib/courier/etc/imapd. If you want to use IMAP SASL
2786 authentication, set up the IMAP_CAPABILITY variable. It performs the
2787 equivalent function as the ESMTPAUTH variable in the esmtpd
2788 configuration file, except that IMAP_CAPABILITY also sets several
2789 other IMAP capabilities that are advertised to IMAP clients. Also, for
2790 IMAP, CRAM-MD5/SHA1 authentication has been tested, and is known to
2791 work, so it is listed as a default. Also, note than if the authpam
2792 authentication module is used, you will need to configure the "imap"
2793 PAM service. Other authentication modules have their own requirements
2794 too.
2795 • Uninstall any existing IMAP server that you have, remove the entry for
2796 the IMAP port in /etc/inetd.conf, and restart the inetd daemon.
2797 • Add the following command to your system startup script
2798
2799 /usr/lib/courier/sbin/imapd start
2800
2801 Of course, add /usr/lib/courier/sbin/imapd stop to your shutdown
2802 script too.
2803
2804 NOTE: if you have previously installed the stand-alone version of the
2805 Courier IMAP server, you will need to remove it prior to using the
2806 directly integrated version. They use the same base source code, but have
2807 a slightly different configuration.
2808
2809 NOTE: this IMAP server supports maildirs only. It does not support mbox
2810 file mailboxes.
2811
2812 Configure IMAP shared folders
2813
2814 It is possible to share folders between different mailboxes, via IMAP. See
2815 the file maildir/README.sharedfolders.(txt|html) for more information.
2816
2817 OPTIONAL: Configure IMAP over SSL
2818
2819 To add SSL support you have to install OpenSSL or GnuTLS before installing
2820 the Courier mail server. Download OpenSSL from http://www.openssl.org/, or
2821 GnuTLS from http://www.gnutls.org.
2822
2823 OpenSSL's support is well-tested, the GnuTLS version is a relatively new
2824 addition, and is considered experimental. Follow OpenSSL's or GnuTLS's
2825 installation instructions, then build the Courier mail server.
2826
2827 > NOTE: Most systems already have an available OpenSSL or GnuTLS package.
2828 > Do not build OpenSSL or GnuTLS yourself, if a prebuilt package is
2829 > already available. Just install the prebuilt package.
2830
2831 > NOTE: The development libraries must be installed in addition to the
2832 > runtime package, in order to build the Courier mail server. On most
2833 > systems, the development files (header files, libraries, etc...) are
2834 > provided in a separate "devel" package. The base OpenSSL/GnuTLS package
2835 > is not sufficient to build the Courier mail server, the development
2836 > libraries must be installed.
2837
2838 The OpenSSL library is selected when both OpenSSL and GnuTLS libraries are
2839 found by the configure script. Use the --with-gnutls option to explicitly
2840 select GnuTLS library over OpenSSL.
2841
2842 The /usr/lib/courier/etc/imapd-ssl configuration file sets some additional
2843 options for SSL support, which you may need to adjust. Consult that
2844 configuration file for additional information. Then, you also have to run
2845 the /usr/lib/courier/sbin/imapd-ssl script from your system startup and
2846 shutdown scripts, just like the /usr/lib/courier/sbin/imapd script. You
2847 may accept both SSL and non-SSL connections by running both scripts.
2848
2849 Note that SSL requires a valid, signed, X.509 certificate to be installed
2850 where the Courier mail server expects to find it. The default location for
2851 the X.509 certificate, in PEM format, is /usr/lib/courier/share/imapd.pem.
2852 The X.509 certificate must be signed by a certificate authority that is
2853 known to the IMAP client. You can generate your own self-signed
2854 certificate by running the script /usr/lib/courier/share/mkimapdcert which
2855 will work too, except that IMAP clients using SSL will display a warning
2856 message the first time they connect to the server. To get rid of the
2857 warning message you'll have to pay for a signed X.509 certificate. The
2858 gory details of setting up SSL is beyond the scope of this document, and
2859 you should consult the OpenSSL documentation for more information.
2860
2861 The mkimapdcert script will not overwrite an existing imapd.pem
2862 certificate, in order to allow precompiled packages to simply call
2863 mkimapdcert after installation, without worry.
2864
2865 The IMAP server also supports the IMAP STARTTLS extension as an
2866 alternative or a complement to IMAP over SSL. The
2867 /usr/lib/courier/etc/imapd-ssl configuration file is also used to enable
2868 or disable IMAP STARTTLS, which has all the same requirements and
2869 prerequisites as IMAP over SSL.
2870
2871 OPTIONAL: Sending mail via an imap connection
2872
2873 This server allows using the IMAP connection to send E-mail. Normally, the
2874 IMAP protocol provides only access to mail in an existing mail account,
2875 and mail clients must use SMTP in order to send mail. The Courier IMAP
2876 server has an optional setting to enable mail to be send via an IMAP
2877 connection in a manner that should work with all existing IMAP mail
2878 clients. This can be useful when an account is logged in from a shared
2879 access pool which normally blocks most access to the SMTP port.
2880
2881 This is implemented by enabling a setting in the imapd configuration file
2882 that designates a folder as a special "Outbox" folder. The default setting
2883 is a folder called "Outbox" (IMAP path INBOX.Outbox), but the name can be
2884 changed to anything. This folder, for the most part, is no different than
2885 any other folder. If a folder by that name doesn't exist, it needs to be
2886 created, just like any other IMAP folder. It looks and acts like any other
2887 folder, except that each message added to the folder, via IMAP's APPEND or
2888 COPY command, will also be mailed out by the Courier IMAP server to the
2889 addresses listed in the To:, Cc:, and Bcc: headers.
2890
2891 It should be possible to use this to send mail from any IMAP client by:
2892
2893 1. Composing a draft message, telling the IMAP client to save the draft
2894 message in its drafts folder on the IMAP server.
2895 2. Opening the drafts folder, and moving or copying the message to the
2896 Outbox folder.
2897 3. The act of copying the message into the Outbox folder will send the
2898 mail. There won't be any explicit notification to the fact that the
2899 message was sent, so it's a good idea to include your own E-mail
2900 address on the Cc: list.
2901
2902 > NOTE: it is tempting to configure the IMAP mail client to use Outbox as
2903 > its default folder for saving drafts. Resist the temptation. If you
2904 > forget, you'll save a partially completed draft, which will be then
2905 > obediently mailed out.
2906
2907 > NOTE: the message, in addition to being sent, will be saved in the
2908 > folder in the normal fashion. After saving the message, reopen the
2909 > Outbox folder and delete the sent message, or move it someplace else.
2910
2911 > NOTE: when enabled, the Courier IMAP server will advertize a private
2912 > XCOURIEROUTBOX IMAP capability. It is theoretically possible to code an
2913 > IMAP mail client that reads this capability and automatically configures
2914 > itself accordingly -- when this IMAP capability is present -- to send
2915 > E-mail in the normal way but using the IMAP connection. At this time,
2916 > I'm not aware of any actual mail clients that know how to do this.
2917
2918 > NOTE: many mail clients save some additional internal information in
2919 > headers of draft messages. The internal information is normally removed
2920 > before the mail client sends the message. Make sure that none of this
2921 > extra information is something that should not be mailed out.
2922
2923 OPTIONAL: Configure IMAP realtime folder status updates
2924
2925 It's possible to allow multiple clients to open the same folder, and have
2926 all clients to be simultaneously notified of any changes to the folder
2927 contents.
2928
2929 After installing the server see the imapd(8) manual page for more
2930 information.
2931
2932 OPTIONAL: Configure SMAP
2933
2934 Starting with the Courier mail server 0.43, the IMAP server supports an
2935 experimental mail access protocol, dubbed "Simple Mail Access Protocol".
2936 SMAP is an experiment to provide enhanced mail processing beyond what's
2937 currently possible with IMAP. SMAP's purpose is to prototype and develop
2938 advanced mail access functionality that's not possible with IMAP. SMAP is
2939 disabled by default. Uncomment the SMAP_CAPABILITY setting in the imapd
2940 configuration file in order to enable SMAP. The Cone mail client supports
2941 SMAP.
2942
2943 OPTIONAL: Configure the POP3 server
2944
2945 The Courier mail server includes an integrated POP3 server. The following
2946 steps will set it up:
2947
2948 • Edit /usr/lib/courier/etc/pop3d. Very few POP3 clients support POP3
2949 SASL authentication, but if you want to use it, for some reason,
2950 uncomment the POP3AUTH variable. It performs the equivalent function
2951 as the corresponding variable in the esmtpd and imapd configuration
2952 files. For POP3, SASL LOGIN authentication has been tested, and is
2953 known to work, and CRAM-MD5/SHA1 has not been tested. Also, note than
2954 if authpam is used, you will need to configure the "pop3" PAM service.
2955 Other authentication modules have their own requirements.
2956 • Uninstall any existing POP3 server that you have, remove the entry for
2957 the POP3 port in /etc/inetd.conf, and restart the inetd daemon.
2958 • Add the following command to your system startup script:
2959
2960 /usr/lib/courier/sbin/pop3d start
2961
2962 Of course, add /usr/lib/courier/sbin/pop3d stop to your shutdown
2963 script too.
2964
2965 NOTE: this POP3 server supports maildirs only. It does not support mbox
2966 file mailboxes.
2967
2968 OPTIONAL: Configure POP3 over SSL
2969
2970 Implementing POP3 over SSL is very similar to implementing IMAP over SSL.
2971 The only differences are that the startup/shutdown command is
2972 "/usr/lib/courier/sbin/pop3d start" and "/usr/lib/courier/sbin/pop3d
2973 stop", the configuration file is /usr/lib/courier/etc/pop3d, the name of
2974 the required SSL certificate is /usr/lib/courier/share/pop3d.pem, and the
2975 command to generate a test SSL certificate is mkpop3dcert.
2976
2977 OPTIONAL: Configure the IMAP/POP3 aggregator proxy
2978
2979 It is possible to distribute IMAP and POP3 mailboxes between multiple
2980 server.
2981
2982 See imap/README.proxy for more information.
2983
2984 CERTIFICATE AUTHENTICATION
2985
2986 The Courier mail server can use SSL certificates for authentication
2987 purposes. That is, instead of using a login ID and a password, for
2988 accessing the mailbox, The Courier mail server uses a client-side SSL
2989 certificate. For certificate authentication purposes, one of the fields in
2990 your certificates' subject must match the login ID in the authentication
2991 database. Consider the following certificate:
2992
2993 ...
2994 Subject: C=US,ST=New York,L=New York,O=Acme Widgets Inc,CN=John Smith,emailAddress=johnsmith@example.com
2995
2996 If the emailAddress field is configured as the login ID, the
2997 authentication database must provide login details for
2998 johnsmith@example.com. To enable certificate authentication, edit the
2999 following configuration files in sysconfdir: imapd-ssl, pop3d-ssl, esmtpd
3000 and esmtpd-ssl (the esmtpd files enable SSL certificate authentication for
3001 incoming SMTP connections, if a good SSL certificate is provided, the
3002 client receives mail relaying privileges). All of these configuration
3003 files require the same set of changes:
3004
3005 • Set TLS_TRUSTCERTS to the filename with your certificate authority's
3006 X.509 certificate.
3007
3008 • Change the TLS_VERIFYPEER setting to "PEER". The setting can also be
3009 changed to "REQUIREPEER" to require all SSL/TLS connections to provide
3010 a certificate. Otherwise, it is optional. If the mail client provides
3011 an SSL certificate, it may be used to authenticate. Without a
3012 certificate, password-based authentication remains an option.
3013
3014 • Change the TLS_EXTERNAL setting to the name of the certificate subject
3015 field that gives the login ID. In the above example, this would be
3016 "TLS_EXTERNAL=emailaddress".
3017
3018 > NOTE: GnuTLS's certtool uses "email" as the name of this field. If
3019 > the Courier mail server is compiled with GnuTLS, you should still
3020 > specify this field as "emailaddress".
3021
3022 OPTIONAL: Configure the webmail server
3023
3024 The integrated webmail server is made up of two parts. The first part, by
3025 default, is installed as /usr/lib/courier/libexec/courier/webmail. You can
3026 simply copy this binary executable to your web server's cgi-bin directory,
3027 or create a link from the cgi-bin directory to this program. This is a
3028 small stub program that connects, via a local socket, to the sqwebmaild
3029 daemon process, which implements the webmail service. It is necessary to
3030 start the webmail server by adding the following command to the system
3031 startup screen (so that the webmail server gets automatically started at
3032 boot):
3033
3034 /usr/lib/courier/sbin/webmaild start
3035
3036 (It is also possible to run "webmaild stop" from the system shutdown
3037 script in order to shut down webmail service gracefully).
3038
3039 Note that the webmail server is used to access mail in existing accounts
3040 only. There is no provision to create accounts through the webmail
3041 interface (nor there should be).
3042
3043 SELinux
3044
3045 The following extension may be necessary to make webmail work when SELinux
3046 kernel extensions are turned on:
3047
3048 allow httpd_sys_script_t var_t:sock_file write;
3049 allow httpd_sys_script_t unconfined_t:unix_stream_socket connectto;
3050
3051 Spell checking
3052
3053 The webmail server can use either the ispell or the aspell package for
3054 spell checking. Install ispell or aspell before installing the Courier
3055 mail server.
3056
3057 NOTE: Courier mail server assumes that the spell checking dictionary is
3058 called "english". Some systems use a different name for the default spell
3059 checking dictionary. To change the name of the spell checking dictionary
3060 used by the webmail server, put the name of the dictionary into the file
3061 /usr/lib/courier/share/sqwebmail/html/en-us/ISPELLDICT.
3062
3063 Images
3064
3065 It is also necessary to install the static icon images used by the webmail
3066 server. The installation script copies the static images to the
3067 /usr/lib/courier/share/sqwebmail/images directory. By default, the webmail
3068 server uses the URL "/webmail/" to specify the location of the static
3069 images, for example: /webmail/folders.gif. This means that you must create
3070 a subdirectory called "webmail" in your web server's document root -
3071 typically /usr/local/etc/apache/htdocs/webmail, or
3072 /usr/local/www/htdocs/webmail, or something similar. You will need to
3073 determine the actual location of your web root directory, which varies
3074 from system to system. Then, create a subdirectory named "webmail", and
3075 copy all the icons to that directory.
3076
3077 Another possibility is to install a soft link, instead of creating the
3078 webmail sub directory, and point the soft link to
3079 /usr/lib/courier/share/sqwebmail/images (you also must make sure that the
3080 web server is configured to follow symlinks).
3081
3082 There is a configuration option, --enable-imageurl, that can be used to
3083 use something other than /webmail/ as the URL prefix for images.
3084
3085 Alternative timezones
3086
3087 The file /usr/lib/courier/share/sqwebmail/html/en-us/TIMEZONELIST contains
3088 a list of alternative timezones. By default all dates and times are shown
3089 in the server's default timezone, and the dropdown list on the login
3090 screen can be used to select an alternative timezone. The default
3091 alternative timezone list that lists only a small number of timezones.
3092 Additional timezones can be entered into this file to be shown on the
3093 login web page.
3094
3095 LDAP address book import
3096
3097 The webmail server can import E-mail addresses from public LDAP address
3098 books into an individual address book. A default systemwide list of
3099 accessible LDAP address books is defined for everyone, and individuals can
3100 configure additional LDAP address books for themselves.
3101
3102 The OpenLDAP development toolkit must be installed before building
3103 SqWebMail, in order for LDAP search code to compile.
3104
3105 The file ldapaddressbook configuration file should contain a default
3106 systemwide list of accessible address book. See courier(8) for more
3107 information. A default file will be installed, listing some common
3108 Internet address books. Each line in this file contains the following
3109 information:
3110
3111 name<tab>host<tab>port<tab>suffix<tab>binddn<tab>bindpw
3112
3113 <tab> is a single ASCII TAB character. name is the unique name for this
3114 LDAP server. host and port specify the connection parameters. suffix
3115 specifies the root LDAP entry whose subtree gets searched. The binddn and
3116 bindpw fields are not presently used (they were used in earlier version of
3117 the webmail server, before the LDAP search interface was rewritten and
3118 simplified).
3119
3120 Webmail session timeouts
3121
3122 A login session is automatically logged out after certain period of
3123 inactivity. The timeout period defaults to 20 minutes, and is set by the
3124 --enable-softtimeout option to the configure script. It is also possible
3125 to adjust this value by setting the SQWEBMAIL_TIMEOUTSOFT environment
3126 variable. For example, with Apache, by adding the following to httpd.conf:
3127
3128 SetEnv SQWEBMAIL_TIMEOUTSOFT 3600
3129
3130 There is also a hard timeout, which logs out a session no matter what. The
3131 default of two hours is changed with the --enable-hardtimeout option to
3132 the configure script, and the SQWEBMAIL_TIMEOUTHARD environment variable.
3133
3134 WARNING:
3135
3136 The hard timeout interval is used to calculate the maintenance of the
3137 login cache (if that option is selected). This factor is used in the
3138 cleancache.pl cleanup script, and changes to this value must be
3139 coordinated appropriately. It is not possible to use different hard
3140 timeout values with the same login cache (in different virtual domains, as
3141 described in the next session). Leisurely tinkering with this environment
3142 variable is STRONGLY DISCOURAGED, it's very easy to screw up the whole
3143 system. You've been warned.
3144
3145 If you adjust the hard timeout, you must simultaneously delete your
3146 current login cache directory, and adjust $timeouthard in the installed
3147 cleancache.pl script.
3148
3149 Maximum message sizes
3150
3151 Messages composed in the webmail server are limited in size. The
3152 additional limitation are on top of the limit set in the sizelimit
3153 configuration file, see the courier(8) manual page.
3154
3155 The --with-maxargsize, --with-maxformargsize, and --with-maxmsgsize
3156 options to the configure script set the parameters that control the
3157 maximum size of messages and attachments. These parameters can also be set
3158 through the following environment variables.
3159
3160 > NOTE: The configure script parameters define the minimum settngs. The
3161 > following environment variables may be used to set larger limits only.
3162
3163 > NOTE: These settings limit only the maximum size of messages sent from
3164 > the webmail server. The limit on the incoming message size is set by
3165 > other Courier mail server settings (usually the sizelimit setting also).
3166
3167 SQWEBMAIL_MAXARGSIZE
3168 Approximate maximum size, in bytes, of the message, excluding any
3169 attachments (overrides the --with-maxargsize parameter to the configure
3170 script). This is the maximum message that can be typed into the webmail
3171 server.
3172
3173 NOTE: The webmail server has an inactivity timeout. While composing a new
3174 message use the "Preview" button frequently to save the unfinished message
3175 and keep the session from timing out.
3176
3177 SQWEBMAIL_MAXATTSIZE
3178 Approximate maximum size, of each allowed attachment. (overrides the
3179 --with-maxargsize parameter to the configure script).
3180
3181 NOTE: Attaching binary files to E-mail messages incurs an overhead of
3182 approximately 33%. E-mail is really not the optimum medium for exchanging
3183 files. Setting SQWEBMAIL_MAXATTSIZE to 4000000 will effectively allow
3184 attaching files of up to 3000000 bytes in length, approximately.
3185
3186 SQWEBMAIL_MAXMSGSIZE
3187 Approximate maximum size, of a message, including the text portion and all
3188 attachments (overrides the --with-maxmsgsize parameter to the configure
3189 script). There can be any number of attachments, each one up to
3190 SQWEBMAIL_MAXATTSIZE bytes long, but the sum total of the entire message
3191 cannot exceed SQWEBMAIL_MAXMSGSIZE.
3192
3193 These variables must be set in the environment that runs the webmail CGI
3194 program. With Apache, these variables can be set in the httpd.conf file by
3195 the SetEnv command. httpd.conf example:
3196
3197 SetEnv SQWEBMAIL_MAXATTSIZE 1000000
3198 SetEnv SQWEBMAIL_MAXMSGSIZE 4000000
3199
3200 > NOTE: These settings are global, and apply to all mailboxes. However,
3201 > advanced Apache configuration can be used to use different environment
3202 > variable settings with different virtual hosts.
3203
3204 > NOTE: On 32-bit platforms, the maximum limits may not exceed 2
3205 > gigabytes. A 64-bit platform is required to have SqWebMail capable of
3206 > handling attachments and messages larger than 2 gigabytes.
3207
3208 Random seed
3209
3210 A random seed is required for preventing certain kinds of external attacks
3211 against the SqWebMail server. The random seed must be a constant value,
3212 only varying between different instances of SqWebMail. By default the
3213 random seed is derived from the inode number of one of the supporting
3214 script files. The script file ordinarily remains constant, thus the random
3215 seed does not change, but different SqWebMail installs will end up with a
3216 different seed.
3217
3218 When a pool of SqWebMail servers is combined for load-balancing, all
3219 servers must use the same random seed. This is done by defining the
3220 SQWEBMAIL_RANDSEED environment variable. This can be set in the httpd.conf
3221 as well:
3222
3223 SetEnv SQWEBMAIL_RANDSEED 82738AZ
3224
3225 SQWEBMAIL_RANDSEED should contain up to ten letters or numbers.
3226
3227 Domain-based templates
3228
3229 The default set of templates for the dynamically generated HTML is
3230 installed in /usr/local/share/sqwebmail/html. When the same server is used
3231 to provide webmail access for multiple domains it is possible to specify a
3232 different set of HTML templates for each domain.
3233
3234 This functionality is not directly implemented in SqWebMail, simply
3235 because there is no standard way to specify this. Instead, this is
3236 something that will need some minor work set up.
3237
3238 Domain-based templates are implemented by making the web server set the
3239 environment variables SQWEBMAIL_TEMPLATEDIR prior to running the sqwebmail
3240 binary. The contents of this environment variable override the default
3241 location of /usr/local/share/sqwebmail/html. By having the web server
3242 initialize this variable based on the domain name it is possible to
3243 present different templates, based on the domain name used.
3244
3245 To do this, make copies of the HTML template directory,
3246 /usr/local/share/sqwebmail/html. Then, configure the web server to
3247 initialize SQWEBMAIL_TEMPLATEDIR appropriately. For example, with Apache:
3248
3249 <VirtualHost a.b.c.d>
3250 ServerName webmail.example.com
3251 [...]
3252 SetEnv SQWEBMAIL_TEMPLATEDIR /usr/local/share/webmail/webmail.example.com
3253 [...]
3254 </VirtualHost>
3255
3256 The possibilities are endless.
3257
3258 Name-based templates
3259
3260 It is now possible to display two or more templates from the same CGI
3261 binary WITHOUT setting up multiple domain names.
3262
3263 For example, with Name-based templates an sqwebmail administrator can set
3264 up sqwebmail to display a template in the /usr/local/share/sqwebmail/html
3265 directory when sqwebmail is called from the URL:
3266 http://www.foo.com/cgi-bin/sqwebmail
3267
3268 And display a different template in the
3269 /usr/local/share/sqwebmail/alternate-html directory when sqwebmail is
3270 called from the URL: http://www.foo.com/cgi-bin/sqwebmail-alt-template
3271
3272 This is made possible by a little web server magic (explained below in the
3273 section entitled "Apache Name-based template configuration example") and
3274 the setting of TWO sqwebmail environment variables:
3275
3276 SQWEBMAIL_TEMPLATEDIR
3277 SQWEBMAIL_IMAGEURL
3278
3279 You should recognize the SQWEBMAIL_TEMPLATEDIR environment variable from
3280 the section above on Domain-based templates. If you haven't read that
3281 section yet, please do so now.
3282
3283 The SQWEBMAIL_IMAGEURL environment variable is new in versions of
3284 sqwebmail greater than sqwebmail-3.5.3.20030629. It allows us to set, at
3285 run time, the image URL, or the root URL, in which to look for our
3286 template's images. This image URL is then automatically inserted into the
3287 current template anytime a conditional image tag or an IMAGEURL tag is
3288 encountered.
3289
3290 This is an example of a conditional image tag:
3291
3292 [#@image.gif, ... @text@#]
3293
3294 The conditional image tag is replaced at template processing time with an
3295 HTML <img src="..."> tag if (hence the word "conditional") sqwebmail is
3296 set up to display images.
3297
3298 This is an example of an IMAGEURL tag:
3299
3300 [#IMAGEURL#]
3301
3302 The IMAGEURL tag is replaced at template processing time with the contents
3303 of the SQWEBMAIL_IMAGEURL environment variable, if set, and otherwise with
3304 the value of the --with-imageurl configure option, which defaults to
3305 "/webmail".
3306
3307 Apache Name-based template configuration example
3308
3309 Let's take a look at a simple Apache Name-based sqwebmail template
3310 configuration example:
3311
3312
3313 # Sqwebmail Alternate Template URL
3314 ScriptAlias /cgi-bin/sqwebmail-alt-template "/usr/local/apache/cgi-bin/sqwebmail"
3315
3316 <Location /cgi-bin/sqwebmail-alt-template>
3317 Setenv SQWEBMAIL_TEMPLATEDIR "/usr/local/share/sqwebmail/alternate-template"
3318 Setenv SQWEBMAIL_IMAGEURL "/alternate-webmail"
3319 [...]
3320 </Location>
3321
3322
3323 The above should allow your users to run sqwebmail with the template in
3324 /usr/local/share/sqwebmail/alternate-template and an image URL of
3325 /alternate-webmail, simply by calling sqwebmail from the following URL:
3326
3327 http://www.yourdomain.com/cgi-bin/sqwebmail-alt-template
3328
3329 The original sqwebmail templates would then still be available from this
3330 URL:
3331
3332 http://www.yourdomain.com/cgi-bin/sqwebmail
3333
3334 Using Apache's <Location> directive we can utilize a virtually unlimited
3335 number of templates without setting up a single virtual domain.
3336
3337 OPTIONAL: Configure webmail calendaring
3338
3339 Optional calendaring services can be enabled in the webmail server. Right
3340 now, the current implementation provides basic calendaring services. For
3341 more information on calendaring, see the file pcp/README.html.
3342
3343 OPTIONAL: Configure mail filtering for the webmail server
3344
3345 This is an optional feature where the webmail server is used to
3346 automatically set up mail filtering rules to forward or deliver incoming
3347 mail to folders. This feature requires maildrop to be used as the local
3348 mail delivery agent.
3349
3350 Edit the courierd configuration file, and follow the instructions in that
3351 file to install maildrop as the local mail delivery agent. Then, follow
3352 the instruction below to create the maildirfilter configuration file,
3353 which may be installed either in the global configuration file directory
3354 (/usr/lib/courier/etc by default), or in each individual Maildir (which
3355 overrides the global default).
3356
3357 Implementing mail filtering requires a couple of dominos to fall in the
3358 right order. This is not difficult to do, but is a bit tricky. Here's how
3359 it works, in general. Specifics follow.
3360
3361 Some people would probably have a difficult time setting it up. That's to
3362 be expected. The implementation allows only selected accounts to be set up
3363 for mail filtering, so the suggested way is to attempt to set up mail
3364 filtering for one account only, test it to make sure it works, then roll
3365 it out globally.
3366
3367 The big picture
3368
3369 The maildrop mail filter is used to do the actual mail filtering. maildrop
3370 must be installed as your local mail delivery agent. The next thing to do
3371 is to actually learn how maildrop works, and learn its filtering language.
3372 Although the mail filter will be automaticaly generated here, you still
3373 need to become familiar with the filtering language in order to
3374 troubleshoot any installation problems. maildrop comes with manual pages
3375 documenting the filtering language, as well as some examples. Read them.
3376
3377 The little picture
3378
3379 Here's what's going to happen. The webmail server will automatically
3380 generate a maildrop filtering recipe. maildrop reads the recipe, and does
3381 its thing. Sounds simple enough, right?
3382
3383 Well, it's not. There are a few little details that need to be resolved.
3384
3385 For starters, the default maildrop filtering recipe is $HOME/.mailfilter.
3386 That's how things usually work physical system accounts are used. When
3387 virtual mailboxes are installed, things are less murky. There are several
3388 ways to set up virtual mailboxes, described elsewhere in this INSTALL
3389 file, so the actual implementation varies from system to system. Somehow,
3390 the virtual mailboxes share the same physical account, and have the same
3391 $HOME. In that case the usual approach is for each virtual mailbox to have
3392 the corresponding mail filtering recipe manually specified to maildrop as
3393 an extra command line argument. Review the maildrop documentation for more
3394 information.
3395
3396 Now, on the other hand, the webmail server doesn't really know anything
3397 about physical and virtual accounts. The mapping between a login ID and
3398 the maildir is completely encapsulated in the black box-type
3399 authentication library. The login ID and password are validated by the
3400 authentication library, which obtains the maildir corresponding to the
3401 login ID, and the webmail server is started for that maildir. Whether or
3402 not a login ID corresponds to an actual system account or to virtual
3403 account, that's something the webmail server doesn't really know, or care.
3404 All it cares about is the maildir where all the mail is, and that's the
3405 end of the story. (The IMAP and POP3 servers work the same way).
3406
3407 So, the issue is that the webmail server needs to find the corresponding
3408 maildrop filtering recipe, so it knows where to write the mail delivery
3409 instructions. That's the deal
3410
3411 In order for mail filtering to be enabled, it is necessary to initialize
3412 the file named maildirfilterconfig in the maildir itself. This is where
3413 the webmail server runs, so it simply reads this file. The contents of
3414 this file should be as follows:
3415
3416 MAILDIRFILTER=pathtomailfilter
3417 MAILDIR=pathtomaildir
3418
3419 pathtomailfilter specifies the location of the maildrop filtering recipe
3420 for this maildir, relative to the maildir itself. Set the current
3421 directory to the maildir directory. Now ask yourself, where's my maildrop
3422 filtering recipe?
3423
3424 In most cases, where virtual mailboxes are not used, everyone's maildir is
3425 $HOME/Maildir, and maildrop uses $HOME/.mailfilter by default. In this
3426 case, pathtomailfilter must be set to ../.mailfilter.
3427
3428 When virtual mail accounts are used, this will obviously be something
3429 else. The only requirement is that the maildrop filtering recipe and the
3430 maildir must be on the same filesystem or partition.
3431
3432 pathtomaildir is the other half of the story. When maildrop gets a message
3433 to deliver, maildrop needs to know where the mailboxes and folders are.
3434 Maildrop begins running in what it considers to be the recipient's home
3435 directory, reading either .mailfilter, by default, or the file specified
3436 on the command line.
3437
3438 The webmail server needs to generate filtering instruction that deliver
3439 messages to its maildir. By default, the maildir for non-virtual accounts
3440 is $HOME/Maildir, so pathtomaildir needs to be set to ./Maildir.
3441
3442 Summary for virtual accounts
3443
3444 Basically, 99% of the time MAILDIRFILTER will be ../.mailfilter and
3445 MAILDIR will be ./Maildir. When virtual mail accounts are used, maildrop
3446 still must be used as a mail delivery agent. Somehow, the correct maildir
3447 that corresponds to the recipient's mail account must be specified as the
3448 argument to maildrop. Usually all or most virtual accounts are set up
3449 inside a single physical account. In that case it is necessary to set up a
3450 different maildrop filtering recipe file for each virtual mail account
3451 (since everyone's $HOME/.mailfilter will be the same file), and in each
3452 maildir specify the relative path to its corresponding filtering recipe,
3453 and the relative path to the maildir from the default home directory.
3454 Then, for each virtual mail account, the mail server must run maildrop to
3455 do the actual mail delivery, explicitly specifying the filtering recipe to
3456 be used.
3457
3458 The global maildirfilterconfig file
3459
3460 In most cases where virtual mail accounts are not used, every maildir's
3461 maildirfilterconfig should be the same. As an alternative to installing
3462 the same maildirfilterconfig in each maildir, it is possible to install a
3463 single maildirfilterconfig systemwide.
3464
3465 Install the global maildirfilterconfig in the Courier mail server's
3466 configuration directory (/usr/lib/courier/etc by default).
3467
3468 The global maildirfilterconfig will be used unless maildirfilterconfig
3469 exists in the maildir directory. Therefore, the global maildirfilterconfig
3470 can be used to provide a default for the majority of the mail accounts,
3471 and any exceptions are handled by installing maildirfilterconfig in the
3472 maildir directory, whose contents will override the global file.
3473
3474 Happy filtering.
3475
3476 If everything is set up correctly, the webmail menu will present a new
3477 link to a screen where mail filtering rules are defined and installed. A
3478 mail filter consists of a condition, and an action. A condition is usually
3479 based on the contents of some header, or the message body. Regular
3480 expressions are allowed. Which means that certain special characters must
3481 be quoted. For example, to search for the string "[announce]" verbatim in
3482 the subject header, it must be entered as "\[announce\]". Pattern
3483 matching, for now, is case-insensitive. The regular expression syntax uses
3484 pretty much the same syntax as Perl. See the maildropfilter manual page
3485 for more information.
3486
3487 Multiple mail filtering rules can be installed. Their relative order can
3488 be rearranged by selecting a filtering rule, then selecting either the
3489 "Up" or the "Down" button. It is necessary to select "Save all changes"
3490 for any changes to the filtering rules to take effect. Leaving that page
3491 in any other way will throw away all changes made.
3492
3493 Webmail runtime configuration
3494
3495 There are some options which can be used to change the webmail server's
3496 behavior for individual accounts, or globally, using the "Account Options"
3497 feature in the Courier mail server Authentication library. The individual
3498 account's setting takes precedence over the DEFAULTOPTIONS settings in the
3499 authdaemonrc configuration, so for example if you want to disable webmail
3500 access for most accounts but enable it for a select few, you can set
3501 DEFAULTOPTIONS="disablewebmail=1" in the authdaemonrc configuration file,
3502 and add the option disablewebmail=0 to individual accounts. See the
3503 section "Account options" in README_authlib.html in the courier-authlib
3504 package for more information on setting the following account options:
3505
3506 disablewebmail - if set to a non-zero value, this account will not be
3507 permitted to login to webmail (e.g. because the user is only allowed to
3508 use POP3 or IMAP)
3509
3510 wbnochangingfrom - if set to a non-zero value, the webmail server will not
3511 allow the From: header to be changed, it will always have its default
3512 value.
3513
3514 wbnochangepass - if set to a non-zero value, the webmail server will not
3515 allow passwords to be changed. See "Changing mail account passwords using
3516 the webmail server", below, for more information.
3517
3518 wbusexsender - if set to a non-zero value, the webmail server will attach
3519 an X-Sender: header to all outgoing messages. This can be used in the
3520 event you would like to be able to modify the From: header, yet also be
3521 able to track sent mail to the original account.
3522
3523 wbnoimages - if set to a non-zero value then no images or icons will be
3524 used. The generated interface will be a text-only interface.
3525
3526 wbnodsn - set to a non-zero value then the option to request delivery
3527 confirmation receipts will not be shown.
3528
3529 OPTIONAL: Changing mail account passwords using the webmail server
3530
3531 After installing the webmail server be sure to test that the login
3532 password can be changed through the webmail server.
3533
3534 If you do not want to use the password change function you can also remove
3535 the sqwebpasswd program. This is a helper program, installed with the
3536 set-groupid bit set, that relays the password change request to the
3537 authentication daemon, through the filesystem socket that is not globally
3538 accessible. The password change request consists of the account name, the
3539 old password, and the new password. The password change request is
3540 validated by the authentication daemon, and the old password must match
3541 the existing password on the account, before the password change goes
3542 through. This set-groupid helper program is safe to use.
3543
3544 OPTIONAL: Configure autoreplies for the webmail server
3545
3546 Enabling mail filtering, according to the instructions in the previous
3547 section, automatically enables MIME autoreply capability. The webmail
3548 interface can be used to configure simple autoresponders. By default there
3549 is no limit on the number of the size of created autoreplies, therefore it
3550 is recommended that a quota be set up on the autoreplies.
3551
3552 An global autoreply quota is set up by initializing the
3553 /usr/lib/courier/etc/autoresponsesquota configuration file. This file sets
3554 the autoreply quota globally. An autoresponsesquota file in the Maildir
3555 will override the global quota setting for that maildir only. See the
3556 courier(8) manual page for the description of the autoresponsesquota file.
3557
3558 Autoreplies can include any valid MIME content (MIME content other than
3559 plain text can be uploaded). The following special procedure needs to be
3560 used to prepare multipart autoreply content, such as text and html
3561 alternatives of the same message:
3562
3563 Assign a filename extension to the message/rfc822 MIME content. For
3564 example, edit your mime.types file, find the message/rfc822 MIME type
3565 (append one if it's not in mime.types), and make sure that it has at least
3566 one filename extension, such as "msg".
3567
3568 Prepare the multipart MIME autoreply. The most convenient way is to
3569 prepare a normal E-mail message using a conventional E-mail client. Save
3570 the RFC822-formatted message in a file with a ".msg" extension, and upload
3571 it on the autoreply screen.
3572
3573 Webmail handles uploaded message/rfc822 content by removing all headers
3574 except the MIME headers, leaving the MIME content type header, and the
3575 actual MIME content.
3576
3577 Normally there is no limit on the number or the total size of autoreplies
3578 configured via the webmail server. A quota can be installed by
3579 initializing the autoresponsesquota configuration file. See courier(8) for
3580 more information.
3581
3582 OPTIONAL: Configure encryption for the webmail server
3583
3584 This is an optional feature in the webmail server that uses GnuPG to send
3585 and receive encrypted/signed E-mail. There is no encryption code in the
3586 webmail server, it uses GnuPG to do encryption and decryption. For more
3587 information on setting up and using encryption, read the file
3588 gpglib/README.html in the source distribution.
3589
3590 OPTIONAL: Install automatically-appended footer text for webmail messages
3591
3592 /usr/lib/courier/share/sqwebmail/html/LANG/footer - if this file exists,
3593 its contents will be appended to the end of every sent message from the
3594 webmail server. The actual directory where sqwebmail's html language files
3595 are installed may be different with prebuilt Courier packages. LANG is the
3596 language code here, there can be a separate footer per installed language.
3597 The footer file carries the following requirements:
3598
3599 • The footer file must be coded in UTF-8.
3600
3601 • The footer file must follow the format=flowed; delsp=yes format, as
3602 specified by RFC 3676. Capsule summary:
3603
3604 • Paragraphs are delimited by blank lines.
3605
3606 • Paragraphs that consist of more than one line must have a
3607 trailing space ending each line except the last line in the
3608 paragraph.
3609
3610 • That trailing space is in addition to a space that delimits
3611 individual words in most Western languages. Therefore, a line
3612 that ends on a word without punctuation and continues with the
3613 next word at the beginning of the next line must end with two
3614 spaces: the usual space that separates individual words, and a
3615 second space that indicates that the paragraph continues on the
3616 next line.
3617
3618 • Restated: a line that ends with a space is logically joined with
3619 the next line, after the trailing space is logically removed.
3620
3621 • Lines that begin with a space character or the ">" character must
3622 have an additional space character prepended to them. This
3623 leading space character is logically removed from the contents of
3624 the line.
3625
3626 A convenient way to format text in flowed format is to use the leaf
3627 editor that's part of the Cone package.
3628
3629 • Signature content gets formatted as part of the message together with
3630 the rest of the content. Sender-selected option to format the message
3631 as either a plain text message, or using wiki-style HTML markup
3632 applies to the footer file too. The footer file's contents should be
3633 constructed taking into account the possibility that wiki-style HTML
3634 markup may get optionally applied to the footer content.
3635
3636 OPTIONAL: Quota support
3637
3638 There are two ways to implement a quota on the size of a mail account:
3639 filesystem quotas and maildir quotas:
3640
3641 Filesystem quotas
3642
3643 The maximum disk space quota is implemented within the operating system's
3644 filesystem support code. Here, the operating system enforces the maximum
3645 disk space that can be used by each account. This is the only reliable
3646 quota implementation if individual accounts have login access to the mail
3647 account. Maildir quotas (see below) are implemented entirely within the
3648 maildir support code, and can easily be superceeded by anyone with login
3649 access to the mail account. Additionally, mail accounts must all be system
3650 accounts. Virtual accounts -- that share the same physical system userid
3651 -- cannot usually be support by filesystem-based quotas, because all mail
3652 accounts have the same userid and groupid.
3653
3654 The webmail server cannot be used with filesystem quotas. The webmail
3655 server creates and maintains, all by itself, a number of database files
3656 that are used to quickly index and access messages. If an account exceeds
3657 its disk quota, the webmail server will not be able to create and update
3658 those database file, which results in a rather spectacular crash. If login
3659 access is available, it is possible to log in and manually delete some
3660 files to reclaim some disk space. If login access is not available, the
3661 administrator will have to manually fix the account -- the webmail server
3662 will not even be able to open an existing folder and delete messages in
3663 order to free up disk space. There is some good news, though: the IMAP and
3664 the POP3 server can still be used to access and delete messages from the
3665 mail account. Due to the way that out-of-quota condition is handled by the
3666 IMAP server, some IMAP clients may mark any existing messages in the
3667 account as unread, but that is a minor glitch that does no harm.
3668
3669 Maildir quotas
3670
3671 The Courier mail server can manually enforce a quota for mail accounts
3672 that use maildirs. This quota enforcement is implemented entirely in
3673 software, and is available only when maildirs are used. This quota
3674 implementation will also work with virtual accounts. Maildir quota support
3675 is available only with userdb, LDAP, MySQL and PostgreSQL authentication
3676 back-ends. Maildir quotas are supported by IMAP, POP3, and the webmail
3677 server. To add a maildir quota with userdb, run the following commands,
3678 for example:
3679
3680 userdb account set quota=quota
3681 makeuserdb
3682
3683 Here, account identifies the account to which the quota applies, and quota
3684 is the quota specification, as described in the maildirquota(7) manual
3685 page.
3686
3687 To implement a quota with an LDAP, MySQL, or a PostgreSQL back end, simply
3688 follow the instructions given in the corresponding configuration file.
3689
3690 Account OPTIONS
3691
3692 It is possible to adjust certain parameters on an account-by-account
3693 basis. This feature is actually implemented in the Courier mail server
3694 Authentication Library. See ACCOUNT OPTIONSin the auth_generic manual
3695 page.
3696
3697 OPTIONAL: Configure outbound faxing
3698
3699 Fax sending is disabled by default and must be explicitly enabled,
3700 according to the following instructions. After fax sending is enabled,
3701 addressing an E-mail message to <5552000@fax> will have this message
3702 faxed.
3703
3704 Of course, the necessary hardware and software must be available. The
3705 requisite hardware is a class 2 faxmodem attached to a serial port.
3706 Additional software, separate from the Courier mail server, must also be
3707 installed. The Courier mail server does not handle the actual job of
3708 faxing. The Courier mail server only reformats E-mail messages as fax
3709 images, and runs mgetty+sendfax to send the fax. The Courier mail server
3710 also needs additional software to convert E-mail messages to faxes. All
3711 additional software must be separately installed, configured, and tested
3712 before enabling faxing in the Courier mail server. Most systems already
3713 include the following software as part of the base operating system, so in
3714 most cases adding fax support will not actually require any additional
3715 software to be installed, only minor reconfiguration of existing software:
3716
3717 mgetty+sendfax
3718
3719 mgetty+sendfax works with most Class 2 faxmodems. The Courier mail server
3720 does not use the spooling scripts found in the mgetty+sendfax package. The
3721 Courier mail server uses its own mail spool. A fax message is handled no
3722 differently than any other E-mail message. The only difference is that the
3723 E-mail message is addressed to <phonenumber@fax>.
3724
3725 mgetty+sendfax should be configured with its default settings, EXCEPT as
3726 follows:
3727
3728 • In /etc/mgetty+sendfax, the "max-tries-continue" setting must be set
3729 to "n".
3730
3731 groff or troff, ghostscript, NetPBM
3732
3733 Conversion of E-mail messages to faxes uses ghostscript, and groff. It
3734 should be possible to use the original UNIX troff instead of groff, but
3735 this has not been tested. The Courier mail server generates the fax cover
3736 page from the contents of the E-mail message's headers. The initial text
3737 portion of the E-mail message will appear as fax cover page comments. Note
3738 that the initial text portion of the E-mail message must be in plain text,
3739 not HTML. E-mail attachments will be converted and attached as additional
3740 fax pages. E-mail attachments may contain plain text, Postscript or PDF
3741 documents. Other attachments will result in the E-mail message being
3742 returned as undeliverable.
3743
3744 On the cover page, the sender's name, the recipient's name, and the fax
3745 subject gets taken from the E-mail message's headers. The ability to use
3746 non-Latin characters depends on the support from the underlying tools,
3747 ghostscript and groff, for the default system locale.
3748
3749 Install the NetPBM library to add the ability to fax GIF, JPEG, and PNG
3750 images. Each image will be converted to a single fax page. Images in
3751 excess of 1500x1500 pixels (approximately) will be truncated, and color
3752 images will be dithered to black-and-white.
3753
3754 Enabling faxing
3755
3756 The configuration file /usr/lib/courier/etc/faxrc must be edited in order
3757 to enable faxing. This file sets up the dialing parameters, and the
3758 default file disables faxing by rejecting all phone numbers. The
3759 configuration file has extensive comments that explain how dialing
3760 parameters are set.
3761
3762 Using webadmin to set up fax sending is highly recommended. A proper faxrc
3763 will automatically hide all the local daling conventions. Webadmin knows
3764 how to generate the dialing configuration for the North American dialing
3765 plan, with a configurable area code. Faxes should be addressed to a fixed
3766 ten digit area code+phone number address, <nnnxxxxxxx@fax>, which will be
3767 converted for dialing from the local area code appropriately. Webadmin can
3768 also optionally enable faxing to international 011 phone numbers. Webadmin
3769 can also fall back to a bare configuration where all phone numbers are
3770 dialed as-is, for locations outside of North America.
3771
3772 Sending faxes
3773
3774 E-mail messages may contain attachments. The Courier mail server combines
3775 all attachments in the message into a single fax transmission. Attachment
3776 types may be freely mixed. A single message may contain one plain text,
3777 and one PDF attachment, for example. It is possible to select certain
3778 options, as follows:
3779
3780 • <phonenumber@fax-lowres>
3781
3782 sends a low-resolution fax.
3783
3784 • <phonenumber@fax-ignore>
3785
3786 Ignore attachments that the Courier mail server doesn't know how to
3787 convert to a FAX image format. Normally, if an attachment cannot be
3788 converted the whole message is returned as undeliverable.
3789
3790 • <phonenumber@fax-cover>
3791
3792 sends only the cover page. This can be useful for .courier files. See
3793 the courierfax(8) manual page for an example.
3794
3795 These options can be combined: <phonenumber>@fax-lowres-ignore>.
3796
3797 Cover pages
3798
3799 /usr/lib/courier/etc/faxcoverpage.tr is the troff source for the FAX cover
3800 page, which includes the first plain text section of the E-mail message.
3801 Do not attempt to play with faxcoverpage.tr without a clear understanding
3802 of troff. It is safe to make trivial changes (such as replacing the
3803 "FACSIMILE COVER PAGE" text).
3804
3805 Dialing
3806
3807 The /usr/lib/courier/etc/faxrc configuration file provides rudimentary
3808 phone number rewriting logic (stuff like dialing "9," to get outside line
3809 from a PBX). The default faxrc configuration file specifies a typical
3810 dialing configuration for the North American numbering plan, with seven
3811 digit local phone numbers, and 1+ten digit long distance phone numbers.
3812 The area code in the default faxrc configuration file is set to "999", you
3813 will need to change it to your area code (there are two places in faxrc
3814 where the area code needs to be set).
3815
3816 In general, messages should be addressed to the full ten-digit phone
3817 numbers. The local area code will be stripped automatically, and "1" will
3818 be dialed before all other area codes. If this is done in practice, local
3819 area code changes will only require an update to faxrc, without any need
3820 to update the address book.
3821
3822 Comments in the faxrc configuration file explain the format of the phone
3823 number rewriting rules, in the event that local phone system customization
3824 is required (for example, dialing 9 to get an outside line). Several
3825 places in North America now use ten digit local phone number overlays,
3826 with 1+ten digit long distance dialing. TODO: Use webadmin if you are not
3827 sure how to set this up.
3828
3829 Security
3830
3831 The default faxrc configuration file allows only locally-generated faxes.
3832 faxrc must be modified in order to accept faxes via ESMTP.
3833
3834 Additionally, faxes are accepted via ESMTP only if the FAXRELAYCLIENT
3835 variable is set. See the makesmtpaccess(8) man page for additional
3836 information.
3837
3838 OPTIONAL: Configure inbound faxing
3839
3840 mgetty has an option that runs a script called "new_fax" after it receives
3841 a fax. The default location for this script is either
3842 /usr/local/lib/etc/mgetty+sendfax/new_fax or /etc/mgetty+sendfax/new_fax.
3843 Consult your mgetty documentation to determine if the new_fax option is
3844 enabled, and the exact script location.
3845
3846 The Courier mail server provides a script -
3847 /usr/lib/courier/share/faxmail/new_fax - that can be used as mgetty's
3848 new_fax script. This script converts incoming faxes to PNG images, and
3849 delivers it to a local mailbox. Simply copy this script to mgetty's etc
3850 directory (or install a soft link there), to automatically drop incoming
3851 faxes to a local mailboxes.
3852
3853 The /usr/lib/courier/etc/faxnotifyrc configuration file specifies the
3854 mailbox that receives incoming faxes, and several other related options.
3855
3856 OPTIONAL: Install the Courier mail server log analyzer
3857
3858 The Courier mail server log analyzer (the courier-analog package) is a
3859 Perl script that generates log summaries for the Courier mail server. The
3860 Courier mail server log analyzer generates log summaries for incoming and
3861 outgoing SMTP connections, and IMAP and POP3 activity. courier-analog can
3862 generate output in text or HTML format.
3863
3864 The Courier log analyzer is not included in the main the Courier mail
3865 server tarball, it must be downloaded separately from
3866 http://www.courier-mta.org/download.html#analog. After downloading and
3867 installing this package, see the courier-analog manual page for more
3868 information.
3869
3870 OPTIONAL: Configure Courier IP address-specific settings for servers with
3871 multiple IP addresses
3872
3873 When running Courier on a server that has more than one IP address, it's
3874 possible to configure Courier to have a "vanity" configuration for each IP
3875 address, such as the IP address for outgoing connections for relaying
3876 messages received by a client that connects to each address, or its server
3877 name that it uses in the "Received:" headers that Courier adds to each
3878 message.
3879
3880 See the "Servers with multiple IP addresses" section in the courier(8)
3881 manual page for more information.
3882
3883 OPTIONAL: configure hostname-dependent configuration
3884
3885 Several Courier configuration files specify settings that reference the
3886 server's fully-qualified domain name. It is possible to have a fixed set
3887 of configuration files with the key configuration files using a wildcard
3888 placeholder for the system hostname, and replicate these configuration
3889 files to multiple servers with externally- assigned hostname (and likely
3890 IP addresses), such as DHCP-provided ones; with the server's hostname
3891 referenced by the relevant placeholders.
3892
3893 Example: replicate the same set of configuration files to servers assigned
3894 hostnames of "mx1" and "mx2", via DHCP, with Courier recognizing its
3895 fully-qualified domain name as "mx1.example.com" and "mx2.example.com",
3896 respectively.
3897
3898 See the "Hostname-dependent configuration" section of the courier(8)
3899 manual page for more information.
3900
3901 Decommission your existing mail server
3902
3903 This step consists of flushing the mail queue of your existing mail server
3904 and removing it from the system.
3905
3906 If you're using sendmail, edit your startup script, and start sendmail
3907 with the option '-q30m' only. Remove the -bd option. This causes sendmail
3908 to stop listening on port 25, and stay as a daemon process only for the
3909 purpose of running the queue every 30 minutes.
3910
3911 If you're using Qmail, remove tcpserver from your system startup script.
3912
3913 Wait for all existing mail to flush itself out, then permanently remove
3914 your existing server.
3915
3916 Depending on your system, you may need to create a bunch of soft links,
3917 such as /usr/bin/sendmail, /usr/sbin/sendmail, /lib/sendmail, or
3918 /etc/sendmail that point to /usr/lib/courier/bin/sendmail. If you want to
3919 receive mail via UUCP you will also need to make sure that UUCP knows to
3920 find rmail in /usr/lib/courier/bin as well.
3921
3922 Sample init script
3923
3924 You're now ready to configure your system to start the Courier mail server
3925 at system boot time (and shut it down at system shutdown). If your system
3926 uses system-V init scripts, here's a sample script that you can install in
3927 your /etc/rc?.ddirectories. This is a slightly modified version of the
3928 init script that's used in the Courier RPM or DEB package
3929 (courier.sysvinit file in the source code tarball).
3930
3931 NOTE: the following script may take a long time to finish, the very first
3932 time it runs. That's because the script automatically creates test SSL
3933 certificates the first time the script runs (provided that SSL support is
3934 available). This can take as much as 5-6 minutes on a slow machine.
3935 Subsequent starts should take only a few seconds.
3936
3937 #! /bin/sh
3938 #
3939 # chkconfig: 2345 35 65
3940 # description: Courier - SMTP server
3941 #
3942 # NOTE: The 'restart' here does a "hard" stop, and a start. Be gentle, use
3943 # "courierd restart" for a kindler, gentler, restart.
3944 #
3945 #
3946
3947 prefix="/usr/lib/courier"
3948 exec_prefix="/usr/lib/courier"
3949 sysconfdir="/usr/lib/courier/etc"
3950 sbindir="${exec_prefix}/sbin"
3951 libexecdir="/usr/lib/courier/libexec"
3952 datadir="/usr/lib/courier/share"
3953
3954 case "$1" in
3955 start)
3956 cd /
3957 # Start daemons.
3958 touch /var/lock/subsys/courier
3959
3960 echo -n "Starting the Courier mail server:"
3961
3962 # Use default DH parameter file, if it does not exist.
3963
3964 if test ! -f ${datadir}/dhparams.pem
3965 then
3966 ln ${datadir}/dhparams.pem.dist ${datadir}/dhparams.pem
3967 fi
3968
3969 # First time after install create aliases.dat and makesmtpaccess.dat
3970
3971 test -f ${sysconfdir}/aliases.dat || ${sbindir}/makealiases
3972
3973 esmtpdcert=0
3974
3975 . ${sysconfdir}/esmtpd
3976 case x$ESMTPDSTART in
3977 x[yY]*)
3978 esmtpdcert=1
3979 ;;
3980 esac
3981
3982 test -f ${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess
3983
3984 . ${sysconfdir}/esmtpd-msa
3985 case x$ESMTPDSTART in
3986 x[yY]*)
3987 esmtpdcert=1
3988 ;;
3989 esac
3990
3991 test -f ${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess-msa
3992
3993 ${sbindir}/courierfilter start
3994 echo -n " courierfilter"
3995
3996 if test -x ${sbindir}/courierldapaliasd
3997 then
3998 ${sbindir}/courierldapaliasd start
3999 echo -n " courierldapaliasd"
4000 fi
4001
4002 if test -f ${libexecdir}/courier/sqwebmaild
4003 then
4004 ${sbindir}/webmaild start
4005 echo -n " webmail"
4006 fi
4007
4008 ${sbindir}/courier start
4009 echo -n " courierd"
4010
4011 if test "$esmtpdcert" = 1
4012 then
4013 # If we do not have a certificate, make one up.
4014
4015 if test ! -f ${datadir}/esmtpd.pem
4016 then
4017 if test -x $COURIERTLS
4018 then
4019 echo -n " generating-ESMTP-SSL-certificate..."
4020 ${sbindir}/mkesmtpdcert >/dev/null 2>&1
4021 fi
4022 fi
4023 fi
4024
4025 . ${sysconfdir}/esmtpd
4026 case x$ESMTPDSTART in
4027 x[yY]*)
4028
4029 ${sbindir}/esmtpd start
4030 echo -n " esmtpd"
4031 ;;
4032 esac
4033
4034 . ${sysconfdir}/esmtpd-msa
4035 case x$ESMTPDSTART in
4036 x[yY]*)
4037
4038 ${sbindir}/esmtpd-msa start
4039 echo -n " esmtpd-msa"
4040 ;;
4041 esac
4042
4043 if test -x ${sbindir}/pop3d
4044 then
4045 POP3DSTART=""
4046 POP3DSSLSTART=""
4047
4048 if test -f ${sysconfdir}/pop3d
4049 then
4050 . ${sysconfdir}/pop3d
4051 fi
4052 case x$POP3DSTART in
4053 x[yY]*)
4054 ${sbindir}/pop3d start
4055 echo -n " pop3d"
4056 ;;
4057 esac
4058 if test -f ${sysconfdir}/pop3d-ssl
4059 then
4060 . ${sysconfdir}/pop3d-ssl
4061 fi
4062 case x$POP3DSSLSTART in
4063 x[yY]*)
4064 if test -x $COURIERTLS
4065 then
4066 # If we do not have a certificate, make one up.
4067
4068 if test ! -f ${datadir}/pop3d.pem
4069 then
4070 echo -n " generating-POP3-SSL-certificate..."
4071
4072 ${sbindir}/mkpop3dcert >/dev/null 2>&1
4073 fi
4074
4075 ${sbindir}/pop3d-ssl start && \
4076 echo -n " pop3d-ssl"
4077 fi
4078 ;;
4079 esac
4080 fi
4081
4082 if test -x ${sbindir}/imapd
4083 then
4084 . ${sysconfdir}/imapd
4085 case x$IMAPDSTART in
4086 x[yY]*)
4087 ${sbindir}/imapd start
4088 echo -n " imapd"
4089 ;;
4090 esac
4091 . ${sysconfdir}/imapd-ssl
4092 case x$IMAPDSSLSTART in
4093 x[yY]*)
4094 if test -x $COURIERTLS
4095 then
4096 # If we do not have a certificate, make one up.
4097
4098 if test ! -f ${datadir}/imapd.pem
4099 then
4100 echo -n " generating-IMAP-SSL-certificate..."
4101
4102 ${sbindir}/mkimapdcert >/dev/null 2>&1
4103 fi
4104
4105 ${sbindir}/imapd-ssl start && \
4106 echo -n " imapd-ssl"
4107 fi
4108 ;;
4109 esac
4110 fi
4111
4112 if test -x ${bindir}/webmlmd
4113 then
4114 . ${sysconfdir}/webmlmrc
4115 if test "$LISTS" != ""
4116 then
4117 ${bindir}/webmlmd start ${sysconfdir}/webmlmrc && \
4118 echo -n " webmlmd"
4119 fi
4120 fi
4121
4122 echo ""
4123 ;;
4124 stop)
4125 echo -n "Stopping the Courier mail server:"
4126
4127 if test -x ${bindir}/webmlmd
4128 then
4129 ${bindir}/webmlmd stop ${sysconfdir}/webmlmrc
4130 echo -n " webmlmd"
4131 fi
4132
4133 if test -x ${sbindir}/imapd
4134 then
4135 ${sbindir}/imapd stop
4136 echo -n " imapd"
4137 fi
4138
4139 if test -x ${sbindir}/imapd-ssl
4140 then
4141 ${sbindir}/imapd-ssl stop
4142 echo -n " imapd-ssl"
4143 fi
4144
4145 ${sbindir}/esmtpd-msa stop
4146 echo -n " esmtpd-msa"
4147
4148 ${sbindir}/esmtpd stop
4149 echo -n " esmtpd"
4150
4151 if test -x ${sbindir}/pop3d
4152 then
4153 ${sbindir}/pop3d stop
4154 echo -n " pop3d"
4155 fi
4156
4157 if test -x ${sbindir}/pop3d-ssl
4158 then
4159 ${sbindir}/pop3d-ssl stop
4160 echo -n " pop3d-ssl"
4161 fi
4162
4163 ${sbindir}/courier stop
4164 echo -n " courierd"
4165
4166 if test -f ${libexecdir}/courier/sqwebmaild
4167 then
4168 ${sbindir}/webmaild stop
4169 echo -n " webmail"
4170 fi
4171
4172 if test -x ${sbindir}/courierldapaliasd
4173 then
4174 ${sbindir}/courierldapaliasd stop
4175 echo -n " courierldapaliasd"
4176 fi
4177
4178 ${sbindir}/courierfilter stop
4179 echo " courierfilter"
4180 ;;
4181 restart)
4182 $0 stop
4183 $0 start
4184 ;;
4185 esac
4186 exit 0
4187
4188 The reason I test for the existence of the POP3 and IMAP server binaries
4189 is because I build the POP3 and IMAP servers as separate sub-packages,
4190 that do not have to be installed. These tests avoid the need for each
4191 sub-package to install its own startup script.