aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-10-15 16:21:32 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2009-10-15 16:21:32 +0300
commitb713e2208519e7cba1c779cbd9387137eb101e5e (patch)
treec1245c09d9cffa5d74ec8961ed0ffd820f0bd23e /doc
parent9dbe6b40d07df41255f0c8fda6895000b7c7e1a6 (diff)
downloadpies-b713e2208519e7cba1c779cbd9387137eb101e5e.tar.gz
pies-b713e2208519e7cba1c779cbd9387137eb101e5e.tar.bz2
Various fixes.
* README: Fix typo. * doc/usr-acl.texi: New file. * doc/Makefile.am (pies_TEXINFOS): Remove pies.texi, add usr-acl.texi (check-config, check-sub-config): Handle @deffnx * doc/pies.texi: Update. * src/Makefile.am (AM_CPPFLAGS): Remove superfluous defs, use ../gnu/configmake.h instead * src/acl.c (_acl_common_section_parser): Handle tag, depending on the value of `flag' parameter. Avoid coredumping on NULL pacl. (acl_section_parser, defacl_section_parser): Update calls to _acl_common_section_parser. * src/pies.c (STATEDIR): Replace with LOCALSTATEDIR. (GRECS_VALUE_IS_EMPTY): New define (possibly belongs to grecs more than to pies). (assert_grecs_value_type) (return_code_section_parser): Use GRECS_VALUE_IS_EMPTY to check for empty value. (_get_array_arg): Bugfix. (component_keywords, pies_keywords): Add missing docstrings. * src/progman.c (TYPE_RETR): Rename to TYPE_REDIRECTOR. All uses updated.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am8
-rw-r--r--doc/pies.texi418
-rw-r--r--doc/usr-acl.texi48
3 files changed, 343 insertions, 131 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index fec8df3..bb2ff49 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -18,8 +18,8 @@ info_TEXINFOS=pies.texi
18pies_TEXINFOS=\ 18pies_TEXINFOS=\
19 fdl.texi\ 19 fdl.texi\
20 macros.texi\ 20 macros.texi\
21 pies.texi\ 21 rendition.texi\
22 rendition.texi 22 usr-acl.texi
23 23
24EXTRA_DIST = \ 24EXTRA_DIST = \
25 check-docs.sh\ 25 check-docs.sh\
@@ -48,7 +48,7 @@ check-options:
48check-config: 48check-config:
49 @check-docs.sh 'configuration statements' \ 49 @check-docs.sh 'configuration statements' \
50 '/pies_keywords\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ 50 '/pies_keywords\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
51 's/@deffn {Config} *\([^@,]*\).*/\1/p' \ 51 's/@deffnx\{0,1\} {Config} *\([^@,]*\).*/\1/p' \
52 $(top_srcdir)/src/pies.c -- \ 52 $(top_srcdir)/src/pies.c -- \
53 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ 53 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
54 $(info_TEXINFOS) 54 $(info_TEXINFOS)
@@ -58,7 +58,7 @@ check-sub-config:
58 while read ident kw; do \ 58 while read ident kw; do \
59 check-docs.sh "$$ident configuration statements" \ 59 check-docs.sh "$$ident configuration statements" \
60 "/$$kw"'\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ 60 "/$$kw"'\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
61 "s/@deffn {Config: *$${ident}}"' *\([^@,]*\).*/\1/p' \ 61 "s/@deffnx\{0,1\} {Config: *$${ident}}"' *\([^@,]*\).*/\1/p' \
62 $(top_srcdir)/src/pies.c $(top_srcdir)/src/acl.c -- \ 62 $(top_srcdir)/src/pies.c $(top_srcdir)/src/acl.c -- \
63 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ 63 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
64 $(info_TEXINFOS); \ 64 $(info_TEXINFOS); \
diff --git a/doc/pies.texi b/doc/pies.texi
index e1ca650..e47f6a6 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -90,8 +90,46 @@ Appendices
90* Concept Index:: Index of Concepts. 90* Concept Index:: Index of Concepts.
91 91
92@detailmenu 92@detailmenu
93@end detailmenu 93 --- The Detailed Node Listing ---
94
95Pies Configuration File
96
97* Syntax:: Configuration File Syntax
98* Component Statement::
99* Notification:: Mail Notification
100* ACL:: Access Control Lists
101* include-meta1::
102* Global Configuration::
103
104Configuration File Syntax
105
106* Comments::
107* Statements::
108* Preprocessor:: Using preprocessor to improve the configuration.
109
110Component Statement
111
112* Prerequisites::
113* Component Privileges::
114* Resources::
115* Actions Before Startup::
116* Exit Actions::
117* Output Redirectors::
118* Inetd-Style Components::
119* Meta1-Style Components::
120* Component Syntax Summary::
121
122Global Configuration
123
124* Less Useful Statements::
125
126Configuration Example
94 127
128* Simple Pies::
129* Hairy Pies::
130* Inetd Pies::
131
132@end detailmenu
95@end menu 133@end menu
96 134
97@node Intro 135@node Intro
@@ -200,7 +238,7 @@ reports them on the standard error and exits with a non-zero status.
200@command{pies} to check its configuration file and exit with status 0 238@command{pies} to check its configuration file and exit with status 0
201if no errors were detected, and with status 1 otherwise. 239if no errors were detected, and with status 1 otherwise.
202 240
203@opindex -E, introduced 241@cindex @option{-E}, introduced
204 Before parsing, configuration file is preprocessed using 242 Before parsing, configuration file is preprocessed using
205@command{m4} (@pxref{Preprocessor}). To see the preprocessed 243@command{m4} (@pxref{Preprocessor}). To see the preprocessed
206configuration without actually parsing it, use @option{-E} command 244configuration without actually parsing it, use @option{-E} command
@@ -212,8 +250,9 @@ detail. You can receive a concise summary of all configuration
212directives any time by running @command{pies --config-help}. 250directives any time by running @command{pies --config-help}.
213 251
214@menu 252@menu
215* Syntax:: Configuration file syntax. 253* Syntax:: Configuration File Syntax
216* Component Statement:: 254* Component Statement::
255* Notification:: Mail Notification
217* ACL:: Access Control Lists 256* ACL:: Access Control Lists
218* include-meta1:: 257* include-meta1::
219* Global Configuration:: 258* Global Configuration::
@@ -438,21 +477,16 @@ this is not required.
438@subsection Using Preprocessor to Improve the Configuration. 477@subsection Using Preprocessor to Improve the Configuration.
439@cindex preprocessor 478@cindex preprocessor
440@cindex m4 479@cindex m4
441 Before parsing configuration file, @command{pies} preprocesses 480 Before parsing, the configuration file is @dfn{preprocessed} using
442it. The built-in preprocessor handles only file inclusion 481external preprocessor @command{m4}. For a complete user manual, refer
443and @code{#line} statements (@FIXME-pxref{Pragmatic Comments}), while the 482to
444rest of traditional preprocessing facilities, such as macro expansion,
445is supported via @command{m4}, which is used as an external preprocessor.
446
447 The detailed description of @command{m4} facilities lies far beyond
448the scope of this document. You will find a complete user manual in
449@ifnothtml 483@ifnothtml
450@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}. 484@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
451@end ifnothtml 485@end ifnothtml
452@ifhtml 486@ifhtml
453@uref{http://www.gnu.org/software/m4/manual}. 487@uref{http://www.gnu.org/software/m4/manual}.
454@end ifhtml 488@end ifhtml
455For the rest of this subsection we assume the reader is sufficiently 489In this subsection we assume the reader is sufficiently
456acquainted with @command{m4} macro processor. 490acquainted with @command{m4} macro processor.
457 491
458@flindex pp-setup 492@flindex pp-setup
@@ -487,7 +521,8 @@ component @var{tag} @{
487The component is identified by its @dfn{tag}, which is given as 521The component is identified by its @dfn{tag}, which is given as
488argument to the @code{component} keyword. 522argument to the @code{component} keyword.
489 523
490The following statements are allowed within the @code{component} block: 524Following are the basic statements which are allowed within the
525@code{component} block:
491 526
492@deffn {Config: component} mode @var{mode} 527@deffn {Config: component} mode @var{mode}
493 Declare the type (style) of the component. Accepted values for 528 Declare the type (style) of the component. Accepted values for
@@ -539,7 +574,14 @@ If @var{bool} is @samp{true}, this component is marked as precious.
539Precious components are never disabled by @command{pies}, even if they 574Precious components are never disabled by @command{pies}, even if they
540respawn too fast. 575respawn too fast.
541@end deffn 576@end deffn
542 577
578@deffn {Config: component} acl @{ ... @}
579Set access control list for this component. @xref{ACL}, for a
580detailed description of access control lists.
581@end deffn
582
583The following subsections describe the rest of @samp{component}
584substatements.
543 585
544@menu 586@menu
545* Prerequisites:: 587* Prerequisites::
@@ -724,7 +766,7 @@ terminates with 0 exit code, a corresponding error message is issued
724to the log file. This behavior can be modified using 766to the log file. This behavior can be modified using
725@code{return-code} statement: 767@code{return-code} statement:
726 768
727@deffn {Config} return-code 769@deffn {Config: component} return-code
728@smallexample 770@smallexample
729return-code @var{codes} @{ 771return-code @var{codes} @{
730 @dots{} 772 @dots{}
@@ -805,60 +847,13 @@ by the administrator.
805@end deffn 847@end deffn
806 848
807@deffn {Config: return-code} notify @var{email-string} 849@deffn {Config: return-code} notify @var{email-string}
808Send an email notification to addresses in @var{email-string}. The 850Send an email notification to addresses in @var{email-string}.
809latter is a comma-separated list of email addresses, e.g.: 851@xref{Notification}, for a detailed discussion of this feature.
810
811@smallexample
812notify "root@@localhost,postmaster@@localhost";
813@end smallexample
814
815The message itself is configured by the @code{message}
816statement.
817@end deffn 852@end deffn
818 853
819@deffn {Config: return-code} message @var{string} 854@deffn {Config: return-code} message @var{string}
820Supply notification message text to use by @code{notify} statement. 855Supply notification message text to use by @code{notify} statement.
821@var{String} must be a valid RFC 822 message text, i.e. it must begin 856@xref{Notification}, for a detailed discussion of this feature.
822with message headers, followed by an empty line and actual message
823body.
824
825The following macro-variables are expanded within @var{string}:
826
827@multitable @columnfractions 0.5 0.5
828@headitem Variable @tab Expansion
829@item canonical-program-name @tab @samp{pies}
830@item program-name @tab Program name of the @command{pies} binary.
831@item package @tab Package name (@samp{Pies}).
832@item version @tab Package version (@value{VERSION}).
833@item component @tab Name of the terminated component.
834@item termination @tab Termination cause (see below).
835@item retcode @tab Component exit code (or signal number, if exited
836on signal), in decimal.
837@end multitable
838
839The @samp{termination} variable is set so as to facilitate its use
840with the @samp{retcode} variable. Namely, its value is @samp{exited
841with}, if the component exited and @samp{terminated on signal}, if
842the component terminated on a signal. Thus, using
843
844@smallexample
845$@{termination@} $@{retcode@}
846@end smallexample
847
848@noindent
849results in a correct English sentence. This message, however, cannot
850be properly internationalized. This will be fixed in the future
851versions.
852
853If @code{message} statement is not given, the following default
854message is used instead:
855
856@smallexample
857From: <>
858X-Agent: $@{canonical-program-name@} ($@{package@} $@{version@})
859Subject: Component $@{component@} $@{termination@} $@{retcode@}.
860
861@end smallexample
862@end deffn 857@end deffn
863 858
864 Any number of @code{return-code} statements are allowed, provided 859 Any number of @code{return-code} statements are allowed, provided
@@ -876,7 +871,7 @@ all components. Any @code{return-code} statements appearing within a
876output of a component to a file or @command{syslog} facility. 871output of a component to a file or @command{syslog} facility.
877 872
878@deffn {Config: component} stderr @var{type} @var{channel} 873@deffn {Config: component} stderr @var{type} @var{channel}
879@deffnx {Config} stdout @var{type} @var{channel} 874@deffnx {Config: component} stdout @var{type} @var{channel}
880Redirect standard error (if @code{stderr}) or standard output (if 875Redirect standard error (if @code{stderr}) or standard output (if
881@code{stdout}) to the given channel. 876@code{stdout}) to the given channel.
882 877
@@ -1091,6 +1086,157 @@ component @var{tag} @{
1091@} 1086@}
1092@end smallexample 1087@end smallexample
1093 1088
1089@node Notification
1090@section Notification
1091@cindex Notification
1092
1093 Pies provides a @dfn{notification} mechanism, which can be used to
1094send email messages when components terminate. The exact contents
1095of such notifications and the list of their recipients may depend on
1096the exit code which the component returned. Notification is
1097configured by supplying @samp{notify} and @samp{message} statements
1098within a @samp{return-code} block.
1099
1100@deffn {Config: return-code} notify @var{email-string}
1101Send an email notification to addresses from @var{email-string}. The
1102latter is a comma-separated list of email addresses, e.g.:
1103
1104@smallexample
1105notify "root@@localhost,postmaster@@localhost";
1106@end smallexample
1107
1108Each address may be optionally enclosed in angular brackets (@samp{<}
1109and @samp{>}).
1110@end deffn
1111
1112@deffn {Config: return-code} message @var{string}
1113Supply the email message text to be sent. @var{String} must be a
1114valid RFC 822 message, i.e. it must begin with message headers,
1115followed by an empty line and the actual message body.
1116
1117The message may contain variable data in the form of
1118variable references. A @dfn{variable} is an entity that holds
1119some data describing the event that occurred. Meta-variables
1120are referenced using the following construct:
1121
1122@smallexample
1123$@{@var{name}@}
1124@end smallexample
1125
1126@noindent
1127where @var{name} is the name of the variable. Before actually sending
1128the message, each occurrence of this construct is removed from the
1129text and replaced by the actual value of the referenced variable.
1130For example, the variables @samp{component} and @samp{retcode} expand
1131to the name of the exited component and its exit code, correspondingly.
1132Supposing that @samp{component} is @samp{ftpd} and @samp{retcode} is
113376, the following fragment:
1134
1135@smallexample
1136Subject: $@{component@} exited with code $@{retcode@}
1137@end smallexample
1138
1139@noindent
1140will become:
1141
1142@smallexample
1143Subject: ftpd exited with code 76
1144@end smallexample
1145
1146The table below lists all available variables and their expansions:
1147
1148@float Table, notification-variables
1149@caption{Notification Variables}
1150@multitable @columnfractions 0.5 0.5
1151@headitem Variable @tab Expansion
1152@item canonical-program-name @tab @samp{pies}
1153@item program-name @tab Program name of the @command{pies} binary.
1154@item package @tab Package name (@samp{Pies}).
1155@item version @tab Package version (@value{VERSION}).
1156@item component @tab Name of the terminated component.
1157@item termination @tab Termination cause (see below).
1158@item retcode @tab Component exit code (or signal number, if exited
1159on signal), in decimal.
1160@end multitable
1161@end float
1162
1163The @samp{termination} variable is set so as to facilitate its use
1164with the @samp{retcode} variable. Namely, its value is @samp{exited
1165with}, if the component exited and @samp{terminated on signal}, if it
1166terminated on a signal. Thus, using
1167
1168@smallexample
1169$@{termination@} $@{retcode@}
1170@end smallexample
1171
1172@noindent
1173results in a correct English sentence. This message, however, cannot
1174be properly internationalized. This will be fixed in the future
1175versions.
1176
1177If @code{message} statement is not given, the following default
1178message is used instead:
1179
1180@smallexample
1181From: <>
1182X-Agent: $@{canonical-program-name@} ($@{package@} $@{version@})
1183Subject: Component $@{component@} $@{termination@} $@{retcode@}.
1184
1185@end smallexample
1186@end deffn
1187
1188@cindex mailer
1189@cindex @command{sendmail}
1190 Notification messages are sent using external program, called
1191@dfn{mailer}. By default it is @command{/usr/sbin/sendmail}. You can
1192change it using the following configuration statement:
1193
1194@deffn {Config} mailer-program @var{prog}
1195Use @var{prog} as a mailer program. The mailer must meet the
1196following requirements:
1197
1198@enumerate 1
1199@item It must read the message from its standard input.
1200@item It must treat the non-optional arguments in its command line as
1201recipient addresses.
1202@end enumerate
1203
1204For example, the following statement instructs @command{pies} to use
1205@command{exim} as a mailer:
1206
1207@smallexample
1208mailer-program /usr/sbin/exim;
1209@end smallexample
1210
1211@end deffn
1212
1213By default, the mailer program is invoked as follows:
1214
1215@smallexample
1216/usr/sbin/sendmail -oi -t @var{rcpts}
1217@end smallexample
1218
1219@noindent
1220where @var{rcpts} is a whitespace-separated list of addresses supplied
1221in the @samp{notify} statement.
1222
1223The mailer command may be altered using @samp{mailer-command-line} statement:
1224
1225@deffn {Config} mailer-command-line @var{string}
1226Set mailer command line. Notice, that @var{string} must include the
1227command name as well. The @samp{mailer-program} statement supplies
1228the full name of the binary which will be executed, while the first word
1229from the @samp{mailer-command-line} argument gives the string it
1230receives as @samp{argv[0]}.
1231
1232 The example below shows how to use this statement to alter the
1233envelope sender address:
1234
1235@smallexample
1236mailer-command-line "sendmail -f root@@domain.com -oi -t";
1237@end smallexample
1238@end deffn
1239
1094@node ACL 1240@node ACL
1095@section Access Control Lists 1241@section Access Control Lists
1096@cindex @acronym{ACL} 1242@cindex @acronym{ACL}
@@ -1103,49 +1249,63 @@ An @acronym{ACL} is defined using @code{acl} block statement:
1103 1249
1104@deffn {Config} acl 1250@deffn {Config} acl
1105@smallexample 1251@smallexample
1106acl @var{name} @{ 1252acl @{
1107 @var{definitions} 1253 @var{definitions}
1108@} 1254@}
1109@end smallexample 1255@end smallexample
1110@end deffn 1256@end deffn
1111 1257
1112The @var{name} parameter specifies a unique name for that 1258 This statement is allowed both in global context and within a
1113@acronym{ACL}. This name can be used by another configuration 1259@samp{component} block. If both are present, the global-level
1114statements to refer to that @acronym{ACL}. 1260@acronym{ACL} is consulted first, and if it allows access, the
1115 1261component @acronym{ACL} is consulted. As a result, access is
1116A part between the curly braces (denoted by @var{definitions} above), 1262granted only if both lists allow it.
1117is a list of @dfn{access statements}. There are two types of
1118such statements:
1119 1263
1120@deffn {Config: acl} allow @var{user-group} @var{sub-acl} @var{host-list} 1264 A @dfn{named @acronym{ACL}} is an access control list which is
1121Allow access to resource. 1265assigned its own name. Named @acronym{ACL}s are defined using
1122@end deffn 1266the @samp{defacl} statement:
1123 1267
1124@deffn {Config: acl} deny @var{user-group} @var{sub-acl} @var{host-list} 1268@deffn {Config} defacl @var{name}
1125Deny access to resource. 1269@smallexample
1270defacl @var{name} @{
1271 @var{definitions}
1272@}
1273@end smallexample
1274
1275 The @var{name} parameter specifies a unique name for that
1276@acronym{ACL}. Named @acronym{ACL}s are applied only if
1277referenced from another @acronym{ACL} (either global or a
1278per-component one, or any named @acronym{ACL}, referenced
1279from these). @xref{acl-ref, ACL references}, below.
1126@end deffn 1280@end deffn
1127 1281
1128All parts of an access statement are optional, but at least one 1282 In both forms, the part between the curly braces (denoted by
1129of them must be present. 1283@var{definitions}), is a list of @dfn{access control statements}.
1284There are two types of such statements:
1130 1285
1131The @var{user-group} part specifies which users match this entry. 1286@deffn {Config: acl} allow [@var{user-group}] @var{sub-acl} @var{host-list}
1132Allowed values are the following: 1287@deffnx {Config: acl} allow any
1133 1288Allow access to the component.
1134@table @code 1289@end deffn
1135@kwindex all 1290@ignore
1136@item all 1291@deffn {Config: defacl} allow [@var{user-group}] @var{sub-acl} @var{host-list}
1137All users. 1292@end deffn
1293@end ignore
1138 1294
1139@kwindex authenticated 1295@deffn {Config: acl} deny [@var{user-group}] @var{sub-acl} @var{host-list}
1140@item authenticated 1296@deffnx {Config: acl} deny any
1141Only authenticated users. 1297Deny access to the component.
1298@end deffn
1299@ignore
1300@deffn {Config: defacl} deny [@var{user-group}] @var{sub-acl} @var{host-list}
1301@end deffn
1302@end ignore
1142 1303
1143@kwindex group 1304All parts of an access statement are optional, but at least one
1144@item group @var{group-list} 1305of them must be present. The @var{user-group} part is reserved for
1145Authenticated users which are members of at least one of groups listed in 1306future use and is described in more detail in @ref{User-Group ACLs}.
1146@var{group-list}.
1147@end table
1148 1307
1308@anchor{acl-ref}
1149The @var{sub-acl} part, if present, allows to branch to another 1309The @var{sub-acl} part, if present, allows to branch to another
1150@acronym{ACL}. The syntax of this group is: 1310@acronym{ACL}. The syntax of this group is:
1151 1311
@@ -1154,9 +1314,10 @@ acl @var{name}
1154@end smallexample 1314@end smallexample
1155 1315
1156@noindent 1316@noindent
1157where @var{name} is the name of a previously defined @acronym{ACL}. 1317where @var{name} is the name of @acronym{ACL} defined previously in
1318@samp{defacl} statement.
1158 1319
1159Finally, the @var{host-list} group allows to match client addresses. 1320The @var{host-list} group allows to match client addresses.
1160It consists of a @code{from} keyword followed by a list of 1321It consists of a @code{from} keyword followed by a list of
1161@dfn{address specifiers}. Allowed address specifiers are: 1322@dfn{address specifiers}. Allowed address specifiers are:
1162 1323
@@ -1167,7 +1328,6 @@ The latter may be given either as an @acronym{IP}
1167address or as a host name, in which case it will be resolved and the 1328address or as a host name, in which case it will be resolved and the
1168first of its @acronym{IP} addresses will be used. 1329first of its @acronym{IP} addresses will be used.
1169 1330
1170
1171@item @var{addr}/@var{netlen} 1331@item @var{addr}/@var{netlen}
1172Matches if first @var{netlen} bits from the client @acronym{IP} 1332Matches if first @var{netlen} bits from the client @acronym{IP}
1173address equal to @var{addr}. The network mask length, @var{netlen} 1333address equal to @var{addr}. The network mask length, @var{netlen}
@@ -1185,41 +1345,40 @@ Matches if connection was received from a @acronym{UNIX} socket
1185@var{filename}, which must be given as an absolute file name. 1345@var{filename}, which must be given as an absolute file name.
1186@end table 1346@end table
1187 1347
1348@anchor{acl-any}.
1349The special form @samp{allow any} means to allow access
1350unconditionally. Similarly, @samp{deny any}, denies access
1351unconditionally. Normally, these forms appear as the last
1352statements in an @acronym{ACL} definition.
1353
1188To summarize, the syntax of an access statement is: 1354To summarize, the syntax of an access statement is:
1189 1355
1190@smallexample 1356@smallexample
1191allow|deny [all|authenticated|group @var{group-list}] 1357allow|deny [acl @var{name}] [from @var{addr-list}]
1192 [acl @var{name}] [from @var{addr-list}]
1193@end smallexample 1358@end smallexample
1194 1359
1195@noindent 1360@noindent
1196where square brackets denote optional parts and vertical bar means 1361where square brackets denote optional parts and vertical bar means
1197@samp{one of}. 1362@samp{one of}.
1198 1363
1199When an @acronym{ACL} is applied to a particular object, its entries 1364When an @acronym{ACL} is checked, its entries are tried in turn until
1200are tried in turn until one of them matches, or the end of the list is 1365one of them matches, or the end of the list is reached. If a matched
1201reached. If a matched entry is found, its command verb, @code{allow} 1366entry is found, its command verb, @code{allow} or @code{deny}, defines
1202or @code{deny}, defines the result of @acronym{ACL} match. If the end 1367the result of @acronym{ACL} match. If the end of list is reached,
1203of list is reached, the result is @samp{allow}, unless explicitly 1368the result is @samp{allow}, unless explicitly specified otherwise
1204specified otherwise. 1369(using the @pxref{acl-any, ``any'' form}).
1205 1370
1206@FIXME{Trim that example:} 1371For example, the following @acronym{ACL} allows access for anybody
1207For example, the following statement defines an @acronym{ACL} named 1372coming from networks @samp{192.168.10.0/24} and @samp{192.168.100.0/24},
1208@samp{common}, that allows access for any user connected via local 1373or any connection that matches the named @acronym{ACL} @samp{my-nets}
1209@acronym{UNIX} socket @file{/tmp/dicod.sock} or coming from a local 1374(which should have been defined before this definition). Access is
1210network @samp{192.168.10.0/24}. Any authenticated users are allowed, 1375denied for anybody else:
1211provided that they are allowed by another @acronym{ACL} @samp{my-nets}
1212(which should have been defined before this definition). Users
1213coming from the network @samp{10.10.0.0/24} are allowed if they
1214authenticate themselves and are members of groups @samp{pies} or
1215@samp{users}. Access is denied for anybody else:
1216 1376
1217@smallexample 1377@smallexample
1218@group 1378@group
1219acl common @{ 1379acl @{
1220 allow all from ("/tmp/pies.sock", "192.168.10.0/24"); 1380 allow from (192.168.10.0/24, 192.168.100.0/24);
1221 allow authenticated acl "my-nets"; 1381 allow acl "my-nets";
1222 allow group ("pies", "users") from "10.10.0.0/24";
1223 deny all; 1382 deny all;
1224@} 1383@}
1225@end group 1384@end group
@@ -1352,18 +1511,19 @@ suit your needs:
1352 1511
1353@deffn {Config} pidfile @var{file} 1512@deffn {Config} pidfile @var{file}
1354Write PID of the master @command{pies} process to @var{file}. By 1513Write PID of the master @command{pies} process to @var{file}. By
1355default, master PID is stored in @file{@var{statedir}/pies.pid} 1514default, master PID is stored in @file{@var{localstatedir}/pies.pid},
1356(@FIXME-pxref{statedir}). 1515where @var{localstatedir} is the @dfn{local state directory}, defined
1516at compile time (usually, it is @file{/usr/local/var} or @file{/usr/var}).
1357@end deffn 1517@end deffn
1358 1518
1359@deffn {Config} control-file @var{file} 1519@deffn {Config} control-file @var{file}
1360Set file name of the @command{pies} control file. Default is 1520Set file name of the @command{pies} control file. Default is
1361@file{@var{statedir}/pies.ctl} 1521@file{@var{localstatedir}/pies.ctl}
1362@end deffn 1522@end deffn
1363 1523
1364@deffn {Config} stat-file @var{file} 1524@deffn {Config} stat-file @var{file}
1365Set file name of the statistics output file. Default is 1525Set file name of the statistics output file. Default is
1366@file{@var{statedir}/pies.stat}. 1526@file{@var{localstatedir}/pies.stat}.
1367@end deffn 1527@end deffn
1368 1528
1369 Normally, @command{pies} must be run with root privileges. If, 1529 Normally, @command{pies} must be run with root privileges. If,
@@ -1513,7 +1673,7 @@ acl @{
1513 deny from any; 1673 deny from any;
1514@} 1674@}
1515 1675
1516debug "<trace4"; 1676debug 3;
1517 1677
1518component ftp @{ 1678component ftp @{
1519 mode inetd; 1679 mode inetd;
@@ -1752,6 +1912,10 @@ line options used).
1752@item Conditions under which the bug appears. 1912@item Conditions under which the bug appears.
1753@end itemize 1913@end itemize
1754 1914
1915@node User-Group ACLs
1916@appendix User-Group ACLs
1917@include usr-acl.texi
1918
1755@node Copying This Manual 1919@node Copying This Manual
1756@appendix GNU Free Documentation License 1920@appendix GNU Free Documentation License
1757@include fdl.texi 1921@include fdl.texi
diff --git a/doc/usr-acl.texi b/doc/usr-acl.texi
new file mode 100644
index 0000000..1fd69f5
--- /dev/null
+++ b/doc/usr-acl.texi
@@ -0,0 +1,48 @@
1@c This is part of the Pies manual.
2@c Copyright (C) 2009 Sergey Poznyakoff
3@c This file is distributed under GFDL 1.1 or any later version
4@c published by the Free Software Foundation.
5
6 This appendix describes the @samp{user-group} extension for
7@command{Pies} @acronym{ACL}s. This extension is reserved for
8the future use.
9
10The @var{user-group} @acronym{ACL} statement specifies which
11users match this entry. Allowed values are the following:
12
13@table @code
14@kwindex all
15@item all
16All users.
17
18@kwindex authenticated
19@item authenticated
20Only authenticated users.
21
22@kwindex group
23@item group @var{group-list}
24Authenticated users which are members of at least one of groups listed in
25@var{group-list}.
26@end table
27
28For example, the following statement defines an @acronym{ACL}
29which allows access for any user connected via local @acronym{UNIX}
30socket @file{/tmp/dicod.sock} or coming from a local network
31@samp{192.168.10.0/24}. Any authenticated users are allowed, provided
32that they are allowed by another @acronym{ACL} @samp{my-nets} (which
33should have been defined before this definition). Users coming from
34the network @samp{10.10.0.0/24} are allowed if they authenticate
35themselves and are members of groups @samp{pies} or @samp{users}.
36Access is denied for anybody else:
37
38@smallexample
39@group
40acl @{
41 allow all from ("/tmp/pies.sock", "192.168.10.0/24");
42 allow authenticated acl "my-nets";
43 allow group ("pies", "users") from "10.10.0.0/24";
44 deny all;
45@}
46@end group
47@end smallexample
48

Return to:

Send suggestions and report system problems to the System administrator.