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