File: INSTALL

package info (click to toggle)
courier 0.76.3-5%2Bdeb9u1
  • links: PTS
  • area: main
  • in suites: stretch
  • size: 47,400 kB
  • sloc: ansic: 122,873; cpp: 23,863; sh: 8,790; perl: 4,127; makefile: 3,082; sed: 16
file content (3999 lines) | stat: -rw-r--r-- 193,181 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
   NOTE: a more readable HTML version of this INSTALL document can be found
   in courier/doc/install.html.

                                  Installation

   --------------------------------------------------------------------------

     NOTE:

     This documentation describes manual installation of the Courier mail
     server. This is a somewhat involved process that may overwhelm people
     that do not have prior experience with installing large software
     packages. Many Linux-based distributions and BSD-family systems have
     separately-maintained, preconfigured, ready-to-install packages that can
     be loaded with much less investment of time. Installing a pre-built
     package would probably be the best approach in this case.

     Should you choose to install a platform-specific prebuilt package, you
     should carefully read any custom documentation files that are included
     in the package. Most platform-specific packages provide custom,
     non-default configuration settings that are optimized for that platform
     unique needs and requirements. Feedback about platform-specific
     precompiled packages should be copied to the development group that
     maintains the package, in additional to the platform-neutral
     courier-users mailing list. They will appreciate the feedback, and take
     it into consideration when preparing the next revision of the
     platform-specific package.

   --------------------------------------------------------------------------

   Read this document in its entirety before entering a single command.
   Installing the Courier mail server for the first time will take a while.
   If possible, consider looking around for anyone who has already packaged
   the Courier mail server for your operating system, and save yourself the
   hassle.

   Fortunately, it gets easier with each subsequent installation. The Courier
   mail server is a complicated piece of software. Most problems people will
   have are likely to be with the configuring and installing it correctly.
   Designing complex software that compiles and installs on a wide variety of
   POSIX systems is not a trivial task.

   The Courier mail server's configuration and installation scripts are very
   flexible in setting up installation directories for each logical set of
   files - configuration files, binaries, scripts, the mail queue, and more.
   If you begin by installing someone else's package, instead of installing
   everything yourself, you should take careful notes where things are
   installed. If you later decide to roll your own package, you will either
   need to use a COMPLETELY IDENTICAL configuration, or take care to back up
   your old configuration, and then restore it after the upgrade. The
   following documentation refers to the default location of various
   configuration files (and other files as well). If you choose to install
   some files in a non-default location (either by yourself, or by using
   someone else's package), you will need to take this into account while
   reading the following documentation.

   This cannot be emphasized enough: the configuration defaults are very
   generic; the goal is to have the default configuration settings work for
   almost everyone. In every case using at least a couple of non-default
   parameters will make the Courier mail server work better on your system.
   You should anticipate going through several trial-and-error installs,
   tweaking the options to see what works better for you. Even my own
   pre-configured RPM package uses a number of non-default parameters.

   NOTE: older versions of the linuxconf configuration tool are hardwired for
   sendmail. They like to change the permission of the sendmail wrapper to
   match the permissions they think the real sendmail should have. Older
   versions of linuxconf also have a tendency to create the /var/spool/mqueue
   directory, even if sendmail is not installed.

Table Of Contents

   The following table of contents might look intimidating at first, but some
   sections are marked "optional". These sections are not required for a
   basic installation as a simple ESMTP server.

     * Upgrading an existing installation
     * Overview
     * Preparing for installation
     * OPTIONAL: Install the Socks 5 client toolkit
     * Run configure
     * IPv6
     * Compile and run make check
     * Installation
     * Install configuration files
     * Adjust system paranoia level
     * Post-installation setup
     * Post-installation checks
     * OPTIONAL: Configure webadmin
     * Create system aliases
     * Create smtp access list
     * Backscatter suppression
     * Miscellaneous configuration
     * Define local domains
     * OPTIONAL: Configure UUCP
     * OPTIONAL: Configure LDAP aliasing
     * OPTIONAL: Configure filtering
     * Create a list of domains to accept mail for
     * Starting and stopping the Courier mail server
     * Run the Courier mail server in parallel to your mail server
     * OPTIONAL: Configure ESMTP authentication and SSL
     * OPTIONAL: Configure ESMTP smarthosting
     * OPTIONAL: Configure the SECURITY ESMTP extension
     * OPTIONAL: Configure the Sender Policy Framework
     * OPTIONAL: Configure the IMAP server
     * OPTIONAL: Configure IMAP shared folders
     * OPTIONAL: Configure IMAP over SSL
     * OPTIONAL: Certificate Authentication
     * OPTIONAL: Sending mail via an IMAP connection
     * OPTIONAL: Configure IMAP realtime folder status updates
     * OPTIONAL: Configure SMAP
     * OPTIONAL: Configure the POP3 server
     * OPTIONAL: Configure POP3 over SSL
     * OPTIONAL: Configure the IMAP/POP3 aggregator proxy
     * OPTIONAL: Configure the webmail server
     * OPTIONAL: Configure webmail calendaring
     * OPTIONAL: Configure mail filtering for the webmail server
     * OPTIONAL: Changing mail account passwords using the webmail server
     * OPTIONAL: Configure autoreplies for the webmail server
     * OPTIONAL: Configure encryption for the webmail server
     * OPTIONAL: Install automatically-appended footer text for webmail
       messages
     * OPTIONAL: Quota support
     * OPTIONAL: Account OPTIONS
     * OPTIONAL: Configure outbound faxing
     * OPTIONAL: Configure inbound faxing
     * OPTIONAL: Install the Courier mail server log analyzer
     * OPTIONAL: Configure Courier IP address-specific settings for servers
       with multiple IP addresses
     * Decommission your existing mail server
     * Sample init script

Upgrading an existing installation

  Upgrading from the Courier mail server 0.73.1, or earlier

   The unicode library in Courier is now a separate package. Download the
   Courier Unicode Library before updating to 0.74, or later.

  Upgrading from the Courier mail server 0.72, or earlier

   Version 0.73 removes the TLS_DHCERTFILE parameter from esmtpd, esmtpd-ssl,
   imap, and pop3d configuration files. DH parameters, and DH parameters
   only, get read from the new TLS_DHPARAMS file (and the other functionaly
   of TLS_DHCERTFILE, for DSA certificates, is merged into TLS_CERTFILE).
   After upgrading, run the mkdhparams script to create a new TLS_DHPARAMS
   file.

  Upgrading from the Courier mail server 0.66.3, or earlier

   In 0.67, the IMAP server resets the epoch for an internal sequence number
   generator for new mailboxes. This is an internal attribute of individual
   IMAP folders, that's defined by the IMAP specification. Each folder in a
   mailbox carries an individual sequence number, it is defined as a 32 bit
   integer value, and required to be a monotonically increasing value. and
   RFC 2060 recommended that "... a good value to use for the unique
   identifier validity value is a 32-bit representation of the creation
   date/time of the mailbox."

   On modern platforms, the system time is now a 64 bit value (even on the
   remaining 32 bit platforms). With Y2038K on the horizon, it's time to
   reset the epoch (the new epoch, for anyone who cares, runs until the year
   2069). The upgrade impact on existing systems is as follows.

   There is no impact on existing folders in existing mailboxes. New folders
   will have their internal sequence number in the new epoch.

   One potential issue exists if a folder gets deleted by the IMAP client,
   and then recreated later. The new folder will now get a lower sequence
   number. Although this is technically not allowed, it's unlikely to cause
   problems with most IMAP clients. If the same IMAP client deletes and
   recreated the mailbox, the client should be completely up to speed. If,
   however, there's an IMAP client that accesses the same folder, and some
   other IMAP client deletes and recreates the same folder, this might cause
   confusion. Most IMAP clients are likely to recover automatically; most
   IMAP clients only care that the new sequence number they see is different
   from the previous one, in order to trigger a full resynchronization with
   the server. In case an IMAP client fails to resynchronize, the remedy is
   to remove the IMAP account configuration from the client, and add it back
   in.

   Copying a mailbox by directly copying the files in maildirs preserves each
   folder's epoch. However if a mailbox gets migrated by copying its contents
   over IMAP, the folders on the destination IMAP server will not necessarily
   have a monotonically higher value -- neither does IMAP guarantee that
   different IMAP servers must be in agreement with each other on the subject
   of sequence numbers -- and if IMAP clients are repointed to a new server
   they may experience problems opening existing mailboxes. To remedy this
   situation it will be necessary to completely remove and then reconfigure
   the IMAP account, in the IMAP client. Again, verbatim copying of maildirs
   has no issues.

   A marginal situation exists where if a server completely runs of disk
   space, or if there's a hardware failure, and the IMAP server is unable to
   retrieve or save an existing folder's sequence number, and must now start
   afresh and generate a new one, the IMAP server running on a new epoch will
   recover with a lower sequence than the one that existed before. The
   rememdy is the same: remove the IMAP account configuration from the
   client, and then recreate it.

  Upgrading from the Courier mail server 0.63.0, or earlier

   There's a new setting, SYSLOCALE, in the courierd configuration file,
   which initializes the environment from the default system locale. The
   configuration script heuristically searches for a list of known locale
   initialization scripts on various platforms, if found.

   If your platform's locale configuration script's name is not known to the
   configuration script, manually specify your default system locale in this
   configuration setting.

  Upgrading from the Courier mail server 0.55.1, or earlier

   The webmlmd tool has been significantly enhanced, with a new
   administration screen that consists of three new template files:
   style.css.tmpl, webmlmlistadmin.tmpl.html, and
   webmlmlistadminpw.html.html. These three template files must be installed
   in each mailing list directory. You may copy them manually, or use the
   couriermlm update command. couriermlm update overwrites all your
   list-specific customizations, so make backups first!

  Upgrading from the Courier mail server 0.54.2, or earlier

   The logic for outbound authenticated SMTP has changed. This is when the
   Courier mail server sends outbound mail through a smarthost that requires
   authentication.

   The specified smarthost's name is still looked up in DNS, as before. When
   smtp.example.com is specified as the smarthost's name, The Courier mail
   server looks up any MX or A records for smtp.example.com. A connection
   gets established to a server whose name may be different than the original
   DNS hostname, if it gets redirected via an MX or a CNAME record.

   In earlier versions of the Courier mail server, the smarthost's userid and
   password must be listed using the resulting server's physical, resolved
   name. Starting with version 0.55, the smarthost's original DNS name must
   be listed instead. In all cases now, the name of the server listed in
   esmtpauthclient will now match the name specified in esmtproutes.

   After updating to 0.55, the contents of the esmtpauthclient configuration
   file may need updating.

   IMPORTANT: After updating to 0.55, all existing couriermlm mailing list
   directories must be updated with new configuration files. See the "update"
   command in the "MANUAL COMMANDS" section of the couriermlm(1) manual page.
   If you run many mailing lists, you are strongly advised to install the new
   version of the Courier mail server on another machine and become
   re-acquainted with couriermlm's configuration. In an emergency, make a
   backup copy of the couriermlm command from your existing version of the
   Courier mail server, before installing this update.

  Upgrading from the Courier mail server 0.51, or earlier

   Version 2.0 of maildrop, in the Courier mail server 0.52, introduces a new
   pattern matching engine that uses the PCRE library, that uses a completely
   different syntax. However, very few changes should be required to upgrade
   existing maildrop recipes to the new syntax.

   After upgrading from the Courier mail server 0.51, or earlier, review the
   maildropfilter manual page which has been revised to document the new
   pattern matching syntax. The legacy pattern matching engine is still
   available by setting MAILDROP_OLD_REGEXP to 1. See also the "Conversion of
   maildrop 1.x pattern to 2.0" section in the manual page, for more
   information.

  Upgrading from the Courier mail server 0.49.0, or earlier

   couriermlm's default configuration now treats both the userid and the
   domain portion of E-mail addresses as case-insensitive.

   Any existing mailing list that has subscribers whose E-mail addresses
   contain uppercase addresses must explicitly set the new CASESENSITIVE=1
   list option, using the couriermlm command, otherwise those subscribers
   will have problems unsubscribing or posting messages to the list.

  Upgrading from the Courier mail server 0.48.2, or earlier

   The Courier mail server's default configuration now includes backscatter
   suppression. Review Backscatter suppression, below, for any needed
   configuration changes.

  Upgrading from the Courier mail server 0.47, or earlier

   Beginning with 0.48, the authentication library that used to be a part of
   the Courier mail server's source has been spun off into a standalone
   authentication library.

   You must download and install the Courier mail server authentication
   library from http://www.courier-mta.org/authlib/ before upgrading. Review
   the documentation in the courier-authlib package for more information.

   As part of installing courier-authlib, the configuration files in the
   Courier mail server's configuration directory that relate to
   authentication will be copied to courier-authlib's configuration
   directory. The files are: authdaemonrc, authmysqlrc, authpgsqlrc,
   authldaprc, and userdb (together with the .dist versions). This works only
   as long as the Courier mail server was installed in one of the known
   default installation directories. The documentation in courier-authlib
   explains what to do if the existing version of the Courier mail server is
   installed in a non-default location.

   In any case, after upgrading to 0.48 these configuration files in the
   Courier mail server's configuration directory will no longer be used. To
   avoid future confusion the old copies of these configuration files
   (including the .dist files), should be removed from the Courier mail
   server's configuration directory. They now live in the Courier mail
   server-authlib's configuration directory (/usr/local/etc/authlib, or
   whatever was specified to the Courier mail server-authlib's configure
   script).

  Upgrading from the Courier mail server 0.45.4 or earlier

   The command to start the webmail server daemon has changed. The system
   startup script must be modified to run the new command:
   "/usr/lib/courier/sbin/webmaild start". Additionally, this scripts also
   starts pcpd, if required. It is no longer necessary to start pcpd by hand.

  Upgrading from the Courier mail server 0.44.0 or earlier

   Version 0.44.1 introduced an updated webmail implementation. The suid
   cgi-bin binary has been replaced by a combination of a stub and a daemon
   process. After upgrading to 0.44.1 you will need to modify your system
   startup script to run /usr/lib/courier/libexec/courier/sqwebmaild start.
   See below for more information.

  Upgrading from the Courier mail server 0.42.2 or earlier

   After upgrading from the Courier mail server 0.42.2, or earlier, any
   existing mail in POP3 mailboxes may show up as new mail, by some mail
   clients. This is a one-time event.

  Upgrading from the Courier mail server 0.42.0 or earlier

   Version 0.43 introduced some functional changes to the LDAP, MySQL, and
   PostgreSQL authentication modules. A new DEFAULTDELIVERY setting is added
   to each module, incorporating some functionality previously done by the
   MAILDIR setting. Previously, MAILDIR served two purposes: 1) define the
   default location to the primary mailbox, relative to the account's home
   directory, 2) provide default mail delivery instructions, overriding
   DEFAULTDELIVERY in the courierd configuration file.

   Starting with this version, MAILDIR only specifies the default location
   for the primary mailbox, and this setting is now used only by the POP3,
   IMAP, and Webmail servers. The new DEFAULTDELIVERY setting specifies the
   default mail delivery instructions. Sites that previously used MAILDIR may
   now need to copy its setting to DEFAULTDELIVERY.

  Upgrading from the Courier mail server 0.34.1 or earlier

   Version 0.35 introduced the ability to update system passwords from the
   webmail server. If you are using the authuserdb authentication module,
   rerun the makeuserdb script after upgrading to 0.35 or later.

   Prior to 0.35, the default configuration of the webmail server maintained
   a separate webmail password file. The webmail server did not have the
   logic to update system login passwords, the approach was to copy system
   login passwords into a webmail password file. Changing the webmail
   password involved simply updating the webmail password file, and life was
   good.

   In 0.35, logic was added to update the real system password file, and the
   eliminate the webmail password file. After upgrading in 0.35, it will
   probably be necessary to reset all mail account passwords on existing
   accounts, since the webmail password file is not being used any more, and
   most people have probably changed their webmail passwords.

   As the result of the password change, the default configuration script
   will now always build the authdaemond authentication module by default.
   Previously, authdaemond was built by default only if LDAP or MySQL support
   was necessary.

  Upgrading from the Courier mail server 0.29.1 or earlier

   Version 0.30 changed the format of most configuration files. The new
   configuration file format allows configuration files to be automatically
   upgraded. The automatic upgrade feature requires that both the old and the
   new installation have preformatted configuration files. Therefore, when
   upgrading from version 0.29.1 or earlier, use the following procedure to
   upgrade the existing configuration files.

   All configuration files are installed in the same directory, "sysconfdir".
   sysconfdir is a configurable parameter, it's usually /usr/lib/courier/etc.
   sysconfdir is /etc/courier in the RPM version of the Courier mail server.

    Back up your existing sysconfdir

   Make a backup copy of your current sysconfdir, then delete the old version
   of the Courier mail server. "rm -rf /usr/lib/courier" will do nicely. All
   the possible configurable settings are in sysconfdir, everything else can
   simply go.

    Back up your existing sysconfdir

   Make a backup copy of your current sysconfdir. The upgrade process
   reinstalls several default configuration files; specifically
   sysconfdir/aliases/system and sysconfdir/smtpaccess/default. Any additions
   to these files will normally be lost in the upgrade, and can be restored
   from the backup afterwards. Don't forget to rerun makealiases and
   makesmtpaccess.

    Install the new version

   Follow the installation procedure in the next section (including the make
   install-configure). The following configuration files are now preformatted
   for automatic installation:

    ldapaddressbook
    esmtpd
    esmtpd-msa
    courierd
    pop3d
    pop3d-ssl
    imapd
    imapd-ssl
    ldapaliasrc
    authldaprc
    authmysqlrc
    authpgsqlrc
    authdaemonrc

   NOTE: depending upon your configuration, you may not actually have every
   one of these files installed, so just disregard the ones that are not
   present. Manually edit filename, and retype any custom modifications from
   the backup copy of the configuration file. This is a hassle, but it only
   needs to be done once. Future upgrades will be 99% automatic.

   Any custom configuration changes are generally confined to these
   configuration files only. Very rarely are any configuration changes made
   to the remaining configuration files. If necessary, they can simply be
   restored from the backup copy made in the previous step. Something to keep
   in mind is that future versions may add additional complexity to other
   configuration files, resulting in additional configuration files being
   reformatted for automatic upgrading.

Overview

   You will need the following software in order to compile and install the
   Courier mail server:

    1. The Courier Unicode Library

       The courier-unicode package must be installed and configured prior to
       installing the Courier mail server. Download the courier-unicode
       package from http://www.courier-mta.org/unicode/.

    2. The Courier mail server Authentication Library

       The courier-authlib package must be installed and configured prior to
       installing the Courier mail server. Download the courier-authlib
       package from http://www.courier-mta.org/authlib/.

    3. A C++ compiler

       The Courier mail server is primarily developed and built with gcc.
       Other C++ compiler may or may not work. Solaris's C++ compiler is
       reported to work without any problems. There are some issues with
       AIX's xlC compiler, which mostly has to do with the C++ libraries and
       header files. IBM has released a GNU/Linux development toolkit for
       AIX, which may help in getting the Courier mail server to compile.

    4. PCRE

       The PCRE library (http:/www.pcre.org) is required.

    5. GNU IDN library

       This library (http://www.gnu.org/software/libidn/) implements support
       for internationalized domain names.

    6. GNU make

       On the BSD platform family GNU make is usually installed as gmake.
       Simply replace 'make' with 'gmake' in the following instructions. GNU
       make is REQUIRED. Use anything else at your own risk.

    7. Perl 5

       A recent version of Perl needs to be installed.

    8. GDBM or Berkeley DB library

       Either library must be installed.

    9. FAM, the File Alteration Monitor, or its modern Linux-specific
       replacement Gamin

       FAM (http://oss.sgi.com/projects/fam/) or Gamin is optional. If FAM or
       Gamin is installed, it is used for an enhanced IMAP IDLE
       implementation that provides real-time folder status updates to
       concurrent IMAP clients that have the same folder opened.

   10. OpenSSL or GnuTLS

       Support for SSL/TLS requires OpenSSL/GnuTLS. If OpenSSL or GnuTLS is
       not installed, SSL/TLS features are disabled.

   11. OpenLDAP

       Support for LDAP directory services requires OpenLDAP client libraries
       to be installed. If OpenLDAP is not installed LDAP directory features
       are disabled. Sometimes there's some confusion when commercial LDAP
       servers are used, which come with their own development toolkits,
       which use a different API than OpenLDAP. Even if a commercial LDAP
       server is used to provide LDAP services, OpenLDAP is still required to
       enable LDAP services in the Courier mail server. Also, note that you
       need OpenLDAP development libraries and files. On most systems, the
       development files are packaged separately, in addition to the runtime
       OpenLDAP libraries. Make sure that you have not just the runtime
       OpenLDAP libraries installed, but the development libraries as well.

       Most of the LDAP support code is already provided by the Courier mail
       server authentication library. Some LDAP features, such as LDAP-based
       mail aliases, are implemented in the Courier mail server directly.
       OpenLDAP client libraries must be installed. If OpenLDAP is not
       installed, LDAP directory features are disabled.

   12. mgetty+sendfax, groff or troff (not tested), ghostscript, and NetPBM

       This optional software is required to send E-mail messages via fax.
       The Courier mail server will compile and install without this
       software, but you will not be able to send faxes. All packages must be
       installed prior to installing the Courier mail server, and binaries
       from all packages must be installed in the default PATH before running
       the Courier mail server's configure script.

       mgetty+sendfax, ghostscript, and groff, are required for basic fax
       support, which supports faxing of plain text, Postscript, and
       PDF-formatted content. It's probably possible to use the original UNIX
       troff instead of groff, but this has not been tested. Installing
       NetPBM adds the ability to fax GIF, JPEG, and PNG images.

   The typical sequence of commands to install the Courier mail server is as
   follows. Read the following section before running these commands:

    ./configure [options]
    make
    make check       # Optional -- see below
    make install
    make install-configure

   These commands are described in greater detail in the following sections.

   --------------------------------------------------------------------------

     If you're using gmake (the make on GNU/Linux, and gmake everywhere
     else), and you are compiling the Courier mail server on a workstation
     with multiple CPUs and plenty of memory, set the following environment
     variable:

    MAKEFLAGS="-j 4"; export MAKEFLAGS         # Bourne or Korn shell

     or:

    setenv MAKEFLAGS="-j 4"                    # The C shell

     This must be done before running the configure script. This works only
     with gmake.

   --------------------------------------------------------------------------

     The Courier mail server will not work on a Linux kernel that's been
     patched with the Openwall security patch in its default configuration.
     The current version of the Openwall patch has a non-default option that
     turns off the portion of the Openwall patch which prevents the Courier
     mail server from running.

     NOTE: Linux-Mandrake includes the Openwall patch in the alternative
     "secure" kernel package. The Courier mail server will not run on
     Linux-Mandrake under the alternative "secure" kernel. This package must
     be removed and the standard kernel package must be installed.

   --------------------------------------------------------------------------

Preparing for installation

   The first step consists of gathering some information about your existing
   mail system. Before proceeding, you will need to identify and resolve the
   following issues:

     * Maildirs or mailbox files

   The Courier mail server can be used as a simple mail relay -- which does
   not store any mail locally but is merely a gateway between internal and
   external mail systems. The Courier mail server can also be used as a
   traditional mail server, accepting and storing messages in individual
   mailboxes that are accessible via POP3, IMAP, or webmail.

   The Courier mail server defaults to storing mail in maildirs, not
   traditional flat file mailbox files. Maildirs require less I/O and CPU
   resources; they do not use locking; and multiple clients can read and
   write from maildirs simultaneously. Maildirs scale very well to servers
   with multiple CPUs. Some benchmark numbers on maildirs are available from
   http://www.courier-mta.org/mbox-vs-maildir/.

   Additionally, The Courier mail server's integrated POP3, IMAP, and
   HTTP/webmail servers support maildir mailboxes only. They do not support
   mailbox files.

   If you have an existing mail server in service, chances are that your
   current mail server delivers mail to mailbox files. You should consider
   migrating and converting to maildirs, but this will require that you also
   upgrade your POP3 server, your IMAP server, and all your other mail
   clients to software that supports maildirs. Fortunately, The Courier mail
   server already includes a fully integrated POP3 and IMAP server.

   Still, if circumstances absolutely require for you to stick with mailbox
   files, The Courier mail server has limited compatibility support for
   delivering mail to mailbox files, but you have more homework to do:

     * What locking mechanism is used on mailbox files

   If you decide to stick with mailbox files, you must know - of course -
   where your mailboxes are located, and what locking mechanism is being used
   by your mail software. Mailbox files require some form of locking, because
   only one application can access the mailbox file at the same time.
   Unfortunately, different operating systems use different locking methods.
   There are several possible locking strategies that can be used: so-called
   "dot-locks", or one of three possible kinds of file locking calls. You
   will need to consult the documentation for your existing mail software to
   determine what locking mechanisms you should use.

   In most cases, mailbox files are located in a separate partition, usually
   the directory /var/spool/mail. In some instances, mailbox files may be
   kept in the home directory of each individual account, and the mail is
   delivered to either $HOME/Mailbox, or $HOME/INBOX. Again, you will have to
   figure this out by yourself.

   The Courier mail server can deliver mail to mailbox files only if the
   default mailbox file is in the home directory of each individual account,
   and if you use file locking. The Courier mail server does not support
   dot-locks, and the Courier mail server does not support a separate mail
   directory for mailbox files. Mailbox files must be located in the home
   directory of each individual account.

   The Courier mail server can use a recipient database (userdb) that can
   specify a non-default location for a recipient's mailbox. In theory, it is
   possible to point each account to its individual mailbox in
   /var/spool/mail, or somewhere else. However, that's a tedious task that
   must be done manually for each account, and is likely to be a major
   maintenance issue.

   A better solution is to use a separate local mail delivery agent. Your
   existing mail system is very likely to include a separate local mail
   delivery agent. If you already use a mail delivery agent such as procmail,
   you probably already have it set to use the correct locking mechanism for
   mailbox files, and it already knows where the mailbox files are. The
   Courier mail server will be happy to hand off all local mail to procmail,
   or anything else for the actual delivery.

   The Courier mail server source distribution includes the maildrop mail
   delivery agent which has some additional file locking options, however
   you'll have less problems if you stick with procmail in the beginning, and
   switch to maildrop after you've gained some experience configuring and
   installing the Courier mail server.

     * Create the courier user and group IDs

   You should create a new userid and groupid named "courier". That's
   optional, but highly recommended. If this is not done, The Courier mail
   server will install as user/group daemon (or some other suitable
   user/group id). Only two of the Courier mail server's daemon processes run
   as a superuser (and one of them is perpetually waiting for a non-superuser
   daemon process to terminate, in order to restart it). Everything else runs
   as a non-superuser process. Ideally, you should reserve a separate user
   and group ID for the Courier mail server's use only, so a compromised mail
   system cannot be used to compromise the rest of the system. If push comes
   to shove, you can set up the Courier mail server to use a well-defined
   existing user and group ID, such as daemon.

     * Define the installation directory

   The Courier mail server, by default, installs in /usr/lib/courier.
   Everything goes in there: binaries, scripts, configuration files, and
   manual pages. You will have to configure your man command to look for
   manual pages in /usr/lib/courier/man by adding this directory to the
   MANPATH environment variable. You will also need to add
   /usr/lib/courier/bin and /usr/lib/courier/sbin (for the root user only) to
   the default PATH. The Courier mail server RPM package installs a script
   that automatically implements that.

   Note that this installation layout is nothing more than a basic default,
   chosen because this simple arrangement works for everyone. The
   installation layout can be easily changed. For example, binaries can go to
   /usr/local/bin, and configuration files to /usr/local/etc. But keep in
   mind that the Courier mail server consists of several hundred individual
   files (at the last count), so if you install the Courier mail server
   somewhere else it might be very cumbersome to keep track of where
   everything went, and it will lead to almost guaranteed problems later,
   when you upgrade.

   You should try to use some kind of a packaging system in order to keep
   track of your the Courier mail server installation. Once you choose a
   packaging system, you should stick to it. If you switch to a different
   packaging system you should take extreme care to remove your previous
   package, and install your new package. Extreme configuration flexibility
   means that different packages will install in different places, and even
   have different file ownerships!

   For example, The Courier mail server's source code tarball can be built by
   RPM version 3.0.3 or higher, into a binary RPM package. The binary RPM
   package installs configuration files in /etc/courier, the mail queue in
   /var/spool/courier, and everything else in /usr/lib/courier. If you
   install my package, and later decide to either create your own package or
   use someone else's, you will have to make sure to use the same settings,
   or remove my package completely, before installing your new package. I
   mean it when I say "remove my package completely". That includes the mail
   queue containing any unsent messages. The Courier mail server will not
   function if you reinstall it using a different user/group ID, or if you
   use a different value for any other option.

     * Conclusion

   Once these issues are squared away, you are ready to configure and install
   the Courier mail server.

OPTIONAL: Install the Socks 5 client toolkit

   The Courier mail server has the ability to send outgoing SMTP mail through
   a Socks 5 proxy. The Socks 5 proxy option requires a separate module, the
   Socks 5 client/server proxy to be installed before installing the Courier
   mail server. Download the Socks 5 proxy client library from
   http://www.courier-mta.org/download.html#sox and follow its installation
   instructions. Binary RPMs can be built from the source code tarball by
   following the procedure outlined in
   http://www.courier-mta.org/FAQ.html#rpm using the "courier-sox-version"
   tarball, and installing the "courier-sox" and "courier-sox-devel" binary
   RPMs afterwards.

     NOTE: Be sure to read the README, NEWS, and INSTALL files in the Courier
     mail server Socks 5 library toolkit, before attempting to install it for
     the first time (unless using the RPM build method).

   Socks proxying must be implemented in relatively low-level manner, and may
   not work on all operating systems. This is why it is packaged separately,
   in case that it doesn't work. The configure script, described in the
   following section, enables Socks 5 support automatically if the Courier
   mail server Socks 5 proxy client library is already installed. To make
   sure that the library is installed correctly, specify the "--with-socks"
   option to the following configure script. This option aborts the configure
   script if it does not detect the Courier mail server Socks 5 proxy client
   library.

Run configure

   After you are squared away with the preliminaries, run the configure
   script:

   ./configure [ options ]

     NOTE

     You MUST run the configure script as normal user, not root. Did you
     extract the tarball as root? It won't work. Delete everything you have
     just extracted, as root. Log in as a normal user. Extract the source
     code as a normal user, then run configure. You will do everything as a
     normal user, except for the final step of installing the compiled
     software. When you're ready to do a make install, later, su yourself to
     root, and run make install.

   The configure script can take a while to complete. There will be more then
   thirty separate configuration scripts that will be executed by this
   command. To an untrained eye it may seem that the same configuration
   script is stuck in a loop; that's because all these configuration scripts
   share a lot of code. It may take as much as 15-20 minutes for configure to
   finish on a slow machine - even more.

   You must have the uux command in your default search path if you intend to
   use the Courier mail server to relay mail via UUCP. You may need to modify
   your PATH environment variable to include the directory containing uux.

   gcc/egcs is officially blessed for building the Courier mail server. In
   most cases there's no need to tweak any compiler-specific settings. Note
   that there currently may be some unresolved issues with gcc 2.96. gcc 2.91
   has been tested and known to work. Occasionally some of your system
   libraries may be stuck in some oddball directory that is not searched by
   default. Non-standard options for the compiler or linker can be set by
   putting them into environment variables. This must be done before running
   the configurescript:

     * CFLAGS

       Additional flags for the C compiler.

     * CXXFLAGS

       Additional flags for the C++ compiler.

     * LDFLAGS

       Additional flags for the linker.

     * LDADD

       Additional libraries to link with. NOTE - everything will be linked
       with these libraries.

   The complete reference to all configure script options is provided below.
   The most important options are:

     * --prefix=pathname

       Install the Courier mail server in pathname, instead of the default
       location of /usr/lib/courier. Note - the examples in the rest of this
       text assumes this is where you will install the Courier mail server.
       Do not attempt to install the Courier mail server in a directory whose
       name contains spaces or punctuation marks. Periods or dashes are fine,
       but refrain the temptation to use other, exotic, punctuation.

     * --with-db=db or --with-db=gdbm

       The Courier mail server requires either the GDBM or the DB database
       library. GDBM is used if both are present. This option forces the
       selection of the database library.

     * --with-locking-method=function

       Select a file locking function. Available functions are: fcntl, lockf,
       and flock. Not every function is available on every platform. If this
       option is not present, configure tries each one, and takes the first
       one that works. You can select a specific locking function by using
       this option. This affects both the locking used for delivering mail to
       mailbox files, and for other kinds of locking that the Courier mail
       server uses internally.

     * --enable-mimecharset=charset

       Specify the default character set the Courier mail server uses when
       adding MIME headers to a message. If not specified, us-ascii is used.

     * --without-tcpddns

       Use this option if you are running a small network without access to a
       DNS server. This option will cause couriertcpd to use the system
       resolver's gethostby functions instead of issuing DNS queries. Also:
       you must initialize the esmtproutes control file with the IP addresses
       of all your servers.

  configure reference

   Here's a comprehensive list of options for the configure script. They are
   presented in no particular order. In almost all cases, the configure
   script will automatically figure out the correct values, but sometimes it
   is necessary to specify them explicitly. If you ever have a need to
   manually specify any configuration option, try to determine whether you
   need it because of a particular unique case that involves your server
   only, or whether it affects any server running your hardware, or system.
   In the later case, try to investigate if it's possible for configure to be
   a bit smarter and make the right decision.

     * --prefix=pathname

       Install the Courier mail server in pathname, instead of the default
       location of /usr/lib/courier. Note - the examples in the rest of this
       text assumes this is where you will install the Courier mail server.

     * --exec-prefix=pathname

       Specify where the Courier mail server's machine-executable binaries
       should be installed. This defaults to the same directory as given by
       the --prefix option. There will be three subdirectories created
       underneath exec-prefix: bin - user-executable binaries; sbin -
       superuser-only binaries; libexec - other binaries that are not
       directly invoked from the command line, but are started by other
       Courier mail server commands.

     * --bindir=pathname, --sbindir=pathname, --libexecdir=pathname

       These options override the default value for the corresponding
       subdirectory underneath --exec-prefix (see above). The bindir
       directory contains programs that can be executed by anyone. sbindir
       contains programs that can only be executed by the superuser.
       libexecdir contains programs and libraries that cannot be directly
       executed from the command line. The default locations are the bin,
       sbin, and libexec subdirectories underneath the directory specified by
       exec_prefix.

     * --datadir=pathname

       Specify the directory where miscellaneous shell scripts, Perl scripts,
       and data files will be installed. This option defaults to the
       subdirectory "share" in the directory specified by the --prefix
       option.

     * --sysconfdir=pathname

       Specifies the directory where the Courier mail server's configuration
       files are installed. This option defaults to the subdirectory "etc" in
       the directory specified by the --prefix option.

     * --localstatedir=pathname

       Specify the directory that will hold the mail queue, and other
       temporary data. This option defaults to the subdirectory "var" in the
       directory specified by the --prefix option.

     * --without-ipv6

       Do not compile IPv6 support. IPv6 support, if available is normally
       automatically detected and enabled. Use --without-ipv6 to disable it.
       IPv6 implementations on various platforms is still in flux, and IPv6
       support will not be enabled if the detection logic fails. Use
       --with-ipv6 in order to fail the configuration stage if IPv6 is not
       detected, instead of silently continuing with IPv4 support only. See
       "IPv6" below for more information.

     * --with-db=db or --with-db=gdbm

       The Courier mail server requires either the GDBM or the DB database
       library. GDBM is used if both are present. This option forces the
       selection of the database library.

     * --with-locking-method=function

       Select a file locking function. Available functions are: fcntl, lockf,
       and flock. Not every function is available on every platform. If this
       option is not present, configure will choose the first locking
       function that's available. You can select a specific locking function
       by using this option. This affects both the locking used for
       delivering mail to mailbox files, and for other kinds of locking that
       the Courier mail server uses internally.

     * --enable-mimecharset=charset

       Specify the default character set the Courier mail server uses when
       adding MIME headers to a message. If not specified, us-ascii will be
       used.

     * --without-tcpddns

       \Use this option if you are running a small network without access to
       a DNS server. This option will cause couriertcpd to use the system
       resolver's gethostby functions instead of issuing DNS queries. Also:
       you will have to initialize the smtproutes control file with the IP
       addresses of all your servers.

     * --without-explicitsync

       Normally the Courier mail server will automatically sync, or flush out
       all file buffers to disk, at certain key points in order to try to
       minimize the extent the mail queue can get corrupted if the system
       crashes. If the mail queue is installed on a reliable disk array or a
       network file server, this may not be necessary, and will only serve to
       slow down the mail delivery. Use this option to turn off syncing.

     * --with-dirsync

       Also explicitly sync the parent directory. There's a school of thought
       which believes that the Linux ext2 filesystem requires the parent
       directory to also be synced, in addition to the new message file
       that's just been written to disk. There's another school of thought
       that thinks that this issue is completely blown out of proportion, and
       is really nothing more than a tempest in a teapot. However -- to
       accomodate the former school of thought -- this option adds a little
       bit of extra code to sync the parent directory.

     * --with-shellpath=path

       Specify the contents of the PATH environment variable that is
       inherited by custom programs started by the Courier mail server to
       deliver messages. If not specified, PATH will be set to
       /bin:/usr/bin:/usr/local/bin.

     * --disable-local-extensions

       Normally, in addition to accepting mail that's addressed to
       <user@domain.com>, The Courier mail server can accept mail that's
       addressed to <user-xxx@domain.com>, for arbitrary values of xxx. In
       order for that to happen the user has to create a special file with
       delivery instructions. See the dot-courier(5) manual page for more
       information. This option disables this feature.

     * --with-paranoid-smtpext

       Be paranoid when negotiating the Courier mail server-specific ESMTP
       extensions with remote servers. The Courier mail server defines and
       implements certain experimental ESMTP extensions: XVERP and XEXDATA.
       Problems may result in the event that someone else uses the same name
       to implement some other extension. If this option is specified, The
       Courier mail server's ESMTP server will also advertise a dummy ESMTP
       capability called XCOURIEREXTENSIONS, and will not recognize any the
       Courier mail server-specific extensions unless the remote mail server
       also advertises this dummy ESMTP capability.

     * --enable-workarounds-for-imap-client-bugs

       There are several confirmed bugs in some IMAP clients that do not
       properly implement the IMAP4rev1 protocol. This option enables some
       workarounds for those buggy IMAP clients. NOTE: make check will fail
       if this option is used. You should first configure without this
       option, and if all post-configuration tests succeed, rerun configure
       with this option and recompile.

     * --with-qdircount=n

       Set n to be the number of mail queue subdirectories. In order to
       improve the speed of access to the mail queue, messages are stored in
       subdirectories, hashed by the message queue number. n specifies how
       many subdirectories will be created. If this option is not specified,
       100 subdirectories will be used. WARNING: once you've installed the
       Courier mail server once, if you decide to reconfigure and reinstall,
       you MUST use the same subdirectory count (by default, or explicitly),
       otherwise you'll end up with a big mess on your hands if you have ANY
       messages in the mail queue. If you need to change this option, wait
       for all messages in the queue to be flushed out, and reinstall with an
       empty mail queue.

     * --with-random=/dev/path, --without-random

       Sometimes the Courier mail server sometimes needs a good source of
       random noise. If configure finds /dev/urandom, it will use that. If
       your random device is named otherwise, specify it using this option.
       If you don't want to use a random device, specify --without-random,
       and the Courier mail server will generate some noise on its own. The
       Courier mail server will generate noise based on the output of a
       random ps command, and several other, hopefully unpredictable,
       sources.

     * --with-gnutls - Use the GnuTLS library even if the OpenSSL library is
       also installed. The Courier mail server automatically uses whichever
       one is available. The OpenSSL library is selected if both are present.
       Use this option to override and select GnuTLS instead.
     * --without-certdb

       Do not install a default set of trusted X.509 root CA certs (in order
       to validate the remote server's X.509 certificate). See "Configure
       ESMTP authentication and SSL" for more information.

     * --with-certdb=pathname

       Do not install the default set, but put pathname as the default
       location of the root CA database, into the configuration file. This is
       a convenient option to have the Courier mail server use an external,
       previously installed, root CA database.

     * --with-certsdir=pathname

       Set up configuration files and scripts that reference the server's SSL
       certificates to use the pathname directory, instead of the directory
       specified by the --datadir option. Scripts that create temporary
       self-signed certificates to be used for testing (mkimapdcert,
       mkpop3dcert, et. al.) install the generated certificate in this
       directory, and it's referenced from the corresponding configuration
       files.

     * --with-waitfunc=wait, --with-waitfunc=wait3

       Specify the system call to use to asynchronously reap child processes.
       This is a sticky one, because the behavior of the wait and wait3
       system calls varies greatly depending on the level of each individual
       system's POSIX compliance. The configure script will attempt to
       compile and run some test programs in order to attempt to figure out
       which system call actually works. If the configure script fails, or if
       it selects a wrong function (which will be evident when mail delivery
       stops, and you have a bunch of zombies that are not being reaped), you
       might have to manually specify it using either option. In that case,
       however, you should also examine the test programs, investigate what
       went wrong, and patch the test programs to give a correct result for
       your system.

     * --without-ispell, --with-ispell=program

       The Courier mail server's webmail server can use spell checking, if
       the ispell program is available (aspell can be used too). If configure
       finds ispell, spell checking is enabled. Use --without-ispell to
       forcefully disable spell checking. If ispell is not in the current
       search path, use --with-ispell=program to explicitly set the location
       of ispell. See "Configure the webmail server" for more information on
       ispell or aspell.

     * --enable-imageurl=/url

       Use /url/ as the URL to the static images displayed by the webmail
       server. HTML pages are dynamically generated by the webmail server
       CGI, but they also include some static icons. The webmail CGI will use
       /url as the URL to the directory containing the static images. The
       default URL is "/webmail", which means that the static images must be
       installed in the <DocumentRoot>/webmail directory. This is a manual
       process that is described in more detail in the "Configure the webmail
       server" section, below.

     * --enable-https, --enable-https=login, --enable-https=auto

       If you have an SSL-enabled web server, use the --enable-https option
       in order to configure webmail access for SSL. Use --enable-https=login
       in order to use SSL only when logging in, to send the password. Use
       --enable-https=auto to generate relative URLs, so that users can
       connect with either http or https and their session will remain that
       way.

       --enable-https=login and --enable-https=auto require that your http
       and https URLs that refer to the webmail CGI be identical (which is
       the usual default).

       --enable-https=auto is the default. Use --disable-https if you need to
       completely disable https, for some reason.

     * --enable-hardtimeout=7200

       set the hard timeout for webmail sessions (in seconds). The default is
       2 hours. webmail sessions are unequivocally logged out after the
       indicated time interval.

     * --enable-softtimeout=1200

       set the inactivity timeout for webmail sessions (in seconds). The
       default is 20 minutes. webmail sessions are logged out if there's no
       activity for the indicated time interval.

     * --with-defaultlang=lang

       reserved for future use.

     * --enable-mimetypes=file:file:file

       this is a colon-separated list of all of your mime.types files. The
       mime.types configuration files are used to map file extension to their
       corresponding MIME content types. The configuration script will look
       in several directories where mime.types usually exists. You can use
       this option to explicitly specify a list of mime.types files to be
       used, instead of the default.

     * --enable-bannerprog=pathname

       advanced option that sets a banner program that the webmail server
       will execute. This program should print HTML, on standard output, to
       generate a typical banner.

     * --with-maxargsize=bytes,--with-maxformargsize=bytes

       Sets an upper limit on the size of CGI arguments for the webmail
       server. Normally there's no reason to modify the defaults (500,000 and
       2,000,000 bytes). The latter is generally the maximum allowed size of
       an attachment. The former is generally the maximum allowed size of the
       typed message. These settings can also be adjusted at runtime. See
       Maximum message size, below.

     * --with-maxmsgsize=bytes

       Sets the upper limit of messages composed in the webmail server, the
       main text and all the attachments. This setting can also be adjusted
       at runtime. See Maximum message size, below.

     * --with-cachedir=dir, --with-cacheowner=userid

       The webmail server uses a cache of currently active logins. The
       webmail server binary, is executed for each and every HTTP request,
       and the user's maildir needs to be quickly located each time. Because
       hitting the authentication module can be expensive (think
       MySQL/PostgreSQL/LDAP query for every HTTP request!) the webmail
       server will cache this information in order to avoid having your
       authentication server brought down to its knees. By default, the
       directory /usr/lib/courier/var/webmail-logincache will be used, owned
       by the bin user. These options can be used to specify a different
       location for the webmail login cache directory.

       If you'll be using the webmail server, you MUST add an hourly cron job
       to run the /usr/lib/courier/share/sqwebmail/cleancache.pl script which
       deletes expired cache records from the cache directory. Add the
       following command to be executed from cron at least once an hour:

 su -c "/usr/lib/courier/share/sqwebmail/cleancache.pl" bin

       (This assumes that your cache directory is owned by the bin user).
       There's no need to set up this cron job if the webmail server is not
       used. NOTE: your su command may use different options or syntax, check
       the su manual page to confirm the correct syntax.

     * --without-gzip

       if the configuration script finds the gzip utility, the webmail server
       will automatically use gzip compression for some large web pages (if
       the client browser supports gzip compression). Use this option to turn
       off gzip compression.

     * --disable-autorenamesent

       do not rename the Sent folder every month. This option can also be
       controlled by the SQWEBMAIL_AUTORENAMESENT environment variable (which
       can be set in Apache's httpd.conf, for example). This setting gives
       the initial configuration, that can be individually adjusted in the
       Preferences screen.

     * --with-calendarpurge=N

       if calendaring is enabled, purge expired calendar events after N days
       (default: 30).

     * --with-trashquota

       include deleted messages, and the Trash folder, in the estimated quota
       usage for maildirs. Quotas are optional, see the file
       maildir/README.maildirquota.html for more information. The default
       configuration does not count messages marked as deleted (but not yet
       expunged) and the contents of the Trash folder (which are
       automatically purged by the server) against the quota usage. NOTE - if
       this option is used, make check WILL FAIL. You should first configure
       the Courier mail server without this option, run make check, then
       reconfigure the Courier mail server with this option.

IPv6

   IPv6 support in the Courier mail server means basically the following:

     * ESMTP, IMAP, and POP3 servers will create an IPv6 socket and accept
       IPv6 connections.
     * The ESMTP client will attempt to resolve AAAA records in addition to A
       records.
     * Headers in incoming mail will log IPv6 addresses, instead of IPv4
       addresses. Delivery Status Notifications and log files will also
       reflect IPv6 addresses.

   IPv6 implementations are required to accept IPv4 connections on IPv6
   sockets, so IPv6 sockets should be able to receive both IPv4 and IPv6
   connections. In the event that your IPv6 implementation is not stable, or
   is partially incomplete, IPv6 support in the Courier mail server should be
   disabled.

   The configuration script will attempt to detect whether IPv6 structures
   and functions are available, and automatically enable IPv6 support if they
   are found. The --without-ipv6 option disables IPv6 support, which may be
   desired for the following reasons:

     * The IPv6 implementation on your platform is incomplete.
     * The IPv6 implementation on your platform is actually not available,
       despite the presence of IPv6 structures and functions. Most GNU/Linux
       distributions ship without IPv6 support enabled in the default kernel
       build. The Courier mail server automatically falls back to creating an
       IPv4 socket, if it can't create an IPv6 socket, so things should
       continue to work in that case. However, each such attempt is likely to
       result in an error message logged to /var/log/messages -- modprobe is
       whining that it can't find an IPv6 module to load. On systems that
       handle a large amount of traffic the log files can fill up rather
       quickly.
     * Implementing IPv6 can increase the amount of DNS traffic, even if
       there is no IPv6 support in the kernel. Even if the Courier mail
       server falls back to IPv4 sockets, it will continue to resolve IPv6
       addresses, resulting in some extra DNS queries. There won't be a lot
       of extra DNS queries, but there will be some. Also, there are still
       some DNS servers that cannot correctly handle IPv6 queries, and
       attempts to deliver mail to these domains will fail despite the
       presence of valid IPv4 records.

   IPv6 support is still a bit spotty in some places. If the configuration
   checks fail, IPv6 support will be quietly suppressed. If you expect IPv6
   support to be present, the --with-ipv6 flag can be used to abort
   configuration if IPv6 support was not detected.

Compile and run make check

     make
     make check

   If the configure script ran without errors, run make to build the Courier
   mail server. If make completes succesfully, run make check. make check
   runs some simple internal tests. It is not feasible to run a complete
   check of the Courier mail server's behavior, but make check does
   automatically run some tests on several modules.

   If make check fails, you need to do some detective work. Investigate the
   source of the failure. It is possible that the issue can be resolved by
   specifying different options to the configure script, in which case you
   have to go back and rerun the configure script again.

Installation

   su yourself to root, if you want to do a live install, then run make
   install or make install-strip to install the Courier mail server. If you
   use the GNU version of make, and you would like to see which files the
   Courier mail server installs and where, don't su yourself to root, but set
   the make variable named DESTDIR. For example:

   make install DESTDIR=/var/tmp/courier-inst

   The contents of DESTDIR are prepended to the name of every file installed,
   so if --prefix was set to /usr/lib/courier, the files will be installed in
   /var/tmp/courier-inst/usr/lib/courier. This only works if you use GNU
   make.

   NOTE: you must make sure that your umask is 022 before you run make
   install.

   If executed by root, make install automatically sets the correct ownership
   on the installed files. Non-root make installs do not set the ownership,
   but still set correct permissions. This feature is mainly for use by
   people who are rolling the Courier mail server into a prebuilt package,
   since this allows them to build the package as a normal user, not root. In
   this situation the command make install-perms will be very useful. This
   command creates a file called permissions.dat. This file contains a
   complete listing of everything that will be installed, and what the
   correct permissions are on every file.

   make install installs the Courier mail server binaries with debugging
   data, which is probably a good idea to do while the Courier mail server is
   in development. Use makeinstall-strip to install binaries without
   debugging data. Some systems have a broken install utility, so make
   install-strip may fail.

Install configuration files

   The following command creates and updates configuration files. It must be
   executed after running make install:

   make install-configure

   This command copies each configuration file "filename.dist" to "filename".
   The existing filename is backed up as filename.bak. If upgrading from the
   Courier mail server 0.30 or later, the previous configuration settings in
   filename.bak will be automatically copied to filename, provided that they
   are still valid. If a configuration setting may no longer be valid, it
   will be reset to its default value. The output of make install-configure
   will indicate the status of each configuration setting, therefore it is
   advistable to save the output to a file, and examine it:

   make install-configure >upgrade.log

   Versions prior to 0.30 cannot have their configuration settings
   automatically preserved, and must be restored manually from filename.bak.
   Do not simply copy filename.bak to filename, this will lose all the
   formatting codes that allow automatic upgrades.

  PAM configuration

   If you use PAM library for authentication, you may need to set up PAM for
   authenticating POP3 logins, IMAP logins, webmail logins, and/or ESMTP
   authentication. In most cases, all you have to do is install
   /usr/lib/courier/etc/pop3d.authpam as /etc/pam.d/pop3,
   /usr/lib/courier/etc/imapd.authpam as /etc/pam.d/imap,
   /usr/lib/courier/etc/webmail.authpam as /etc/pam.d/webmail, and
   /usr/lib/courier/etc/esmtp.authpam as /etc/pam.d/esmtp. However you will
   have to consult your PAM documentation, and the manual pages for authpam,
   in order to make sure.

   Some versions of the PAM library, do not use the /etc/pam.d directory.
   Instead they use a single configuration file /etc/pam.conf. Here's an
   example of what needs to be added to /etc/pam.conf on FreeBSD 4.0. NOTE:
   other platforms may need something similar:

 imap  auth    required        pam_unix.so      try_first_pass
 imap  account required        pam_unix.so
 imap  session required        pam_permit.so
 pop3  auth    required        pam_unix.so      try_first_pass
 pop3  account required        pam_unix.so
 pop3  session required        pam_permit.so
 esmtp auth    required        pam_unix.so      try_first_pass
 esmtp account required        pam_unix.so
 esmtp session required        pam_permit.so

  Building RPM packages

   NOTE: If you build an RPM package directly from the source tarball, the
   resulting RPMs may not install if you have an existing IMAP or an existing
   POP3 server installed. The RPM packages will contain these PAM
   configuration files, and they will conflict with any PAM configuration
   files installed by another IMAP or POP3 server. If you manually installed
   an IMAP or a POP3 server without packaging them up into an RPM, the
   Courier mail server RPM package will install and the old configuration
   files will be silently removed, since they were not installed using RPM.

   The Courier mail server includes integrated POP3, IMAP, and webmail
   servers, however they only work with maildirs. Decide if you want to keep
   using your current server, or switch to the Courier mail server's
   IMAP/POP3/webmail servers. If you want to keep your existing servers, back
   up the contents of your /etc/pam.d directory before installing the RPM,
   install it, then restore the overwritten files. If you want to switch to
   the Courier mail server, blow away your current server before running make
   install.

Adjust system paranoia level

   There are four setuid binaries in the Courier mail server that are owned
   by root: sendmail, maildrop, webmail and webadmin. There's also one setgid
   binary, sqwebpasswd.

   /usr/lib/courier/bin/maildrop is the mail filter. If you do not need mail
   filtering, you can remove it. The setuid root privilege is only needed to
   implement mail filtering "on the wire", when receiving mail from an
   external mail relay (see localmailfilter(7) for more information).
   Removing the setuid root bit still allows traditional mail filtering to be
   used, after the message is received and delivered to the mailbox.

   /usr/lib/courier/libexec/courier/webmail/webmail is the webmail CGI. It is
   executed by the web server, and needs to change its userid/groupid, in
   order to enter the maildir. If you do not need webmail access, you can
   remove it. An alternative is to implement virtual mailboxes, owned by a
   non-privileged userid, and change the ownership of the webmail CGI to the
   non-privileged user (you will also need to use the --with-cacheowner
   option to the configure script since the webmail process must have write
   access to the webmail login cache directory).

   /usr/lib/courier/libexec/courier/webmail/webadmin is the wrapper for the
   web-based administration tool. See below for more information.

   /usr/lib/courier/bin/sendmail is the command line mail sender. Its first
   order of business is to set its group id to the Courier mail server's
   group id, and restore the original userid, dropping root. The reason that
   it needs root setuid is to set its real group id, because setting the
   setgid bit on the executable is not enough. The setgid bit sets only the
   effective group id, and the root setuid bit is required to set both
   effective and real group ids. Both real and effective group IDs are needed
   in order to be able to implement maildrop mail filtering.

   /usr/lib/courier/libexec/courier/sqwebpasswd is described in detail in the
   "OPTIONAL: Changing mail account passwords using the webmail server"
   section.

Post-installation setup

   A first-time the Courier mail server installation may not require the
   system startup scripts to be modified to start the Courier mail server at
   system boot. Until the system's functionality is verified, the system will
   probably continue to use the existing mail server. Still, most the Courier
   mail server configurations will require two things to be started before
   any part of the system is put to use:

     * An hourly cron job needs to be created to run the cleancache.pl
       script, which purges expired webmail login cache records. Logging in
       to the mail account via the web creates a file in a temporary
       directory that caches the login session identity. The output of make
       install includes the command that needs to be set up as a cron job by
       root. The cron job runs su to change to the userid that owns the login
       cache directory, then runs the purge script. The su command on some
       system uses a slightly different syntax than what's shown by make
       install. It may be necessary to consult the su man page before setting
       up the cron job. Run the su command as root, to make sure that its
       syntax is correct, before setting up the cron job. The cron job can be
       omitted if webmail is not going to be used.
     * Run the mkdhparams script to create the DH parameter file. A monthly
       job should also be created to run the mkdhparams script, in order to
       periodically generate a new set of DH parameters. DH parameters are
       used to set up encrypted connections.

Post-installation checks

   The following tests should be run to verify that your installation works
   properly. These tests are not really comprehensive tests, they only make
   sure that the basic functionality is there, and they definitely must be
   done the first time you install a version of the Courier mail server on
   your system. If you later reinstall the same version on the same platform,
   using the same configuration, you don't need to run these installation
   checks (but you better be sure that the reinstallation is COMPLETELY
   identical to the original install). You might also wish to rerun these
   installation checks after upgrading your base operating system.

   The following documentation assumes that the Courier mail server is
   installed in /usr/lib/courier.

  Verify module installation

   Run the showmodules utility after all files have been installed, but
   before you attempt to start the Courier mail server. The showmodules
   utility attempts to load and initialize transport modules that have been
   configured, without actually starting up the Courier mail server. Running
   showmodules should result in something that looks like this:

    showmodules[5060]: Loading STATIC transport module libraries.
    showmodules[5060]: Installing i586-gnu-linux [0/0]
    showmodules[5060]: Installing local
    showmodules[5060]: Installed local
    showmodules[5060]: Installing esmtp
    showmodules[5060]: Installed esmtp
    showmodules[5060]: Installing dsn
    showmodules[5060]: Installed dsn
    showmodules[5060]: Initializing local
    showmodules[5060]: Initializing esmtp
    showmodules[5060]: Initializing dsn

  Test child process termination

   In this test, you will start the Courier mail server, then attempt to
   rapidly pump through as many messages as fast as possible, to verify that
   asynchronous child process termination handling works. For this test (and
   the following tests) you need to use a test account.

   Log on to the test account and run maildirmake to create two maildirs:
   maildirmake $HOME/test, and maildirmake $HOME/bounces.

   Create $HOME/.courier-test-default, containing one line: ./test. Create
   $HOME/.courier, containing one line: ./bounces. If you previously selected
   .qmail compatibility, you will need to use .qmail-test-default and .qmail,
   of course. Keep that in mind as you work through the remaining tests.

   Start the Courier mail server as root:

   /usr/lib/courier/sbin/courier start

   Check your system log files for any error messages. Run the ps command,
   and check that you only have the following processes running: courierd
   (two processes), courierdsn, courieruucp, courieresmtp, and courierlocal.
   You will also have a couple of "logger" processes hanging around, that's
   ok too.

   One of the two courierd processes will be running as root. The
   courierlocal process will also be running as root. All other processes
   will be running as the courier (or daemon, or mail) user. courieruucp may
   be running as uucp.

   Run the perftest1 script, which can be found in the directory containing
   the Courier mail server's source code:

 sh perftest1 1000 "user-test-1 user-test-2 user-test-3 user-test-4 user-test-5"

   Run this script while logged on to the test account. Replace "user" with
   the name of your test account. This will send 1000 messages with five
   recipients per message. You should end up with exactly 5000 messages in
   $HOME/test/new. Count them.

   Monitor the system logs. There will be a lot of activity. On my test
   system, the system logger usually backs up. The Courier mail server
   generates log messages faster than the logger can record them. When all
   the activity stops, count how many files you have in $HOME/test/new. For
   extra credit, total up the Delivered-To: headers in all the messages,
   there should be 1000 headers for each one of the five addresses.

   If you did not get 5000 messages, and mailq comes up empty, check
   $HOME/bounces/new. If you're lucky, the rest bounced. That's still a
   problem, but the bounces will help you to investigate things further.

   If you did not get 5000 messages, and mailq shows some messages remaining
   in the queue, and ps shows some dead zombie processes that are not being
   reaped, this means that asynchronous process termination is not working.
   You will need to examine your configuration to see whether configure
   selected the wait or the wait3 function. Unpack the source code again and
   rerun configure. This time use the --with-waitfunc option to choose the
   other wait function, manually. Recompile, reinstall, and rerun this test.

   If you did get all the messages, go through your syslog for extra-extra
   credit. grep it for the word "defer" to see if any messages required
   multiple delivery attempts. This shouldn't happen either.

   If your hardware has enough juice to pump through 5000 messages in a short
   period of time, rerun this test with a larger number of messages. Before
   doing that, wipe the Maildirs clean, in order to confirm the message
   count, later. The test must run for at least 3-4 minutes in order to get
   meaningful results.

  User/group ID check

   For this test you will need to use or create a regular user test account,
   which will be referred to as user. You can use the same test account you
   used in the last test, but erase all .courier (or .qmail) files.

   In user's home directory, create .courier which contains the following
   text:

 | /usr/bin/id >ID
 | /usr/bin/env >ENV

   Make sure that your id and env commands are in /usr/bin. If not, use the
   correct path.

   Send a single message to user:

   echo "To: user" | /usr/lib/courier/bin/sendmail

   Thie message will disappear into the never-never land, so don't waste time
   looking for it. Just examine, very closely, the contents of the ID and the
   ENV files in user's home directory. Double check what user and the group
   ids recorded in ID match user's. Pay close attention to any auxiliary
   group IDs, make sure that they haven't "leaked" from the root user who
   started the Courier mail server.

   Also, examine the environment, in ENV. Check the manual page for
   dot-courier, ENV should contain only the documented environment variables,
   and any environment variables that are defined in the
   /usr/lib/courier/etc/courierd file.

OPTIONAL: Configure webadmin

   This is a web-based administration tool. webadmin is a web CGI
   application. It is necessary to have a local web server installed in order
   to use webadmin. Apache will do, but so will any other server with a
   complete CGI implementation (PHP is not required). Installing webadmin is
   a three step process:

    1. Move /usr/lib/courier/libexec/courier/webmail/webadmin to your web
       server's SSL cgi-bin directory. Take care to preserve the binary's
       ownership and permissions.
    2. Execute "make install-webadmin-password". This prompts for a password,
       which is saved in the file /usr/lib/courier/etc/webadmin/password.
    3. The web server SHOULD be configured to run webadmin from the cgi-bin
       directory using SSL only. webadmin's authentication is rather simple:
       the password is saved in a cookie. Unless SSL is used, the webadmin
       password can be intercepted in transit. If SSL is not available, an
       acceptable level of security can be achieved by setting up a firewall
       that allows web access only from trusted IP addresses, then use a
       dedicated webadmin password. This is not perfect, but is generally
       adequate. A firewall is a good idea even if SSL is used. This is not
       Fort Knox, and webadmin is not going to be publicly accessible, so the
       only needed security is to keep everyone out except for authorized IP
       addresses.

       Note that webadmin, by default, will enforce this restriction: either
       SSL, or access from a local IP address. Create the file
       /usr/lib/courier/etc/webadmin/unsecureok to allow non-SSL webadmin
       connections from remote IP addresses.

   webadmin is designed to be self-explanatory. Configuration options are
   divided into logical sections. Changes made to configuration options do
   not take effect immediately. To apply configuration changes, select
   "Install new configuration" from the main menu. To cancel all changes
   made, select "Cancel new configuration". Selecting "Install new
   configuration" will apply all the changes to the configuration files, and
   restart any the Courier mail server modules that must be restarted in
   order for the changes to take effect.

   If you decide to use webadmin, most of the remaining steps in this INSTALL
   document can be done using webadmin's equivalent screens.

Create system aliases

   You must now specify which account gets postmaster mail. The Courier mail
   server does NOT deliver any mail to root. You must use a non-privileged
   for postmaster mail. You will also need to specify where your postmaster
   account is. In the following example the same account is used for both,
   but you can easily use separate mailboxes.

   Let's say that you want postmaster mail to be delivered to the user
   "admin".

   Create /usr/lib/courier/etc/aliases/system using any text editor. An
   example aliases/system file is created by make install, and you can simply
   edit what you have there. The default contents of this file are as
   follows:

   root: postmaster

   mailer-daemon: postmaster

   MAILER-DAEMON: postmaster

   uucp: postmaster

   You need to append the following line:

   postmaster: admin

   These aliases cause all mail addressed to root, postmaster, or
   mailer-daemon, to be delivered to admin's account. If you want root's mail
   delivered somewhere else, you can replace "root: postmaster", with
   something else.

   Run the following command as root:

   /usr/lib/courier/sbin/makealiases

   This command creates /usr/lib/courier/etc/aliases.dat, a database that
   contains your new aliases.

   Send a test message:

   echo "To: postmaster" | /usr/lib/courier/bin/sendmail

   Check admin's mailbox, the message should be there.

   Let's do it again:

   echo "To: postmaster" | /usr/lib/courier/bin/sendmail -Nsuccess

   This time, in addition to the blank message, the sending account should
   receive a return receipt.

   Additional aliases can be either added to this file, or placed in any
   other text file in the /usr/lib/courier/etc/aliases directory.

Create smtp access list

   You need to define which IP addresses are allowed to relay SMTP mail
   through the server. The installation script creates
   /usr/lib/courier/etc/smtpaccess/default containing an example of how to
   enable relaying for IP address 127.0.0.1, and several reserved netblocks.
   You can either append additional entries to this file, or put your
   additional entries in any other file in the
   /usr/lib/courier/etc/smtpaccess subdirectory. Afterwars, run the following
   as root:

   /usr/lib/courier/sbin/makesmtpaccess

   This command creates the /usr/lib/courier/etc/smtpaccess.dat database that
   couriertcpd uses to initialize the environment for courieresmtpd.

   You will need to rerun makesmtpaccess in order to rebuild smtpaccess.dat
   after any changes in the smtpaccess subdirectory.

   The default the Courier mail server configuration applies smtpaccess.dat
   to both the regular ESMTP server (port 25), and the message submission
   server (port 587). It is possible to set up different access files for
   both ports. To do that, edit /usr/lib/courier/etc/esmtpd-msa, and
   explicitly set ACCESSFILE to a different file, create that file, and use
   the makesmtpaccess-msa command to compile the dedicated port 587 access
   database.

     NOTE: Authenticated SMTP is preferred over defining explicit IP address
     ranges. When combined with SSL, authenticated SMTP enables relaying
     privileges to any sender that securely provides a valid login/password,
     from any IP address, instead of only a small range of preauthorized IP
     addresses. The "OPTIONAL: Configure ESMTP authentication and SSL"
     section, later in this installation guide, gives more information on
     enabling authenticated SMTP and SSL-based encryption.

     Furthermore, preauthorized IP address ranges are vulnerable to being a
     source of abusive backscatter E-mail. Using authenticated SMTP together
     with the optional backscatter setting, described in the following
     section, prevents transmission of abusive backscatter bounces to
     external recipients even from trusted senders that have been
     compromised.

Backscatter suppression

     NOTE: It is important to know that the Courier mail server's default
     backscatter configuration means that if the Courier mail server receives
     a message for delivery to a local mailbox, and encounters an error
     during the delivery, the sender may not receive a delivery failure
     notification. The most common reason is an error in a custom mail
     filtering script. The next most common reason is a configuration error
     (the Courier mail server authentication library gives the account's home
     directory, optional non-default mailbox location, the account's system
     userid and groupid; but they differ from the actual files and
     directories (the home directory or the account's mailbox does not exist,
     exists somewhere else, or they're owned by a different userid or
     groupid).

     When installing the Courier mail server for the first time, it is
     usually helpful to termporary turn off the default backscatter filters,
     by setting BOFHSUPPRESSBACKSCATTER to "none", as described below. Remove
     this setting after the Courier mail server is installed and its basic
     functions appear to be working.

   The term "backscatter" refers to non-delivery reports sent to a forged
   return address. SMTP was created a long time ago, in better times when
   everyone trusted each other. Anyone could provide any return address for
   any E-mail message.

   Times have changed. At the time this documentation is written, most
   surveys report that between 75% and 80% of Internet E-mail is junk E-mail
   or viruses, with a forged return address.

   Backscatter becomes a problem when a mail server does not reject unwanted
   mail. The mail server decides that the message is unwanted only after it
   is accepted. It generates a non-delivery notice, and sends it to the
   original message's return address. Because viruses and junk mail use
   random forged return addresses, the unfortunate victim of address forgery
   must deal with large amounts of useless non-delivery notices from the
   mailbox. Not to mention a bunch of uninformed people who think he is
   responsible for sending the virus or the junk mail to them.

   There's now a growing consensus that backscatter bounces should be
   considered E-mail abuse. The Courier mail server is already very good at
   minimizing the amount of backscatter, by the virtue of refusing to receive
   any mail to a nonexistent local mailbox. However it's still possible for
   the Courier mail server to bounce a received message. Several settings
   control how the Courier mail server filters out its own backscatter, and
   avoids becoming a nuisance to others.

   Two settings are available. The first setting instructs the Courier mail
   server to simply discard backscatter bounces. This is the
   ESMTP_BLOCKBACKSCATTER setting in the courierd configuration file. This
   setting lists the so-called "message sources" which are dropped by the
   SMTP client. All messages from any matching source are quietly discarded.
   The default setting lists one message source: a code that means "a
   delivery status notification for a message received via SMTP from a
   non-authenticated source". "Non-authenticated" means a message received
   from an IP address that does not have relaying privileges, and did not
   authenticate. It's also possible to include authenticated SMTP sources; or
   it's possible to disable this setting altogether, instructing the Courier
   mail server to deliver all bounces via SMTP, even if they may potentially
   be backscatter.

   Note that messages received in other ways (such as messages sent via the
   sendmail command) are not affected. Their bounces will be sent via SMTP in
   all cases (although there exists an undocumented setting to block those
   bounces too). Also, bounces are always delivered to local mailboxes, this
   setting is ignored for local mail deliveries.

   The default setting means that if the Courier mail server receives a
   message via SMTP for delivery to a local mailbox, and it bounces for some
   reason, the bounce will be discarded.

   The Courier mail server is also often used as a smarthost for SMTP
   clients. These SMTP clients either connect from trusted IP addresses (IP
   addresses that belong to the organization that runs the mail server), or
   that succesfully authenticate, using SMTP authenticate. If those messages
   bounce, the non-delivery report gets delivered, because the default
   setting only drops bounces from non-authenticated source (a connection
   from a trusted IP address is always processed as if the sender succesfully
   authenticated).

     NOTE: Sometimes the Courier mail server serves as a backup MX for
     another organization. If mail cannot be delivered to the primary MX (it
     rejects the message, or the message times out), the bounce will be
     discarded, because the message was probably received from a
     non-authenticated source.

   The second setting minimizes the possibility of generating a bounce, of
   any kind, in the first place. The second setting controls the backscatter
   suppression list, which is a list of blacklisted E-mail addresses.

   When the Courier mail server fails to deliver a message to an address,
   this address goes on the suppression list, and the Courier mail server
   will refuse to accept any more messages to the same address. If the
   delivery failure was a temporary failure, any future messages will also be
   turned away with a temporary error. A permanent delivery failure results
   in future messages rejected with a permanent error.

   Note that the suppression list does not apply to messages already accepted
   by the Courier mail server, and which are in its mail queue. The
   suppression list is checked when the Courier mail server is receiving a
   new message. The Courier mail server automatically clears an address from
   the suppression list after two hours. If the original message encountered
   a temporary delivery failure, The Courier mail server periodically tries
   again to re-deliver the message. If the message continues to encounter a
   temporary delivery failure, the clock starts running again, from the
   beginning, If a re-delivery attempts succeeds, the address is cleared from
   the suppression list, and the Courier mail server will now accept more
   messages to the same address, immediately.

   If a message keeps encountering temporary delivery failures, the time
   before re-delivery attempts gets longer. It's possible that it could take
   more than two hours for another delivery attempt, on a busy mail server.
   The address then falls off the list, and the Courier mail server will
   accept another message to the undeliverable address. This situation is
   unavoidable, but is not considered to be a major issue.

   The second setting is the BOFHSUPPRESSBACKSCATTER setting, in the bofh
   configuration file. See the courier(8) man page for more information. The
   default BOFHSUPPRESSBACKSCATTER setting also filters only messages from
   non-authenticated SMTP sources against the suppression list.

   The suppression list is not updated when problematic messages are manually
   removed from the mail queue (using the "courier cancel" command). Even
   though the stuck messages are deleted, The Courier mail server will
   continue to refuse messages to suppressed addresses, until they time out.
   Use the "courier clear" command to manually clear addresses from the
   suppression list, if so desired.

     NOTE: A mailbox that exceeded its storage quota results in temporary
     delivery failures. Therefore, when a mailbox fills up, The Courier mail
     server stops accepting any more messages to this mailbox (there might be
     one or two messages already in the mail queue, but that shouldn't be a
     major issue). Mail deliveries will resume when the mailbox goes below
     the quota (although this may take an hour, or two, as explained
     previously). It's possible that an existing version of the Courier mail
     server was originally modified to generate a permanent delivery failure
     for a quota exceeded condition. This change should now be undone, in
     order for backscatter suppression to work properly.

   The third setting is the DSNTOAUTHADDR=1 setting in the courierd
   configuration file. This setting, when enabled, alters bounce handling of
   messages that were received from an authenticated SMTP connection.

   Bounces of authenticated messages are processed according to the previous
   two settings, except that the bounce message gets sent (if it gets sent at
   all) to the authenticated login address, instead of the message's return
   address.

     NOTE: This works only if the Courier mail server is configured, via the
     Courier mail server Authentication Library, to validate login IDs that
     consist of a full E-mail address, "user@domain", with the login ID
     corresponding to the mailbox's E-mail address.

   Enabling this setting removes the possibility of the Courier mail server
   sending abusive backscatter bounces to external recipients, from a
   compromised trusted sender, even if the compromised trusted sender uses
   authenticated SMTP. Instead of sending the bounces to the forged return
   address, they get redirected to the sender's mailbox.

     NOTE: The authenticated address is used for bounces only. When the
     message gets sent to its listed recipients, the message's return address
     gets used, as usual.

     NOTE: Authenticated SMTP must be used for this option to have any
     effect. When relaying privileges are granted to explicit IP address
     ranges (see the preceding "Create smtp access list" section), The
     Courier mail server will not have the sender's authenticated login
     address (unless the sender voluntary authenticates).

Miscellaneous configuration

   Review/edit contents of various configuration files in
   /usr/lib/courier/etc:

     * courierd

       this file controls general aspects of the Courier mail server's
       message processing. A default file is installed with comments
       describing what the various options are. Review the default options,
       and make whatever changes you deem appropriate. You will probably need
       to make changes to this configuration file in order to select the
       correct way to deliver local mail (whether to have the Courier mail
       server handle the delivery directly, or whether to run procmail or
       maildrop). There are comments in this file that tell you what needs to
       be done to have the Courier mail server use a separate local mail
       delivery agent, such as procmail, for mail delivery. Read and follow
       the instructions there.

     * esmtpd

       this is an important file that controls the Courier mail server's
       ESMTP server. Options in this file include setting the maximum limit
       on simultaneous server connections, whether to disable certain
       optional SMTP features, whether or not you have a mail filter module
       installed, and whether or not DNS-based blacklists or whitelists are
       used.

     * esmtpd-msa

       this file controls the Courier mail server's ESMTP message submission
       server (RFC 2476). The settings in this file supplement the settings
       in esmtpd. The default startup script first reads esmtpd, then
       esmtpd-msa in order to initialize the ESMTP message submission server
       on port 587.

     * smtpaccess

       this configuration file/directory is used to ban explicit IP addresses
       from connecting to the ESMTP server at all, or to specify which IP
       address ranges are allowed to relay mail through the ESMTP server. The
       default file turns on relaying in a couple of reserved IP address
       ranges, as an example. The makesmtpaccess command must be executed for
       any changes to smtpaccess to take effect.

     * pop3d

       this file sets various options for the Courier mail server's POP3
       server. The Courier mail server's POP3 server can be used only if mail
       is stored in Maildirs. You will need to use another POP3 server if you
       choose to deliver your mail to legacy mailbox files. A default
       configuration file is installed, describing the available options.

     * imapd

       this file sets various options for the Courier mail server's IMAP
       server. The Courier mail server's IMAP server can be used only if mail
       is stored in Maildirs. You will need to use another IMAP server if you
       choose to deliver your mail to legacy mailbox files. A default
       configuration file is installed, describing the available options.

    Qmail compatibility mode.

 echo "qmail" >/usr/lib/courier/etc/dotextension

   Run this command if you are installing the Courier mail server on a system
   that's currently running the Qmail mail server. The Courier mail server
   will now read .qmail files for delivery instructions, instead of .courier
   files. The Courier mail server's .courier files are mostly compatible with
   Qmail's .qmail files, but there are some minor differences. Still, most of
   your .qmail files should work without too many problems.

Define local domains

   The configuration file /usr/lib/courier/etc/locals is a list of all the
   domains that are considered local. Mail to any address in any local domain
   is handled as a local delivery. If this file does not exist the Courier
   mail server will use the contents of the me configuration file, or it will
   obtain its machine name from the operating system.

   This file contains a list of domains, one per line. In most cases you need
   to initialize this file to contain every hostname that has a DNS A, or
   AAAA, record pointing to any IP address assigned to this machine,
   including "localhost". You will also need to include any domain that lists
   this machine as its primary MX relay.

   You may also include domain wildcards in locals by prefixing the domain
   with a period. For example: ".example.com" will treat any domain
   underneath example.com - like a.example.com, b.example.com - as a local
   domain. Note that this does not include example.com itself, so you may
   need to list it explicitly as well!

   NOTE: The makealiases command must be entered after making any changes to
   this file.

Create a list of domains to accept mail for

   If you would like your server to function as a backup mail relay for other
   domains, create /usr/lib/courier/etc/esmtpacceptmailfor. This is a plain
   text file, containing a list of domains, one per line. This file lists all
   domains your server will accept mail for. NOTE: if you create this file,
   you MUST include all your local domains. Usually you can simply append
   what you have in /usr/lib/courier/etc/locals. If
   /usr/lib/courier/etc/esmtpacceptmailfor does not exist, The Courier mail
   server will accept mail only for the machine name listed in
   /usr/lib/courier/etc/me, (or the system machine name).

   Like /usr/lib/courier/etc/locals, prepending a period to a domain name in
   esmtpacceptmailfor will cause the Courier mail server to accept mail for
   all subdomains of this domain.

OPTIONAL: Configure UUCP

   The Courier mail server is capable of sending and receiving mail via UUCP.
   The Courier mail server does not implement UUCP directly, but instead uses
   your existing UUCP software to send and receive mail.

   The Courier mail server's UUCP functionality has been tested with Taylor
   UUCP 1.06. It's likely that some minor tweaking will be necessary to get
   the Courier mail server working with other UUCP builds. Give it a shot,
   and keep an eye out for problems.

  /usr/lib/courier/etc/uucpme

   This configuration file must be initialized to list the UUCP node name
   that this machine is known as. Currently the Courier mail server does not
   support multiple UUCP node aliases for the same machine.

  /usr/lib/courier/etc/uucpneighbors

   This configuration file contains a list of all the nodes that your machine
   talks to via UUCP. Obviously this information will be a duplicate of the
   corresponding data in your existing UUCP configuration files, and some
   maintenance will be necessary to keep both lists in sync. That is,
   unfortunately, unavoidable. The makeuucpneighbors commands turns this
   plain text file into a database, which is what the Courier mail server
   uses directly. The format of the uucpneighbors configuration file is
   described in the makeuucpneighbors(8) manual page.

  /usr/lib/courier/etc/uuucprewriteheaders

   The Courier mail server automatically rewrites message envelope addresses
   from ESMTP to UUCP format. If this file exists, the addresses in the
   headers of messages sent to/from UUCP addresses will also be rewritten.

Configure UUCP domain aliases

   The Courier mail server can accept mail addressed to <user@example.com>,
   and then forward it to uucp!bang!path!user, via UUCP. This is done by
   adding a UUCP virtual domain alias to your aliases file, see "Create
   system aliases". Append the following entry to your /etc/aliases, then run
   the makealiases command:

    @example.com: uucp!bang!path!

   See the makealiases(8) manual page for more information.

OPTIONAL: Configure LDAP aliasing

   In addition to using LDAP for authentication and for managing accounts,
   The Courier mail server can use an LDAP directory for routing, or
   "aliasing" mail.

   The term "aliasing" refers to substituting one or more addresses for
   another address. A one-to-one substitution results in the Courier mail
   server accepting mail for one address, and delivering the mail to another
   address. A one-to-many substitution results in the Courier mail server
   accepting mail for one address, and delivering a separate copy of the
   message to every address defined by the alias.

   The Courier mail server supports a basic form of aliasing using a GDBM or
   DB-based database. The makealiases(8) command reads a plain text file
   containing the aliasing rules, the creates a GDBM or a DB database. Each
   recipient address is looked up in the database, and if an alias is defined
   for the recipient address, it is used in place of the original address.
   Aliasing can be used against individual addresses, one by one. An extended
   form of aliasing maps an entire domain to a single local address, using
   dot-courier(5) delivery instruction files.

   The Courier mail server can use an LDAP directory instead of a GDBM or a
   DB database, to perform essentially the same function. If OpenLDAP is
   available at time of installation, the installation script installs the
   courierldapaliasd(8) program and a ldapaliasrc configuration file. It will
   be necessary to enter appropriate information into ldapaliasrc, and
   arrange to run "courierldapaliasd start" at system boot time (it is a
   background daemon process that opens persistent connections to the LDAP
   server).

   Additional instructions for setting up LDAP-based aliasing are found in
   the courierldapaliasd(8) manual page.

OPTIONAL: Configure mail filtering

   The Courier mail server includes several options for selectively filtering
   mail. In general, The Courier mail server provides only the plug-in
   interfaces by which arbitrary external mail filters can be used to
   selectively accept or reject messages. The Courier mail server comes only
   with some sample code that demonstrates how to write a mail filter. An
   actual mail filter must be written and installed separately. Please note
   that running mail filters can have a non-trivial impact on mail system
   performance and throughput.

   The Courier mail server provides two mail filtering interfaces:

     * Global mail filters

       these filters are installed and will be used to filter every incoming
       message. Global mail filters are permanently running daemons that
       create and listen on a filesystem domain socket. Each new message that
       the Courier mail server receives must be acknowledged by every global
       mail filter. Note that if global mail filters are installed, but their
       daemons are not running, The Courier mail server will not accept any
       new messages.

     * Local mail filter

       this filter can be used when the message is addressed to a local
       recipient - when the Courier mail server itself will deliver the
       message to a physical mailbox. Local mail filtering is designed to be
       primarily used by the maildrop mail filter. With the local mail
       filtering installed, individual recipients can create files containing
       mail filtering instructions that can selectively accept or reject
       individual messages.

   See courierfilter(8) for more information on global mail filters.

   See maildropfilter(7) for more information on local mail filters.

  Miscellaneous UUCP configuration

   The Courier mail server sends UUCP mail by running rmail via uux. The
   configuration script searches for the uux command in the default search
   path. If your uux command is not in a directory that's in your search path
   you will have to modify PATH before running configure.

   The Courier mail server receives UUCP mail by expecting your UUCP software
   to run the rmail command, which is installed in /usr/lib/courier/bin.
   (It's actually a soft link to sendmail, but we'll talk about it later).
   Your UUCP software probably does not run commands from this directory by
   default, so you will have to make the necessary adjustments. You can
   always create another soft link in a directory that UUCP searches by
   default.

Starting and stopping the Courier mail server

   To start the Courier mail server, run the command
   /usr/lib/courier/sbin/courier start. To stop the Courier mail server, run
   the command /usr/lib/courier/sbin/courier stop. See the courier(8) manual
   page for more information.

   You should add these commands to your system startup and shutdown scripts.

   Note that this command starts and stops the Courier mail server's core
   processes only. It does not start any additional daemon processes that you
   may need, such as the mail filtering daemon, the ESMTP server daemon, the
   POP3 server daemon, or the IMAP server daemon.

   The commands courierfilter start, courierfilter stop, esmtpd start, esmtpd
   stop, esmtpd-msa start, esmtpd-msa stop, pop3d start, pop3d stop, imapd
   start, and imapd stop (all commands are installed in the sbin directory)
   are used to start or stop their respective daemons, and they should be
   added to your system startup and shutdown scripts, where required. As
   described in the relevant manual pages, courierfilter should be the first
   daemon process to start, and the last one to terminate. The remaining
   daemons may be started in any order.

Run the Courier mail server in parallel to your mail server

   You now have several options for migrating from your existing mail server
   to the Courier mail server:

     * Your existing mail server can continue to handle incoming mail, by
       listening on the smtp port. The Courier mail server will be used to
       send all outgoing mail. This is accomplished by configuring your mail
       software to run /usr/lib/courier/bin/sendmail to send mail, instead of
       your current sendmail program.
     * The Courier mail server can handle incoming mail by listening on the
       smtp port, and your existing mail server can continue to handle all
       outgoing mail. You will need to stop your existing mail server from
       listening on the smtp port, and run the following command:

 /usr/lib/courier/sbin/esmtpd start

       from your system start up script. You should also add
       /usr/lib/courier/sbin/esmtpd stop to your system shutdown script. Note
       that there's a separate script that starts the ESMTP submission server
       on port 587 - /usr/lib/courier/sbin/esmtpd-msa, that is used in an
       analogous fashion.

OPTIONAL: Configure ESMTP authentication and SSL

   The Courier mail server supports authenticated ESMTP in order to grant
   ESMTP relaying privileges to remote users. The following steps set up
   authenticated ESMTP:

     * Edit /usr/lib/courier/etc/esmtpd and initialize the ESMTPAUTH
       configuration setting. The configuration file
       /usr/lib/courier/etc/esmtpd-msa is used for the ESMTP submission
       server on port 587. Setting this variable in esmtpd is sufficient,
       because esmtpd-msa merely supplements the settings in esmtpd.
       Explicitly initialize this setting in esmtpd-msa only if you wish to
       apply it to port 587 only.

       ESMTPAUTH is a list of SASL authentication methods to use use.
       Currently, The Courier mail server supports LOGIN, PLAIN, CRAM-SHA1
       and CRAM-MD5. The list of authentication methods is sometimes
       influenced by the installed authentication modules in the Courier mail
       server Authentication Library. Not all authentication modules
       implement CRAM-MD5/SHA1. The authentication modules that support
       CRAM-MD5/SHA1 authentication are: authuserdb, authldap, authmysql, and
       authpgsql.

     * Your authentication modules may require additional configuration, you
       will have to take care of that too. For example, authpam - the PAM
       authentication module - requires that you also configure your PAM
       library. In this case, you need to configure your PAM library to
       support the "esmtp" service. The PAM library configuration details
       depend on your particular operating system, and are beyond the scope
       of this document. Consult the documentation for your PAM library for
       more information.
     * Restart the Courier mail server.

  ESMTP over TLS/SSL

   The Courier mail server also supports ESMTP over TLS/SSL, by using the
   ESMTP STARTTLS extension:

     * To add SSL support you have to install OpenSSL or GnuTLS before
       installing the Courier mail server. Download OpenSSL from
       http://www.openssl.org/, or GnuTLS from http://www.gnutls.org.

       Follow OpenSSL's or GnuTLS's installation instructions, then build the
       Courier mail server.

         NOTE: Most systems already have an available OpenSSL or GnuTLS
         package. Do not build OpenSSL or GnuTLS yourself, if a prebuilt
         package is already available. Just install the prebuilt package.

         NOTE: The development libraries must be installed in addition to the
         runtime package, in order to build the Courier mail server. On most
         systems, the development files (header files, libraries, etc...) are
         provided in a separate "devel" package. The base OpenSSL/GnuTLS
         package is not sufficient to build the Courier mail server, the
         development libraries must be installed.

       The OpenSSL library is selected when both OpenSSL and GnuTLS libraries
       are found by the configure script. Use the --with-gnutls option to
       explicitly select GnuTLS library over OpenSSL.

     * STARTTLS is enabled simply by installing an X.509 certificate as
       /usr/lib/courier/share/esmtpd.pem. If this file exists, the STARTTLS
       ESMTP extension will be automatically advertised. This file must be
       owned by the userid the Courier mail server is installed as, and MUST
       NOT be world readable!
     * Note that SSL requires a signed X.509 certificate. You can generate
       your own self-signed certificates with OpenSSL, but mail clients will
       display a warning message the first time they connect to the server.
       To prevent the warning message, you will need to pay money to have
       your certificate signed by a certificate authority. The gory details
       of setting up SSL is beyond the scope of this document, and you should
       consult the OpenSSL documentation for more information.
     * The certificate must be installed as
       /usr/lib/courier/share/esmtpd.pem. This file MUST NOT HAVE any group
       or world permissions! It must be owned by the Courier mail server
       userid (the userid used to install the Courier mail server, usually
       courier or daemon).
     * In times of extreme desperation the script
       /usr/lib/courier/sbin/mkesmtpdcert can be used to generate
       /usr/lib/courier/share/esmtpd.pem. This script will silently terminate
       if OpenSSL is not installed, or if the esmtpd.pem certificate file
       already exists (so it will not be overwritten). This makes it easier
       to have this script invoked from a package install script.
     * Restart the Courier mail server's ESMTP server after installing the
       X.509 certificate.

   The Courier mail server will also use TLS/SSL when sending ESMTP mail,
   automatically. If the remote mail server support STARTTLS, The Courier
   mail server will use it automatically.

   SSL/TLS settings for the ESMTP client can be adjusted in the
   /usr/lib/courier/etc/courierd configuration file. When sending mail using
   SSL, The Courier mail server can optionally verify the remote server's
   X.509 certificate. This is done by setting ESMTP_TLS_VERIFY_DOMAIN to 1,
   in /usr/lib/courier/etc/courierd. Also, TLS_PEERCERTDIR must be set to a
   directory that contains PEM files of X.509 certificates of trusted root
   certificate authorities. The PEM files must be hashed by OpenSSL's
   c_rehash script. When this is done, the remote server's X.509 certificate
   must signed by trusted root CA, else the Courier mail server will bounce
   the recipient.

   The configuration script checks for the system's list of trusted
   certificate authorities, and initializes TLS_TRUSTCERTS in the courierd
   configuration file, during installation. When the Courier connects to a
   remote server, setting ESMTP_TLS_VERIFY_DOMAIN to 1 in the courierd
   configuration file (usually /usr/lib/courier/etc/courierd or
   /etc/courierd) enables certificate verifications. However, many mail
   servers on the Internet use self-signed certificates, so this is generally
   of little use.

OPTIONAL: Configure ESMTP smarthosting

   Initialize the esmtproutes configuration file if all outgoing mail need to
   be forwarded to your Internet provider's mail server, or some other
   "smarthost". See courier(8) for more information:

 : relay.example.com

   This forwards all mail to relay.example.com

 : relay.example.com,587

   This forwards all mail to relay.example.com on port 587.

 : relay.example.com,465 /SECURITY=SMTPS

   This forwards all mail to relay.example.com on port 465, using encrypted
   SMTP.

   If the smarthost requires authentication, initialize the esmtpauthclient
   configuration file:

 relay.example.com,587 john@example.com snerkle

   When the Courier mail server connects to relay.example.com on port 587, it
   will authentication using the userid of "john@example.com" and password
   "snerkle".

OPTIONAL: Configure the SECURITY ESMTP extension

   The Courier mail server includes an experimental extension to ESMTP that
   can be used to set up secure E-mail delivery between trusted mail relays
   over an untrusted network. This is implemented by an experimental ESMTP
   extension in the Courier mail server. Therefore, at present time both the
   sending and the receiving mail relay must be running the Courier mail
   server that's configured to support this extension. The specification for
   this ESMTP extension is publicly available. This is a very small extension
   of the existing, draft-standard STARTTLS ESMTP extension. The SECURITY
   extension should only require minor changes to existing mail servers and
   clients that already implement STARTTLS.

  Overview

   The first necessary step is to read the formal definition of the SECURITY
   extension, which can be found on http://www.courier-mta.org. Although the
   following instructions do not use any information directly from this
   document, it is important to understandi how this mechanism works. This
   will be very useful in troubleshooting. This is not called an
   "experimental" extension just for the hell of it.

   The SECURITY extension builds on top of several existing, proven,
   technologies in order to deliver mail with the highest level of security
   that can possibly be implemented using the existing technology. The
   several steps in implementing the SECURITY extension:

    1. Install and configure the STARTTLS ESMTP extension. This extension
       uses TLS/SSL encryption for sending mail.
    2. Create a private, controlled, X.509 Certificate Authority.
    3. Use the private CA to sign X.509 certificates of all mail nodes in the
       trusted mail network. This CA's certificate is also installed in every
       trusted mail node.

   The SECURITY extension is an optional tag that's attached to an E-mail
   message. The Courier mail server requires STARTTLS to forward
   SECURITY-tagged messages, and the receiving mail nodes must present an
   X.509 certificate, signed by the private Certificate Authority, before the
   Courier mail server will send the message. The Courier mail server will
   refuse to send the message to a mail node that does not support STARTTLS,
   or doesn't present a suitable X.509 certificate.

   Therefore, in an ideal world, mail clients will simply tag messages with
   the SECURITY extension. Obviously, this means that mail clients must be
   updated to implement this feature. Until this happens, The Courier mail
   server will provide a workaround that automatically tags all messages for
   selected domains with the SECURITY extension. This is not a perfect
   solution, and it has some minor limitations, which will be mentioned
   later.

  Install and configure the STARTTLS ESMTP extension

   The first step is to implement ESMTP STARTTLS. Use the instructions
   elsewhere in this document to activate ESMTP STARTTLS support. The
   following instructions use the scripts from OpenSSL 0.9.6, but should also
   work with OpenSSL 0.9.5a.

  Create a private X.509 Certificate Authority

   Create an empty subdirectory:

     mkdir /etc/myca
     cd /etc/myca

   There's a convenient OpenSSL script called CA.pl that you want to copy to
   the current directory:

     cp /usr/share/ssl/misc/CA.pl .

   Your OpenSSL package may have CA.pl installed someplace else. Find it, and
   copy it to /etc/myca. The CA.pl needs to be slightly modified before it
   can be used. Find the following commands in CA.pl, and change them as
   follows:

   Replace:

       system ("$REQ -new -keyout newreq.pem -out newreq.pem $DAYS");

   replace with:

       system ("$REQ -new -nodes -keyout newreq.pem -out newreq.pem $DAYS");

   Also replace:

       system ("$REQ -new -x509 -keyout " .
           "${CATOP}/private/$CAKEY -out ${CATOP}/$CACERT $DAYS");

   replace with:

       system ("$REQ -new -nodes -x509 -keyout " .
           "${CATOP}/private/$CAKEY -out ${CATOP}/$CACERT $DAYS");

   The CA.pl script creates password-protected certificate keys by default.
   Password protected certificates currently do not work with the Courier
   mail server. Adding the -nodes parameter turns off password protection.
   This means that it is vital to make sure that the trusted mail relays are
   properly secured. All the encryption in the world will not be of much use
   if the mail relays are running a rootable FTP server (for example).
   Anyway, run CA.pl to create a new certificate authority:

     ./CA.pl -newca

   CA.pl prompts for a basic description of the new CA, then creates the
   certificate and the certificate key. The CA's root certificate is saved in
   /etc/myca/demoCA/cacert.pem.

  Use the private CA to sign X.509 certificates of all trusted mail nodes

   This step must be performed to create the X.509 certificates for every
   mail node in the trusted secure network. First, a certificate request is
   created:

     ./CA.pl -newreq

   CA.pl prompts for a basic description of the new certificate. Special care
   must be paid to the "commonName" setting. "commonName" MUST be set to the
   hostname of the trusted mail node, NOT its mail domain. For example, given
   the following DNS setup for example.com:

      example.com.  MX 10 mx1.example.com.
      example.com.  MX 20 mx2.example.com.

      mx1.example.com. A 192.68.0.1
      mx2.example.com. A 192.68.1.1

   This domain will need two certificates, one with "commonName" set to
   "mx1.example.com", and one with "commonName" set to mx2.example.com.

   Running ./CA.pl produces a certificate request in the file newreq.pem. Run
   the following command to sign it:

     ./CA.pl -signreq

   This step creates the file newcert.pem that contains a new signed
   certificate. The private key from the original certificate request must be
   appended to this file, before the certificate can be used. Simply take the
   newreq.pem file from the previous step, and append the private key in that
   file to newcert.pem. The resulting certificate file should look something
   like this:

    [ description of the certificate ]

 -----BEGIN CERTIFICATE-----

    [ binary goo ]

 -----END CERTIFICATE-----
 -----BEGIN RSA PRIVATE KEY-----

    [ binary goo ]

 -----END RSA PRIVATE KEY-----

   The OpenSSL documentation contains instructions on how to perform the
   equivalent procedure with Diffie-Hellman instead of RSA.

  Configure trusted mail nodes

   Two files must be installed on every trusted mail node.

     * The mail node's certificate, the newcert.pem file from the previous
       step. The following documentation assumes that this file is installed
       as /etc/mycert.pem. This mail node will use this certificate to
       authenticate itself to other trusted mail nodes.
     * The certificate authority file, cacert.pem. The following
       documentation assumes that it's installed as /etc/cacert.pem. The CA's
       certificate is used to authenticate other trusted mail nodes.

   Edit the /usr/lib/courier/etc/esmtpd configuration file. Set TLS_CERTFILE
   to /etc/mycert.pem. The Courier mail server will use TLS_CERTFILE to
   authenticate itself to other trusted mail nodes.

   Edit the /usr/lib/courier/etc/courierd configuration file. Set
   TLS_TRUSTSECURITYCERTS to /etc/cacert.pem. The Courier mail server will
   not send ESMTP mail tagged with the SECURITY extension to other mail
   relays unless they produce a certificate that's signed by
   TLS_TRUSTSECURITYCERTS.

  Testing

   The following simple steps can be carried out to verify that everything is
   working correctly. These examples use two mail nodes called
   send.example.com and receive.example.com. The test messages are sent from
   send.example.com, and are addressed to receive.example.com. The Courier
   mail server must be restarted on both send and receive, after
   reconfiguring the machines for each test. It is not strictly necessary to
   do this every time, actually, but it's simply easier to do make it a part
   of the routine. It is necessary to restart both the main the Courier mail
   server daemon processes as well as the separate ESMTP daemon process (on
   receive):

     courier stop
     courier start
     esmtpd stop
     esmtpd start

    1. Temporary get rid of /usr/lib/courier/bin/couriertls wrapper on
       receive.example.com. Rename it to couriertls.save. STARTTLS is
       automatically disabled if couriertls is missing,
    2. Run the following command on send.example.com:

     echo "To: postmaster" | /usr/lib/courier/bin/sendmail \
               -S STARTTLS postmaster@receive.example.com

       This message should bounce back since receive has STARTTLS disabled.

    3. Restore couriertls on receive.example.com, but then rename it on
       send.example.com. The situation is now reversed, and the test message
       should still bounce.
    4. Restore couriertls on send.example.com. Edit receive's
       /usr/lib/courier/etc/esmtpd file. Comment out the current TLS_CERTFILE
       setting (which points to the private CA certificate). Reset
       TLS_CERTFILE to /usr/lib/courier/share/esmtpd.pem, which is the
       self-signed test certificate created by the mkesmtpdcert script, when
       STARTTLS support in the Courier mail server was first set up.

       Send a test message WITHOUT the "-S STARTTLS" option. This message
       should go through, assuming all the other setting in all configuration
       files are the initial defaults. The regular ESMTP STARTTLS extension,
       without authentication, will be used the deliver this message. Verify
       this by checking the headers in the received message on
       receive.example.com.

       Send a test message WITH the "-S STARTTLS" option. It should bounce,
       even though receive.example.com supports STARTTLS. That's because it
       is using an X.509 certificate that's not signed by the private CA
       authority.

    5. Restore TLS_CERTFILE on receive, and send a test message with the -S
       STARTTLS option, which should now go through.

  Force SECURITY for selected domains

   As demonstrated by the test messages, messages must be tagged with the
   SECURITY extension in order for them to be securely transmitted. This must
   be done by the sending mail client. Until mail clients support SECURITY
   The Courier mail server can automatically add the SECURITY tag to every
   message addressed to a domain. This is done by entering the domain in the
   esmtproutes configuration file using the following syntax:

 receive.example.com:  /SECURITY=STARTTLS

   Repeat the tests in the previous section, but this time add and delete
   this entry in /usr/lib/courier/etc/esmtproutes instead of using the -S
   STARTTLS option. The test messages must still bounce or not bounce in the
   same way.

   Consult the courier(8) manual page for more information on the esmtproutes
   configuration file.

  Limitations

   This setup makes it virtually impossible to intercept mail traffic between
   trusted mail nodes. Even if the DNS cache is poisoned to intercept mail to
   a hostile mail node, mail will not go through since the attacker will not
   have a signed X.509 cert. However, all is lost if the mail nodes
   themselves are compromised directly. After securing the compromised node,
   everything must be rebuilt. A new CA must be created, and all mail nodes
   must now receive new certificates. Once support for certificate revocation
   lists is improved, this situation will get somewhat better.

   Another possible way to mitigate that possibility is to use a different
   certificate authority for every trusted mail node. TLS_TRUSTSECURITYCERTS
   can point to a directory, instead of a file. This directory can contain
   multiple certificate authorities (hashed by OpenSSL's c_rehash script).
   Then, only the compromised mail node's authority certificate needs to be
   tossed out, regenerated, and redistributed.

   TODO: it may be possible to avoid generating individual certificates, and
   distribute self-signed certificate authority certs only, with a
   properly-initialized commonName field. This needs to be researched.

   There are some minor differences between using -S STARTTLS versus putting
   the domain into esmtproutes. If the sending mail node forward mail to this
   domain via UUCP, -S STARTTLS will bounce. Since esmtproutes does not apply
   to UUCP, putting this domain in esmtproutes will have no effect
   whatsoever.

OPTIONAL: Configure the Sender Policy Framework

   The Courier mail server can optionally check the return address on all
   SMTP mail for the sender's published Sender Policy Framework (SPF). Keep
   in mind SPF is an experimental protocol that's still maturing. The Courier
   mail server's SPF configuration is set up in the "bofh" configuration
   file, and is fully explained in the courier(8) manual page.

OPTIONAL: Configure the IMAP server

   The Courier mail server includes an integrated IMAP server. The following
   steps set it up:

     * Edit /usr/lib/courier/etc/imapd. If you want to use IMAP SASL
       authentication, set up the IMAP_CAPABILITY variable. It performs the
       equivalent function as the ESMTPAUTH variable in the esmtpd
       configuration file, except that IMAP_CAPABILITY also sets several
       other IMAP capabilities that are advertised to IMAP clients. Also, for
       IMAP, CRAM-MD5/SHA1 authentication has been tested, and is known to
       work, so it is listed as a default. Also, note than if the authpam
       authentication module is used, you will need to configure the "imap"
       PAM service. Other authentication modules have their own requirements
       too.
     * Uninstall any existing IMAP server that you have, remove the entry for
       the IMAP port in /etc/inetd.conf, and restart the inetd daemon.
     * Add the following command to your system startup script

 /usr/lib/courier/sbin/imapd start

       Of course, add /usr/lib/courier/sbin/imapd stop to your shutdown
       script too.

   NOTE: if you have previously installed the stand-alone version of the
   Courier IMAP server, you will need to remove it prior to using the
   directly integrated version. They use the same base source code, but have
   a slightly different configuration.

   NOTE: this IMAP server supports maildirs only. It does not support mbox
   file mailboxes.

Configure IMAP shared folders

   It is possible to share folders between different mailboxes, via IMAP. See
   the file maildir/README.sharedfolders.(txt|html) for more information.

OPTIONAL: Configure IMAP over SSL

   To add SSL support you have to install OpenSSL or GnuTLS before installing
   the Courier mail server. Download OpenSSL from http://www.openssl.org/, or
   GnuTLS from http://www.gnutls.org.

   OpenSSL's support is well-tested, the GnuTLS version is a relatively new
   addition, and is considered experimental. Follow OpenSSL's or GnuTLS's
   installation instructions, then build the Courier mail server.

     NOTE: Most systems already have an available OpenSSL or GnuTLS package.
     Do not build OpenSSL or GnuTLS yourself, if a prebuilt package is
     already available. Just install the prebuilt package.

     NOTE: The development libraries must be installed in addition to the
     runtime package, in order to build the Courier mail server. On most
     systems, the development files (header files, libraries, etc...) are
     provided in a separate "devel" package. The base OpenSSL/GnuTLS package
     is not sufficient to build the Courier mail server, the development
     libraries must be installed.

   The OpenSSL library is selected when both OpenSSL and GnuTLS libraries are
   found by the configure script. Use the --with-gnutls option to explicitly
   select GnuTLS library over OpenSSL.

   The /usr/lib/courier/etc/imapd-ssl configuration file sets some additional
   options for SSL support, which you may need to adjust. Consult that
   configuration file for additional information. Then, you also have to run
   the /usr/lib/courier/sbin/imapd-ssl script from your system startup and
   shutdown scripts, just like the /usr/lib/courier/sbin/imapd script. You
   may accept both SSL and non-SSL connections by running both scripts.

   Note that SSL requires a valid, signed, X.509 certificate to be installed
   where the Courier mail server expects to find it. The default location for
   the X.509 certificate, in PEM format, is /usr/lib/courier/share/imapd.pem.
   The X.509 certificate must be signed by a certificate authority that is
   known to the IMAP client. You can generate your own self-signed
   certificate by running the script /usr/lib/courier/share/mkimapdcert which
   will work too, except that IMAP clients using SSL will display a warning
   message the first time they connect to the server. To get rid of the
   warning message you'll have to pay for a signed X.509 certificate. The
   gory details of setting up SSL is beyond the scope of this document, and
   you should consult the OpenSSL documentation for more information.

   The mkimapdcert script will not overwrite an existing imapd.pem
   certificate, in order to allow precompiled packages to simply call
   mkimapdcert after installation, without worry.

   The IMAP server also supports the IMAP STARTTLS extension as an
   alternative or a complement to IMAP over SSL. The
   /usr/lib/courier/etc/imapd-ssl configuration file is also used to enable
   or disable IMAP STARTTLS, which has all the same requirements and
   prerequisites as IMAP over SSL.

OPTIONAL: Sending mail via an imap connection

   This server allows using the IMAP connection to send E-mail. Normally, the
   IMAP protocol provides only access to mail in an existing mail account,
   and mail clients must use SMTP in order to send mail. The Courier IMAP
   server has an optional setting to enable mail to be send via an IMAP
   connection in a manner that should work with all existing IMAP mail
   clients. This can be useful when an account is logged in from a shared
   access pool which normally blocks most access to the SMTP port.

   This is implemented by enabling a setting in the imapd configuration file
   that designates a folder as a special "Outbox" folder. The default setting
   is a folder called "Outbox" (IMAP path INBOX.Outbox), but the name can be
   changed to anything. This folder, for the most part, is no different than
   any other folder. If a folder by that name doesn't exist, it needs to be
   created, just like any other IMAP folder. It looks and acts like any other
   folder, except that each message added to the folder, via IMAP's APPEND or
   COPY command, will also be mailed out by the Courier IMAP server to the
   addresses listed in the To:, Cc:, and Bcc: headers.

   It should be possible to use this to send mail from any IMAP client by:

    1. Composing a draft message, telling the IMAP client to save the draft
       message in its drafts folder on the IMAP server.
    2. Opening the drafts folder, and moving or copying the message to the
       Outbox folder.
    3. The act of copying the message into the Outbox folder will send the
       mail. There won't be any explicit notification to the fact that the
       message was sent, so it's a good idea to include your own E-mail
       address on the Cc: list.

     NOTE: it is tempting to configure the IMAP mail client to use Outbox as
     its default folder for saving drafts. Resist the temptation. If you
     forget, you'll save a partially completed draft, which will be then
     obediently mailed out.

     NOTE: the message, in addition to being sent, will be saved in the
     folder in the normal fashion. After saving the message, reopen the
     Outbox folder and delete the sent message, or move it someplace else.

     NOTE: when enabled, the Courier IMAP server will advertize a private
     XCOURIEROUTBOX IMAP capability. It is theoretically possible to code an
     IMAP mail client that reads this capability and automatically configures
     itself accordingly -- when this IMAP capability is present -- to send
     E-mail in the normal way but using the IMAP connection. At this time,
     I'm not aware of any actual mail clients that know how to do this.

     NOTE: many mail clients save some additional internal information in
     headers of draft messages. The internal information is normally removed
     before the mail client sends the message. Make sure that none of this
     extra information is something that should not be mailed out.

OPTIONAL: Configure IMAP realtime folder status updates

   If FAM, the File Alteration Monitor (http://oss.sgi.com/projects/fam/) or
   Gamin is installed, it will be possible to allow multiple clients to open
   the same folder, and have all clients to be simultaneously notified of any
   changes to the folder contents.

   After installing the server see the imapd(8) manual page for more
   information.

OPTIONAL: Configure SMAP

   Starting with the Courier mail server 0.43, the IMAP server supports an
   experimental mail access protocol, dubbed "Simple Mail Access Protocol".
   SMAP is an experiment to provide enhanced mail processing beyond what's
   currently possible with IMAP. SMAP's purpose is to prototype and develop
   advanced mail access functionality that's not possible with IMAP. SMAP is
   disabled by default. Uncomment the SMAP_CAPABILITY setting in the imapd
   configuration file in order to enable SMAP. The Cone mail client supports
   SMAP.

OPTIONAL: Configure the POP3 server

   The Courier mail server includes an integrated POP3 server. The following
   steps will set it up:

     * Edit /usr/lib/courier/etc/pop3d. Very few POP3 clients support POP3
       SASL authentication, but if you want to use it, for some reason,
       uncomment the POP3AUTH variable. It performs the equivalent function
       as the corresponding variable in the esmtpd and imapd configuration
       files. For POP3, SASL LOGIN authentication has been tested, and is
       known to work, and CRAM-MD5/SHA1 has not been tested. Also, note than
       if authpam is used, you will need to configure the "pop3" PAM service.
       Other authentication modules have their own requirements.
     * Uninstall any existing POP3 server that you have, remove the entry for
       the POP3 port in /etc/inetd.conf, and restart the inetd daemon.
     * Add the following command to your system startup script:

 /usr/lib/courier/sbin/pop3d start

       Of course, add /usr/lib/courier/sbin/pop3d stop to your shutdown
       script too.

   NOTE: this POP3 server supports maildirs only. It does not support mbox
   file mailboxes.

OPTIONAL: Configure POP3 over SSL

   Implementing POP3 over SSL is very similar to implementing IMAP over SSL.
   The only differences are that the startup/shutdown command is
   "/usr/lib/courier/sbin/pop3d start" and "/usr/lib/courier/sbin/pop3d
   stop", the configuration file is /usr/lib/courier/etc/pop3d, the name of
   the required SSL certificate is /usr/lib/courier/share/pop3d.pem, and the
   command to generate a test SSL certificate is mkpop3dcert.

OPTIONAL: Configure the IMAP/POP3 aggregator proxy

   It is possible to distribute IMAP and POP3 mailboxes between multiple
   server.

   See imap/README.proxy for more information.

CERTIFICATE AUTHENTICATION

   The Courier mail server can use SSL certificates for authentication
   purposes. That is, instead of using a login ID and a password, for
   accessing the mailbox, The Courier mail server uses a client-side SSL
   certificate. For certificate authentication purposes, one of the fields in
   your certificates' subject must match the login ID in the authentication
   database. Consider the following certificate:

 ...
 Subject: C=US,ST=New York,L=New York,O=Acme Widgets Inc,CN=John Smith,emailAddress=johnsmith@example.com

   If the emailAddress field is configured as the login ID, the
   authentication database must provide login details for
   johnsmith@example.com. To enable certificate authentication, edit the
   following configuration files in sysconfdir: imapd-ssl, pop3d-ssl, esmtpd
   and esmtpd-ssl (the esmtpd files enable SSL certificate authentication for
   incoming SMTP connections, if a good SSL certificate is provided, the
   client receives mail relaying privileges). All of these configuration
   files require the same set of changes:

     * Set TLS_TRUSTCERTS to the filename with your certificate authority's
       X.509 certificate.

     * Change the TLS_VERIFYPEER setting to "PEER". The setting can also be
       changed to "REQUIREPEER" to require all SSL/TLS connections to provide
       a certificate. Otherwise, it is optional. If the mail client provides
       an SSL certificate, it may be used to authenticate. Without a
       certificate, password-based authentication remains an option.

     * Change the TLS_EXTERNAL setting to the name of the certificate subject
       field that gives the login ID. In the above example, this would be
       "TLS_EXTERNAL=emailaddress".

         NOTE: GnuTLS's certtool uses "email" as the name of this field. If
         the Courier mail server is compiled with GnuTLS, you should still
         specify this field as "emailaddress".

OPTIONAL: Configure the webmail server

   The integrated webmail server is made up of two parts. The first part, by
   default, is installed as /usr/lib/courier/libexec/courier/webmail. You can
   simply copy this binary executable to your web server's cgi-bin directory,
   or create a link from the cgi-bin directory to this program. This is a
   small stub program that connects, via a local socket, to the sqwebmaild
   daemon process, which implements the webmail service. It is necessary to
   start the webmail server by adding the following command to the system
   startup screen (so that the webmail server gets automatically started at
   boot):

   /usr/lib/courier/sbin/webmaild start

   (It is also possible to run "webmaild stop" from the system shutdown
   script in order to shut down webmail service gracefully).

   Note that the webmail server is used to access mail in existing accounts
   only. There is no provision to create accounts through the webmail
   interface (nor there should be).

   Your web server also needs to be configured to use HTTP/1.0 when talking
   to any MSIE browser. The MSIE browser has a number of bugs in its HTTP/1.1
   implementation, at least as of MSIE 4.x and 5.x. You must configure your
   web server to use HTTP/1.0 when talking to any MSIE browser (at least
   until MSIE gets fixed). The problem has to do with downloading
   attachments. Apparently, MSIE forgets how MIME works, when it uses
   HTTP/1.1. For the Apache server, insert the following directive in
   httpd.conf:

 BrowserMatch "MSIE" nokeepalive downgrade-1.0 force-response-1.0

   Recent versions of Apache already have a similar directive for a specific
   version of MSIE, MSIE 4.0b2. Just replace it with a browsermatch for any
   MSIE version.

  SELinux

   The following extension may be necessary to make webmail work when SELinux
   kernel extensions are turned on:

 allow httpd_sys_script_t var_t:sock_file write;
 allow httpd_sys_script_t unconfined_t:unix_stream_socket connectto;

  Spell checking

   The webmail server can use either the ispell or the aspell package for
   spell checking. Install ispell or aspell before installing the Courier
   mail server.

   NOTE: Courier mail server assumes that the spell checking dictionary is
   called "english". Some systems use a different name for the default spell
   checking dictionary. To change the name of the spell checking dictionary
   used by the webmail server, put the name of the dictionary into the file
   /usr/lib/courier/share/sqwebmail/html/en-us/ISPELLDICT.

  Images

   It is also necessary to install the static icon images used by the webmail
   server. The installation script copies the static images to the
   /usr/lib/courier/share/sqwebmail/images directory. By default, the webmail
   server uses the URL "/webmail/" to specify the location of the static
   images, for example: /webmail/folders.gif. This means that you must create
   a subdirectory called "webmail" in your web server's document root -
   typically /usr/local/etc/apache/htdocs/webmail, or
   /usr/local/www/htdocs/webmail, or something similar. You will need to
   determine the actual location of your web root directory, which varies
   from system to system. Then, create a subdirectory named "webmail", and
   copy all the icons to that directory.

   Another possibility is to install a soft link, instead of creating the
   webmail sub directory, and point the soft link to
   /usr/lib/courier/share/sqwebmail/images (you also must make sure that the
   web server is configured to follow symlinks).

   There is a configuration option, --enable-imageurl, that can be used to
   use something other than /webmail/ as the URL prefix for images.

  Alternative timezones

   The file /usr/lib/courier/share/sqwebmail/html/en-us/TIMEZONELIST contains
   a list of alternative timezones. By default all dates and times are shown
   in the server's default timezone, and the dropdown list on the login
   screen can be used to select an alternative timezone. The default
   alternative timezone list that lists only a small number of timezones.
   Additional timezones can be entered into this file to be shown on the
   login web page.

  LDAP address book import

   The webmail server can import E-mail addresses from public LDAP address
   books into an individual address book. A default systemwide list of
   accessible LDAP address books is defined for everyone, and individuals can
   configure additional LDAP address books for themselves.

   The OpenLDAP development toolkit must be installed before building
   SqWebMail, in order for LDAP search code to compile.

   The file ldapaddressbook configuration file should contain a default
   systemwide list of accessible address book. See courier(8) for more
   information. A default file will be installed, listing some common
   Internet address books. Each line in this file contains the following
   information:

 name<tab>host<tab>port<tab>suffix<tab>binddn<tab>bindpw

   <tab> is a single ASCII TAB character. name is the unique name for this
   LDAP server. host and port specify the connection parameters. suffix
   specifies the root LDAP entry whose subtree gets searched. The binddn and
   bindpw fields are not presently used (they were used in earlier version of
   the webmail server, before the LDAP search interface was rewritten and
   simplified).

OPTIONAL: Configure webmail calendaring

   Optional calendaring services can be enabled in the webmail server. Right
   now, the current implementation provides basic calendaring services. For
   more information on calendaring, see the file pcp/README.html.

  Webmail session timeouts

   A login session is automatically logged out after certain period of
   inactivity. The timeout period defaults to 20 minutes, and is set by the
   --enable-softtimeout option to the configure script. It is also possible
   to adjust this value by setting the SQWEBMAIL_TIMEOUTSOFT environment
   variable. For example, with Apache, by adding the following to httpd.conf:

 SetEnv SQWEBMAIL_TIMEOUTSOFT 3600

   There is also a hard timeout, which logs out a session no matter what. The
   default of two hours is changed with the --enable-hardtimeout option to
   the configure script, and the SQWEBMAIL_TIMEOUTHARD environment variable.

   WARNING:

   The hard timeout interval is used to calculate the maintenance of the
   login cache (if that option is selected). This factor is used in the
   cleancache.pl cleanup script, and changes to this value must be
   coordinated appropriately. It is not possible to use different hard
   timeout values with the same login cache (in different virtual domains, as
   described in the next session). Leisurely tinkering with this environment
   variable is STRONGLY DISCOURAGED, it's very easy to screw up the whole
   system. You've been warned.

   If you adjust the hard timeout, you must simultaneously delete your
   current login cache directory, and adjust $timeouthard in the installed
   cleancache.pl script.

  Maximum message sizes

   Messages composed in the webmail server are limited in size. The
   additional limitation are on top of the limit set in the sizelimit
   configuration file, see the courier(8) manual page.

   The --with-maxargsize, --with-maxformargsize, and --with-maxmsgsize
   options to the configure script set the parameters that control the
   maximum size of messages and attachments. These parameters can also be set
   through the following environment variables.

     NOTE: The configure script parameters define the minimum settngs. The
     following environment variables may be used to set larger limits only.

     NOTE: These settings limit only the maximum size of messages sent from
     the webmail server. The limit on the incoming message size is set by
     other Courier mail server settings (usually the sizelimit setting also).

   SQWEBMAIL_MAXARGSIZE
           Approximate maximum size, in bytes, of the message, excluding any
           attachments (overrides the --with-maxargsize parameter to the
           configure script). This is the maximum message that can be typed
           into the webmail server.

           NOTE: The webmail server has an inactivity timeout. While
           composing a new message use the "Preview" button frequently to
           save the unfinished message and keep the session from timing out.

   SQWEBMAIL_MAXATTSIZE
           Approximate maximum size, of each allowed attachment. (overrides
           the --with-maxargsize parameter to the configure script).

           NOTE: Attaching binary files to E-mail messages incurs an overhead
           of approximately 33%. E-mail is really not the optimum medium for
           exchanging files. Setting SQWEBMAIL_MAXATTSIZE to 4000000 will
           effectively allow attaching files of up to 3000000 bytes in
           length, approximately.

   SQWEBMAIL_MAXMSGSIZE
           Approximate maximum size, of a message, including the text portion
           and all attachments (overrides the --with-maxmsgsize parameter to
           the configure script). There can be any number of attachments,
           each one up to SQWEBMAIL_MAXATTSIZE bytes long, but the sum total
           of the entire message cannot exceed SQWEBMAIL_MAXMSGSIZE.

   These variables must be set in the environment that runs the webmail CGI
   program. With Apache, these variables can be set in the httpd.conf file by
   the SetEnv command. httpd.conf example:

 SetEnv SQWEBMAIL_MAXATTSIZE 1000000
 SetEnv SQWEBMAIL_MAXMSGSIZE 4000000

     NOTE: These settings are global, and apply to all mailboxes. However,
     advanced Apache configuration can be used to use different environment
     variable settings with different virtual hosts.

     NOTE: On 32-bit platforms, the maximum limits may not exceed 2
     gigabytes. A 64-bit platform is required to have SqWebMail capable of
     handling attachments and messages larger than 2 gigabytes.

  Random seed

   A random seed is required for preventing certain kinds of external attacks
   against the SqWebMail server. The random seed must be a constant value,
   only varying between different instances of SqWebMail. By default the
   random seed is derived from the inode number of one of the supporting
   script files. The script file ordinarily remains constant, thus the random
   seed does not change, but different SqWebMail installs will end up with a
   different seed.

   When a pool of SqWebMail servers is combined for load-balancing, all
   servers must use the same random seed. This is done by defining the
   SQWEBMAIL_RANDSEED environment variable. This can be set in the httpd.conf
   as well:

 SetEnv SQWEBMAIL_RANDSEED 82738AZ

   SQWEBMAIL_RANDSEED should contain up to ten letters or numbers.

  Domain-based templates

   The default set of templates for the dynamically generated HTML is
   installed in /usr/local/share/sqwebmail/html. When the same server is used
   to provide webmail access for multiple domains it is possible to specify a
   different set of HTML templates for each domain.

   This functionality is not directly implemented in SqWebMail, simply
   because there is no standard way to specify this. Instead, this is
   something that will need some minor work set up.

   Domain-based templates are implemented by making the web server set the
   environment variables SQWEBMAIL_TEMPLATEDIR prior to running the sqwebmail
   binary. The contents of this environment variable override the default
   location of /usr/local/share/sqwebmail/html. By having the web server
   initialize this variable based on the domain name it is possible to
   present different templates, based on the domain name used.

   To do this, make copies of the HTML template directory,
   /usr/local/share/sqwebmail/html. Then, configure the web server to
   initialize SQWEBMAIL_TEMPLATEDIR appropriately. For example, with Apache:

   <VirtualHost a.b.c.d>
     ServerName webmail.example.com
     [...]
     SetEnv SQWEBMAIL_TEMPLATEDIR /usr/local/share/webmail/webmail.example.com
     [...]
   </VirtualHost>

   The possibilities are endless.

  Name-based templates

   It is now possible to display two or more templates from the same CGI
   binary WITHOUT setting up multiple domain names.

   For example, with Name-based templates an sqwebmail administrator can set
   up sqwebmail to display a template in the /usr/local/share/sqwebmail/html
   directory when sqwebmail is called from the URL:
   http://www.foo.com/cgi-bin/sqwebmail

   And display a different template in the
   /usr/local/share/sqwebmail/alternate-html directory when sqwebmail is
   called from the URL: http://www.foo.com/cgi-bin/sqwebmail-alt-template

   This is made possible by a little web server magic (explained below in the
   section entitled "Apache Name-based template configuration example") and
   the setting of TWO sqwebmail environment variables:

 SQWEBMAIL_TEMPLATEDIR
 SQWEBMAIL_IMAGEURL

   You should recognize the SQWEBMAIL_TEMPLATEDIR environment variable from
   the section above on Domain-based templates. If you haven't read that
   section yet, please do so now.

   The SQWEBMAIL_IMAGEURL environment variable is new in versions of
   sqwebmail greater than sqwebmail-3.5.3.20030629. It allows us to set, at
   run time, the image URL, or the root URL, in which to look for our
   template's images. This image URL is then automatically inserted into the
   current template anytime a conditional image tag or an IMAGEURL tag is
   encountered.

   This is an example of a conditional image tag:

   [#@image.gif, ... @text@#]

   The conditional image tag is replaced at template processing time with an
   HTML <img src="..."> tag if (hence the word "conditional") sqwebmail is
   set up to display images.

   This is an example of an IMAGEURL tag:

   [#IMAGEURL#]

   The IMAGEURL tag is replaced at template processing time with the contents
   of the SQWEBMAIL_IMAGEURL environment variable, if set, and otherwise with
   the value of the --with-imageurl configure option, which defaults to
   "/webmail".

  Apache Name-based template configuration example

   Let's take a look at a simple Apache Name-based sqwebmail template
   configuration example:


   # Sqwebmail Alternate Template URL
   ScriptAlias /cgi-bin/sqwebmail-alt-template "/usr/local/apache/cgi-bin/sqwebmail"

   <Location /cgi-bin/sqwebmail-alt-template>
       Setenv SQWEBMAIL_TEMPLATEDIR "/usr/local/share/sqwebmail/alternate-template"
       Setenv SQWEBMAIL_IMAGEURL "/alternate-webmail"
       [...]
   </Location>


   The above should allow your users to run sqwebmail with the template in
   /usr/local/share/sqwebmail/alternate-template and an image URL of
   /alternate-webmail, simply by calling sqwebmail from the following URL:

   http://www.yourdomain.com/cgi-bin/sqwebmail-alt-template

   The original sqwebmail templates would then still be available from this
   URL:

   http://www.yourdomain.com/cgi-bin/sqwebmail

   Using Apache's <Location> directive we can utilize a virtually unlimited
   number of templates without setting up a single virtual domain.

OPTIONAL: Configure mail filtering for the webmail server

   This is an optional feature where the webmail server is used to
   automatically set up mail filtering rules to forward or deliver incoming
   mail to folders. This feature requires maildrop to be used as the local
   mail delivery agent.

   Edit the courierd configuration file, and follow the instructions in that
   file to install maildrop as the local mail delivery agent. Then, follow
   the instruction below to create the maildirfilter configuration file,
   which may be installed either in the global configuration file directory
   (/usr/lib/courier/etc by default), or in each individual Maildir (which
   overrides the global default).

   Implementing mail filtering requires a couple of dominos to fall in the
   right order. This is not difficult to do, but is a bit tricky. Here's how
   it works, in general. Specifics follow.

   Some people would probably have a difficult time setting it up. That's to
   be expected. The implementation allows only selected accounts to be set up
   for mail filtering, so the suggested way is to attempt to set up mail
   filtering for one account only, test it to make sure it works, then roll
   it out globally.

  The big picture

   The maildrop mail filter is used to do the actual mail filtering. maildrop
   must be installed as your local mail delivery agent. The next thing to do
   is to actually learn how maildrop works, and learn its filtering language.
   Although the mail filter will be automaticaly generated here, you still
   need to become familiar with the filtering language in order to
   troubleshoot any installation problems. maildrop comes with manual pages
   documenting the filtering language, as well as some examples. Read them.

  The little picture

   Here's what's going to happen. The webmail server will automatically
   generate a maildrop filtering recipe. maildrop reads the recipe, and does
   its thing. Sounds simple enough, right?

   Well, it's not. There are a few little details that need to be resolved.

   For starters, the default maildrop filtering recipe is $HOME/.mailfilter.
   That's how things usually work physical system accounts are used. When
   virtual mailboxes are installed, things are less murky. There are several
   ways to set up virtual mailboxes, described elsewhere in this INSTALL
   file, so the actual implementation varies from system to system. Somehow,
   the virtual mailboxes share the same physical account, and have the same
   $HOME. In that case the usual approach is for each virtual mailbox to have
   the corresponding mail filtering recipe manually specified to maildrop as
   an extra command line argument. Review the maildrop documentation for more
   information.

   Now, on the other hand, the webmail server doesn't really know anything
   about physical and virtual accounts. The mapping between a login ID and
   the maildir is completely encapsulated in the black box-type
   authentication library. The login ID and password are validated by the
   authentication library, which obtains the maildir corresponding to the
   login ID, and the webmail server is started for that maildir. Whether or
   not a login ID corresponds to an actual system account or to virtual
   account, that's something the webmail server doesn't really know, or care.
   All it cares about is the maildir where all the mail is, and that's the
   end of the story. (The IMAP and POP3 servers work the same way).

   So, the issue is that the webmail server needs to find the corresponding
   maildrop filtering recipe, so it knows where to write the mail delivery
   instructions. That's the deal

   In order for mail filtering to be enabled, it is necessary to initialize
   the file named maildirfilterconfig in the maildir itself. This is where
   the webmail server runs, so it simply reads this file. The contents of
   this file should be as follows:

 MAILDIRFILTER=pathtomailfilter
 MAILDIR=pathtomaildir

   pathtomailfilter specifies the location of the maildrop filtering recipe
   for this maildir, relative to the maildir itself. Set the current
   directory to the maildir directory. Now ask yourself, where's my maildrop
   filtering recipe?

   In most cases, where virtual mailboxes are not used, everyone's maildir is
   $HOME/Maildir, and maildrop uses $HOME/.mailfilter by default. In this
   case, pathtomailfilter must be set to ../.mailfilter.

   When virtual mail accounts are used, this will obviously be something
   else. The only requirement is that the maildrop filtering recipe and the
   maildir must be on the same filesystem or partition.

   pathtomaildir is the other half of the story. When maildrop gets a message
   to deliver, maildrop needs to know where the mailboxes and folders are.
   Maildrop begins running in what it considers to be the recipient's home
   directory, reading either .mailfilter, by default, or the file specified
   on the command line.

   The webmail server needs to generate filtering instruction that deliver
   messages to its maildir. By default, the maildir for non-virtual accounts
   is $HOME/Maildir, so pathtomaildir needs to be set to ./Maildir.

  Summary for virtual accounts

   Basically, 99% of the time MAILDIRFILTER will be ../.mailfilter and
   MAILDIR will be ./Maildir. When virtual mail accounts are used, maildrop
   still must be used as a mail delivery agent. Somehow, the correct maildir
   that corresponds to the recipient's mail account must be specified as the
   argument to maildrop. Usually all or most virtual accounts are set up
   inside a single physical account. In that case it is necessary to set up a
   different maildrop filtering recipe file for each virtual mail account
   (since everyone's $HOME/.mailfilter will be the same file), and in each
   maildir specify the relative path to its corresponding filtering recipe,
   and the relative path to the maildir from the default home directory.
   Then, for each virtual mail account, the mail server must run maildrop to
   do the actual mail delivery, explicitly specifying the filtering recipe to
   be used.

  The global maildirfilterconfig file

   In most cases where virtual mail accounts are not used, every maildir's
   maildirfilterconfig should be the same. As an alternative to installing
   the same maildirfilterconfig in each maildir, it is possible to install a
   single maildirfilterconfig systemwide.

   Install the global maildirfilterconfig in the Courier mail server's
   configuration directory (/usr/lib/courier/etc by default).

   The global maildirfilterconfig will be used unless maildirfilterconfig
   exists in the maildir directory. Therefore, the global maildirfilterconfig
   can be used to provide a default for the majority of the mail accounts,
   and any exceptions are handled by installing maildirfilterconfig in the
   maildir directory, whose contents will override the global file.

  Happy filtering.

   If everything is set up correctly, the webmail menu will present a new
   link to a screen where mail filtering rules are defined and installed. A
   mail filter consists of a condition, and an action. A condition is usually
   based on the contents of some header, or the message body. Regular
   expressions are allowed. Which means that certain special characters must
   be quoted. For example, to search for the string "[announce]" verbatim in
   the subject header, it must be entered as "\[announce\]". Pattern
   matching, for now, is case-insensitive. The regular expression syntax uses
   pretty much the same syntax as Perl. See the maildropfilter manual page
   for more information.

   Multiple mail filtering rules can be installed. Their relative order can
   be rearranged by selecting a filtering rule, then selecting either the
   "Up" or the "Down" button. It is necessary to select "Save all changes"
   for any changes to the filtering rules to take effect. Leaving that page
   in any other way will throw away all changes made.

  Webmail runtime configuration

   There are some options which can be used to change the webmail server's
   behavior for individual accounts, or globally, using the "Account Options"
   feature in the Courier mail server Authentication library. The individual
   account's setting takes precedence over the DEFAULTOPTIONS settings in the
   authdaemonrc configuration, so for example if you want to disable webmail
   access for most accounts but enable it for a select few, you can set
   DEFAULTOPTIONS="disablewebmail=1" in the authdaemonrc configuration file,
   and add the option disablewebmail=0 to individual accounts. See the
   section "Account options" in README_authlib.html in the courier-authlib
   package for more information on setting the following account options:

   disablewebmail - if set to a non-zero value, this account will not be
   permitted to login to webmail (e.g. because the user is only allowed to
   use POP3 or IMAP)

   wbnochangingfrom - if set to a non-zero value, the webmail server will not
   allow the From: header to be changed, it will always have its default
   value.

   wbnochangepass - if set to a non-zero value, the webmail server will not
   allow passwords to be changed. See "Changing mail account passwords using
   the webmail server", below, for more information.

   wbusexsender - if set to a non-zero value, the webmail server will attach
   an X-Sender: header to all outgoing messages. This can be used in the
   event you would like to be able to modify the From: header, yet also be
   able to track sent mail to the original account.

   wbnoimages - if set to a non-zero value then no images or icons will be
   used. The generated interface will be a text-only interface.

   wbnodsn - set to a non-zero value then the option to request delivery
   confirmation receipts will not be shown.

OPTIONAL: Changing mail account passwords using the webmail server

   After installing the webmail server be sure to test that the login
   password can be changed through the webmail server.

   If you do not want to use the password change function you can also remove
   the sqwebpasswd program. This is a helper program, installed with the
   set-groupid bit set, that relays the password change request to the
   authentication daemon, through the filesystem socket that is not globally
   accessible. The password change request consists of the account name, the
   old password, and the new password. The password change request is
   validated by the authentication daemon, and the old password must match
   the existing password on the account, before the password change goes
   through. This set-groupid helper program is safe to use.

OPTIONAL: Configure autoreplies for the webmail server

   Enabling mail filtering, according to the instructions in the previous
   section, automatically enables MIME autoreply capability. The webmail
   interface can be used to configure simple autoresponders. By default there
   is no limit on the number of the size of created autoreplies, therefore it
   is recommended that a quota be set up on the autoreplies.

   An global autoreply quota is set up by initializing the
   /usr/lib/courier/etc/autoresponsesquota configuration file. This file sets
   the autoreply quota globally. An autoresponsesquota file in the Maildir
   will override the global quota setting for that maildir only. See the
   courier(8) manual page for the description of the autoresponsesquota file.

   Autoreplies can include any valid MIME content (MIME content other than
   plain text can be uploaded). The following special procedure needs to be
   used to prepare multipart autoreply content, such as text and html
   alternatives of the same message:

   Assign a filename extension to the message/rfc822 MIME content. For
   example, edit your mime.types file, find the message/rfc822 MIME type
   (append one if it's not in mime.types), and make sure that it has at least
   one filename extension, such as "msg".

   Prepare the multipart MIME autoreply. The most convenient way is to
   prepare a normal E-mail message using a conventional E-mail client. Save
   the RFC822-formatted message in a file with a ".msg" extension, and upload
   it on the autoreply screen.

   Webmail handles uploaded message/rfc822 content by removing all headers
   except the MIME headers, leaving the MIME content type header, and the
   actual MIME content.

   Normally there is no limit on the number or the total size of autoreplies
   configured via the webmail server. A quota can be installed by
   initializing the autoresponsesquota configuration file. See courier(8) for
   more information.

OPTIONAL: Configure encryption for the webmail server

   This is an optional feature in the webmail server that uses GnuPG to send
   and receive encrypted/signed E-mail. There is no encryption code in the
   webmail server, it uses GnuPG to do encryption and decryption. For more
   information on setting up and using encryption, read the file
   gpglib/README.html in the source distribution.

OPTIONAL: Install automatically-appended footer text for webmail messages

   /usr/lib/courier/share/sqwebmail/html/LANG/footer - if this file exists,
   its contents will be appended to the end of every sent message from the
   webmail server. The actual directory where sqwebmail's html language files
   are installed may be different with prebuilt Courier packages. LANG is the
   language code here, there can be a separate footer per installed language.
   The footer file carries the following requirements:

     * The footer file must be coded in UTF-8.

     * The footer file must follow the format=flowed; delsp=yes format, as
       specified by RFC 3676. Capsule summary:

          * Paragraphs are delimited by blank lines.

          * Paragraphs that consist of more than one line must have a
            trailing space ending each line except the last line in the
            paragraph.

          * That trailing space is in addition to a space that delimits
            individual words in most Western languages. Therefore, a line
            that ends on a word without punctuation and continues with the
            next word at the beginning of the next line must end with two
            spaces: the usual space that separates individual words, and a
            second space that indicates that the paragraph continues on the
            next line.

          * Restated: a line that ends with a space is logically joined with
            the next line, after the trailing space is logically removed.

          * Lines that begin with a space character or the ">" character must
            have an additional space character prepended to them. This
            leading space character is logically removed from the contents of
            the line.

       A convenient way to format text in flowed format is to use the leaf
       editor that's part of the Cone package.

     * Signature content gets formatted as part of the message together with
       the rest of the content. Sender-selected option to format the message
       as either a plain text message, or using wiki-style HTML markup
       applies to the footer file too. The footer file's contents should be
       constructed taking into account the possibility that wiki-style HTML
       markup may get optionally applied to the footer content.

OPTIONAL: Quota support

   There are two ways to implement a quota on the size of a mail account:
   filesystem quotas and maildir quotas:

  Filesystem quotas

   The maximum disk space quota is implemented within the operating system's
   filesystem support code. Here, the operating system enforces the maximum
   disk space that can be used by each account. This is the only reliable
   quota implementation if individual accounts have login access to the mail
   account. Maildir quotas (see below) are implemented entirely within the
   maildir support code, and can easily be superceeded by anyone with login
   access to the mail account. Additionally, mail accounts must all be system
   accounts. Virtual accounts -- that share the same physical system userid
   -- cannot usually be support by filesystem-based quotas, because all mail
   accounts have the same userid and groupid.

   The webmail server cannot be used with filesystem quotas. The webmail
   server creates and maintains, all by itself, a number of database files
   that are used to quickly index and access messages. If an account exceeds
   its disk quota, the webmail server will not be able to create and update
   those database file, which results in a rather spectacular crash. If login
   access is available, it is possible to log in and manually delete some
   files to reclaim some disk space. If login access is not available, the
   administrator will have to manually fix the account -- the webmail server
   will not even be able to open an existing folder and delete messages in
   order to free up disk space. There is some good news, though: the IMAP and
   the POP3 server can still be used to access and delete messages from the
   mail account. Due to the way that out-of-quota condition is handled by the
   IMAP server, some IMAP clients may mark any existing messages in the
   account as unread, but that is a minor glitch that does no harm.

  Maildir quotas

   The Courier mail server can manually enforce a quota for mail accounts
   that use maildirs. This quota enforcement is implemented entirely in
   software, and is available only when maildirs are used. This quota
   implementation will also work with virtual accounts. Maildir quota support
   is available only with userdb, LDAP, MySQL and PostgreSQL authentication
   back-ends. Maildir quotas are supported by IMAP, POP3, and the webmail
   server. To add a maildir quota with userdb, run the following commands,
   for example:

 userdb account set quota=quota
 makeuserdb

   Here, account identifies the account to which the quota applies, and quota
   is the quota specification, as described in the maildirquota(7) manual
   page.

   To implement a quota with an LDAP, MySQL, or a PostgreSQL back end, simply
   follow the instructions given in the corresponding configuration file.

Account OPTIONS

   It is possible to adjust certain parameters on an account-by-account
   basis. This feature is actually implemented in the Courier mail server
   Authentication Library. See ACCOUNT OPTIONSin the auth_generic manual
   page.

OPTIONAL: Configure outbound faxing

   Fax sending is disabled by default and must be explicitly enabled,
   according to the following instructions. After fax sending is enabled,
   addressing an E-mail message to <5552000@fax> will have this message
   faxed.

   Of course, the necessary hardware and software must be available. The
   requisite hardware is a class 2 faxmodem attached to a serial port.
   Additional software, separate from the Courier mail server, must also be
   installed. The Courier mail server does not handle the actual job of
   faxing. The Courier mail server only reformats E-mail messages as fax
   images, and runs mgetty+sendfax to send the fax. The Courier mail server
   also needs additional software to convert E-mail messages to faxes. All
   additional software must be separately installed, configured, and tested
   before enabling faxing in the Courier mail server. Most systems already
   include the following software as part of the base operating system, so in
   most cases adding fax support will not actually require any additional
   software to be installed, only minor reconfiguration of existing software:

  mgetty+sendfax

   mgetty+sendfax works with most Class 2 faxmodems. The Courier mail server
   does not use the spooling scripts found in the mgetty+sendfax package. The
   Courier mail server uses its own mail spool. A fax message is handled no
   differently than any other E-mail message. The only difference is that the
   E-mail message is addressed to <phonenumber@fax>.

   mgetty+sendfax should be configured with its default settings, EXCEPT as
   follows:

     * In /etc/mgetty+sendfax, the "max-tries-continue" setting must be set
       to "n".

  groff or troff, ghostscript, NetPBM

   Conversion of E-mail messages to faxes uses ghostscript, and groff. It
   should be possible to use the original UNIX troff instead of groff, but
   this has not been tested. The Courier mail server generates the fax cover
   page from the contents of the E-mail message's headers. The initial text
   portion of the E-mail message will appear as fax cover page comments. Note
   that the initial text portion of the E-mail message must be in plain text,
   not HTML. E-mail attachments will be converted and attached as additional
   fax pages. E-mail attachments may contain plain text, Postscript or PDF
   documents. Other attachments will result in the E-mail message being
   returned as undeliverable.

   On the cover page, the sender's name, the recipient's name, and the fax
   subject gets taken from the E-mail message's headers. The ability to use
   non-Latin characters depends on the support from the underlying tools,
   ghostscript and groff, for the default system locale.

   Install the NetPBM library to add the ability to fax GIF, JPEG, and PNG
   images. Each image will be converted to a single fax page. Images in
   excess of 1500x1500 pixels (approximately) will be truncated, and color
   images will be dithered to black-and-white.

  Enabling faxing

   The configuration file /usr/lib/courier/etc/faxrc must be edited in order
   to enable faxing. This file sets up the dialing parameters, and the
   default file disables faxing by rejecting all phone numbers. The
   configuration file has extensive comments that explain how dialing
   parameters are set.

   Using webadmin to set up fax sending is highly recommended. A proper faxrc
   will automatically hide all the local daling conventions. Webadmin knows
   how to generate the dialing configuration for the North American dialing
   plan, with a configurable area code. Faxes should be addressed to a fixed
   ten digit area code+phone number address, <nnnxxxxxxx@fax>, which will be
   converted for dialing from the local area code appropriately. Webadmin can
   also optionally enable faxing to international 011 phone numbers. Webadmin
   can also fall back to a bare configuration where all phone numbers are
   dialed as-is, for locations outside of North America.

  Sending faxes

   E-mail messages may contain attachments. The Courier mail server combines
   all attachments in the message into a single fax transmission. Attachment
   types may be freely mixed. A single message may contain one plain text,
   and one PDF attachment, for example. It is possible to select certain
   options, as follows:

     * <phonenumber@fax-lowres>

       sends a low-resolution fax.

     * <phonenumber@fax-ignore>

       Ignore attachments that the Courier mail server doesn't know how to
       convert to a FAX image format. Normally, if an attachment cannot be
       converted the whole message is returned as undeliverable.

     * <phonenumber@fax-cover>

       sends only the cover page. This can be useful for .courier files. See
       the courierfax(8) manual page for an example.

   These options can be combined: <phonenumber>@fax-lowres-ignore>.

  Cover pages

   /usr/lib/courier/etc/faxcoverpage.tr is the troff source for the FAX cover
   page, which includes the first plain text section of the E-mail message.
   Do not attempt to play with faxcoverpage.tr without a clear understanding
   of troff. It is safe to make trivial changes (such as replacing the
   "FACSIMILE COVER PAGE" text).

  Dialing

   The /usr/lib/courier/etc/faxrc configuration file provides rudimentary
   phone number rewriting logic (stuff like dialing "9," to get outside line
   from a PBX). The default faxrc configuration file specifies a typical
   dialing configuration for the North American numbering plan, with seven
   digit local phone numbers, and 1+ten digit long distance phone numbers.
   The area code in the default faxrc configuration file is set to "999", you
   will need to change it to your area code (there are two places in faxrc
   where the area code needs to be set).

   In general, messages should be addressed to the full ten-digit phone
   numbers. The local area code will be stripped automatically, and "1" will
   be dialed before all other area codes. If this is done in practice, local
   area code changes will only require an update to faxrc, without any need
   to update the address book.

   Comments in the faxrc configuration file explain the format of the phone
   number rewriting rules, in the event that local phone system customization
   is required (for example, dialing 9 to get an outside line). Several
   places in North America now use ten digit local phone number overlays,
   with 1+ten digit long distance dialing. TODO: Use webadmin if you are not
   sure how to set this up.

  Security

   The default faxrc configuration file allows only locally-generated faxes.
   faxrc must be modified in order to accept faxes via ESMTP.

   Additionally, faxes are accepted via ESMTP only if the FAXRELAYCLIENT
   variable is set. See the makesmtpaccess(8) man page for additional
   information.

OPTIONAL: Configure inbound faxing

   mgetty has an option that runs a script called "new_fax" after it receives
   a fax. The default location for this script is either
   /usr/local/lib/etc/mgetty+sendfax/new_fax or /etc/mgetty+sendfax/new_fax.
   Consult your mgetty documentation to determine if the new_fax option is
   enabled, and the exact script location.

   The Courier mail server provides a script -
   /usr/lib/courier/share/faxmail/new_fax - that can be used as mgetty's
   new_fax script. This script converts incoming faxes to PNG images, and
   delivers it to a local mailbox. Simply copy this script to mgetty's etc
   directory (or install a soft link there), to automatically drop incoming
   faxes to a local mailboxes.

   The /usr/lib/courier/etc/faxnotifyrc configuration file specifies the
   mailbox that receives incoming faxes, and several other related options.

OPTIONAL: Install the Courier mail server log analyzer

   The Courier mail server log analyzer (the courier-analog package) is a
   Perl script that generates log summaries for the Courier mail server. The
   Courier mail server log analyzer generates log summaries for incoming and
   outgoing SMTP connections, and IMAP and POP3 activity. courier-analog can
   generate output in text or HTML format.

   The Courier log analyzer is not included in the main the Courier mail
   server tarball, it must be downloaded separately from
   http://www.courier-mta.org/download.html#analog. After downloading and
   installing this package, see the courier-analog manual page for more
   information.

OPTIONAL: Configure Courier IP address-specific settings for servers with
multiple IP addresses

   When running Courier on a server that has more than one IP address, it's
   possible to configure Courier to have a "vanity" configuration for each IP
   address, such as the IP address for outgoing connections for relaying
   messages received by a client that connects to each address, or its server
   name that it uses in the "Received:" headers that Courier adds to each
   message.

   See the "Servers with multiple IP addresses" section in the courier(8)
   manual page for more information.

Decommission your existing mail server

   This step consists of flushing the mail queue of your existing mail server
   and removing it from the system.

   If you're using sendmail, edit your startup script, and start sendmail
   with the option '-q30m' only. Remove the -bd option. This causes sendmail
   to stop listening on port 25, and stay as a daemon process only for the
   purpose of running the queue every 30 minutes.

   If you're using Qmail, remove tcpserver from your system startup script.

   Wait for all existing mail to flush itself out, then permanently remove
   your existing server.

   Depending on your system, you may need to create a bunch of soft links,
   such as /usr/bin/sendmail, /usr/sbin/sendmail, /lib/sendmail, or
   /etc/sendmail that point to /usr/lib/courier/bin/sendmail. If you want to
   receive mail via UUCP you will also need to make sure that UUCP knows to
   find rmail in /usr/lib/courier/bin as well.

Sample init script

   You're now ready to configure your system to start the Courier mail server
   at system boot time (and shut it down at system shutdown). If your system
   uses system-V init scripts, here's a sample script that you can install in
   your /etc/rc?.ddirectories. This is a slightly modified version of the
   init script that's used in my RPM package (courier.sysvinit file in the
   source code tarball).

   NOTE: the following script may take a long time to finish, the very first
   time it runs. That's because the script automatically creates test SSL
   certificates the first time the script runs (provided that SSL support is
   available). This can take as much as 5-6 minutes on a slow machine.
   Subsequent starts should take only a few seconds.

 #! /bin/sh
 #
 # chkconfig: 2345 35 65
 # description: Courier - SMTP server
 #
 # NOTE: The 'restart' here does a "hard" stop, and a start.  Be gentle, use
 # "courierd restart" for a kindler, gentler, restart.
 #
 #

 prefix="/usr/lib/courier"
 exec_prefix="/usr/lib/courier"
 sysconfdir="/usr/lib/courier/etc"
 sbindir="${exec_prefix}/sbin"
 libexecdir="/usr/lib/courier/libexec"
 datadir="/usr/lib/courier/share"

 case "$1" in
 start)
         cd /
         # Start daemons.
         touch /var/lock/subsys/courier

         echo -n "Starting the Courier mail server:"

         # Use default DH parameter file, if it does not exist.

         if test ! -f ${datadir}/dhparams.pem
         then
             ln ${datadir}/dhparams.pem.dist ${datadir}/dhparams.pem
         fi

         # First time after install create aliases.dat and makesmtpaccess.dat

         test -f ${sysconfdir}/aliases.dat || ${sbindir}/makealiases

         esmtpdcert=0

         . ${sysconfdir}/esmtpd
         case x$ESMTPDSTART in
         x[yY]*)
                 esmtpdcert=1
                 ;;
         esac

         test -f ${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess

         . ${sysconfdir}/esmtpd-msa
         case x$ESMTPDSTART in
         x[yY]*)
                 esmtpdcert=1
                 ;;
         esac

         test -f ${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess-msa

         ${sbindir}/courierfilter start
         echo -n " courierfilter"

         if test -x ${sbindir}/courierldapaliasd
         then
                 ${sbindir}/courierldapaliasd start
                 echo -n " courierldapaliasd"
         fi

         if test -f ${libexecdir}/courier/sqwebmaild
         then
                 ${sbindir}/webmaild start
                 echo -n " webmail"
         fi

         ${sbindir}/courier start
         echo -n " courierd"

         if test "$esmtpdcert" = 1
         then
 # If we do not have a certificate, make one up.

                 if test ! -f ${datadir}/esmtpd.pem
                 then
                         if test -x $COURIERTLS
                         then
                                 echo -n " generating-ESMTP-SSL-certificate..."
                                 ${sbindir}/mkesmtpdcert >/dev/null 2>&1
                         fi
                 fi
         fi

         . ${sysconfdir}/esmtpd
         case x$ESMTPDSTART in
         x[yY]*)

                 ${sbindir}/esmtpd start
                 echo -n " esmtpd"
                 ;;
         esac

         . ${sysconfdir}/esmtpd-msa
         case x$ESMTPDSTART in
         x[yY]*)

                 ${sbindir}/esmtpd-msa start
                 echo -n " esmtpd-msa"
                 ;;
         esac

         if test -x ${sbindir}/pop3d
         then
                 POP3DSTART=""
                 POP3DSSLSTART=""

                 if test -f ${sysconfdir}/pop3d
                 then
                         . ${sysconfdir}/pop3d
                 fi
                 case x$POP3DSTART in
                 x[yY]*)
                         ${sbindir}/pop3d start
                         echo -n " pop3d"
                         ;;
                 esac
                 if test -f ${sysconfdir}/pop3d-ssl
                 then
                         . ${sysconfdir}/pop3d-ssl
                 fi
                 case x$POP3DSSLSTART in
                 x[yY]*)
                         if test -x $COURIERTLS
                         then
 # If we do not have a certificate, make one up.

                                 if test ! -f ${datadir}/pop3d.pem
                                 then
                                         echo -n " generating-POP3-SSL-certificate..."

                                         ${sbindir}/mkpop3dcert >/dev/null 2>&1
                                 fi

                                 ${sbindir}/pop3d-ssl start && \
                                         echo -n " pop3d-ssl"
                         fi
                         ;;
                 esac
         fi

         if test -x ${sbindir}/imapd
         then
                 . ${sysconfdir}/imapd
                 case x$IMAPDSTART in
                 x[yY]*)
                         ${sbindir}/imapd start
                         echo -n " imapd"
                         ;;
                 esac
                 . ${sysconfdir}/imapd-ssl
                 case x$IMAPDSSLSTART in
                 x[yY]*)
                         if test -x $COURIERTLS
                         then
 # If we do not have a certificate, make one up.

                                 if test ! -f ${datadir}/imapd.pem
                                 then
                                         echo -n " generating-IMAP-SSL-certificate..."

                                         ${sbindir}/mkimapdcert >/dev/null 2>&1
                                 fi

                                 ${sbindir}/imapd-ssl start && \
                                         echo -n " imapd-ssl"
                         fi
                         ;;
                 esac
         fi

         if test -x ${bindir}/webmlmd
         then
                 . ${sysconfdir}/webmlmrc
                 if test "$LISTS" != ""
                 then
                         ${bindir}/webmlmd start ${sysconfdir}/webmlmrc && \
                                 echo -n " webmlmd"
                 fi
         fi

         echo ""
         ;;
 stop)
         echo -n "Stopping the Courier mail server:"

         if test -x ${bindir}/webmlmd
         then
                 ${bindir}/webmlmd stop ${sysconfdir}/webmlmrc
                 echo -n " webmlmd"
         fi

         if test -x ${sbindir}/imapd
         then
                 ${sbindir}/imapd stop
                 echo -n " imapd"
         fi

         if test -x ${sbindir}/imapd-ssl
         then
                 ${sbindir}/imapd-ssl stop
                 echo -n " imapd-ssl"
         fi

         ${sbindir}/esmtpd-msa stop
         echo -n " esmtpd-msa"

         ${sbindir}/esmtpd stop
         echo -n " esmtpd"

         if test -x ${sbindir}/pop3d
         then
                 ${sbindir}/pop3d stop
                 echo -n " pop3d"
         fi

         if test -x ${sbindir}/pop3d-ssl
         then
                 ${sbindir}/pop3d-ssl stop
                 echo -n " pop3d-ssl"
         fi

         ${sbindir}/courier stop
         echo -n " courierd"

         if test -f ${libexecdir}/courier/sqwebmaild
         then
                 ${sbindir}/webmaild stop
                 echo -n " webmail"
         fi

         if test -x ${sbindir}/courierldapaliasd
         then
                 ${sbindir}/courierldapaliasd stop
                 echo -n " courierldapaliasd"
         fi

         ${sbindir}/courierfilter stop
         echo " courierfilter"
         ;;
 restart)
         $0 stop
         $0 start
         ;;
 esac
 exit 0

   The reason I test for the existence of the POP3 and IMAP server binaries
   is because I build the POP3 and IMAP servers as separate sub-packages,
   that do not have to be installed. These tests avoid the need for each
   sub-package to install its own startup script.