aboutsummaryrefslogtreecommitdiff
path: root/doc/pies.texi
blob: e1ca650975ab8d876f48030785a3480153a6faac (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
\input texinfo @c -*-texinfo-*-
@smallbook
@c %**start of header
@setfilename pies.info
@settitle Pies
@c %**end of header
@setchapternewpage odd

@defcodeindex pr
@defcodeindex op
@c mt is the same as op, but used for mtasim options.
@defcodeindex mt
@defcodeindex kw
@defcodeindex fl

@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex mt cp
@syncodeindex pg cp
@syncodeindex tp cp
@syncodeindex op cp
@syncodeindex pr cp
@syncodeindex kw cp
@syncodeindex fl cp

@include version.texi
@include rendition.texi
@include macros.texi

@ifinfo
@dircategory GNU Utilities
@direntry (pies) pies.        Program execution supervisor.
@end direntry
@end ifinfo

@copying
Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301 USA 

Copyright @copyright{} 2005, 2006, 2007, 2008, 2009 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 ``Pies 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

@titlepage
@title Program Invocation and Execution Supervisor
@subtitle version @value{VERSION}, @value{UPDATED}
@author Sergey Poznyakoff.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@page
@summarycontents
@page
@contents

@ifnottex
@node Top
@top Pies

This edition of the @cite{Pies Manual}, last updated @value{UPDATED},
documents @command{pies} Version @value{VERSION}.
@end ifnottex

@menu
* Intro::
* Pies Configuration File::
* Pies Debugging::
* Configuration Example::
* Command Line Usage::
* Pies Invocation::
* Reporting Bugs::

Appendices

* Copying This Manual::  The GNU Free Documentation License.
* Concept Index::        Index of Concepts.

@detailmenu
@end detailmenu

@end menu

@node Intro
@chapter Introduction
@cindex component
  The name @command{pies} (pronounced @samp{p-yes}) stands for
@samp{Program Invocation and Execution Supervisor}.  This utility
starts and controls execution of external programs, called
@dfn{components}.  Each component is a stand-alone program, which is
executed in the foreground.  Upon startup, @command{pies} reads the list
of components from its configuration file, starts them, and remains in
the background, controlling their execution.  When any of the components
terminates, @command{pies} restarts it.  Its configuration allows to
specify actions other than simple restart, depending on the exit code
of the component.

@cindex prerequisite
@cindex dependency
@cindex dependents
@anchor{component prerequisite}
  A component @samp{A} may depend on another components, say
@samp{B} and @samp{C}, i.e. require them to be running at the moment of its
startup.  Components @samp{B} and @samp{C} are called
@dfn{prerequisites} for @samp{A}, while @samp{A} is called a
@dfn{dependency} or @dfn{dependent} component of @samp{B}, @samp{C}.

  Before restarting any component, @command{pies} verifies if it is a
prerequisite for any other components.  If so, it first terminates its
dependencies, then restarts the component, and then starts its
dependencies again, in the order of their appearance in the
configuration file.

  The standard output and standard error streams of a component can be
redirected to a file or to an arbitrary @command{syslog} channel.

@anchor{init-style}
@cindex init-style components
  This way of operation applies to the @dfn{init-style}
components, called so because of the similarity with the
@command{init} process manager.  @command{Pies} is also able to handle
components that receive input on their @samp{stdin} and send reply to
@samp{stdout}.  Such components are called @dfn{inetd-style}
components.

@anchor{inetd-style}
@cindex inetd-style components
  Inetd-style components are not executed right after @command{pies}
startup.  Instead, @command{pies} opens a socket for each of them and
listens for connections on these sockets.  When a connection arrives,
it decides what component the socket corresponds to, and invokes this
component to handle that connection.  In this case, the connection is
bound to component's @samp{stdin} and @samp{stdout} streams.  The
@samp{stderr} stream can be redirected to a file or to syslog, as
described above.  This mode of operation is similar to that of
@command{inetd} utility.

@anchor{meta1-style}
@cindex meta1-style components
@cindex smtps
  The third type of components, supported by @command{pies} are
@dfn{meta1-style} components.  As the name suggests this type is
designed expressly as a support for MeTA1@footnote{See
@uref{http://www.meta1.org}} components, namely
@command{smtps}.  This type can be regarded as a mixture of the above
two.  For each meta1-style component @command{pies} opens a socket
after start-up, and then executes the component.  Once the component
is running, @command{pies} passes it the file descriptor of the
socket, using a preconfigured @acronym{UNIX}-style socket.  Further
handling of the socket is the responsibility of the component itself.

@anchor{accept-style}
@cindex accept-style components
  The last flavor of @command{pies} components are @dfn{accept-style}
components, which are handled basically as @samp{inetd-style} ones,
except that after binding to the socket @command{pies} immediately
starts the component, without waiting for an actual connection.

  Any number of components of all three styles can be handled
simultaneously.

  Components are started in the order of their appearance in the
configuration file and terminated in the reverse order.  When starting or
stopping component dependencies, the same ordering is preserved.

  This order is reversed for files included by @code{include-meta1}
statement (@pxref{include-meta1}).

@node Pies Configuration File
@chapter Pies Configuration File
@cindex configuration file
@flindex pies.conf
@xopindex{config-file, introduced}
  @command{Pies} reads its settings and component definitions from the
@dfn{configuration file} @file{pies.conf}, located in the @dfn{system
configuration directory} (in most cases @file{/etc} or
@file{/usr/local/etc}, depending on how the package was compiled).
An alternative location may be specified using @option{--config-file}
(@option{-c} command line option.

  If any errors are encountered in the configuration file, the program
reports them on the standard error and exits with a non-zero status.

@xopindex{lint, introduced}
  To test the configuration file without actually starting the server, the 
@option{--lint} (@option{-t}) command line option is provided.  It causes
@command{pies} to check its configuration file and exit with status 0
if no errors were detected, and with status 1 otherwise.

@opindex -E, introduced
  Before parsing, configuration file is preprocessed using
@command{m4} (@pxref{Preprocessor}).  To see the preprocessed
configuration without actually parsing it, use @option{-E} command
line option.

@xopindex{config-help, introduced}
  The rest of this section describes the configuration file syntax in
detail.  You can receive a concise summary of all configuration
directives any time by running @command{pies --config-help}.

@menu
* Syntax::               Configuration file syntax.
* Component Statement::
* ACL::                  Access Control Lists
* include-meta1::
* Global Configuration::
@end menu

@node Syntax
@section Configuration File Syntax
  The configuration file consists of statements and comments.

  There are three classes of lexical tokens: keywords, values, and
separators. Blanks, tabs, newlines and comments, collectively called
@dfn{white space} are ignored except as they serve to separate
tokens.  Some white space is required to separate otherwise adjacent 
keywords and values.

@menu
* Comments::
* Statements::
* Preprocessor::         Using preprocessor to improve the configuration.
@end menu

@node Comments
@subsection Comments
@cindex Comments in a configuration file
@cindex single-line comments
  @dfn{Comments} may appear anywhere where white space may appear in the
configuration file.  There are two kinds of comments:
single-line and multi-line comments.  @dfn{Single-line} comments start
with @samp{#} or @samp{//} and continue to the end of the line:

@smallexample
# This is a comment
// This too is a comment
@end smallexample

@cindex multi-line comments
  @dfn{Multi-line} or @dfn{C-style} comments start with the two
characters @samp{/*} (slash, star) and continue until the first
occurrence of @samp{*/} (star, slash).

  Multi-line comments cannot be nested.

@node Statements
@subsection Statements
@cindex statements, configuration file
@cindex configuration file statements
@cindex statement, simple
@cindex simple statements
  A @dfn{simple statement} consists of a keyword and value
separated by any amount of whitespace.  Simple statement is terminated
with a semicolon (@samp{;}), unless it contains a @dfn{here-document}
(see below), in which case semicolon is optional.

  Examples of simple statements:

@smallexample
pidfile /var/run/pies.pid;
source-info yes;
debug 10;
@end smallexample

  A @dfn{keyword} begins with a letter and may contain letters,
decimal digits, underscores (@samp{_}) and dashes (@samp{-}).
Examples of keywords are: @samp{group}, @samp{control-file}.

  A @dfn{value} can be one of the following:

@table @asis
@item number
  A number is a sequence of decimal digits.

@item boolean
@cindex boolean value
  A boolean value is one of the following: @samp{yes}, @samp{true},
@samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no},
@samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}.
  
@item unquoted string
@cindex string, unquoted
  An unquoted string may contain letters, digits, and any of the
following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/},
@samp{:}.

@item quoted string
@cindex quoted string
@cindex string, quoted
@cindex escape sequence
  A quoted string is any sequence of characters enclosed in
double-quotes (@samp{"}).  A backslash appearing within a quoted
string introduces an @dfn{escape sequence}, which is replaced
with a single character according to the following rules:

@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 \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 \\ @tab A single backslash (@samp{\})
@item \" @tab A double-quote.
@end multitable
@end float

  In addition, the sequence @samp{\@var{newline}} is removed from
the string.  This allows to split long strings over several
physical lines, e.g.:

@smallexample
@group
"a long string may be\
 split over several lines"
@end group
@end smallexample

  If the character following a backslash is not one of those specified
above, the backslash is ignored and a warning is issued.

  Two or more adjacent quoted strings are concatenated, which gives
another way to split long strings over several lines to improve
readability.  The following fragment produces the same result as the
example above:

@smallexample
@group
"a long string may be"
" split over several lines"
@end group
@end smallexample

@anchor{here-document}
@item Here-document
@cindex here-document
  @dfn{Here-document} is a special construct that allows to introduce
strings of text containing embedded newlines.  

  The @code{<<@var{word}} construct instructs the parser to read all
the following lines up to the line containing only @var{word}, with
possible trailing blanks.  Any lines thus read are concatenated
together into a single string.  For example:

@smallexample
@group
<<EOT
A multiline
string
EOT
@end group
@end smallexample

  Body of a here-document is interpreted the same way as
double-quoted string, unless @var{word} is preceded by a backslash
(e.g. @samp{<<\EOT}) or enclosed in double-quotes, in which case
the text is read as is, without interpretation of escape sequences.

  If @var{word} is prefixed with @code{-} (a dash), then all leading
tab characters are stripped from input lines and the line containing
@var{word}.  Furthermore, if @code{-} is followed by a single space,
all leading whitespace is stripped from them.  This allows to indent
here-documents in a natural fashion.  For example:

@smallexample
@group
<<- TEXT
    All leading whitespace will be
    ignored when reading these lines.
TEXT
@end group
@end smallexample

  It is important that the terminating delimiter be the only token on
its line.  The only exception to this rule is allowed if a
here-document appears as the last element of a statement.  In this
case a semicolon can be placed on the same line with its terminating 
delimiter, as in: 

@smallexample
help-text <<-EOT
        A sample help text.
EOT;
@end smallexample

@item list
@cindex list
  A @dfn{list} is a comma-separated list of values.  Lists are
delimited by parentheses.  The following example shows a statement
whose value is a list of strings:

@smallexample
dependents (pmult, auth);
@end smallexample

  In any case where a list is appropriate, a single value is allowed
without being a member of a list: it is equivalent to a list with a
single member.  This means that, e.g. @samp{dependents auth;} is
equivalent to @samp{dependents (mime);}.

@end table

@cindex statement, block
@cindex block statement
  A @dfn{block statement} introduces a logical group of another
statements.  It consists of a keyword, followed by an optional value,
and a sequence of statements enclosed in curly braces, as shown in
the example below:

@smallexample
@group
component multiplexor @{
        command "pmult";
@}
@end group
@end smallexample

  The closing curly brace may be followed by a semicolon, although
this is not required.

@node Preprocessor
@subsection Using Preprocessor to Improve the Configuration.
@cindex preprocessor
@cindex m4
  Before parsing configuration file, @command{pies} preprocesses
it.  The built-in preprocessor handles only file inclusion
and @code{#line} statements (@FIXME-pxref{Pragmatic Comments}), while the
rest of traditional preprocessing facilities, such as macro expansion,
is supported via @command{m4}, which is used as an external preprocessor. 

  The detailed description of @command{m4} facilities lies far beyond
the scope of this document.  You will find a complete user manual in
@ifnothtml
@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
@end ifnothtml
@ifhtml
@uref{http://www.gnu.org/software/m4/manual}.
@end ifhtml
For the rest of this subsection we assume the reader is sufficiently
acquainted with @command{m4} macro processor.

@flindex pp-setup
  The external preprocessor is invoked with @option{-s} flag, instructing
it to include line synchronization information in its output.  This
information is then used by the parser to display meaningful
diagnostic.  An initial set of macro definitions is supplied by the 
@file{pp-setup} file, located in
@file{@var{$prefix}/share/pies/@var{version}/include} directory (where
@var{version} means the version of the package).

The default @file{pp-setup} file renames all @command{m4} built-in
macro names so they all start with the prefix @samp{m4_}.  This
is similar to GNU m4 @option{--prefix-builtin} options, but has an
advantage that it works with non-GNU @command{m4} implementations as
well.

@node Component Statement
@section Component Statement
@kwindex component

@deffn {Config} component
  The @code{component} statement defines a new component:
@end deffn

@smallexample
component @var{tag} @{
  @dots{}
@}
@end smallexample

The component is identified by its @dfn{tag}, which is given as
argument to the @code{component} keyword.

The following statements are allowed within the @code{component} block:

@deffn {Config: component} mode @var{mode}
  Declare the type (style) of the component.  Accepted values for
@var{mode} are:

@table @asis
@item exec
@itemx wait
  Create an @samp{init-style} component (@pxref{init-style}).  This is
the default.
  
@item inetd
@itemx nostartaccept
  Create an @samp{inetd-style} component (@pxref{inetd-style}).
  
@item pass
@itemx pass-fd 
  Create a @samp{meta1-style} component (@pxref{meta1-style}).
  
@item accept
  Create a @samp{accept-style} component (@pxref{accept-style}).
@end table
@end deffn

@deffn {Config: component} program @var{name}
Full file name of the component binary.  This binary will be executed
(via @command{/bin/sh -c}) each time @command{pies} decides it needs
to start the component.

To supply command line arguments, use @code{command} statement.
@end deffn
  
@deffn {Config: component} command @var{string}
Command line for the program.  The argument should be just as
arguments normally are, starting with the name of the program.  The
latter may be different from the one specified to @code{program}
statement.  Its value will be available to the program as
@code{argv[0]}. 
@end deffn

@deffn {Config: component} disable @var{bool}
If @var{bool} is @samp{true}, this component is disabled,
i.e. @command{pies} will ignore it.
@end deffn

@deffn {Config: component} precious @var{bool}
@cindex precious components
If @var{bool} is @samp{true}, this component is marked as precious.
Precious components are never disabled by @command{pies}, even if they
respawn too fast.
@end deffn
  

@menu
* Prerequisites::
* Component Privileges::
* Resources::
* Actions Before Startup::
* Exit Actions::
* Output Redirectors::
* Inetd-Style Components::
* Meta1-Style Components::
* Component Syntax Summary::
@end menu

@node Prerequisites
@subsection Component Prerequisites
@cindex declaring prerequisites
@cindex prerequisites, declaring
Prerequisites (@pxref{component prerequisite}) for a component are
declared using the following statement: 

@deffn {Config: component} prerequisites @var{tag-list}
The argument is either a list of component tags, @emph{defined before
this component}, or one of the following words:

@table @asis
@item all
Declare all components defined so far as prerequisites for this one.

@item none
No prerequisites.  This is the default.
@end table
@end deffn

  If you wish, you can define dependents, instead of prerequisites:

@deffn {Config: component} dependents @var{tag-list}
Declare dependents for this component.  @var{var-list} is a list of
component tags.
@end deffn

@node Component Privileges
@subsection Component Privileges
@cindex privileges
  Following statements control the privileges the component
is executed with.

@deffn {Config: component} user @var{user-name}
Start component with the UID and GID of this user. 
@end deffn

@deffn {Config: component} group @var{group-list}
Retain supplementary groups, specified in @var{group-list}.
@end deffn

@deffn {Config: component} allgroups @var{bool}
Retain all supplementary groups of which the user (as given with
@command{user} statement) is a member.  This is the default for
components specified in @file{meta1.conf} file (@pxref{include-meta1}).
@end deffn

@node Resources
@subsection Resources

@deffn {Config: component} limits @var{string}
Impose limits on system resources, as defined by @var{string}.  The
argument consists of @dfn{commands}, optionally separated by any
amount of whitespace.  A command is a single command letter followed
by a number, that specifies the limit.  The command letters are
case-insensitive and coincide with those used by the shell @code{ulimit}
utility:

@multitable @columnfractions 0.3 0.6 
@headitem Command @tab  The limit it sets
@item     A       @tab  max address space (KB)
@item     C       @tab  max core file size (KB)
@item     D       @tab  max data size (KB)
@item     F       @tab  maximum file size (KB)
@item     M       @tab  max locked-in-memory address space (KB)
@item     N       @tab  max number of open files
@item     R       @tab  max resident set size (KB)
@item     S       @tab  max stack size (KB)
@item     T       @tab  max CPU time (MIN)
@item     U       @tab  max number of processes
@item     P       @tab  process priority -20..20 (negative = high priority)
@end multitable

For example:

@smallexample
limits T10 R20 U16 P20
@end smallexample

Additionally, the command letter @samp{L} is recognized.  It is
reserved for future use (@samp{number of logins} limit) and is ignored
in version @value{VERSION}.
@end deffn

@deffn {Config: component} umask @var{number}
Set the umask.  The @var{number} must be an octal value not greater
than @samp{777}.  The default umask is inherited at startup.
@end deffn

@deffn {Config: component} env @var{args}
Set program environment.

Arguments are a whitespace-delimited list of specifiers.  The
following specifiers are understood: 

@table @asis
@item - (a dash)
Clear the environment.  This is understood only when used as a first
word in @var{args}.

@item -@var{name}
Unset the environment variable @var{name}.

@item -@var{name}=@var{val}
Unset the environment variable @var{name} only if its value is @var{val}.

@item @var{name}
Retain the environment variable @var{name}.

@item @var{name}=@var{value}
Define environment variable @var{name} to have given @var{value}.

@item @var{name}+=@var{value}
Retain variable @var{name} and append @var{value} to its existing
value.  If no such variable is present in the environment, it is
created and @var{value} is assigned to it.  However, if @var{value}
begins with a punctuation character, this character is removed from it
before the assignment.  This is convenient for using this construct with
environment variables like @env{PATH}, e.g.:

@smallexample
PATH+=:/sbin
@end smallexample

In this example, if @env{PATH} exists, @samp{:/sbin} will be appended
to it.  Otherwise, it will be created and @samp{/sbin} will be
assigned to it.

@item @var{name}=+@var{value}
Retain variable @var{name} and prepend @var{value} to its existing
value.  If no such variable is present in the environment, it is
created and @var{value} is assigned to it.  However, if @var{value}
ends with a punctuation character, this character is removed from it
before assignment. 
@end table
@end deffn

@node Actions Before Startup
@subsection Actions Before Startup

  Several statements are available that specify actions to perform
immediately before starting the component:

@deffn {Config: component} chdir @var{dir}
Change to the directory @var{dir}.
@end deffn

@deffn {Config: component} remove-file @var{file-name}
Remove @var{file-name}.  This is useful, for example, to remove stale
@acronym{UNIX} sockets or pid-files, which may otherwise prevent the
component from starting normally.

As of version @value{VERSION} only one @command{remove-file} may be given.
@end deffn

@deffn {Config: component} settle-timeout @var{number}
Wait @var{number} seconds.  This is kind of kludge.  Currently it is
used for components imported from @file{meta1.conf} file
(@pxref{include-meta1}), where @code{settle-timeout 1} is implied.
This may change in future versions.
@end deffn

@node Exit Actions
@subsection Exit Actions
@kwindex return-code
  The default behavior of @command{pies} if an @samp{init-style}
component terminates is to restart it.  Unless the component
terminates with 0 exit code, a corresponding error message is issued
to the log file.  This behavior can be modified using
@code{return-code} statement:

@deffn {Config} return-code
@smallexample
return-code @var{codes} @{
  @dots{}
@}
@end smallexample
@end deffn

  The @var{codes} argument is a list of exit codes or signal names.
Exit codes can be specified either as decimal numbers or as symbolic code
names from the table below: 

@multitable @columnfractions 0.5 0.3
@headitem Name       @tab Numeric value
@item EX_OK          @tab 0 
@item EX_USAGE       @tab 64
@item EX_DATAERR     @tab 65
@item EX_NOINPUT     @tab 66
@item EX_NOUSER      @tab 67
@item EX_NOHOST      @tab 68
@item EX_UNAVAILABLE @tab 69
@item EX_SOFTWARE    @tab 70
@item EX_OSERR       @tab 71
@item EX_OSFILE      @tab 72
@item EX_CANTCREAT   @tab 73
@item EX_IOERR       @tab 74
@item EX_TEMPFAIL    @tab 75
@item EX_PROTOCOL    @tab 76
@item EX_NOPERM      @tab 77
@item EX_CONFIG      @tab 78
@end multitable

Signal codes can be given either as @samp{SIG+@var{n}}, where @var{n}
is the signal number, or as signal names from the following list:
@samp{SIGHUP}, @samp{SIGINT}, @samp{SIGQUIT}, @samp{SIGILL},
@samp{SIGTRAP}, @samp{SIGABRT}, @samp{SIGIOT}, @samp{SIGBUS},
@samp{SIGFPE}, @samp{SIGKILL}, @samp{SIGUSR1}, @samp{SIGSEGV},
@samp{SIGUSR2}, @samp{SIGPIPE}, @samp{SIGALRM}, @samp{SIGTERM},
@samp{SIGSTKFLT}, @samp{SIGCHLD}, @samp{SIGCONT}, @samp{SIGSTOP},
@samp{SIGTSTP}, @samp{SIGTTIN}, @samp{SIGTTOU}, @samp{SIGURG},
@samp{SIGXCPU}, @samp{SIGXFSZ}, @samp{SIGVTALRM}, @samp{SIGPROF},
@samp{SIGWINCH}, @samp{SIGPOLL}, @samp{SIGIO}, @samp{SIGPWR},
@samp{SIGSYS}.

  If the component exits with an exit code listed in @var{codes}
or is terminated on a signal listed in @var{codes},  
@command{pies} executes actions specified by its substatements.
They are executed in the order of their appearance below:

@deffn {Config: return-code} exec @var{command}
Execute external command.  Prior to execution of @var{command} all
file descriptors are closed.  It inherits the environment from the
main @command{pies} process with the following additional variables:

@table @env
@item PIES_VERSION
The @command{pies} version number (@value{VERSION}).

@item PIES_COMPONENT
Tag of the terminated component (@pxref{Component Statement, tag}).

@item PIES_PID
PID of the terminated component.

@item PIES_SIGNAL
If the component terminated on signal, the number of that signal.

@item PIES_STATUS
Program exit code.
@end table
@end deffn

@deffn {Config: return-code} action @samp{disable | restart}
If @samp{restart} is given, restart the component.  This is the
default.  Otherwise, mark the component as disabled.  Component
dependents are stopped and marked as disabled as well.  Once disabled,
the components are never restarted, unless their restart is requested
by the administrator. 
@end deffn

@deffn {Config: return-code} notify @var{email-string}
Send an email notification to addresses in @var{email-string}.  The
latter is a comma-separated list of email addresses, e.g.:

@smallexample
notify "root@@localhost,postmaster@@localhost";
@end smallexample

The message itself is configured by the @code{message}
statement.
@end deffn

@deffn {Config: return-code} message @var{string}
Supply notification message text to use by @code{notify} statement.
@var{String} must be a valid RFC 822 message text, i.e. it must begin
with message headers, followed by an empty line and actual message
body.

The following macro-variables are expanded within @var{string}:

@multitable @columnfractions 0.5 0.5
@headitem Variable @tab Expansion
@item canonical-program-name @tab @samp{pies}
@item program-name @tab Program name of the @command{pies} binary.
@item package    @tab Package name (@samp{Pies}).
@item version    @tab Package version (@value{VERSION}).
@item component  @tab Name of the terminated component.
@item termination @tab Termination cause (see below).
@item retcode    @tab Component exit code (or signal number, if exited
on signal), in decimal.
@end multitable

The @samp{termination} variable is set so as to facilitate its use
with the @samp{retcode} variable.  Namely, its value is @samp{exited
with}, if the component exited and @samp{terminated on signal}, if
the component terminated on a signal.  Thus, using

@smallexample
$@{termination@} $@{retcode@}
@end smallexample

@noindent
results in a correct English sentence.  This message, however, cannot
be properly internationalized.  This will be fixed in the future
versions.

If @code{message} statement is not given, the following default
message is used instead:

@smallexample
From: <>
X-Agent: $@{canonical-program-name@} ($@{package@} $@{version@})
Subject: Component $@{component@} $@{termination@} $@{retcode@}.

@end smallexample
@end deffn

  Any number of @code{return-code} statements are allowed, provided
that their @var{codes} do not intersect.

  Such statements can also be used outside of @code{component} block.
In this case, they supply global actions, i.e. actions applicable to
all components.  Any @code{return-code} statements appearing within a
@code{component} block override the global ones.

@node Output Redirectors
@subsection Output Redirectors
@cindex repeater
  Output redirectors allow to redirect the standard error and/or standard
output of a component to a file or @command{syslog} facility.

@deffn {Config: component} stderr @var{type} @var{channel}
@deffnx {Config} stdout @var{type} @var{channel}
Redirect standard error (if @code{stderr}) or standard output (if
@code{stdout}) to the given channel.

The type of redirection is specified by @var{type} argument:

@table @asis
@item file
Redirect to the file.  In this case @var{channel} gives the full name of
the file.  For example:

@smallexample
stderr file /var/log/component/name.err;
@end smallexample

@item syslog
Redirect to the syslog channel.  The syslog priority is given by the
@var{channel} argument.  Its allowed values are: @samp{emerg},
@samp{alert}, @samp{crit}, @samp{err}, @samp{warning}, @samp{notice},
@samp{info}, @samp{debug}.  The facility is inherited from the
@code{syslog} statement (@pxref{syslog}), or from @code{facility}
statement (see below), if given.

Example:

@smallexample
stderr syslog err;
@end smallexample
@end table
@end deffn

@deffn {Config: component} facility @var{syslog-facility}
Specify the syslog facility to use in syslog redirectors.  Allowed 
values for @var{syslog-facility} are: @samp{user}, @samp{daemon},
@samp{auth}, @samp{authpriv}, @samp{mail}, @samp{cron}, @samp{local0}
through @samp{local7} (all names case-insensitive), or a facility number.
@end deffn

@node Inetd-Style Components
@subsection Inetd-Style Components
@cindex inetd-style components
  Inetd-style components are declared using @code{mode inetd}
statement.  You must also declare a socket to listen for requests for
such components:

@anchor{inetd-socket}
@deffn {Config: component} socket @var{url}
Define a socket to listen on.  Allowed values for @var{url} are:

@table @asis
@item file name
Specifies a @acronym{UNIX} socket file name.  You may use a relative
file name, provided that @code{chdir} statement is used for this
component (@pxref{Actions Before Startup, chdir}).

@item local://@var{file}[;@var{args}]
@itemx file://@var{file}[;@var{args}]
@itemx unix://@var{file}[;@var{args}]
Listen on the @acronym{UNIX} socket file @var{file}, which may be either
absolute or relative file name, as described above.  Optional
arguments @var{args} control ownership and file mode of @var{file}.  They
are a list of assignments, separated by semicolons.  The following
values are allowed:

@table @asis
@item user
User name of the socket owner.

@item group
Owner group of the socket, if it differs from the @code{user} group.

@item mode
Socket file mode (octal number between @samp{0} and @samp{777}).

@item umask
Umask to use when creating the socket (octal number between @samp{0}
and @samp{777}). 
@end table

For example:

@smallexample
socket unix:/var/run/socket;user=nobody;group=mail;mode=770
@end smallexample

@item inet://@var{ip}:@var{port}
Listen on IPv4 address @var{ip} (may be given as a symbolic host name),
on port @var{port}.
@end table

Notice, that @command{pies} version @value{VERSION} handles only
@acronym{TCP} sockets and only IPv4 addresses.  Support for IPv6 will
be added in future versions.  Support for @acronym{UDP} sockets will
be added if there is a demand.
@end deffn

@node Meta1-Style Components
@subsection Meta1-Style Components
@cindex meta1-style components
  Meta1-style components are declared using @code{mode pass}
statement.  For such components, you must declare both a socket to
listen on (@pxref{inetd-socket} and a @acronym{UNIX} socket name to
pass the file descriptor to the component.  The latter is defined
using @code{pass-fd-socket} statement:

@deffn {Config: component} pass-fd-socket @var{file-name}
The argument is an absolute or relative file name of the socket file.
In the latter case, the @code{chdir @var{dir}} statement must be used
for this component (@pxref{Actions Before Startup, chdir}), and the
socket will be looked under @var{dir}.

This socket file is supposed to be created by the component binary
upon its startup.
@end deffn

@node Component Syntax Summary
@subsection Component Syntax Summary
  This subsection summarizes the @code{component} summary.  For each
statement, a reference to its detailed description is supplied.

@smallexample
component @var{tag} @{
  # @r{Component execution mode.}
  # @xref{Component Statement, mode}.
  mode @samp{exec | wait | accept | inetd | nostartaccept | pass-fd | pass};
  
  # @r{Full name of the program.}
  # @xref{Component Statement, program}.
  program @var{name};
  # @r{Command line.}
  # @xref{Component Statement, command}.
  command @var{string};
  
  # @r{Disable this entry.}
  # @xref{Component Statement, disable}.
  disable @var{bool};
  # @r{Mark this entry as precious.}
  # @xref{Component Statement, precious}.  
  precious @var{bool};
  
  # @r{List of prerequisites.}
  # @xref{Prerequisites}.
  prerequisites (@var{compnames});
  # @r{List of components for which this one is a prerequisite.}
  # @xref{Prerequisites, dependents}.
  dependents (@var{compnames});
  
  # @r{Listen on the given url.}
  # @xref{Inetd-Style Components}.
  socket @var{url};
  
  # @r{Pass fd through this socket.}
  # @xref{Meta1-Style Components}.
  pass-fd-socket @var{soket-name};
  
  # @r{ACL for this component.}
  # @xref{ACL Statement, ACL Statement,, mailutils, GNU Mailutils Manual}.
  acl @{ @dots{} @}
  
  # @r{Override default syslog facility for this component.}
  facility @var{facility};
  # @r{Redirect program's standard output to the given}
  # @r{file or syslog priority.}
  # @xref{Output Redirectors}.
  stdout @samp{file | syslog} @var{channel};
  # @r{Redirect program's standard error to the given}
  # @r{file or syslog priority.}
  # @xref{Output Redirectors}.
  stderr @samp{file | syslog} @var{channel};
  
  # @r{Run with this user privileges.}
  # @xref{Component Privileges}.
  user @var{user-name};
  # @r{Retain supplementary group.}
  # @xref{Component Privileges, group}.
  group @var{group-name};
  # @r{Retain all supplementary groups of which user is a member.}
  # @xref{Component Privileges, allgroups}.
  allgroups @var{bool};
  
  # @r{Set system limits.}
  # @xref{Resources}.
  limits @var{string};
  
  # @r{Force this umask.}
  # @xref{Resources, umask}.
  umask @var{number};
  
  # @r{Set program environment.}
  # @xref{Resources, env}.
  env @var{assignments};
  
  # @r{Change to this directory before executing the component.}
  # @xref{Actions Before Startup, chdir}.
  chdir @var{dir};
  # @r{Remove @var{file-name} before starting the component.}
  # @xref{Actions Before Startup, remove-file}.
  remove-file @var{file-name};
  # @r{Time to wait before starting this component.}
  # @xref{Actions Before Startup, settle-timeout}.
  settle-timeout @var{number};
  
  # @r{Actions:}
  # @xref{Exit Actions}.
  return-code @var{exit-code-list} @{
    # @r{Action to take when a component finishes with this return code.}
    action @samp{disable | restart};
    # @r{Notify these addresses when then component terminates.}
    notify @var{email-string};
    # @r{Notification message text (with headers).}
    message @var{string};
  @}
@}
@end smallexample

@node ACL
@section Access Control Lists
@cindex @acronym{ACL}
@cindex access control lists
@dfn{Access control lists}, or @acronym{ACL}s for short, are lists of
permissions that control access to @samp{inetd}, @samp{access} and
@samp{meta1}-style components.

An @acronym{ACL} is defined using @code{acl} block statement:

@deffn {Config} acl
@smallexample
acl @var{name} @{
  @var{definitions}
@}
@end smallexample
@end deffn

The @var{name} parameter specifies a unique name for that
@acronym{ACL}.  This name can be used by another configuration
statements to refer to that @acronym{ACL}. 

A part between the curly braces (denoted by @var{definitions} above),
is a list of @dfn{access statements}.  There are two types of
such statements:  

@deffn {Config: acl} allow @var{user-group} @var{sub-acl} @var{host-list}
Allow access to resource.
@end deffn

@deffn {Config: acl} deny @var{user-group} @var{sub-acl} @var{host-list}
Deny access to resource.
@end deffn

All parts of an access statement are optional, but at least one
of them must be present.

The @var{user-group} part specifies which users match this entry.
Allowed values are the following:

@table @code
@kwindex all
@item all
All users.

@kwindex authenticated
@item authenticated
Only authenticated users.

@kwindex group
@item group @var{group-list}
Authenticated users which are members of at least one of groups listed in
@var{group-list}.
@end table

The @var{sub-acl} part, if present, allows to branch to another
@acronym{ACL}.  The syntax of this group is:

@smallexample
acl @var{name}
@end smallexample

@noindent
where @var{name} is the name of a previously defined @acronym{ACL}.

Finally, the @var{host-list} group allows to match client addresses.
It consists of a @code{from} keyword followed by a list of
@dfn{address specifiers}.  Allowed address specifiers are:

@table @asis
@item @var{addr}
Matches if the client @acronym{IP} equals @var{addr}.
The latter may be given either as an @acronym{IP}
address or as a host name, in which case it will be resolved and the
first of its @acronym{IP} addresses will be used.


@item @var{addr}/@var{netlen}
Matches if first @var{netlen} bits from the client @acronym{IP}
address equal to @var{addr}.  The network mask length, @var{netlen}
must be an integer number in the range from 0 to 32.  The address part,
@var{addr}, is as described above. 

@item @var{addr}/@var{netmask}
The specifier matches if the result of logical @acronym{AND} between
the client @acronym{IP} address and @var{netmask} equals to
@var{addr}.  The network mask must be specified in ``dotted quad''
form, e.g. @samp{255.255.255.224}.

@item @var{filename}
Matches if connection was received from a @acronym{UNIX} socket
@var{filename}, which must be given as an absolute file name.
@end table

To summarize, the syntax of an access statement is:

@smallexample
allow|deny [all|authenticated|group @var{group-list}]
           [acl @var{name}] [from @var{addr-list}]
@end smallexample

@noindent
where square brackets denote optional parts and vertical bar means
@samp{one of}.

When an @acronym{ACL} is applied to a particular object, its entries
are tried in turn until one of them matches, or the end of the list is
reached.  If a matched entry is found, its command verb, @code{allow}
or @code{deny}, defines the result of @acronym{ACL} match.  If the end
of list is reached, the result is @samp{allow}, unless explicitly
specified otherwise.

@FIXME{Trim that example:}
For example, the following statement defines an @acronym{ACL} named
@samp{common}, that allows access for any user connected via local
@acronym{UNIX} socket @file{/tmp/dicod.sock} or coming from a local
network @samp{192.168.10.0/24}.  Any authenticated users are allowed,
provided that they are allowed by another @acronym{ACL} @samp{my-nets}
(which should have been defined before this definition).  Users 
coming from the network @samp{10.10.0.0/24} are allowed if they
authenticate themselves and are members of groups @samp{pies} or
@samp{users}.  Access is denied for anybody else:

@smallexample
@group
acl common @{
    allow all from ("/tmp/pies.sock", "192.168.10.0/24");
    allow authenticated acl "my-nets";
    allow group ("pies", "users") from "10.10.0.0/24";
    deny all;
@}
@end group
@end smallexample

@node include-meta1
@section Using MeTA1 Configuration File
@flindex /etc/meta1/meta1.conf
  MeTA1 is a mail transfer agent of new generation, designed
to replace Sendmail in the future (@uref{http://www.meta1.org}).
It has a modular structure, each module being an independent
program, which is responsible for a particular task.  The components
are configured in the MeTA1 configuration file
@file{/etc/meta1/meta1.conf}.

  @command{Pies} is able to take a list of components directly
from MeTA1 configuration file:

@deffn {Config} include-meta1 @var{file}
Parse @var{file} as MeTA1 configuration file and incorporate
components defined there into the current component list.

For example:

include-meta1 /etc/meta1/meta1.conf;
@end deffn

Thus, you can use @command{pies} instead of the default MeTA1 program
manager @command{mcp}.  This is particularly useful if you use
@samp{Mailfromd} (@uref{http://mailfromd.software.gnu.org.ua}) to
control the mail flow.

To ensure compatibility with MeTA1, the components read from its
configuration file are started in the reverse order (i.e. from last to
first), and stopped in the order of their appearance in @var{file}.
Of course, this does not affect normal @command{pies} components.

The following @command{pies} statements are silently applied to
all MeTA1 components:

@smallexample
allgroups yes;
stderr file @var{compname}.log
chdir @var{queue-dir}
@end smallexample

Here, @var{compname} stands for the name of the component, and
@var{queue-dir} stands for the name of MeTA1 queue directory.  The
latter is @file{/var/spool/meta1} by default.  It can be changed using
the following statement

@deffn {Config} meta1-queue-dir @var{dir}
Set name of MeTA1 queue directory.
@end deffn

To override any default settings for a MeTA1 component, add a
@code{command} section with the desired settings after including
@file{meta1.conf}.  For example, here is how to redirect program
diagnostics to @samp{local1.debug} syslog channel:

@smallexample
include-meta1 /etc/meta1/meta1.conf

component smtps @{
  facility local1;
  stderr syslog debug;
@}
@end smallexample

@node Global Configuration
@section Global Configuration
@cindex Global Configuration
The statements described in this section affect @command{pies}
behavior as a whole.

@anchor{syslog}
@deffn {Config} syslog @{ ... @}
This block statement configures logging via syslog.  It has two
substatements:
@end deffn

@deffn {Config: syslog} tag @var{string}
Prefix syslog messages with this string.  By default, the program name
is used.

@deffn {Config: syslog} facility @var{string}
Set syslog facility to use.  Allowed values are: @samp{user},
@samp{daemon}, @samp{auth}, @samp{authpriv}, @samp{mail}, @samp{cron},
@samp{local0} through @samp{local7} (case-insensitive), or a facility
number.
@end deffn
@end deffn

@deffn {Config} umask @var{number}
Set the default umask.  The @var{number} must be an octal value not greater
than @samp{777}.  The default umask is inherited at startup.
@end deffn

@deffn {Config} limits @var{arg}
Set global system limits for all pies components.  @xref{Resources,
limits}, for a detailed description of @var{arg}.
@end deffn

@deffn {Config} return-code @{ ... @}
Configure global exit actions.  @xref{Exit Actions}, for a detailed
description of this statement.
@end deffn

@deffn {Config} shutdown-timeout @var{number};
Wait @var{number} of seconds for all components to shut down.
Default is 5 seconds.
@end deffn

@menu
* Less Useful Statements::
@end menu

@node Less Useful Statements
@subsection Less Useful Statements

  Some configuration file statements are provided for completeness and
are rarely, if at all used.  If used improperly, they may severely
impair the functionality of @command{pies} or even render it
useless.  Do not use them, unless you have a good knowledge of
@command{pies} internals and understand their impact.

  The following three statements define file names of various files
needed by @command{pies}.  Use them only if the defaults does not
suit your needs:

@deffn {Config} pidfile @var{file}
Write PID of the master @command{pies} process to @var{file}.  By
default, master PID is stored in @file{@var{statedir}/pies.pid}
(@FIXME-pxref{statedir}). 
@end deffn

@deffn {Config} control-file @var{file}
Set file name of the @command{pies} control file.  Default is
@file{@var{statedir}/pies.ctl} 
@end deffn

@deffn {Config} stat-file @var{file}
Set file name of the statistics output file.  Default is
@file{@var{statedir}/pies.stat}. 
@end deffn

  Normally, @command{pies} must be run with root privileges.  If,
however, you found such an implementation for it, that requires another
privileges, you may change them using the following three statements:

@command{pies} process.  
@deffn {Config} user @var{user-name}
Start @command{pies} with the UID and GID of this user. 
@end deffn

@deffn {Config} group @var{group-list}
Retain supplementary groups, specified in @var{group-list}.
@end deffn

@deffn {Config} allgroups @var{bool}
Retain all supplementary groups of which user, given with
@command{user} statement, is a member.  
@end deffn

@node Pies Debugging
@chapter Pies Debugging
@xopindex{debug, described}
  The amount of debugging information produced by @command{pies} is configured
by the following statements:

@deffn {Config} debug @var{level}
Set debugging level.  The @var{level} must be a non-negative decimal
integer.  In version @value{VERSION} the following debugging levels
are used:

@table @asis
@item 1
Log all basic actions: starting and stopping of components, received incoming
@acronym{TCP} connections, sending mails.  Notify about setting
limits.  Log pre-startup actions (@pxref{Actions Before Startup}).

@item 2
Log setting particular limits.  Log the recomputed alarms.

@item 4
Dump execution environments

@item 6
Debug the parser of MeTA1 configuration grammar.

@item 7
Debug the lexical analyzer of MeTA1 configuration file.
@end table
@end deffn

@anchor{source-info}
@deffn {Config} source-info @var{bool}
This statement decides whether debugging messages should contain
source information.  To enable source information, use:

@smallexample
source-info yes;
@end smallexample

This feature is designed for @command{pies} developers.
@end deffn

@node Configuration Example
@chapter Configuration Example
  In this section we provide several examples of working @command{pies}
configuration files.

@menu
* Simple Pies::
* Hairy Pies::
* Inetd Pies::
@end menu

@node Simple Pies
@section Simplest Case: Using Pies to Run Pmult
  The example below runs @command{pmult} (@pxref{pmult, Pmilter
multiplexer program,, mailfromd, Mailfromd Manual}) utility with
the privileges of @samp{meta1} user.  Both standard error and standard
output are redirected to the syslog facility @samp{mail}, priorities
@samp{err} and @samp{info}, correspondingly.

@smallexample
component pmult @{
  command "/usr/local/sbin/pmult";
  user meta1s;
  facility mail;
  stderr syslog err;
  stdout syslog info;
@}
@end smallexample

@node Hairy Pies
@section Using Pies to Run Pmult and MeTA1
  The example below is a working configuration file for running
@command{pmult} and all components of MeTA1, configured in
@file{/etc/meta1/meta1.conf}.  The global @code{return-code} statement
is used to configure @command{pies} behavior for some exit codes.

@smallexample
# Sample pies configuration for running pmult and MeTA1

# Special handling for exit codes that mean the program was
# incorrectly used or misconfigured.
return-code (EX_USAGE, EX_CONFIG) @{
  action disable;
  notify "root";
  message <<- EOT
    From: Pies <>
    X-Agent: $@{canonical-program-name@} ($@{package@} $@{version@})
    Subject: Component $@{component@} disabled.
    
    Component "$@{component@}" has terminated with code $@{retcode@},
    which means it encountered some configuration problem.
    I will not restart it automatically. Please fix its configuration
    and restart it manually at your earliest convenience.
    
    To restart, run ``$@{program-name@} -R $@{component@}''
    ---
    Wuff-wuff,
    Pies
  EOT;
@}

component pmult @{
  command "/usr/local/sbin/pmult";
  user meta1s;
  stderr syslog err;
  stdout syslog info;
@}

include-meta1 "/etc/meta1/meta1.conf";
@end smallexample

@node Inetd Pies
@section Running Pies Instead of Inetd

This configuration file allows to run @command{pies} instead of
@command{initd}.  It starts two services: @samp{ftp} and @samp{pop3d},
and restricts access to them to two local subnets:

@smallexample
acl @{
   log from any "Connect from $@{address@}";
   allow from 10.10.10.0/24;
   allow from 192.168.10.0/27;
   deny from any;
@}

debug "<trace4";

component ftp @{
   mode inetd;
   socket "inet://0.0.0.0:21";
   umask 027;
   program /usr/sbin/ftpd
   command ftpd -l -C;
@}

component pop3d @{
   mode inetd;
   socket "inet://0.0.0.0:110";
   program "/usr/sbin/pop3d";
   command "pop3d --inetd";
@}
@end smallexample

@node Command Line Usage
@chapter Command Line Usage

  When run without arguments, @command{pies} parses and loads the
configuration file, detaches itself from the controlling terminal
(becomes a daemon), and starts all components.  Before actually
starting up, it ensures that no another instance of it is 
already running, by looking for a PID file and verifying that the PID
listed there is alive and responding.  If another instance is running,
@command{pies} refuses to start up.

@anchor{pies-status}
  After startup, you can verify the status of the running process
using @option{--status} command line option:

@smallexample
$ pies --status
redirector smtps/stderr 4697
redirector pmult/stderr 4677
redirector pmult/stdout 4676
component pmult 4678 /usr/local/sbin/pmult
component smar 4680 smar -f /etc/meta1/meta1.conf -d 100
component qmgr 4691 qmgr -f /etc/meta1/meta1.conf
component smtpc 4696 smtpc -f /etc/meta1/meta1.conf
component smtps 4698 smtps -d100 -f /etc/meta1/meta1.conf
@end smallexample

  In its output, lines beginning with @samp{component} refer to
running components.  For running components, the following information
is displayed:

@enumerate 1
@item Component tag (@pxref{Component Statement}).
@item PID of the running instance of the component.
@item Command line of the component, as set by the @code{command}
statement (@pxref{Component Statement, command}).
@end enumerate

If the component is not running, the reason is indicated in the PID
column, between the square brackets, e.g.:

@smallexample
component pmult [disabled; scheduled for Mon 01 Dec 2008 20:27:02] 
  /usr/local/sbin/pmult
@end smallexample

@noindent
(the example above is split in two lines for readability).

@anchor{pies-restart}
@xopindex{restart-component, described}
  You can restart any component by using the
@option{--restart-component} (@option{-R}) option, e.g.:

@smallexample
$ pies -R pmult smtps
@end smallexample

@xopindex{stop, described}
  To stop all running components and shut down @command{pies}, use the
@option{--stop} (@option{-S}) command line option:

@smallexample
$ pies --stop
@end smallexample

@cindex dependencies
@anchor{dump-depmap}
@xopindex{dump-depmap option, introduced}
  Two options are provided for verifying inter-component
dependencies.  The @option{--dump-depmap} option prints on the
standard output the @dfn{dependency map}.  This map is a square matrix
with rows representing dependents and columns representing prerequisites.
An @samp{X} sign is placed on each crossing which corresponds to the
actual dependency.  For example:

@smallexample
$ pies --dump-depmap
Dependency map:
    0  1  2  3  4
 0                
 1                
 2     X          
 3        X       
 4     X  X       

Legend:
 0: pmult
 1: smar
 2: qmgr
 3: smtpc
 4: smtps
@end smallexample

This example corresponds to the configuration file shown in @ref{Hairy
Pies}.  To illustrate how to read it, consider the 4th row of the
table.  According to the legend, number 4 means @samp{smtps}
component.  There are two @samp{X} marks: in columns 1 and 2.  This
means that @samp{smtps} depends on @samp{smar} and @samp{qmgr}.

@anchor{dump-prereq}
@xopindex{dump-prereq, described}
  You can also list prerequisites explicitly:

@smallexample
$ pies --dump-prereq
qmgr: smar
smtpc: qmgr
smtps: smar qmgr
@end smallexample

@node Pies Invocation
@chapter Pies Invocation

This section summarizes @command{pies} command line options.

@table @option
@opsummary{config-help}
@item --config-help
Show configuration file summary.  @xref{Pies Configuration File}.

@opsummary{config-file}
@item --config-file=@var{file}
@item -c @var{file}
Read configuration from @var{file}, instead of the default
@file{/etc/pies.conf}.

@xref{Pies Configuration File}.

@item -E
Preprocess configuration file and exit.  @xref{Preprocessor}.

@opsummary{force}
@item --force
Force startup even if another instance may be running.

@opsummary{foreground}
@item --foreground
Remain in foreground.

@opsummary{source-info}
@item --source-info
Show source info with debugging messages.  @xref{source-info}.

@opsummary{lint}
@item --lint
@itemx -t

@opsummary{stderr}
@item --stderr
Log to standard error.

@opsummary{syslog}
@item --syslog
Log to syslog.  This is the default.

@opsummary{debug}
@item -x @var{level}
@itemx --debug=@var{level}
Set debug verbosity level.  @xref{Pies Debugging}, for a description
of @var{level}.

@opsummary{reload}
@opsummary{hup}
@item -r
@itemx --reload
@itemx --hup
Reload the running instance of pies.

@opsummary{restart-component}
@item -R
@itemx --restart-component
Restart components named in the command line.  @xref{pies-restart}.

@opsummary{status}
@item -s
@itemx --status
Display info about the running instance.  @xref{pies-status}.

@opsummary{stop}
@item -S
@itemx --stop
Stop the running instance.  

@opsummary{dump-depmap}
@item --dump-depmap
Dump dependency map.  @xref{dump-depmap}.

@opsummary{dump-prereq}
@item --dump-prereq
Dump prerequisite charts.  @xref{dump-prereq}.

@item --help
Display a short usage summary and exit.

@item --usage
Display a short summary of available options and exit.

@item --version
Display program version and license information and exit.

@end table

@node Reporting Bugs
@chapter How to Report a Bug

  Send bug-reports and suggestions to @email{bug-pies@@gnu.org.ua}.

  If you think you've found a bug, please be sure to include maximum
information needed to reliably reproduce it, or at least to analyze
it.  The information needed is:

@itemize
@item Version of the package you are using.
@item Compilation options used when configuring the package.
@item Run-time configuration (@file{pies.conf} file and the command
line options used).
@item Detailed description of the bug.
@item Conditions under which the bug appears.
@end itemize  

@node Copying This Manual
@appendix GNU Free Documentation License
@include fdl.texi

@node Concept Index
@unnumbered Concept Index

This is a general index of all issues discussed in this manual

@printindex cp

@bye

Return to:

Send suggestions and report system problems to the System administrator.