summaryrefslogtreecommitdiffabout
path: root/doc/anubis.texi
blob: eec5cfcbd7720d3be7dad787dfe5b59318d241d3 (plain)
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
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename anubis.info
@settitle GNU Anubis Manual
@setchapternewpage odd
@finalout
@c %**end of header
@include version.texi
@include rendition.texi
@smallbook

@defcodeindex op
@defcodeindex cm
@syncodeindex fn cp

@copying
Copyright @copyright{} 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2011
Wojciech Polak and Sergey Poznyakoff.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end copying

@ifinfo
@dircategory Email
@direntry
* Anubis: (anubis).                   The GNU SMTP message submission daemon.
* anubis: (anubis) Invoking Anubis.   Anubis command line summary.
* anubisadm: (anubis) Administrators. Administration of the Anubis User Database. 
* anubisusr: (anubis) Users.          User interface to the Anubis User Database.
@end direntry
@end ifinfo

@titlepage
@title GNU Anubis
@subtitle An SMTP message submission daemon.
@subtitle GNU Anubis Version @value{VERSION}
@subtitle @value{UPDATED}
@author Wojciech Polak and Sergey Poznyakoff

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnothtml
@page
@summarycontents
@page
@contents
@end ifnothtml

@ifnottex
@node Top
@top GNU Anubis
This edition of the @cite{GNU Anubis Manual}, last updated @value{UPDATED},
documents GNU Anubis Version @value{VERSION}.
@end ifnottex

@menu
* Overview::                        Program Overview.
* Glossary::                        Frequently Used Terms Explained.
* Authentication::                  Authenticating Incoming Connections.
* Configuration::                   Writing your Configuration Files.
* Rule System::                     How to Use the Rule System.
* Invoking Anubis::                 How to Invoke the GNU @command{anubis}.
* Sample Beginning::                Here is a sample beginning.
* TLS/SSL::                         Using TLS/SSL Encryption.
* S/MIME::                          Using S/MIME Signatures.
* MDA Mode::                        Processing Incoming Mail.
* Mutt::                            Using Anubis with Mutt.
* Problems::                        Reporting Bugs.

Appendices

* Pixie-Dixie::                     Original description of the new
                                    GNU Anubis operation mode.
* Multi-Part Message Processing::   New Method of Processing
                                    Multi-Part messages.
* GNU Free Documentation License::  This manual is under the GNU Free
                                    Documentation License.
Indices

* Concept Index::                   Index of concepts.

@detailmenu
 --- The Detailed Node Listing ---

Auth mode.

* User Database::
* Database URL::
* Managing the Database::

Database URL

* text::        Plain text databases
* gdbm::        Databases in GDBM format
* sql::         MySQL and PostgreSQL databases

Managing the Database

* Administrators::      Administrator's View
* Users::               User's View

Administrators

* Create::              Creating the Database
* List::                Listing Database Records
* Add::                 Adding New Records
* Remove::              Removing Existing Records       
* Modify::              Modifying Existing Records
* anubisadm summary::   Summary of All Administrative Commands

Logical Structure

* AUTH Section::
* CONTROL Section::
* TRANSLATION Section::
* GUILE Section::

CONTROL Section

* Basic Settings::
* Output and Debugging Settings::
* SOCKS Proxy::
* ESMTP Authentication Settings::
* Encryption Settings::
* Security Settings::

The Rule System

* Actions::
* Conditional Statements::
* Triggers::
* Boolean Operators::
* Regular Expressions::
* Action List::
* Using Guile Actions::

Conditional Statements

* Concatenations::

Action List

* Stop Action::            Stopping Processing
* Call Action::            Invoking Another Section
* Adding Headers or Text:: How to add a new header or body line(s).
* Removing Headers::       How to remove a message header line(s).
* Modifying Messages::     How to modify a message contents on-the-fly.
* Modifying SMTP Commands::
* Inserting Files::        How to append text files to an outgoing message.
* Mail Encryption::        How to encrypt a message on-the-fly.
* External Processor::     How to process a message body using an external tool.
* Quick Example::          A quick example of using an action list.

Using Guile Actions

* Defining Guile Actions::
* Invoking Guile Actions::

Predefined Guile Actions
* Rot-13::
* Remailers::
* Entire Message Filters::

Using Mutt with Anubis

* mutt-smtp::            Using @acronym{SMTP}
* maidag::               Using GNU Mailutils
* msg2smtp.pl::          Using @command{msg2smtp.pl}

@end detailmenu
@end menu

@node Overview
@chapter Overview
@cindex overview
@cindex Simple Mail Transport Protocol, SMTP
@cindex daemon
@cindex client
@cindex tunnel
@cindex proxy
@cindex server
@cindex message submission daemon
@cindex outgoing mail processor
@cindex MUA, Mail User Agent
@cindex MTA, Mail Transport Agent

GNU Anubis is an @acronym{SMTP} message submission daemon. Its purpose is to receive
the outgoing message, optionally perform some manipulations over its contents,
and to forward altered message to the mail transport agent.

A usual mail sending scheme looks as follows: the user composes
his message using @dfn{mail user agent} (@dfn{MUA} for short). Once
the message is composed, the user sends it. While sending, the
@acronym{MUA} connects to the @dfn{mail transport agent}
(@dfn{MTA} for short) and passes it the message for delivery. The
figure below illustrates this interaction:

@smallexample
+-------+                 +-------+               
|  MUA  | ---[outmsg]---> |  MTA  | ... [outmsg]
+-------+                 +-------+         |     
                                            |
                                            V
                                     +--------------+
                                     |  Recipient's |
                                     |   Mailbox    |  
                                     +--------------+
                                                        
@end smallexample

As shown in this figure, outgoing message (@dfn{outmsg}) reaches
the recipient's mailbox unaltered.

However, there are situations where it may be necessary to modify
the outgoing message before it reaches @acronym{MTA}. For example,
the user might wish to sign outgoing messages with his PGP
key, because his @acronym{MUA} does not support this operation.

In such cases, installing GNU Anubis between the @acronym{MUA} and @acronym{MTA}
allows the user to perform any additional processing on the
sent message. The figure below illustrates this concept:

@smallexample
+-------+                 +--------+                 +-------+               
|  MUA  | ---[outmsg]---> | Anubis | ---[modmsg]---> |  MTA  | 
+-------+                 +--------+                 +-------+     
                                                         |
                                                      [modmsg]
                                                         .
                                                         .
                                                         V
                                                  +--------------+
                                                  |  Recipient's |
                                                  |   Mailbox    |  
                                                  +--------------+
@end smallexample

The outgoing message is modified by GNU Anubis, and it is
the resulting message (@dfn{modmsg}) that reaches the @acronym{MTA}.

GNU Anubis is able to perform a wide set of operations on messages,
such as modifying headers or body, encrypting or signing 
messages with GPG (GNU Privacy Guard) keys, installing secure tunnels
to @acronym{MTA} using @acronym{TLS/SSL} encryption, tunneling messages through
SOCKS proxies, etc.

When the set of built-in operations is not enough, the user can
define his own operations using Guile, a @dfn{GNU's Ubiquitous
Intelligent Language for Extensions}.

@cindex SMTP normalization
Apart from configurable operations, GNU Anubis always performs
@dfn{SMTP session normalization}, a process that ensures that the
@acronym{SMTP} stream coming out of Anubis complies with the RFC
2821, even if the incoming stream does not. In particular, Anubis
removes any extra whitespace appearing between @samp{MAIL FROM:} or
@samp{SMTP TO} command and its argument.

Message processing is controlled by two configuration files: a
system-wide one that affects functionality of the system as
a whole, and user configuration files, which modify Anubis
behaviour on a per-user basis.

@node Glossary
@chapter Glossary of Frequently Used Terms

@table @dfn
@item Authentication
A process whereby Anubis determines authenticity of the connecting
party, its user name and configuration settings.

@item Protocol
Any standard for information exchange. A protocol
defines specific wording and control flow for communications between
two or more programs, devices or systems.

@item SMTP
Simple Mail Transport Protocol is a common mechanism for exchanging
mail across a network. This protocol is described in the @acronym{RFC} 821 document.

@item Daemon
A process that runs in the background, doing automated processing.

@item Server
A server provides information or other services for its
clients. Most network protocols are client--server based. This term often
refers to hardware, but it can also refer (and we're using it that way)
to a particular program or process, on that machine, which provides the
service.

@item Proxy
A program, which goes between @acronym{MUA} and @acronym{MTA}. It can
be used as a gateway to the outside world, while using a firewall. In
this case a host under the firewall sends data to the proxy server,
which in turn forwards it to a server outside, receives its
replies, and passes them back to the internal host.

@item Guile
GNU's Ubiquitous Intelligent Language for Extensions. It provides a
Scheme interpreter conforming to the R5RS language specification. GNU
Anubis uses Guile as its extension language.
For more information about Guile,
@ref{Top,,Overview,guile,The Guile Reference Manual}.

@item GPG
GNU Privacy Guard, a tool compatible with @dfn{PGP} (@dfn{Pretty Good
Privacy}).
@end table

@node Authentication
@chapter Authentication
@cindex authentication

When GNU Anubis accepts incoming connection, it first has to identify
the remote party, i.e. to determine whether it has enough rights to use
Anubis resources and, if so, what configuration settings to use 
during the session. We call this process @dfn{authentication}.
The exact method of authentication depends on Anubis @dfn{operation
mode}. Currently there are three modes:

@table @asis
@item proxy
No authentication is performed.  Anubis switches to the unprivileged
user (@pxref{Security Settings,,user-unprivileged}) and acts as an
@dfn{@acronym{SMTP} proxy}.

@item transparent
Anubis relies on AUTH service (@command{identd}) to authenticate users.
This is the default mode. It is compatible with versions of GNU Anubis
up to 3.6.2.

@item auth
This mode uses @acronym{SMTP} AUTH mechanism to authenticate incoming
connections. @xref{Pixie-Dixie}, this is the first draft
description of this mode.
@end table

Both modes have their advantages and deficiencies, which you need
to weigh carefully before choosing which one to use. They are
discussed below:

@heading Transparent (@samp{traditional}) mode.

Deficiencies:
@enumerate
@item User must have @command{identd} installed on his machine.
@item Each user must have a system account on the machine running
GNU Anubis (though the system administrator may relax
this limitation by using user name translation, @pxref{TRANSLATION
Section}).
@end enumerate

@noindent
Advantages:
@enumerate
@item Relative simplicity. No user database is necessary.
@item Authentication is performed immediately after connecting.
@end enumerate

@heading Auth mode.

Deficiencies:
@enumerate
@item A user database is needed
@item User's @acronym{MUA} must be able to perform ESMTP AUTH.@footnote{It is
not a serious restriction, however. Users may install Anubis on their
machines for the sole purpose of @acronym{SMTP} authentication, as Pixie-Dixie suggests.}
@end enumerate

@noindent
Advantages:
@enumerate
@item Improved reliability.
@item Users do not have to run @command{identd} on their machines.
@item Users are not required to have accounts on the machine where
Anubis runs.
@item Users can remotely modify their configuration files.
@end enumerate

@menu
* User Database::
* Database URL::
* Managing the Database::
@end menu

@node User Database
@section User Database

@dfn{User Database} is a place where GNU Anubis keeps @dfn{user
credentials}, i.e. data necessary for authenticating and authorizing
users. The exact way of storing these data is described further in
this manual. In this section we treat user database as an abstraction
layer.

User database consists of @dfn{records}. Each record keeps
information about a particular @dfn{user}. A record consists
of four @dfn{fields}. A field may contain some value, or be
empty, in which case we say that it has @dfn{null}
value.

The fields are:

@table @code
@item SMTP AUTHID
@acronym{SMTP} authentication @acronym{ID} of the user.

@item AUTH PASSWORD
@acronym{SMTP} password.

@item ACCOUNT
System user name.

@item CONFIG
Path to the configuration file.
@end table

The first two fields are mandatory and must always have non-null values.
No two records in the database may have the same value of
@code{SMTP AUTHID} field. When @command{anubis} is trying to
authenticate a user, it first looks up in the database a record
with the value of @code{SMTP AUTHID} field matching AUTHID given
by the user. If no such entry is found, authentication fails.
Otherwise, @command{anubis} goes on and compares the password
supplied by the user with that from @code{AUTH PASSWORD} field.
If they match, authentication succeeds and @command{anubis}
passes to authorization state.

In this state, it first determines the user @acronym{ID}
(@acronym{UID}) to switch to. If the @code{ACCOUNT} field
is not null, its value is used as account login name. If it is null,
@command{anubis} uses the privileges of the @dfn{default not
privileged user}, 
specified by @code{user-notprivileged} statement in the global
configuration file (@pxref{Security Settings, user-notprivileged}).

The final step is to parse the @dfn{user configuration file}. If
@code{CONFIG} field is not null, its value is used as absolute
path to the configuration file. Otherwise, @command{anubis} searches
for file @file{~/.anubisrc} (where @samp{~} denotes home directory
for the system account obtained on the previous step) and if such
a file exists, loads it.

@node Database URL
@section Database URL

Anubis database is identified by its @dfn{URL}, or @dfn{Universal
Resource Locator}. A @code{URL} consists of following elements
(square brackets enclose optional elements):

@smallexample
@var{proto}://[[@var{user}[:@var{password}]@@]@var{host}]/@var{path}[@var{params}]
@end smallexample

@noindent
where:

@table @var
@item proto
Specifies the database @dfn{protocol}. Protocol describes how
the database is to be accessed. In a way, it may be regarded as
specifying the database @dfn{type}. Currently, GNU Anubis supports
the following database protocols:

@multitable @columnfractions .20 .80
@item @samp{text} @tab A plain text file with users' credentials.
@item @samp{gdbm} @tab @acronym{GDBM} database
@item @samp{mysql} @tab @acronym{MySQL} database
@item @samp{pgsql} @tab @acronym{PostgreSQL} database
@item @samp{postgres} @tab Alias for @samp{pgsql}.
@end multitable

These protocols are described in detail below.

@item user
User name necessary to access the database. 

@item password
User password necessary to access the database. 

@item host
Domain name or @acronym{IP} address of a machine running the database.

@item path
A @dfn{path} to the database. The exact meaning of this element
depends on the database protocol. It is described in detail when
discussing particular protocols.

@item params
A list of protocol-dependent parameters. Each parameter consists
of the @dfn{parameter name}, or @dfn{keyword} and its @dfn{value}
separated by a equals sign:

@smallexample
@var{keyword}=@var{name}
@end smallexample

Multiple parameters are separated by semicolons.
@end table

@menu
* text::        Plain text databases
* gdbm::        Databases in GDBM format
* sql::         MySQL and PostgreSQL databases
@end menu

@node text
@subsection Plain text databases

A simplest database is a plain text file, with lines representing
@dfn{records}. Empty lines and lines beginning with @samp{#}
(@dfn{comments}) sign are ignored. A record consists of
@dfn{fields}, separated by colons (@samp{:}, @acronym{ASCII} 58).
If @samp{:} character occurs as a part of a field, it must be escaped
by a single  backslash character (@samp{\\}, @acronym{ASCII} 92).
The record must contain at least two fields. Fields are placed in
this order:

@enumerate 1
@item @acronym{SMTP} @samp{AUTHID}.
@item @acronym{SMTP} password.
@item Account name. 
@item Path to user configuration file.
@end enumerate 

@subsubheading URL syntax

The @acronym{URL} syntax for this type of databases is quite simple:

@smallexample
text:@var{path}
@end smallexample

@noindent
where @var{path} specifies absolute file name of the database file.

@node gdbm
@subsection Databases in GDBM format

The protocol value @samp{gdbm} specifies a @dfn{GDBM database}. For
the detailed description of @acronym{GDBM} system
@ref{Top,,Introduction,gdbm,The GNU DBM Manual}.

Technically speaking, each @acronym{GDBM} record consists of
a @dfn{key} and @dfn{content}. Its @code{key} holds the value of
@acronym{SMTP} @samp{AUTHID}, whereas its @code{content} holds
@acronym{SMTP} password, system account name and path to user
configuration file, separated by commas. As usual, the two last fields
are optional. 

The @acronym{URL} syntax for @acronym{GDBM} databases is: 

@smallexample
gdbm:@var{path}
@end smallexample

@noindent
where @var{path} specifies absolute file name of the database file.

@node sql
@subsection MySQL and PostgreSQL

This is the most flexible database format. GNU Anubis @value{VERSION}
supports MySQL@footnote{See @url{http://www.mysql.com}.} and
PostgreSQL@footnote{See @url{http://www.postgres.org}.} interfaces.
No matter which of them you use, the implementation details are hidden
behind a single consistent Anubis interface.

GNU Anubis supposes that all user data are kept in a single database
table. This table must have at least four columns for storing
@acronym{SMTP} @samp{AUTHID}, @acronym{SMTP} password, system account name and path to
user configuration file. Among those, only the last two may have
NULL values. There is no restriction on the name of the database or
the authentication table, nor on its column names. This information
may be specified in @acronym{URL} as discussed below.

@subsubheading URL syntax

@smallexample
@var{proto}://[[@var{user}[:@var{password}]@@@var{host}/@var{dbname}[@var{params}]
@end smallexample

@var{Proto} describes the database type to use. Use @samp{mysql}
for MySQL databases and @samp{pgsql} or @samp{postgres} for PostgreSQL
databases.

Optional @var{user} and @var{password} specify authentication
credentials necessary to access the database. 

@var{Host} sets domain name or @acronym{IP} address of the machine running
the database. It may be omitted if the database resides on 
@samp{localhost}.

The database name is specified by the @var{dbname} element.

Any further details needed for connecting to the database are
given by @acronym{URL} parameters. All of them have reasonable
default values, so you'll have to specify only those parameters that
differ from the default. The following parameters are defined:

@table @option
@item port=@var{number}
Specifies port number the database server is listening on.
If it is not given, the behavior depends on the value of the
@option{socket} parameter (see below). If @option{socket} is not present, the
program will use the default port number for the given protocol
(i.e. 3306 for @samp{mysql} and 5432 for @samp{pgsql}.

@item socket=@var{string}
Specifies the UNIX file name of the socket to connect to. This
parameter cannot be used together with @option{port} (see above).

@item bufsize=@var{number}
Sets length of the buffer for storing SQL queries. Default is
1024 bytes.

@item table=@var{string}
Specifies name of the database table with the authentication
data. Default is @samp{users}.

@item authid=@var{string}
Specifies the name of a column in @option{table} which holds 
@samp{AUTHID} value. Default is @samp{authid}.

@item passwd=@var{string}
Specifies the name of a column in @option{table} which holds 
the user password. Default is @samp{passwd}.

@item account=@var{string}
Specifies the name of a column in @option{table} which holds
the name of system account to be used for this @samp{AUTHID}. Default
is @samp{account}.

@item rcfile=@var{string}
Specifies the name of a column in @option{table} which holds
the path to the user's configuration file. Default is @samp{rcfile}.

@FIXME{An example, please.}
@end table

@cindex options file, MySQL
@findex my.cnf
@findex /etc/my.cnf
When using a MySQL database (@samp{mysql://}), database parameters and
access credentials are first read from the file @file{/etc/my.cnf}, if
it exists.  This file called @dfn{option file} in @samp{MySQL} parlance
@ifhtml
(see @uref{http://dev.mysql.com/doc/refman/5.0/en/option-files.html,
option files}).
@end ifhtml
@ifnothtml
(@pxref{option-files, Using Option Files,,mysql,MySQL Manual})
@end ifnothtml
is organized in groups, each group beginning with the group name in
square brackets on a separate line.  Within a group, each non-empty
line consists of a MySQL option name, optionally followed by an equal
sign and the value.  By default, the values from the @samp{anubis}
group are read.

Two additional parameters are provided to fine-tune this behavior:

@table @option
@item options-file=@var{file}
Read options from @var{file} instead of @file{/etc/my.cnf}.  An
empty value (@samp{options-file=}), disables using the options file.

@item options-group=@var{name}
Set the name of the group in the MySQL configuration file, from
which to read configuration options.     
@end table

@node Managing the Database
@section Managing the Database

Managing the user database is a complex task, which looks differently
from administrator's and user's point of view. Administrators have
all privileges on the database, they can add new records and delete or
modify existing ones. Users, of course, do not have such ample
rights. The only thing a user is able to do is to maintain his own
record in the database, provided that he already has one. 

@menu
* Administrators::      Administrator's View
* Users::               User's View
@end menu

@node Administrators
@subsection Administrators

All administrative tasks are done using @command{anubisadm} command ---
a multipurpose tool for Anubis administrator.

The command usage syntax is:

@smallexample
anubisadm @var{command} [@var{options}] @var{database-url}
@end smallexample

@noindent
where @var{command} specifies the operation to be performed on the
database, @var{options} give additional operation-specific parameters,
and @var{database-url} specifies the database to operate upon.

All administrative tasks can be subdivided into the following
five categories:

@itemize
@item Creating the Database
@item Listing Database Records
@item Adding New Records
@item Removing Existing Records       
@item Modifying Existing Records
@end itemize

@menu
* Create::              Creating the Database
* List::                Listing Database Records
* Add::                 Adding New Records
* Remove::              Removing Existing Records       
* Modify::              Modifying Existing Records
* anubisadm summary::   Summary of All Administrative Commands
@end menu

@node Create
@subsubsection Creating the Database

To create a database, use @kbd{anubisadm --create} (or
@kbd{anubisadm -c}). @command{Anubisadm} will read database
entries from the standard input and write them to the database.
The standard input is supposed to be formatted as a @code{text} database
(@pxref{text}).

For example, to create a @acronym{GDBM} database from plain text file
@file{userlist}, use the following command

@smallexample
anubisadm --create gdbm:/etc/anubis.db < userlist
@end smallexample

@noindent
Similarly, to create an initially empty database, type

@smallexample
anubisadm --create gdbm:/etc/anubis.db < /dev/null
@end smallexample

@emph{Notice}, that if you use @acronym{SQL} database format,
@option{--create} command does not imply creating the database
structure! So, before running

@smallexample
anubisadm --create mysql://localhost/dbname < userlist
@end smallexample 

@noindent
make sure you create the underlying database structure (including
granting privileges to the @command{anubis} user), via the
usual procedure. Please refer to corresponding database manual
for the detailed instructions on this.

It is sometimes necessary to convert an existing user database
from one format (protocol) to another. For example, suppose you
have been running @acronym{GDBM} database (@code{text:/etc/anubis.db})
for some time, but now it has grown considerably and you decided to
switch to PostgreSQL database to improve performance. To do so,
first create the database using postgres utilities. Then run

@smallexample
anubisadm --list text:/etc/anubis.db | \
 anubisadm --create pgsql://localhost/dbname
@end smallexample

@noindent 
That's all there is to it!

@node List
@subsubsection Listing Database Records

The @option{--list} (or @option{-l}) option lists the existing
database:

@smallexample
anubisadm --list gdbm:/etc/anubis.db
@end smallexample

By default it displays all records from the database.

Among its other uses, such invocation is handy for converting
user database to another format (@pxref{Create}).

If you wish to list only a particular record, specify the 
@code{AUTHID} using @option{--authid} (@option{-i}) option. For example,
to list the record for @code{AUTHID} @samp{test},
type:

@smallexample
example$ anubisadm --list --authid test gdbm:/etc/anubis.db
@end smallexample


@node Add
@subsubsection Adding New Records

To add a new record use the @option{--add} (@option{-a}) option.
Additional data are specified via the following options:

@table @option
@item -i @var{string}
@itemx --authid=@var{string}
Specify the user @code{SMTP AUTHID}. 

@item -p @var{string}
@itemx --password=@var{string}
Specify the user password. 

@item -u @var{string}
@itemx --user=@var{string}
Specify the system user name for this @code{AUTHID}.

@item -f @var{string}
@itemx --rcfile=@var{string}
Specify configuration file to be used for this user.
@end table

For example, the following command adds a record with @code{SMTP
AUTHID} @samp{test}, password @samp{guessme} and maps it
to the system account @samp{gray}:

@smallexample
anubisadm --add --authid test --password guessme \
          --user gray gdbm:/etc/anubis.db
@end smallexample

@node Remove
@subsubsection Removing Existing Records

Removing a record is quite straightforward: use the @option{--remove}
(@option{-r}) option and supply the @code{AUTHID} to delete via the
@option{--authid} option. For example, to remove the record created
in the previous subsection, run:

@smallexample
anubisadm --remove --authid test gdbm:/etc/anubis.db
@end smallexample

@node Modify
@subsubsection Modifying Existing Records

To modify an existing record use the @option{--modify}
(@option{-m}) option. The record is identified via the
@option{--authid} option. The following options supply
the changed values:

@table @option
@item -p @var{string}
@itemx --password=@var{string}
Specify new user password. 

@item -u @var{string}
@itemx --user=@var{string}
Specify new system user name for this @code{AUTHID}.

@item -f @var{string}
@itemx --rcfile=@var{string}
Specify the user's configuration file.
@end table

For example, the following command sets new configuration file name
for the user @samp{smith}:

@smallexample
anubisadm --authid smith \
          --rcfile=/var/spool/anubis/common gdbm:/etc/anubis.db
@end smallexample

@node anubisadm summary
@subsubsection Summary of All Administrative Commands

@itemize @bullet
@item Usage
@smallexample
anubisadm @var{command} [@var{options}] @var{database-url}
@end smallexample

@item Commands:
@table @option
@item -c
@itemx --create
Create the database.

@item -l
@item --list
List the contents of an existing database.

@item -a
@item --add
Add a new record.

@item -m
@itemx --modify
Modify an existing record.

@item -r
@item --remove
Remove an existing record.

@item --version
Display program version number and exit.

@item --help
Display short usage summary and exit.
@end table

@item Options:
@table @option
@item -i @var{string}
@itemx --authid=@var{string}
Specify the authid to operate upon. This option is mandatory for
@option{--add}, @option{--modify} and @option{--remove} commands.
It may also be used with @option{--list} command.

@item -p @var{string}
@itemx --password=@var{string}
Specify the password for the authid. This option is mandatory for
@option{--add}, @option{--modify} and @option{--remove} commands.

@item -u @var{string}
@itemx --user=@var{string}
Specify the system user name corresponding to the given authid. It may
be used with @option{--add}, @option{--modify}, and @option{--remove}
commands.

@item -f @var{string}
@itemx --rcfile=@var{string}
Specify the rc file to be used for this authid. The option may
be used with @option{--add}, @option{--modify}, and @option{--remove}
commands.
@end table
@end itemize

@node Users
@subsection Users

Users maintain their database records via the @command{anubisusr}
command. We recommend to invoke
@command{anubisusr} from your @file{~/.profile}, which will make
sure that your configuration file is up to date when you log in.
@footnote{Make sure to run @command{anubisusr} in background, so
it does not slow down your normal login sequence.}.
@FIXME{anubisusr should also allow to modify user
password. This is the only database field, apart from @code{CONFIG}
that the user may be allowed to change}

@subsubheading Usage

@smallexample
anubisusr [@var{options}] [@var{smtp-url}]
@end smallexample

@noindent
where @var{smtp-url} is a @acronym{URL} of your GNU Anubis server.
Notice that if it lacks user name and password, then
@command{anubisusr} will first try to retrieve them from your
@file{~/.netrc} file (@pxref{netrc,,,netrc(5), netrc manual page}), and if not
found, it will prompt you to supply them.

@subsubheading Options

@table @option
@item -m @var{mech}
@itemx --mechanism @var{mech}
Use the SASL mechanism @var{mech}. Give this option several times
to set a list of allowed mechanisms.

@item --file=@var{file}
@itemx -f @var{file}
Sets the user configuration file name (default is @file{.anubisrc}).

@item --netrc+@var{file}
@itemx -n @var{file}
Sets the name of the automatic login configuration file (default is
@file{.netrc}).

@item -v
@itemx --verbose
Verbose output. Multiple options increase verbosity. Maximum verbosity
level is 3.
@end table

Options controlling encryption:
  
@table @option  
@item --disable-tls
@itemx -d
Disable the use of TLS encryption.

@item --tls-cafile=@var{file}
@itemx -C @var{file}
Sets the name of certificate authority file to use when verifying the
server certificate.

@item --tls-priorities=@var{list}
Sets cipher suite preferences to use.  The @var{list} argument may
contain a single initial keyword or be a colon-separated list of TLS
keywords.  The description of TLS keywords is well beyond the scope of
this document.  Please refer to @ref{Priority Strings,Priority
Strings,,gnutls,GnuTLS Manual}, for a detailed discussion.

Default priority list is @samp{NORMAL}.
@end table
  
Informational options:  

@table @option
@item --version
Display program version number and exit.

@item --help
Display short usage summary and exit.
@end table

@node Configuration
@chapter Configuration
@cindex configuration
@cindex settings
@cindex system configuration file
@cindex user configuration file

The behavior of GNU Anubis is controlled by two configuration files.
The @dfn{system configuration file}, @file{/etc/anubisrc},
supplies system-wide settings that affect all users. This file is usually
owned by root. The @dfn{user configuration file} specifies what GNU
Anubis should do for a particular user. By default it is located
in @file{~/.anubisrc}. This location can be changed if
@command{anubis} operates in auth mode. The permissions of
a user configuration file must be set to 0600 (u=rw,g=,o=),
otherwise GNU Anubis won't accept the file.

@subheading Lexical Structure

Both configuration files use simple line-oriented syntax. Each
line introduces a single statement. A statement consists of
@dfn{words}, each word being defined as a contiguous sequence of
non-whitespace symbols. A word may be composed of alphanumeric
characters and any of the following punctuation symbols:
@samp{_}, @samp{.}, @samp{/}, @samp{-}. Any arbitrary sequence
of characters enclosed in a pair of double quotes is also recognized
as a word. Such a sequence is called @dfn{quoted string}.

@cindex Quoted Strings
@cindex Escape Sequences
Quoted strings follow the same syntax rules as in the C language.
A backslash character @samp{\} alters the meaning of the character
following it. This special construct is called @dfn{escape sequence}.
When processing an escape sequence, Anubis removes it from the string
and replaces it with a single character as described in the following
table:

@float Table, backslash-interpretation
@caption{Backslash escapes}
@multitable @columnfractions 0.30 .5
@item Sequence @tab Replaced with
@item \a @tab Audible bell character (@acronym{ASCII} 7)
@item \b @tab Backspace character (@acronym{ASCII} 8)
@item \e @tab Escape (@acronym{ASCII} (@acronym{ASCII} 27)
@item \f @tab Form-feed character (@acronym{ASCII} 12)
@item \n @tab Newline character (@acronym{ASCII} 10)
@item \r @tab Carriage return character (@acronym{ASCII} 13)
@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
@item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
@end multitable
@end float

A backslash followed by any character not listed above is replaced by
the character alone. This can be used, in particular, for inserting
@samp{"} character within a string, as in the example below:

@smallexample
"This string contains \"quoted string\"."
@end smallexample

Similarly, a backslash followed by a newline is replaced by the newline
itself. Thus, the following two strings are equivalent:

@smallexample
"This string is split\nover two lines"

"This string is split\
over two lines"
@end smallexample

@FIXME{Should we support \ooo (o is an octal digit) and \\xHH (H is a
hex digit) syntax? I'd say yes, but then a special exception should be
made for back references \1 - \9.}

The familiar shell @dfn{here document} syntax may be used to produce
a word containing several lines of text. The syntax is:

@smallexample
<<[-]delimiter
    text
delimiter
@end smallexample                                                  

If ``here document'' starts with @samp{<<-}, then all leading tab
characters are stripped from input lines and the line containing
@dfn{delimiter}. This allows to indent here-document in a natural
fashion.

To summarize all the above, let's consider an example:

@smallexample
@group
first-word "second word" <<-EOT
                            Third word
                            containing several
                            lines of text
                            EOT
@end group
@end smallexample

@noindent
This line contains three words: @samp{first-word}, @samp{second word}
and the third one composed of the three lines between the @samp{EOT}
markers.

If a statement is very long, it may be split among several lines
of text. To do so, end each line with a backslash (@samp{\}),
immediately before the newline, as in:

@smallexample
@group
a very long statement\
  occupying several lines\
  of text
@end group  
@end smallexample

A @samp{#} in a line starts a @dfn{comment}. It and the rest of
the line are ignored. Comments may appear on any of the lines in
the configuration file, except on a command and within a
``here-document'' construction.
A line containing just a comment (with optional whitespace before it) is
effectively blank, and is ignored. For example:

@smallexample
@group
# This is a comment
if header[Subject] :re "No.*"  # This is also a comment
  guile-process action-name This # is not a comment!!!
fi
@end group
@end smallexample

@subheading Logical Structure

Statements in a configuration file are grouped into
@dfn{sections}. Each section has its name. A section begins with
one of the following constructs:

@smallexample
BEGIN @var{name}
---BEGIN @var{name}---
@end smallexample

@noindent

and ends with one of the following constructs:

@smallexample
END
---END---
@end smallexample

Notice, that both @samp{BEGIN} and @samp{END} must be uppercase.
When using the second form, any amount of whitespace is allowed
between the three dashes and the word.

Sections cannot be nested.

There are five predefined sections, whose names are uppercase.
The user may define his own sections, which may then be referred
to from the @code{RULE} section as subroutines (@pxref{Call Action}).

The predefined section names are:

@table @dfn
@item AUTH
Defines authentication mechanisms. 
@item CONTROL
This section specifies the basic GNU Anubis behavior. Its presence
is required in the system configuration file. It may be used in
the user configuration file to override the system-wide settings.
@item TRANSLATION
This section specifies a translation map for mapping
remote user names to local ones. It may be used only in the system-wide
configuration file.
@item GUILE
Configures Guile interpreter. This section is allowed in both
configuration files.
@item RULE
Defines rules that for altering the message contents.
@end table

@menu
* AUTH Section::
* CONTROL Section::
* TRANSLATION Section::
* GUILE Section::
@end menu

@node AUTH Section
@section AUTH Section
@cindex AUTH section

The @code{AUTH} session controls various aspects of authentication mode.

@deffn Option smtp-greeting-message @var{text}
Configures the greeting message issued by GNU Anubis upon accepting
the connection.
@end deffn

@deffn Option smtp-help-message @var{help-text}
Defines the message issued in response to @acronym{SMTP}
@code{HELP} command. @var{Help-text} is a list of strings. Each string
from the list will be displayed on a separate response line.
@end deffn

@deffn Option sasl-password-db @var{url}
Sets @acronym{URL} of the user database (@pxref{User Database}).
@end deffn

@deffn Option sasl-allowed-mech @var{mech-list}
Defines the list of allowed authentication methods.
@end deffn

@deffn Option sasl-service @var{name}
Sets the SASL @dfn{service name}. It is used, among others, with GSSAPI
authentication method. Default is @samp{anubis}.
@end deffn

@deffn Option sasl-hostname @var{name}
Sets the SASL hostname. By default, the server determines it
automatically. If, however, it makes a wrong guess, you can fix it
using this directive.
@end deffn

@deffn Option sasl-realm @var{name}
Sets the SASL realm. By default, the local domain is used as SASL realm
(@pxref{Basic Settings, local-domain}).
@end deffn

@node CONTROL Section
@section CONTROL Section
@cindex CONTROL section

The @samp{CONTROL} section defines basic GNU Anubis behavior.
If used in the system configuration file, it applies to all users on
the machine. Each user can have a @samp{CONTROL} section in his
configuration file, to customize his personal settings. Of course, not
all options can be set or changed by the user. Some options can only be
set in the system configuration file, and some only in user
configuration file. By default, options specified in the user
configuration file have a @strong{higher} priority than those
specified in system configuration file.

All option names are case insensitive, so that
@code{bind} or @code{BIND} or @code{BiNd} all refer to the same option.

@menu
* Basic Settings::
* Output and Debugging Settings::
* SOCKS Proxy::
* ESMTP Authentication Settings::
* Encryption Settings::
* Security Settings::
@end menu


@node Basic Settings
@subsection Basic Settings
@UNREVISED{}

@deffn Option bind [@var{host}:]@var{port}
Specify the @acronym{TCP} port on which GNU Anubis listens for connections.
The default @var{host} value is @w{@samp{INADDR_ANY}}, which means
that anyone can connect to GNU Anubis. The default @var{port} number
is 24 (private mail system). This option is available only in the
system configuration file.

For example, to bind GNU Anubis to port 25 (@acronym{SMTP}) and limit
its clients only to those from @samp{localhost}, set the following in
your system configuration file:

@smallexample
bind localhost:25
@end smallexample
@end deffn

@deffn Option remote-mta @var{host}[:@var{port}]
Specify a host name or @acronym{IP} address of the remote
@acronym{SMTP}. GNU Anubis will forward mails to that server. The
default @var{port} number is 25. This option is available in both
configuration files.
@end deffn

@deffn Option local-mta @var{file-name} [@var{args}]
Execute a local @acronym{SMTP} server, which works on standard input and output
(inetd-type program). For example:

@smallexample
local-mta /usr/sbin/sendmail -bs
@end smallexample

The @samp{CONTROL} section must contain either @code{local-mta} or
@code{remote-mta}, but not both.
@end deffn

@deffn Option mode @var{mode-name}
Selects Anubis operation mode. Allowed values for @var{mode-name}
are:

@table @asis
@item proxy
@item transparent
@item auth
@end table

@xref{Authentication}, for the detailed discussion of GNU Anubis
operation modes.
@end deffn

@deffn Option read-entire-body @var{yes-or-no}
Normally, when processing a multi-part message with external
filter (@pxref{External Processor}), Anubis feeds
only the first part to the filter. The rest of the message is copied
verbatim. To alter this behavior so that your external program
sees the entire message body, set @code{read-entire-body yes}
in your control  section.
@end deffn

@deffn Option incoming-mail-rule @var{string} 
Declares the name of command section for incoming mail. Default is
@samp{INCOMING}. This option is available only for system
configuration file. @xref{MDA Mode}, for detailed description of
incoming mail processing.
@FIXME{More info?}
@end deffn

@deffn Option outgoing-mail-rule @var{string}
Declares the name of command section for outgoing mail. Default is
@samp{RULE}. This option is available only for system
configuration file.
@end deffn

@deffn Option smtp-command-rule @var{string}
Declares the name of command section for rewriting @acronym{SMTP}
commands. Default is @samp{SMTP}. This option is available only
for system configuration file. @xref{Modifying SMTP Commands}.
@end deffn

@deffn Option log-tag @var{string}
Tag syslog messages with @var{string}. Default is @samp{anubis}.
@end deffn

@deffn Option log-facility @var{string}
Use syslog facility @var{string} for logging. Valid argument values
are: @samp{user}, @samp{daemon}, @samp{auth}, @samp{authpriv},
@samp{mail}, @samp{cron}, @samp{local0} through @samp{local7} (all
names case-insensitive, optionally prefixed by @samp{log_}), or a
decimal facility number.  Default is @samp{mail}.
@end deffn

@deffn Option local-domain @var{string}
Set local domain name.  By default, the domain name is defined as the
part of the local host name following the first dot.

Local domain name is used as @acronym{SASL} realm, unless overridden
by @samp{sasl-realm} statement (@pxref{AUTH Section, sasl-realm}).
@end deffn

@node Output and Debugging Settings
@subsection Output Settings

@deffn Option termlevel @var{level}
Defines logging verbosity level. Allowed values are:

@table @asis
@item normal
Only errors are logged. This is the default level.

@item verbose
Produce more diagnostic output.

@item debug
Produce debugging output.

@item silent
Do not log anything.

@end table
This command is allowed only in the system configuration file.
@end deffn

@deffn Option logfile @var{file-name}
This command sets the name of the additional log file. GNU Anubis logs
there the messages about user's @acronym{SMTP} session, as defined by
the @samp{loglevel} statement (see below). For example:

@smallexample
logfile "anubis.log"
@end smallexample

This will direct additional logging to the @file{~/anubis.log} file in
the user's home directory.
@end deffn

@deffn Option loglevel @var{level}
This option defines the verbosity level for the additional log
file. It may be used only in user configuration file. Allowed
values for @var{level} are:

@table @asis
@item none
@item fails
Log only failure messages.

@item all
Log all relevant messages.
@end table
@end deffn

@deffn Option tracefile @var{yes-or-no}
@deffnx Option tracefile @var{file-name}
This option instructs @command{anubis} to log the execution of
tests and actions from the RULE sections. This is useful
for debugging configuration files.

When this option is used in the system-wide configuration file,
only boolean argument is allowed. Using @samp{tracefile yes} enables
logging of the actions and tests to the default syslog channel.
Using @samp{tracefile no} disables it.

When used in the user configuration file, a filename is allowed
as an argument to this option. This allows you to explicitly
specify to which file the tracing output should go. Otherwise,
using @samp{tracefile yes} enables logging to the same file
as @samp{logfile} (if possible).
@end deffn

@deffn Option HANG @var{delay}
@emph{Do not use this option, unless you are developing or debugging
Anubis!}

This option instructs each child process to hang for the given number
of seconds. Before hanging, the process issues the following
diagnostic message:

@smallexample
Child process suspended for @var{delay} seconds
@end smallexample

This option is useful for Anubis developers who wish to
attach to a child process with debugger. After attaching, set the
variable @code{_anubis_hang} to zero to continue processing. You may
wish to add the following statement to your @file{.gdbinit} file:

@smallexample
set variable _anubis_hang=0
@end smallexample

@end deffn

@node SOCKS Proxy
@subsection SOCKS Proxy
@cindex @acronym{SOCKS} proxy

@deffn Option socks-proxy @var{host}[:@var{port}]
Enables tunneling incoming connections through a @acronym{SOCKS} proxy server,
specified as an argument @var{host}. The default value for @var{port} is
1080, which is a common port number for @acronym{SOCKS} proxies.
@end deffn

@deffn Option socks-v4 @var{yes-or-no}
Use @acronym{SOCKS} protocol version 4. By default it is turned off,
and version 5 of the @acronym{SOCKS} protocol is used.
@end deffn

@deffn Option socks-auth @var{username}:@var{password}
Sets user name and password for the @acronym{SOCKS} proxy server.
@end deffn

@node ESMTP Authentication Settings
@subsection ESMTP Authentication Settings
@cindex ESMTP authentication

The following options set authentication credentials for @acronym{ESMTP}
authentication. They are useful, for example, if your @acronym{MTA}
requires such an authentication, but your @acronym{MUA} does not support it.

You can also use these statements in a @samp{SMTP} section. 
@xref{Modifying SMTP Commands}, for a detailed description of this feature.

@deffn Option esmtp-allowed-mech @var{mech-list}
Defines the list of allowed authentication mechanisms. @var{Mech-list}
is a list of valid authentication mechanism names separated by
whitespace.

Anubis selects the authentication method using the following algorithm:
@acronym{MTA} presents the list of authentication methods it supports.
For each element in @var{mech-list}, Anubis tests whether it is
available in the list presented by @acronym{MTA}. If found, this method is
selected. For example, suppose that the @acronym{MTA} supports the following
mechanisms:

@smallexample
PLAIN LOGIN CRAM-MD5 ANONYMOUS
@end smallexample

@noindent
and in your configuration file you have:

@smallexample
esmtp-allowed-mech DIGEST-MD5 CRAM-MD5 LOGIN
@end smallexample

@noindent
Then, Anubis will select CRAM-MD5.

@end deffn

@deffn Option esmtp-require-encryption @var{mech-list}
Declares the list of mechanisms that may be used only over
a TLS encrypted channel. By default Anubis uses

@smallexample
esmtp-require-encryption LOGIN PLAIN
@end smallexample

@noindent
This prevents sending user password over an unencrypted connection.

@end deffn

@deffn Option esmtp-auth-delayed @var{yes-or-no}
By default, ESMTP authentication is attempted as early as
possible, normally while handling the client @samp{EHLO} command.

When this statement is set to @samp{yes}, authentication is delayed
until the client issued the @samp{MAIL} command. This allows you
to select authentication credentials depending on the sender email.
For a detailed description of this feature, see @ref{Modifying SMTP Commands}.
@end deffn

@deffn Option esmtp-auth-id @var{authentication-id}
Sets authentication @acronym{ID} (user name).
@end deffn

@deffn Option esmtp-authz-id @var{authorization-id}
Sets authorization @acronym{ID} (user name).
@end deffn

@deffn Option esmtp-password @var{password}
Sets @acronym{ESTMP AUTH} password.
@end deffn

@deffn Option esmtp-auth @var{username}:@var{password}
This is a shortcut to set both authentication and authorization
@acronym{ID}s and the password. It is equivalent to

@smallexample
esmtp-auth-id @var{username}
esmtp-authz-id @var{username}
esmtp-password @var{password}
@end smallexample

@end deffn

The following options specify authentication credentials for GSSAPI,
DIGEST-MD5 and KERBEROS_V5 authentication mechanisms:

@deffn Option esmtp-service @var{service-name}
Sets the name of GSSAPI service.
@end deffn

@deffn Option esmtp-hostname @var{hostname}
Sets hostname of the machine.
@end deffn

@deffn Option esmtp-generic-service @var{servise-name}
Sets generic service name.
@end deffn

@deffn Option esmtp-passcode @var{passcode}
Sets passcode.
@end deffn

@deffn Option esmtp-realm @var{realm-name}
Sets GSSAPI realm.
@end deffn

The following option is useful with the @samp{ANONYMOUS}
authentication mechanism:

@deffn Option esmtp-anonymous-token @var{token}
Sets the token to be used with the @samp{ANONYMOUS} authentication mechanism
@end deffn

@node Encryption Settings
@subsection Encryption Settings

@deffn Option ssl @var{yes-or-no}
Enable or disable the @acronym{TLS/SSL} encryption between the
@acronym{MUA} and the @acronym{MTA}. The default is @samp{no}, but
using the @acronym{TLS/SSL} encryption is recommended. You should also
set your private key and certificate using the @samp{ssl-key} and
@samp{ssl-cert} keywords (defined below).

@xref{TLS/SSL}, for details.
@end deffn

@deffn Option ssl-oneway @var{yes-or-no}
Enable the @dfn{ONEWAY} encryption. Set @code{ssl-oneway yes},
if you want to use the @acronym{TLS/SSL}, but your @acronym{MUA}
doesn't support @acronym{ESMTP} @acronym{TLS/SSL}. Using
this option does not require setting the @samp{ssl-key} and
@samp{ssl-cert} options. 
@end deffn

@deffn Option ssl-priorities @var{list}
Sets cipher suite preferences to use.  The @var{list} argument may
contain a single initial keyword or be a colon-separated list of TLS
keywords.  The description of TLS keywords is well beyond the scope of
this document.  Please refer to @ref{Priority Strings,Priority
Strings,,gnutls,GnuTLS Manual}, for a detailed discussion.

Default priority list is @samp{NORMAL}.
@end deffn

@deffn Option ssl-cert @var{file-name}
Specify the certificate for the @acronym{TLS/SSL} encryption.

Default for @var{file-name} is @file{anubis.pem}.
@end deffn

@deffn Option ssl-key @var{file-name}
Set the private key for the @acronym{TLS/SSL} encryption.

The default @var{file-name} is @file{anubis.pem}.
@end deffn

@deffn Option ssl-cafile @var{file-name}
Specify CA certificate file (supported only by GnuTLS).
@end deffn


@node Security Settings
@subsection Security Settings

The following options control various security settings. 

@deffn Option drop-unknown-user @var{yes-or-no}
If this option is set to @samp{yes}, @command{anubis} drops
sessions which failed verification by the @acronym{IDENT} service.

This option is in effect only in @samp{transparent} mode.

Default is @samp{no}.
@end deffn

@deffn Option user-notprivileged @var{username}
Defines the @dfn{unprivileged} user, i.e. the user with whose
privileges @command{anubis} runs most of the time. This option is
available only in the system configuration file. For example: 

@smallexample
user-notprivileged "anubis"
@end smallexample

@strong{Caution:} This user must exist in the system user database
(@file{/etc/passwd}).
@end deffn

@deffn Option rule-priority @var{value}
This statement defines the order of execution of the system and user
@code{RULE} sections (@xref{Rule System}, for a detailed description).
It is available only in system configuration file.

Allowed values are:

@table @code
@item system
First execute the system section, then the user one.

@item user
First execute the user section, then the system one.

@item system-only
Execute only the system @code{RULE} section.

@item user-only
Execute only the user @code{RULE} section.
@end table
@end deffn

@deffn Option control-priority @var{value}
Sets the order of processing @code{CONTROL} sections. This option is
available only in system configuration file.

Allowed values are:

@table @code
@item system
The system @code{CONTROL} section is processed first. Notice, that
this means that the user may override the system settings in his
configuration file. This is the default setting.

@item user
The user @code{CONTROL} section is processed first. Thus, the
system-wide settings always override users' private settings.
@end table
@end deffn

@node TRANSLATION Section
@section TRANSLATION Section
@cindex TRANSLATION section

The @samp{TRANSLATION} section specifies how to translate remote or local
user names, or host names or addresses, to local user names.
The @samp{TRANSLATION} section is available only in the system
configuration file. The syntax is:

@smallexample
@group
---BEGIN TRANSLATION---
translate  [@var{user}@@]@var{address} into  @var{username}
...
---END---
@end group
@end smallexample

@var{address} means host name or @acronym{IP} address. You can also specify
@samp{0.0.0.0}, and it means any address (@samp{INADDR_ANY}).

For example:

@smallexample
@group
BEGIN TRANSLATION
translate jack@@somewhere.net into john
END
@end group
@end smallexample

@noindent
This rule will allows the remote user @samp{jack} at @samp{somewhere.net}
to use the configuration file of the local user @samp{john}.

In the contrast, this statement:
@smallexample
translate somewhere.net into john
@end smallexample
@noindent
means that @emph{all} users at @samp{somewhere.net} are allowed to use
the local john's configuration file.

@node GUILE Section
@section GUILE Section
@cindex GUILE section
@cindex Guile
@cindex extension language
@cindex Scheme

@deffn Command guile-output @var{file}
Specifies the name of the file to bind to the Scheme standard error
and output ports.

By default both ports are redirected to syslog. Standard error port
uses the @samp{err} priority, standard output port writes to the
@samp{warning} priority.

This option has no effect if GNU Anubis is started
with either of @option{--foreground} or @option{--stdio} command line
options. 
@end deffn

@deffn Command guile-debug @var{yes-or-no}
When set to @samp{yes} enables Guile stack traces and debugging output.
@end deffn

@deffn Command guile-load-path-append @var{path}
Appends the given @var{path} to the list of Guile load paths
(@pxref{Build Config, %load-path,,guile,The Guile Reference Manual}).
@end deffn

@deffn Command guile-load-program @var{file}
Reads the given Scheme program.
@end deffn


@node Rule System
@chapter The Rule System
@cindex rule system

The rule system is a core part of GNU Anubis. It can be regarded
as a program that is executed for every outgoing message. 

Throughout this chapter, when showing syntax definitions their
optional parts will be enclosed in a pair of square
brackets, e.g.:

@smallexample
keyword [@var{optional-part}] @var{mandatory-part}
@end smallexample

@noindent
When the square braces are required symbols, they will be marked
as such, e.g.:

@smallexample
remove @samp{[}@var{key}@samp{]}
@end smallexample

The rule system is defined in the @dfn{RULE} section.
The statements within this section are executed sequentially.
Each statement is either an @dfn{action} or a @dfn{conditional
statement}.

@menu
* Actions::
* Conditional Statements::
* Triggers::
* Boolean Operators::
* Regular Expressions::
* Action List::
* Using Guile Actions::
@end menu


@node Actions
@section Actions
@cindex actions defined

An @dfn{action} is a statement defining an operation 
over the message. Syntactically, each action is

@smallexample
@var{command} [=] @var{right-hand-side}
@end smallexample

@noindent
Where @var{command} specifies the operation and
@var{right-hand-side} specifies its arguments. The equal sign
is optional.


@node Conditional Statements
@section Conditional Statements
@cindex Conditional statements
@cindex @code{if}, conditional statements
@cindex @code{else}, conditional statements
@cindex @code{fi}, conditional statements

A @dfn{conditional statement} defines the control flow within the section.
It allows to execute arbitrary actions depending on whether a certain
condition is met. The conditional statement in its simplest form is:

@smallexample
if @var{condition}
  @var{action-list-1}
fi
@end smallexample

If @var{condition} evaluates to true, then the list of statements
@var{action-list-1} is executed.

A simple @var{condition} has the following syntax:

@smallexample
@var{part} [@var{sep}] [@var{op}] [@var{pattern-match-flags}] @var{regex}
@end smallexample

@noindent
(where the square brackets denote optional parts).  Its parts are:

@table @var
@item part
Specifies which part of the input should be considered
when evaluating the condition. It is either @samp{command}, meaning
the text of the @acronym{SMTP} command issued while sending the message, or
@samp{header}, meaning the value of an @acronym{RFC}822 header. Either
of the two may be followed by the name of the corresponding command or
header enclosed in square brackets. If this part is missing, all
command or headers will be searched. 

@item sep
Optional @dfn{concatenation separator}.  @xref{Concatenations},
for its meaning.

@item op
Either @samp{=}, meaning ``match'', or @samp{!=}, meaning ``does not
match''.  Missing @var{op} is equivalent to @samp{=}.

@item pattern-match-flags
Optional @var{pattern-match-flags} alter the pattern matching
type used in subsequent conditional expression. It
will be described in detail in the section @ref{Regular Expressions}.

@item regex
Regular expression enclosed in double quotes.
@end table

The condition yields true if @var{regex} matches
the @var{part} (if @var{op} is @samp{=}), or does not
match it (if @var{op} is @samp{!=}).

For example:

@smallexample
@group
if header [Subject] "^ *Re:"
  ...
fi
@end group
@end smallexample

The actions represented by @dots{} will be executed only if the
@samp{Subject:} header of the message starts with @samp{Re:} optionally
preceded by any amount of whitespace.

A more elaborate form of the conditional allows you to choose among
the two different action sets depending on a given condition. The
syntax is:

@smallexample
if @var{condition}
  @var{action-list-1}  
else
  @var{action-list-2}
fi
@end smallexample

Here, @var{action-list-1} is executed if the 
@var{condition} is met. Otherwise, @var{action-list-2} is
executed.

Note, that both @var{action-list-1} and @var{action-list-2} may in
turn contain conditionals, so that the conditional
statements may be nested. This allows to create very sophisticated
rule sets. As an example, consider the following statement:

@smallexample
if [List-Id] :re ".*<anubis-commit@@gnu.org>"
  modify [Subject] "[Anubis Commit Notice] &"
else
  if [List-Id] :re ".*<bug-anubis@@gnu.org>"
    modify [Subject] "[Anubis Bug Notice] &"
  else
    add [X-Passed] "Subject checking"
  fi
fi  
@end smallexample

The effect of this statement is: depending on the value of
@code{List-Id} header, prepend the @code{Subject} header with an
identification string, or add an @code{X-Passed} header if no known
@code{List-Id} was found.

To simplify writing such nested conditional statements, the
@samp{elif} keyword is provided:

@smallexample
if @var{condition-1}
  @var{action-list-1}
elif @var{condition-2}  
  @var{action-list-2}
else
  @var{action-list-3}
fi
@end smallexample

This statement is equivalent to:

@smallexample
if @var{condition}
  @var{action-list-1}
else
  if @var{condition-2}  
    @var{action-list-2}
  else
    @var{action-list-3}
  fi
fi
@end smallexample

Any number of @samp{elif} branches may appear in a conditional
statement, the only requirement being that they appear before
the @samp{else} statement, if it is used.

@menu
* Concatenations::
@end menu


@node Concatenations
@subsection Concatenations
@cindex Concatenation
It is important to understand that conditional expressions choose
the first match.  To illustrate this, lets suppose you wish to store
all recipient emails from the envelope in the
@samp{X-Also-Delivered-To} header.  A naive way to do so is:

@smallexample
if command [rcpt to:] = "(.*)"
  add header [X-Also-Delivered-To] "\1"
fi
@end smallexample

However, this will store only the very first @code{RCPT TO} value, so
you will not achieve your goal.

To help you in this case, @command{anubis} offers a
@dfn{concatenation} operator, whose effect is to concatenate the
values of all requested keys prior to matching them against the
regular expression.  Syntactically, the concatenation operator is a
string enclosed in parentheses, placed right after the key part of a
condition.  This string is used as a separator when concatenating
values.  For example:

@smallexample
if command [rcpt to:] (",") = "(.*)"
  add header [X-Also-Delivered-To] "\1"
fi
@end smallexample

This fragment will first create the string containing all @code{RCPT
TO} addresses, separated by a comma, and then match it against
the regular expression on the right hand side.  Since this expression
matches any string, the @samp{\1} will contain a comma-separated list
of addresses.

@node Triggers
@section Triggers
@cindex Triggers

Triggers are conditional statements that use the value of the
@samp{Subject} header to alter the control flow. Syntactically, a
trigger is:

@smallexample
@group
trigger [@var{flags}] @var{pattern}
  @var{action-list}
done
@end group
@end smallexample

@noindent
Here, @var{pattern} is the pattern against which the @samp{Subject}
header is checked, @var{flags} are optional flags controlling the
type of regular expression used (@pxref{Regular Expressions}). For
backward compatibility, the keyword @code{rule} may be used instead
of @code{trigger}.

The triggers act as follows: First, the value of the @samp{Subject} header is
matched against the pattern @samp{@@@@}@var{pattern}. If it matches,
then the matched part is removed from the @samp{Subject}, and the
@var{action-list} is executed.

Basically, putting aside the possibility to use different flavors of
regular expressions, a trigger is equivalent to the following statement:

@smallexample
@group
if header[Subject] :posix "(.*)@@@@@var{pattern}"
  modify header [Subject] "\1"
  @var{action-list}
fi
@end group
@end smallexample

Thus, adding the @samp{@@@@@var{rule-name}} code to the @samp{Subject}
header of your message, triggers a rule named @var{rule-name},
specified in a user configuration file. For example:

@smallexample
@group
BEGIN RULE
trigger :basic "^gpg-encrypt-john"
   gpg-encrypt "john's_gpg_key"
done
END
@end group
@end smallexample

@noindent
Now, if you send an email with the subject ending on
@samp{@@@@gpg-encrypt-john} (e.g.: @samp{Subject: hello
John!@@@@gpg-encrypt-john}), it will be encrypted with John's public
key. The trigger will remove the @samp{@@@@}, so John will only
receive a message with @samp{hello John!} as a subject.

Another example shows an even more dynamic trigger, that is using
a substitution and back-references:

@smallexample
@group
---BEGIN RULE---
trigger :extended "^gpg-encrypt:(.*)"
   gpg-encrypt "\1"
   add [X-GPG-Comment] "Encrypted for \1"
done
---END---
@end group
@end smallexample

@noindent
To encrypt a message to user e.g. @samp{John}, simply send an email with
a subject @w{@samp{hello John!@@@@gpg-encrypt:john's_gpg_key}}.
This way, you decide at a run time which public key should be used,
without creating separate rules for each user; thanks to back-references,
those 3---4 lines are enough.


@node Boolean Operators
@section Boolean Operators

The following table lists the three boolean operators that can be used
in Anubis conditional expressions in the order of increasing binding
strength:

@itemize @bullet
@item @samp{OR}
@item @samp{AND}
@item @samp{NOT}
@end itemize

As an example, let's consider the following statement:

@smallexample
@group
if header[X-Mailer] "mutt" or header[X-Mailer] "mail" \
   and not header[Content-Type] "^multipart/mixed;.*"
   @var{action}
fi
@end group
@end smallexample

In this case the @var{action} will be executed if the @code{X-Mailer}
header contains the word @samp{mutt}. The same @var{action} will also
be executed if the @code{X-Mailer} header contains the word @samp{mail}
@emph{and} the value of the @code{Content-Type} header does not begin
with the string @samp{multipart/mixed}.

Now, if we wished to execute the @var{action} for any message sent
using @command{mail} or @command{mutt} whose @code{Content-Type}
header does not begin with the string @samp{multipart/mixed}, we would
write the following:

@smallexample
@group
if (header[X-Mailer] "mutt" or header[X-Mailer] "mail") \
   and not header[Content-Type] "^multipart/mixed;.*"
   @var{action}
fi
@end group
@end smallexample

@noindent
Notice the use of parentheses to change the binding strength of the
boolean operators.


@node Regular Expressions
@section Regular Expressions
@cindex regex, flag
@cindex re, flag
@cindex perl, flag
@cindex perlre, flag
@cindex exact, flag
@cindex ex, flag
@cindex scase, flag
@cindex icase, flag
@cindex basic, flag
@cindex extended, flag

GNU Anubis supports two types of regular expressions: POSIX (both
basic and extended), and Perl-style regular expressions. Among this,
the former are always supported, whereas the support for the latter
depends on the configuration settings at compile time. By default
POSIX extended regexps are assumed.

Regular expressions often contain characters, prefixed
with a backslash (e.g. @samp{\(} in basic POSIX or @samp{\s} in
perl-style regexp). Due to escape substitution
(@pxref{backslash-interpretation}), you will have to escape the
backslash character, e.g. write:

@smallexample
modify :perl body ["\\stext"] "text"
@end smallexample

@noindent
instead of

@smallexample
# WRONG!
modify :perl body ["\stext"] "text"
@end smallexample

However, this rule does not apply to back references, i.e. @code{"\1"}
is OK. @FIXME{This is clearly a special case. When we support \ooo and
\xHH escapes, this will have to be handled separately...}

A number of modifiers is provided to change the type of regular
expressions. These are described in the following table.

@table @code
@item :regex
@itemx :re
Indicates that the following pattern should be considered a regular
expression. The default type for this expression is assumed.

@item :perl
@itemx :perlre
The regular expression is a Perl-style one. 

@item :exact
@itemx :ex
Disables regular expression matching, all patterns will be matched
as exact strings.

@item :scase
Enables case-sensitive comparison.

@item :icase
Enables case-insensitive comparison.

@item :basic
Switches to the POSIX Basic regular expression matching.

@item :extended
Switches to the POSIX Extended regular expression matching.
@end table

The special statement @code{regex} allows you to alter the default
regular expression type. For example, the following statement

@smallexample
regex :perl :scase
@end smallexample

sets the default regular expression types to Perl-style, case-sensitive.
The settings of @code{regex} statement regard only those patterns that
appear after it in the configuration file and have force until the
next occurrence of the @code{regex} statement. 

A couple of examples:

@smallexample
@group
if header[Subject] :perlre "(?<=(?<!foo)bar)baz"
 ...
fi
@end group
@end smallexample

@noindent
This will match any @code{Subject} header whose value
matches an occurrence of @samp{baz} that is preceded by @samp{bar}
which in turn is not preceded by @samp{foo}.
              
@smallexample
if header[Subject] :scase "^Re"
@end smallexample

@noindent
will match a @code{Subject} header whose value starts with @samp{Re},
but will not match it if it starts with @samp{RE} or @samp{re}.

When using POSIX regular expressions, the extended syntax is enabled
by default. If you wish to use a basic regular expression, precede
it with the @code{:basic} flag.

For the detailed description of POSIX regular expressions,
@xref{Top,,Regular Expression Library,regex,Regular Expression Library}.
For information about Perl-style regular expressions, refer to the
Perl documentation.


@node Action List
@section Action List
@cindex Action List

An @dfn{action list} is a list of action commands, which control processing
of messages. All action command names are case insensitive, so you
can use for instance: @samp{add} or @samp{ADD} or @samp{AdD}, and so on.

@menu
* Stop Action::            Stopping Processing
* Call Action::            Invoking Another Section
* Adding Headers or Text:: How to add a new header or body line(s).
* Removing Headers::       How to remove a message header line(s).
* Modifying Messages::     How to modify a message contents on-the-fly.
* Modifying SMTP Commands::
* Inserting Files::        How to append text files to an outgoing message.
* Mail Encryption::        How to encrypt a message on-the-fly.
* External Processor::     How to process a message body using an external tool.
* Quick Example::          A quick example of using an action list.
@end menu


@node Stop Action
@subsection Stop Action
@cindex @code{stop}

The @code{stop} command stops processing of the
section immediately. It may be used in the main @code{RULE} section as well as
in any user-defined section. For example:

@smallexample
if not header[Content-Type] "text/plain; .*"
  stop
fi
@end smallexample


@node Call Action
@subsection Call Action
@cindex @code{call}

The @code{call} command invokes a user-defined section much
in the same manner as a subroutine in a programming language. The
invoked section continues to execute until its end or the @code{stop}
statement is encountered, whichever the first.

@smallexample
BEGIN myproc
if header[Subject] "Re: .*"
  stop
fi
trigger "pgp"
  gpg-encrypt "my_gpg_key"
done
END

BEGIN RULE
call myproc
END
@end smallexample


@node Adding Headers or Text
@subsection Adding Headers or Text
@cindex @code{add}

The @code{add} command adds arbitrary headers or text
to the message. To add a header, use the following syntax:

@deffn Command add header @samp{[}@var{name}@samp{]} @var{string}
@deffnx Command add @samp{[}@var{name}@samp{]} @var{string}
For example:

@smallexample
add header[X-Comment-1] "GNU's Not Unix!"
add [X-Comment-2] "Support FSF!"
@end smallexample
@end deffn

To add text to the body of the message, use:

@deffn Command add body @var{text}
Adds the @var{text} to the message body. Use of this command with
@samp{here document} syntax allows to append multi-line text to the
message, e.g.:

@smallexample
@group
add body <<-EOT
    Regards,
    Hostmaster
    EOT
@end group
@end smallexample
@end deffn


@node Removing Headers
@subsection Removing Headers
@cindex @code{remove}

The @code{remove} command removes headers from the
message. The syntax is:

@deffn Command remove [@var{flags}] header @samp{[}@var{string}@samp{]}
@deffnx Command remove [@var{flags}] @samp{[}@var{string}@samp{]}

The name of the header to delete is given by @var{string} parameter.
By default only those headers are removed whose names match it exactly.
Optional @var{flags} allow to change this behavior. @xref{Regular Expressions},
for the detailed description of these.

An example:

@smallexample
remove ["X-Mailer"]
remove :regex ["^X-.*"]
@end smallexample

The first example will remove the @samp{X-Mailer:} header from
an outgoing message, and the second one will remove all "X-*"
headers.
@end deffn


@node Modifying Messages
@subsection Modifying Messages
@cindex @code{modify}

The @code{modify} command alters headers or body of the message. 

@deffn Command modify [@var{flags}] header @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]}
@deffnx Command modify [@var{flags}] @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]}

@cindex Back References
For each header whose name matches @var{key}, replaces its name
with @var{new-key}. If @var{key} is a regular expressions, @var{new-key}
may contain back references. For example, the following statement
selects all headers whose names start with @samp{X-} and changes their
names to begin with @samp{X-Old-}:

@smallexample
modify header :re ["X-\(.*\)"] ["X-Old-\1"]
@end smallexample
@end deffn

@deffn Command modify [@var{flags}] header @samp{[}@var{key}@samp{]} @var{value}
@deffnx Command modify [@var{flags}] @samp{[}@var{key}@samp{]} @var{value}

For each header whose name matches @var{key}, changes its value to
@var{value}. For example:

@smallexample
modify [Subject] "New subject"
@end smallexample

@noindent
This statement sets the new value to the @code{Subject} header.

Every occurrence of unescaped @samp{&} in the new value will be replaced
by the old header value. To enter the @samp{&} character itself,
escape it with two backslash characters (@samp{\\}). For example, the
following statement

@smallexample
modify [Subject] "[Anubis \\& others] &"
@end smallexample

@noindent
prepends the @code{Subject} header with the string @samp{[Anubis &
others]}. Thus, the header line

@smallexample
Subject: Test subject
@end smallexample

@noindent

after having been processed by Anubis, will contain:

@smallexample
Subject: [Anubis & others] Test subject
@end smallexample

@end deffn

@deffn Command modify [@var{flags}] header @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]} @var{value}
@deffnx Command modify [@var{flags}] @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]} @var{value}

Combines the previous two cases, i.e. changes both the header
name and its value, as shown in the following example:

@smallexample
modify header [X-Mailer] [X-X-Mailer] "GNU Anubis"
@end smallexample
@end deffn

@deffn Command modify [@var{flags}] body @samp{[}@var{key}@samp{]}
Removes all occurrences of @var{key} from the message body.
For example, this statement will remove every occurrence of
the word @samp{old}:

@smallexample
modify body ["old"]
@end smallexample
@end deffn

@deffn Command modify [@var{flags}] body @samp{[}@var{key}@samp{]} @var{string}
Replaces all occurrences of @var{key} with @var{string}. For example:

@smallexample
modify body :extended ["the old \([[:alnum:]]+\)"] "the new \1"
@end smallexample
@end deffn

@node Modifying SMTP Commands
@subsection Modifying SMTP Commands

GNU Anubis is able to modify arguments of the @acronym{SMTP} commands.
To instruct it to do so, define a section named @samp{SMTP}.
Anubis will call this section each time
it receives an @acronym{SMTP} command. This section may contain
any statements allowed for @samp{RULE} section, plus the
following special flavor of the @samp{modify} statement:

@deffn Command modify [@var{flags}] command @samp{[}@var{cmd}@samp{]} @var{value}
If the current @acronym{SMTP} command matches @var{cmd}, rewrite it by
using @var{value} as its argument.
@end deffn

For example, this is how to force using @samp{my.host.org} as the
@samp{EHLO} argument:

@smallexample
@group
BEGIN SMTP
modify command [ehlo] "my.host.org"
END
@end group
@end smallexample

Additionally, the ESMTP authentication settings (@pxref{ESMTP
Authentication Settings}) can be used as actions in this section.
To do so, you must first set @code{esmtp-auth-delayed} to @samp{yes}
in the @samp{CONTROL} section (@pxref{ESMTP Authentication Settings,
esmtp-auth-delayed}).  Changes in the settings take effect if they
occur either before the @samp{MAIL} @acronym{SMTP} command, or while
handling this command.  

Consider, for example, the following configuration:

@smallexample
BEGIN CONTROL
 mode transparent
 bind 25
 remote-mta mail.example.com
 esmtp-auth-delayed yes
END

BEGIN SMTP
if command ["mail from:"] "<smith(\+.*)?@@example.net>"
  esmtp-auth-id smith
  esmtp-password guessme
else
  esmtp-auth no
fi
END
@end smallexample

It delays ESMTP authentication until the receipt of the @code{MAIL}
command from the client. Authentication is used only if the mail
is being sent from @email{smith@@example.net} or any additional mailbox
of that user (e.g. @email{smith+mbox@@example.net}). Otherwise,
authentication is disabled.

The following points are worth mentioning:

@enumerate 1
@item As usual, you may use conditional expressions to decide what
to modify and how. For example, the code below replaces the domain
part of each @samp{MAIL FROM} command with @samp{gnu.org}:

@smallexample
BEGIN SMTP
if command ["mail from:"] "<(.*)@@(.*)>(.*)"
  modify command ["mail from:"] "<\1@@gnu.org>\2"
fi
END
@end smallexample

@item Each @samp{modify command} statement applies only if
the current command matches its @var{cmd} argument. In particular,
this means that you cannot modify already transferred @acronym{SMTP}
commands nor the commands to be transferred. For example, the
following code will not work:

@smallexample
@group
BEGIN SMTP
# @r{Wrong!}
if command ["mail from:"] "<>(.*)"
  modify command [ehlo] "domain.net"
fi
END
@end group
@end smallexample

It is because by the time @samp{MAIL FROM} is received, the
@samp{EHLO} command has already been processed and send to
the server.
@end enumerate

The final point to notice is that you may use an alternative name for
that section (if you really want to). To do so, define the new name
via the @samp{smtp-command-rule} option in the @samp{CONTROL} section
(@pxref{Basic Settings,,smtp-command-rule}).

@node Inserting Files
@subsection Inserting Files

@deffn Command signature-file-append @var{yes-or-no}
@cmindex signature-file-append @var{yes-or-no}
This action command adds at the end of a message body the
@samp{-- } line, and includes a client's
@file{~/.signature} file.

Default is @samp{no}.
@end deffn

@deffn Command body-append @var{file-name}
@cmindex body-append @var{file-name}
This action command includes at the end of the message body
the contents of the given file. Unless @file{@var{file-name}}
starts with a @samp{/} character, it is taken relative to
the current user home directory.
@end deffn

@deffn Command body-clear
@cmindex body-clear
Removes the body of the message.
@end deffn

@deffn Command body-clear-append @var{file-name}
@cmindex body-clear-append @var{file-name}
Replaces the message body with the contents of the specified
file. The action is equivalent to the following command sequence:

@smallexample
body-clear
body-append @var{file-name}
@end smallexample
@end deffn


@node Mail Encryption
@subsection Mail Encryption
@cindex GNU Privacy Guard, GnuPG
@cindex Pretty Good Privacy, PGP
@cindex GPG/PGP private key
@cindex GPG/PGP public key

@deffn Command gpg-passphrase @var{passphrase}
@cmindex gpg-passphrase @var{passphrase}
Specifies your private key's pass phrase for signing messages
using the GNU Privacy Guard. Of course, to protect your passwords in
the configuration file use the 0600 (u=rw,g=,o=) permissions,
otherwise GNU Anubis won't accept them.

We recommend setting the @samp{gpg-passphrase} once in your
configuration file, e.g. at the start of @code{RULE} section.

GNU Anubis support for the GNU Privacy Guard is based on the
@dfn{GnuPG Made Easy} library, available from
@w{@uref{http://www.gnupg.org/gpgme.html}}.
@end deffn

@deffn Command gpg-encrypt @var{gpg-keys}
@cmindex gpg-encrypt @var{gpg-keys}
This command enables encrypting messages with the
GNU Privacy Guard (Pretty Good Privacy) public key(s).
@var{gpg-keys} is a comma separated list of keys (with no space
between commas and keys).

@smallexample
gpg-encrypt "John's public key"
@end smallexample
@end deffn

@deffn Command gpg-sign @var{gpg-signer-key}
@deffnx Command gpg-sign @samp{yes-or-default}
@cmindex gpg-sign @var{gpg-signer-key}
This command signs the message with your
GNU Privacy Guard private key. Specify a @var{passphrase} with
@code{gpg-passphrase}. Value @samp{default} means your default
private key, but you can change it if you have more than one
private key.

For example:

@smallexample
gpg-sign default
@end smallexample

or

@smallexample
@group
gpg-passphrase "my office key passphrase"
gpg-sign office@@example.key
@end group
@end smallexample
@end deffn

@deffn Command gpg-sign-encrypt @var{gpg-keys}[:@var{gpg-signer-key}]
@deffnx Command gpg-se @var{gpg-keys}[:@var{gpg-signer-key}]
@cmindex gpg-sign-encrypt @var{gpg-keys}[:@var{gpg-signer-key}]
This command simultaneously signs and encrypts the message.
It has the same effect as @command{gpg} command line switch
@option{-se}. The argument before the colon is a comma-separated list
of PGP keys to encrypt the message with. This argument is mandatory.
The @var{gpg-signer-key} part is optional. In the absence of it,
your default private key is used.

For example:

@smallexample
gpg-sign-encrypt John@@example.key
@end smallexample

or

@smallexample
gpg-se John@@example.key:office@@example.key
@end smallexample
@end deffn


@node External Processor
@subsection Using an External Processor

@deffn Command external-body-processor @var{program} [@var{args}]
@cmindex external-body-processor @var{program} [@var{args}]
Pipes the message body through @var{program}. The @var{program} must
be a filter that reads the text from the standard input
and prints the transformed text on the standard output. The output
from it replaces the original body of the message.
@var{args} are any additional arguments the program may require.
@end deffn

@cindex read-entire-body
@cindex Multi-part Messages, Processing with External Programs
The amount of data fed to the external program depends on the
message. For plain messages, entire body is passed. For
multi-part messages, only the first part is passed by default.
This is based on the assumption that in most multi-part messages
the first part contains textual data, while the rest contains
various (mostly non-textual) attachments. There is a special
configuration variable @code{read-entire-body} that controls this
behavior (@pxref{Basic Settings}). Setting @code{read-entire-body yes}
in @code{CONTROL} section of your configuration file instructs
Anubis to pass the entire body of multi-part messages to
your external processor.

There is a substantial difference between operating in
@code{read-entire-body no} (the default) and @code{read-entire-body
yes} modes. When operating in @code{read-entire-body no}, the first
part of the message is decoded and then passed to the external
program. In contrast, when @code{read-entire-body} is set to
@code{yes}, the message is not decoded. Thus, your external processor
must be able to cope with MIME messages.

@node Quick Example
@subsection Quick Example

Here is a quick example of an action list:

@smallexample
@group
---BEGIN RULE---
if header [X-Mailer] :re ".*"
   remove [X-Mailer]
   add [X-Comment] "GNU's Not Unix!"
   gpg-sign "my password"
   signature-file-append yes
fi
---END---
@end group
@end smallexample

@noindent
The example above removes the @samp{X-Mailer:} header from the
message, adds the @samp{X-Comment:} header, then signs the
message with your private key, and finally adds a signature from
the file in your home directory.


@node Using Guile Actions
@section Using Guile Actions
@cindex Guile

@dfn{Guile} is the @dfn{GNU's Ubiquitous Intelligent Language for
Extensions}. It provides a Scheme interpreter conforming to the R5RS
language specification. GNU Anubis uses Guile as its extension language.

This section describes how to write GNU Anubis actions in Scheme.
It assumes that the reader is sufficiently familiar with the
Scheme language. For information about the language, refer to
@ref{Top,,,r5rs,Revised(5) Report on the Algorithmic Language Scheme}.
For more information about Guile,
@xref{Top,,Overview,guile,The Guile Reference Manual}.

@menu
* Defining Guile Actions::
* Invoking Guile Actions::

Predefined Guile Actions
* Rot-13::
* Remailers::
* Entire Message Filters::
@end menu


@node Defining Guile Actions
@subsection Defining Guile Actions
@cindex Guile Actions, defining

A Guile action is defined as follows:

@smalllisp
(define (@var{function-name} @var{header} @var{body} . @var{rest})
 ...)
@end smalllisp

@noindent
Its arguments are:

@table @var
@item header
List of message headers. Each list element is a cons

@smallexample
(@var{name} . @var{value})
@end smallexample

@noindent
where @var{name} is the name of the header field, and @var{value} is
its value with final CRLF stripped off. Both @var{name} and
@var{value} are strings.

@item body
A string containing the message body.

@item rest
Any additional arguments passed to the function from the configuration
file (@pxref{Invoking Guile Actions}). This argument may be absent if
the function is not expected to take optional arguments.
@end table

The function must return a cons whose car contains the new message
headers, and cdr contains the new message body. If the car is
@code{#t}, it means that no headers are changed. If the cdr is
@code{#t}, it means that the body has not changed. If the cdr is
@code{#f}, Anubis will delete the entire message body.

As the first example, let's consider a @dfn{no-operation} action,
i.e. an action that does not alter the message in any way. It can
be written in two ways:

@smalllisp
(define (noop-1 header body)
  (cons header body))
  
(define (noop-2 header body)
  (cons #t #t))
@end smalllisp

The following example is a function that deletes the message body
and adds an additional header:

@smalllisp
(define (proc header body)
  (cons (append header
                (cons "X-Body-Deleted" "yes"))
        #f))
@end smalllisp        

Let's consider a more constructive example. The following function
checks if the @code{Subject} header starts with string @samp{ODP:}
(a Polish equivalent to @samp{Re:}), and if it does, the function
replaces it with @samp{Re:}. It always adds to the message the header

@smallexample
X-Processed-By: GNU Anubis
@end smallexample

@noindent
Additionally, if the optional argument is given, it is appended to
the body of the message.

@smalllisp
(define (fix-subject hdr body . rest)
  "If the Subject: field starts with characters \"ODP:\", replace
them with \"Re:\".
If REST is not empty, append its car to BODY"
  (cons (append
         (map (lambda (x)
                (if (and (string-ci=? (car x) "subject")
                         (string-ci=? (substring (cdr x) 0 4) "ODP:"))
                    (cons (car x)
                          (string-append "Re:"
                                         (substring (cdr x) 4)))
                    x))
              hdr)
         (list (cons "X-Processed-By" "GNU Anubis")))
        (if (null? rest)
            #t
            (string-append body "\n" (car rest)))))
@end smalllisp


@node Invoking Guile Actions
@subsection Invoking Guile Actions
@cindex @code{guile-process}

Guile actions are invoked from the @code{RULE} section using the
@code{guile-process} command. Its syntax is:

@deffn {Scheme Function} @var{function} @var{args}
Arguments:

@table @var
@item function
The name of the Guile function to be invoked.

@item args
Additional arguments. These are passed to the @var{function} as
its third argument (@var{rest}).
@end table
@end deffn

To pass keyword arguments to the function, use the usual Scheme
notation: @samp{#:key}.

As an example, let's consider the invocation of the @code{fix-subject}
function, defined in the previous subsection:

@smallexample
guile-process fix-subject <<-EOT
                                ----------
                                Kind regards,
                                Antonius Block
                          EOT
@end smallexample

@noindent
In this example, the additional argument (a string of three lines) is
passed to the function, which will add it to the message of the body.


@node Rot-13
@subsection Support for @sc{rot-13}
@cindex rot-13

The @sc{rot-13} transformation is a simple form of encryption where the
letters A-M are transposed with the letters L-Z. It is often used in
Usenet postings/mailing lists to prevent people from accidentally
reading a disturbing message.

GNU Anubis supports @sc{rot}-13 via a loadable Guile function. To enable
this support, you will have to add the following to your @code{GUILE}
section:

@smallexample
guile-load-program rot-13.scm
@end smallexample

Then, in your @code{RULE} section use:

@deffn {Scheme Function} rot-13 @var{keyword-arguments}
@fnindex rot-13, Scheme function
The command accepts the following @var{keyword-arguments}:

@table @code
@item #:body
Encrypt the entire body of the message

@item #:subject
Encrypt the @samp{Subject} header.
@end table

For example:

@smallexample
@group
trigger "rot-13.*body"
 guile-process rot-13 #:body
done

trigger "rot-13.*subj"
 guile-process rot-13 #:subject
done
@end group
@end smallexample  
@end deffn

@node Remailers
@subsection Remailers Type-I
@cindex remailer

GNU Anubis supports remailers of type I. The support is written
entirely in Scheme. To enable it, you need to specify the following
in the @code{GUILE} section of your configuration file:

@smallexample
@group
guile-load-program remailer.scm
@end group
@end smallexample

To send the message via a remailer, use the following command
in the @code{RULE} section:

@deffn {Scheme Function} remailer-I @var{keyword-arguments}
@fnindex remailer-I, Scheme function
@cmindex guile-process remailer-I @var{keyword-arguments}
The @var{keyword-arguments} specify the various parameters for
the remailer. These are:

@table @code
@item #:rrt @var{string}
This is the only required keyword argument. It sets the value for the
@dfn{Request Remailing To} line. @var{string} should be your actual
recipient's email address.

@item #:post @var{news-group}
Adds the @samp{Anon-Post-To: @var{news-group}} line,
and prepares the message for sending it to the Usenet
via a remailer. Note, that this is only possible with remailers
that support @samp{Anon-Post-To:} header.

@item #:latent @var{time}
Adds the @samp{Latent-Time:} line, that causes a remailer to keep
your message for specified @var{time} before forwarding it. 

@item #:random
Adds random suffix to the latent time.

@item #:header @var{string}
Adds an extra header line to the remailed message.
@end table

Example:

@smallexample
@group
trigger "remail:(.*)/(.*)"
 guile-process remailer-I \
             #:rrt antonius_block@@helsingor.net \
             #:post \1 \
             #:latent \2 \
             #:header "X-Processed-By: GNU Anubis & Remailer-I"
done
@end group
@end smallexample
@end deffn

Some remailers require the message to be GPG encrypted or signed.
You can do so by placing @code{gpg-encrypt} or @code{gpg-sign}
statement right after the invocation of @code{remailer-I}, for
example:

@smallexample
@group
trigger "remail:(.*)/(.*)"
 guile-process remailer-I \
             #:rrt antonius_block@@helsingor.net \
             #:post \1 \
             #:latent \2 \
             #:header "X-Processed-By: GNU Anubis & Remailer-I"
 gpg-sign mykey
done
@end group
@end smallexample

@xref{Mail Encryption}, for more information on mail encryption in
GNU Anubis.

@node Entire Message Filters
@subsection Entire Message Filters
@cindex entire-msg.scm
@fnindex entire-msg-filter, Scheme function
@fnindex openssl-filter, Scheme function
@cindex entire message, filtering

There may be some cases when you need to use an external filter that
processes entire message (including headers). You cannot use
@code{external-body-processor}, since it feeds only the
message body to the program. To overcome this difficulty, GNU Anubis
is shipped with @file{entire-msg.scm} module. This module provides
Scheme function @code{entire-msg-filter}, which is to be used in
such cases.

@deffn {Scheme Function} entire-msg-filter @var{program} [@var{args}]
Feeds entire message to the given program. The output from the program
replaces message headers and body.

@table @var
@item progname
Full pathname of the program to be executed.

@item args
Any additional arguments it may require.
@end table
@end deffn

Suppose you have a program @code{/usr/libexec/myfilter}, that accepts
entire message as its output and produces on standard output a
modified version of this message. The program takes as its argument
he name of a directory for temporary files. The following example
illustrates how to invoke this program:

@smallexample
BEGIN GUILE
guile-load-program entire-msg.scm
END

BEGIN RULE
guile-process entire-msg-filter /usr/libexec/myfilter /tmp
END
@end smallexample

Another function defined in this module is @code{openssl-filter}:

@deffn {Scheme Function} openssl-filter @var{program} [@var{args}]

This function is provided for use with @code{openssl}
program. @code{Openssl} binary attempts to rewind its input and
fails if the latter is a pipe, so @code{openssl} cannot be used
with @code{entire-msg-filter}. Instead, you should use 
@code{openssl-filter}. Its arguments are:

@table @var
@item program
Path to @code{openssl} binary.

@item args
Its arguments
@end table

@xref{S/MIME}, for an example of use of this function.
@end deffn

@node Invoking Anubis
@chapter Invoking GNU Anubis
@cindex command line

The @command{anubis} executable acts like a daemon, i.e. after
a successful startup it disconnects itself from the controlling
terminal@footnote{Unless given the @option{--foreground} command line
option.} and continues its work in the background. The program reads
its initial settings from the @samp{CONTROL} section of the site-wide
configuration file (@pxref{CONTROL Section}) and from the command
line options.

Command line options have higher priority than configuration file
settings and can be used to temporarily override them.

The following command line options are understood:

@table @samp
@item --altrc @var{file}
Specify alternate system configuration file.

@item --bind [@var{host}:]@var{port}
@itemx -b
Specify the @acronym{TCP} port on which GNU Anubis listens for connections.
The default @var{host} value is @w{@samp{INADDR_ANY}}, and default
@var{port} number is 24 (private mail system).

@item --check-config[=@var{level}]
@itemx -c[@var{level}]
Run the configuration file syntax checker. Optional @var{level}
specifies the verbosity level. The following levels are allowed:

@table @asis
@item 0
Display only errors. This is the default.

@item 1
Print the syntax tree after parsing the file.

@item 2
As @samp{1}, but also prints the parser traces.

@item 3
As @samp{2}, but also prints the lexical analyzer traces.
@end table

@item --debug
@itemx -D
Debug mode.

@item --foreground
@itemx -f
Foreground mode.

@item --help
Print short usage summary and exit.

@item --local-mta @var{file}
@itemx -l
Execute a local @acronym{SMTP} server, which works on standard input and output
(inetd-type program). This option excludes the @samp{--remote-mta} option.

@item --mode @var{mode-name}
@itemx -m @var{mode-name}
Selects Anubis operation mode. Allowed values for @var{mode-name}
are @samp{proxy}, @samp{transparent} (the default), @samp{auth} and
@samp{mda}. @xref{Authentication}, for the detailed discussion of
Anubis operation modes.

@item --norc
Ignore system configuration file.

@item --relax-perm-check
Do not check a user config file permissions.

@item --remote-mta @var{host}[:@var{port}]
@itemx -r
Specify a remote @acronym{SMTP} host name or @acronym{IP} address, which GNU Anubis will
connect and forward mail to (after a processing).
The default @var{port} number is 25.

@item --silent
@itemx -s
Work silently.

@item --show-config-options
Print the list of configuration options used to build GNU Anubis.

@item --stdio
@itemx -i
Use the @acronym{SMTP} protocol (OMP/Tunnel) as described in @acronym{RFC} 821 on standard
input and output.

@item --verbose
@itemx -v
Work noisily.

@item --version
Print version number and copyright.
@end table

Examples:

@smallexample
$ anubis --remote-mta @var{smtp-host}:25
@end smallexample

@noindent
Run GNU Anubis on port number 24 (private mail system). Note that
you must have root privileges to use port number lower than 1024.
Make the tunnel between your localhost:24 and @var{smtp-host}:25.

@smallexample
$ anubis -f --remote-mta @var{smtp-host}:25
@end smallexample

@noindent
Same as above, but run GNU Anubis in a foreground mode.

@smallexample
$ anubis -f --local-mta /usr/sbin/sendmail -- sendmail -bs
@end smallexample

@noindent
Similar to above, but create a tunnel between localhost:24
and a local program (local @acronym{MTA}). In this example local program
is @command{sendmail} with @samp{-bs} command line option.
The @samp{-bs} option forces @command{sendmail} to work on standard
input and output.

@smallexample
$ anubis --norc --remote-mta @var{smtp-host}:25
@end smallexample

@noindent
Do not read the system configuration file, make the tunnel between
localhost:24 and @var{smtp-host}:25.

@smallexample
$ anubis --bind localhost:1111 --remote-mta @var{smtp-host}:25
@end smallexample

@noindent
Create the tunnel between localhost:1111 and @var{smtp-host}:25.

@smallexample
$ anubis -i
@end smallexample

@noindent
Use the @acronym{SMTP} protocol (OMP/Tunnel) as described in @acronym{RFC} 821
on standard input and output.


@node Sample Beginning
@chapter Sample Beginning

By default, GNU Anubis binds to port number 24 (private mail system),
so there shouldn't be any conflict with your local @acronym{MTA} (Mail
Transport Agent). You only have to reconfigure your @acronym{MUA} (Mail User
Agent) to talk to GNU Anubis directly on port number 24. All
@acronym{MUA}s are normally set up to talk directly to the
@acronym{MTA}, so you must change their settings and specify GNU
Anubis' port number as their target. This makes GNU Anubis to work as
an outgoing mail processor between your @acronym{MUA} and the
@acronym{MTA}. Read your @acronym{MUA}'s documentation for more
information. 

Then you need to choose whether you want to connect GNU Anubis to a remote
or local @acronym{SMTP} host via @acronym{TCP/IP} or a local
@acronym{SMTP} program, which works on standard input and output. In
the former case, specify the following option: 

@smallexample
REMOTE-MTA @var{smtp-host}:25
@end smallexample

@noindent
In the latter case (local @acronym{SMTP} program), use this:

@smallexample
LOCAL-MTA @var{/path/to/your/mta/mta-executable} -bs
@end smallexample

Please note that the @samp{-bs} command line option is a common way
to run @acronym{MTA}s on standard input and output, but it is not a rule.
Read your local @acronym{MTA}'s documentation, how to get it working
on standard input and output.

If you would like to run GNU Anubis on port number 25 (which is a
default value for the @acronym{SMTP}) or any other port number, then
use the @samp{bind} keyword. For instance, the following code will
bind GNU Anubis to @samp{localhost:25}:

@smallexample
bind localhost:25
@end smallexample

This can make a conflict between GNU Anubis and your local
@acronym{MTA}, which usually listens on port number 25. To solve this
problem, you may disable the @acronym{MTA} and specify the
@samp{local-mta} keyword, or run @acronym{MTA} on port number
different than GNU Anubis' port number (e.g. 1111). Please read your 
local @acronym{MTA}'s documentation about this topic. For example:

@smallexample
@group
bind localhost:25
remote-mta localhost:1111
@end group
@end smallexample

@strong{Caution:} Make sure that your local machine doesn't accept any
incoming mail (i.e. it is @emph{not} a POP or IMAP server), otherwise
you cannot disable your @acronym{MTA} or change its port number!

@node TLS/SSL
@chapter Using the TLS/SSL Encryption
@cindex Transport Layer Security, TLS
@cindex Secure Socket Layer, SSL
@cindex GnuTLS
@cindex encryption

According to the @acronym{RFC} 2246 document, the TLS (Transport Layer Security)
protocol provides communications privacy over the Internet. The protocol
allows client/server applications to communicate in a way that is designed
to prevent eavesdropping, tampering, or message forgery. The primary goal
of the TLS Protocol is to provide privacy and data integrity between two
communicating applications. The TLS protocol itself is based on the SSL 3.0
(Secure Socket Layer) protocol specification.

GNU Anubis supports the @acronym{TLS/SSL} (via the GnuTLS, a Transport
Layer Security Library available from @w{@uref{http://www.gnutls.org/}}),
but your @acronym{MTA} must provide the STARTTLS command first. This can be checked by:

@smallexample
@group
$ telnet @var{your-smtp-host} 25
  ehlo @var{your-domain-name}
@end group
@end smallexample

@noindent
The server will response with all its available commands.
If you see the word @samp{STARTTLS}, then you can use the
@acronym{TLS/SSL} encryption. If your @acronym{MUA} doesn't support
the @acronym{TLS/SSL} encryption, but your @acronym{MTA} does, then
you should use the @samp{oneway-ssl} keyword in your configuration
file. Before using the @acronym{TLS/SSL} encryption, generate
a proper private key and a certificate. You can do it simply with: 

@smallexample
@group
$ cd anubis-directory
$ ./build/keygen.sh
@end group
@end smallexample

@noindent
This will create the @file{anubis.pem} file.
For example, copy this file to @w{@file{/usr/share/ssl/certs/}}.
Next, edit your configuration file by adding:

@smallexample
@group
ssl yes
ssl-key @var{path-to-the-private-key}
ssl-cert @var{path-to-the-certificate}
@end group
@end smallexample

For example:

@smallexample
@group
ssl-key /usr/share/ssl/certs/anubis.pem
ssl-cert /usr/share/ssl/certs/anubis.pem
@end group
@end smallexample

@noindent
@strong{Caution:} Each client can specify its own private key
and a certificate by adding the @samp{ssl-key} and @samp{ssl-cert}
keywords in its own user configuration file.

@noindent
@xref{Encryption Settings}, for details.

@node S/MIME
@chapter Using S/MIME Signatures
@cindex smime
@cindex openssl

Anubis version @value{VERSION} does not yet provide built-in support
for @acronym{S/MIME} encryption or signing. To encrypt or sign messages using
@acronym{S/MIME}, you will have to use external programs. Usually such programs
require the whole message as their input, so simply using
@code{external-body-processor} will not work. GNU Anubis distribution
includes a special Guile program, @file{entire-msg.scm}, designed for
use with such programs. For its detailed description, please refer to
@ref{Entire Message Filters}. This chapter addresses a special case of
using it with @code{openssl} to sign outgoing messages.

To use @code{openssl} for @acronym{S/MIME} signing, invoke it using
@code{openssl-filter} function defined in @file{entire-msg.scm}. You
will have to supply at least @code{-sign} and @code{-signer} arguments
to the program. Notice, that you should not specify any input or
output files.

The following example illustrates this approach:

@smallexample
BEGIN GUILE
guile-load-program entire-msg.scm
END

BEGIN RULE
guile-process openssl-filter /usr/local/ssl/bin/openssl \
              smime -sign -signer FILE
END
@end smallexample

@node MDA Mode
@chapter Using Anubis to Process Incoming Mail
@cindex MDA mode
@cindex incoming mail, processing

Historically Anubis was designed to process outgoing mail. Support for
processing incoming mail was added in version 4.1.

To process incoming mail, Anubis must be started as @dfn{mail
delivery agent} from your @acronym{MTA} configuration file. The invocation
line must contain @option{--mode=mda} option, that tells Anubis
to act in @dfn{mail delivery mode}. In this mode, Anubis receives
the message from standard input, processes it using configuration
file sections named @code{incoming-mail-rule} (@pxref{Basic Settings,,
incoming-mail-rule}) and finally calls local mailer to actually
deliver the modified message. The local mailer must be given using
@option{--local-mta} option.


Let's summarize the special features of mail delivery mode
@FIXME{This is basically a reminder for me to provide a detailed
description of MDA mode}:

@enumerate 1
@item
The mode is triggered by @option{--mode=mda} in the command line.
It cannot be specified in configuration file. @FIXME{Why?}

@item
Anubis uses local mailer to actually deliver messages. The invocation
line of the local mailer must be given via @option{--local-mta}
command line option. The @option{local-mta} settings (if any) (@pxref{Basic
Settings}) are ignored. @FIXME{Is it really so? And, again: why?}

The local mailer invocation line may contain meta-variables
@code{%sender} and @code{%recipient}, which will be replaced by
the actual sender and recipient email addresses before starting
the mailer.

@item
Special option @option{--from} may be used in Anubis command line.
This option sets sender email address (see @code{%sender} meta
variable above). It implies @option{--mode=mda}. If the option is
not given, GNU Anubis will deduce sender address from UNIX
@samp{From } header or, if it is not present, from the value of
@code{From} @acronym{SMTP} header.

@item
In MDA mode, Anubis takes recipient email addresses from the command line.

@item
Anubis uses a separate rule section for processing incoming mails. The
default section name is @samp{INCOMING}. It may be overridden in 
system configuration file using @option{incoming-mail-rule}
(@pxref{Basic Settings,,incoming-mail-rule}).
@end enumerate

The following discussion explains how to configure Anubis in MDA mode with
different mail transport agents.

@itemize @bullet
@item Sendmail

If you use @code{mc} file to generate @file{sendmail.cf}, use
@code{LOCAL_MAILER_PATH} and @code{LOCAL_MAILER_ARGS} as shown
in the following example:

@smallexample
@group
define(`LOCAL_MAILER_PATH', `/usr/local/sbin/anubis')
define(`LOCAL_MAILER_ARGS',
       `mail --mode=mda -l '/libexec/mail.local -f %sender %recipient')
@end group
@end smallexample

@noindent
If you prefer to directly edit @file{sendmail.cf}, use @code{M}
macro to declare Anubis as a local mailer. Following example
illustrates this:
          
@smallexample
@group
Mlocal, P=/usr/local/sbin/anubis,
        F=lsDFMAw5:/|@@qSPfhn9,
        S=EnvFromL/HdrFromL, R=EnvToL/HdrToL,
        T=DNS/RFC822/X-Unix,
        A=mail --mode=mda -l '/libexec/mail.local -f %sender %recipient' $u
@end group        
@end smallexample
                                
@item Exim

With @command{exim}, you will need to declare appropriate transport
and director in @file{exim.conf}:

@smallexample
@group
# transport
mail_local_pipe:
  driver = pipe
  command = /usr/local/sbin/anubis --mode=mda \
             -l '/libexec/mail.local -f %sender %recipient' $local_part
  return_path_add
  delivery_date_add
  envelope_to_add

# director
mail_local:
  driver = localuser
  transport = mail_local_pipe
@end group   
@end smallexample
              
@end itemize
@FIXME{More mailers, anybody?}

@node Mutt
@chapter Using Mutt with Anubis
@cindex mutt

Newer versions of @command{mutt} (1.5.20) are able to
send mail directly via @acronym{SMTP} channel.  Older ones
(1.4.1 and 1.5.3) can only use an external program to send
messages.

The following sections describe the recommended ways of
configuring @command{mutt}.

@menu
* mutt-smtp::            Using @acronym{SMTP}
* maidag::               Using GNU Mailutils
* msg2smtp.pl::          Using @command{msg2smtp.pl}
@end menu

@node mutt-smtp
@section Configure Mutt @acronym{SMTP}

@command{Mutt} version 1.5.20 supports @acronym{SMTP} if compiled
with the @option{--enable-smtp} option. You can verify if it is so
by running the following command:

@smallexample
mutt -v | fgrep '+USE_SMTP'
@end smallexample

If the output contains @samp{+USE_SMTP}, then @command{mutt} is
compiled properly and you can use further instructions from this
section.

@table @code
@item set smtp_url = "@var{url}"
Sets @acronym{URL} of the Anubis server. The format of @var{url} is

@smallexample
smtp://[@var{user}[:@var{pass}]@@]host[:@var{port}]
@end smallexample

@noindent
where square brackets denote optional parts.  If Anubis is running
in @samp{auth} mode, @var{user} and @var{pass} become mandatory.
The latter can also be set using the following statement.

@item set smtp_pass = "@var{pass}"
Sets @acronym{SMTP} password.

@item set smtp_authenticators="@var{auth-list}"
Sets the list of the authentication methods to try when
attempting to perform @acronym{SMTP AUTH}.  The argument
is a colon-delimited list of method names.
@end table

For example, if Anubis runs on the server @samp{anubis.domain.org},
port 24, your @file{.muttrc} could contain:

@smallexample
set smtp_url = "smtp://anubis.domain.org:24"
@end smallexample

@node maidag
@section Using GNU mailutils as an interface to mutt
@cindex maidag
@cindex mailutils
@cindex GNU mailutils

GNU Mailutils is a collection of utilities for handling electronic
mail. It includes lots of programs necessary for dealing with
e-mail messages. One of them is @command{maidag} --- a general-purpose
mail delivery agent (@pxref{maidag,,, mailutils, GNU Mailutils
Manual}).

The package can be downloaded from
@url{ftp://ftp.gnu.org/@/gnu/@/mailutils} or any of the mirrors 
(See @url{http://www.gnu.org/@/order/@/ftp.html} for a complete
list of these. Please, select the mirror closest too you). The
complete information about the package is available from its
home page at @url{http://www.gnu.org/@/software/@/mailutils/} 

To use @command{maidag}, first download and install GNU mailutils
(as usual the package is shipped with files @file{README} and
@file{INSTALL} which provide the necessary guidelines). Then
add to your @file{.muttrc} file the following line:

@smallexample
set sendmail="@var{maidag} --url smtp://@var{hostname}[:@var{port}]"
@end smallexample

@noindent
where @var{maidag} stands for the full file name of
@command{maidag} utility, @var{hostname} and optional
@var{port} specify the host name (or @acronym{IP} address) of the machine
running @command{anubis} and the port it listens on. Notice, that
default port value for @samp{smtp} is 25, which means
that in most cases you will have to specify it explicitly.

For example, suppose you run @command{anubis} on machine
@samp{anubis.domain.org} and that it listens on port 24.
Let's also assume you have installed mailutils in the default
location, so that full file name of the @command{maidag} utility is
@file{/usr/local/sbin/maidag}. Then, your @file{.muttrc}
will contain:

@smallexample
set sendmail="/usr/local/sbin/maidag \
              --url smtp://anubis.domain.org:24"
@end smallexample

@noindent
(the line being split for readability).

@node msg2smtp.pl
@section Using msg2smtp.pl as an interface to mutt
@cindex msg2smtp.pl

GNU Anubis is shipped with @code{msg2smtp.pl} --- a perl script
designed as an interface between it and @command{mutt}. The script
is kindly contributed by Michael de Beer. 

The script is located in the subdirectory @file{contrib} of 
GNU Anubis distribution. Copy it to any convenient location, e.g.:

@smallexample
cp anubis-@value{VERSION}/contrib/msg2smtp.pl /usr/local/libexec
@end smallexample

@noindent
and add the following line to your @file{.muttrc}:

@smallexample
set sendmail="/usr/local/libexec/msg2smtp.pl -h @var{hostname} -p @var{port}"
@end smallexample

@noindent
where @var{hostname} and @var{port} specify the host name (or @acronym{IP}
address) of the machine running @command{anubis} and the port it
listens on, respectively.

A complete description of @command{msg2smtp.pl} and a discussion of
its command line switches can be found in file @file{contrib/msg2smtp.txt}.

@node Problems
@chapter Reporting Bugs
@cindex bugs
@cindex problems

Please send any bug reports, improvements, comments,
suggestions, or questions to @email{bug-anubis@@gnu.org}.

Before reporting a bug, make sure you have actually found
a real bug. Carefully reread the documentation and see if it
really says you can do what you are trying to do. If it is
not clear whether you should be able to do something or not,
report that too; it's a bug in the documentation!

@node Pixie-Dixie
@appendix Pixie & Dixie
@include pixie-dixie.texi

@node Multi-Part Message Processing
@appendix Multi-Part Message Processing
@include mime.texi

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texi

@node Concept Index
@unnumbered Concept Index
@printindex cp
@shortcontents
@contents

@bye

@c anubis.texi ends here

Return to:

Send suggestions and report system problems to the System administrator.