aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-10 00:05:13 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2009-12-10 00:09:44 +0200
commite668360caeb54d64b67130f6f4f674d8738a909a (patch)
treea361085cf1fafee2afa4a89a18b2f4815736a5cd /doc
parent41c55a1a93840363c996fc9aae54329dadcf0a86 (diff)
downloadpies-e668360caeb54d64b67130f6f4f674d8738a909a.tar.gz
pies-e668360caeb54d64b67130f6f4f674d8738a909a.tar.bz2
Update
* doc/macros.texi (xprindex) (example-output, mtasimopt): Remove (RFC): New macro. * doc/pies.texi: Document inetd-style components. * doc/Makefile.am (fix-sentence-spacing): Fix rule. * src/progman.c (progman_lookup_tcpmux): Use case-insensitive comparison, as required by RFC.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am2
-rw-r--r--doc/macros.texi17
-rw-r--r--doc/pies.texi262
3 files changed, 249 insertions, 32 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 73bd72a..21618f0 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -144,7 +144,7 @@ fix-sentence-spacing:
144 do \ 144 do \
145 if grep -q '\. [@A-Z]' $$file; then \ 145 if grep -q '\. [@A-Z]' $$file; then \
146 mv $$file $${file}~; \ 146 mv $$file $${file}~; \
147 sed -r 's/\. ([@A-Z])/. \1/g' $${file}~ > $$file; \ 147 sed -r -f fix-sentence-spacing.sed $${file}~ > $$file; \
148 fi; \ 148 fi; \
149 done 149 done
150 150
diff --git a/doc/macros.texi b/doc/macros.texi
index a26ad0c..bc9fd0a 100644
--- a/doc/macros.texi
+++ b/doc/macros.texi
@@ -10,21 +10,8 @@
10@xopindex{\option\, summary} 10@xopindex{\option\, summary}
11@end macro 11@end macro
12 12
13@macro xprindex{option} 13@macro RFC{number}
14@ifclear ANCHOR-PR-\option\ 14@uref{http://tools.ietf.org/html/rfc\number\, RFC \number\}
15@set ANCHOR-PR-\option\ 1
16@anchor{pragma \option\}
17@end ifclear
18@end macro
19
20@macro example-output{text}
21@smallexample
22\text\
23@end smallexample
24@end macro
25
26@macro mtasimopt{option,text}
27@mtindex \option\, --\option\, @r{@command{mtasim} option, \text\}
28@end macro 15@end macro
29 16
30 17
diff --git a/doc/pies.texi b/doc/pies.texi
index e21ea62..d5e9d02 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -126,6 +126,12 @@ Component Statement
126* Meta1-Style Components:: 126* Meta1-Style Components::
127* Component Syntax Summary:: 127* Component Syntax Summary::
128 128
129Inetd-Style Components
130
131* builtin:: Built-in Inetd Services
132* TCPMUX:: TCPMUX Services
133* sockenv:: Socket Environment Variables
134
129Global Configuration 135Global Configuration
130 136
131* Less Useful Statements:: 137* Less Useful Statements::
@@ -632,6 +638,7 @@ statement. Its value will be available to the program as
632@code{argv[0]}. 638@code{argv[0]}.
633@end deffn 639@end deffn
634 640
641@anchor{flags}
635@deffn {Config: component} flags (@var{flag-list}) 642@deffn {Config: component} flags (@var{flag-list})
636Define flags for this component. The @var{flag-list} is a 643Define flags for this component. The @var{flag-list} is a
637comma-separated list of flags. Valid flags are: 644comma-separated list of flags. Valid flags are:
@@ -662,7 +669,7 @@ This is an internal inetd component. @xref{builtin}.
662 669
663@item sockenv 670@item sockenv
664This inetd component wants socket description variables in its 671This inetd component wants socket description variables in its
665environment. @FIXME-xref{sockenv}. 672environment. @xref{sockenv}.
666 673
667@item resolve 674@item resolve
668When used with @samp{sockenv}, the @env{LOCALHOST} and 675When used with @samp{sockenv}, the @env{LOCALHOST} and
@@ -1075,6 +1082,7 @@ provided that @code{chdir} statement is used for this component
1075@end table 1082@end table
1076@end deffn 1083@end deffn
1077 1084
1085@anchor{socket-type}
1078@deffn {Config: component} socket-type @var{type} 1086@deffn {Config: component} socket-type @var{type}
1079Sets the socket type. Allowed values for @var{type} are: 1087Sets the socket type. Allowed values for @var{type} are:
1080@samp{stream}, @samp{dgram}, @samp{raw}, @samp{rdm}, 1088@samp{stream}, @samp{dgram}, @samp{raw}, @samp{rdm},
@@ -1100,26 +1108,227 @@ opened connections.
1100@menu 1108@menu
1101* builtin:: Built-in Inetd Services 1109* builtin:: Built-in Inetd Services
1102* TCPMUX:: TCPMUX Services 1110* TCPMUX:: TCPMUX Services
1111* sockenv:: Socket Environment Variables
1103@end menu 1112@end menu
1104 1113
1105@node builtin 1114@node builtin
1106@subsubsection Built-in Inetd Services 1115@subsubsection Built-in Inetd Services
1107@cindex builtin services 1116@cindex builtin services
1108@WRITEME 1117@cindex internal services
1118@dfn{Built-in} or @dfn{internal} services are such inetd-style
1119components that are supported internally by @command{pies} and do not
1120require external programs. In @command{pies} version @value{VERSION}
1121those are:
1122
1123@table @asis
1124@cindex echo
1125@item echo
1126Send back any received data. Defined in @RFC{862}.
1127@cindex discard
1128@item discard
1129Read the data and discard them. Defined in @RFC{863}.
1130@cindex time
1131@item time
1132Return a machine readable date and time as seconds since the Epoch.
1133Defined in @RFC{868}.
1134@cindex daytime
1135@item daytime
1136Return current date and time in human-readable format. Defined in
1137@RFC{867}.
1138@cindex chargen
1139@item chargen
1140Send a continuous stream of ASCII printable characters without regard
1141to the input. Defined in @RFC{864}
1142@cindex qotd
1143@item qotd
1144Send a @samp{quotation of the day} text without regard
1145to the input. Defined in @RFC{865}.
1146@cindex tcpmux
1147@item tcpmux
1148TCP Port Service Multiplexer. Defined in @RFC{1078}.
1149@end table
1150
1151@cindex @code{internal} flag
1152A definition of a built-in service component must
1153have the @code{internal} flag (@pxref{flags}). It may not have
1154@code{command} or @code{program} statements, as built-in services do
1155not need external programs. Instead, it must have a @dfn{service}
1156declaration:
1157
1158@deffn {Config: component} service @var{name}
1159Set the built-in service name. Its argument is one of the keywords
1160listed in the above table.
1161@end deffn
1162
1163 For example, the following component declaration defines a standard
1164TCP-based echo service:
1165
1166@smallexample
1167@group
1168component echo @{
1169 socket "inet://0.0.0.0:echo";
1170 service echo;
1171 flags internal;
1172@}
1173@end group
1174@end smallexample
1175
1176 It corresponds to the following @file{inetd.conf} line:
1177
1178@smallexample
1179echo stream tcp nowait root internal
1180@end smallexample
1181
1182 Another built-in services are defined in the same manner, replacing
1183@samp{echo} in the @code{service} field with the corresponding service
1184name.
1185
1186 The @samp{qotd} service reads the contents of the @dfn{qotd file}
1187and sends it back to the client. By default the @samp{qotd} file
1188is located in the local state directory and named
1189@file{@var{instance}.qotd} (where @var{instance} is the name of the
1190@command{pies} instance, @FIXME-pxref{instances}). This default location
1191can be changed using the following statement:
1192
1193@deffn {Config} qotd-file @var{file-name}
1194Set the name of the @samp{quotation-of-the-day} file.
1195@end deffn
1196
1197 The text read from the @samp{qotd} file is preprocessed, by
1198replacing each @acronym{LF} character (@acronym{ASCII} 10) with two
1199characters: @acronym{CR} (@acronym{ASCII} 13) followed by
1200@acronym{LF}. The resulting text is truncated to 512 characters.
1201
1202 The use of @samp{tcpmux} services is covered below.
1109 1203
1110@node TCPMUX 1204@node TCPMUX
1111@subsubsection TCPMUX Services 1205@subsubsection TCPMUX Services
1112@cindex TCPMUX 1206@cindex TCPMUX
1113@UNREVISED 1207
1208 TCPMUX allows to use multiple services on a single well-known TCP
1209port using a service name instead of a well-known number. It is
1210defined in @RFC{1078}. The protocol operation is as follows.
1211The @dfn{master} TCPMUX component listens on a certain TCP port
1212(usually on port 1) for incoming requests. After connecting to the
1213master, the client sends the name of the service it wants, followed
1214by a carriage-return line-feed (@acronym{CRLF}). @command{Pies}
1215looks up this name in the list of services handled by the master
1216(@dfn{subordinate services}) and reports with @samp{+} or @samp{-}
1217followed by optional text and terminated with the @acronym{CRLF},
1218depending on whether such service name is found or not. If the reply
1219was @samp{+}, @command{pies} then starts the requested component.
1220Otherwise, it closes the connection.
1221
1222 TCPMUX service names are case-insensitive. The special service
1223@samp{help} is always defined; it outputs a list of all the
1224subordinate services, one name per line, and closes the connection.
1225
1226 The master TCPMUX service is declared as a usual built-in service,
1227e.g.:
1228
1229@smallexample
1230component tcpmux-master @{
1231 socket "inet://0.0.0.0:1";
1232 service tcpmux;
1233 flags internal;
1234@}
1235@end smallexample
1236
1237 Any number of subordinate services may be defined for each master.
1238A subordinate server component definition must contain at least the
1239following statements:
1114 1240
1115@deffn {Config: component} service @var{name} 1241@deffn {Config: component} service @var{name}
1116Sets the name of the service for TCPMUX sub-services. 1242Sets the name of the subordinate service. The @var{name} will be compared
1243with the first input line from the client.
1117@end deffn 1244@end deffn
1118 1245
1119@deffn {Config: component} tcpmux-master @var{name} 1246@deffn {Config: component} tcpmux-master @var{name}
1120Sets the name of the master TCPMUX service. 1247Sets the name of the master TCPMUX service.
1121@end deffn 1248@end deffn
1122 1249
1250@deffn {Config: component} flags @var{list}
1251The @code{flags} statement (@pxref{flags}) must contain at least one
1252of the following flags:
1253
1254@table @asis
1255@item tcpmux
1256A ``dedicated'' TCPMUX subordinate service. When invoked, it must
1257output the @samp{+ CRLF} response itself.
1258
1259@item tcpmuxplus
1260Simple service. Before starting it, @command{pies} will send the
1261@samp{+ CRLF} reply.
1262@end table
1263@end deffn
1264
1265@deffn {Config: component} command @var{command-line}
1266The command line for handling this service.
1267@end deffn
1268
1269 For example:
1270
1271@smallexample
1272component scp-to @{
1273 service scp-to;
1274 flags (tcpmuxplus, sockenv);
1275 tcpmux-master tcpmux;
1276 command "/usr/sbin/in.wydawca";
1277@}
1278@end smallexample
1279
1280@cindex ACL in TCPMUX services
1281 For TCPMUX services, access control lists are handled in the
1282following order. First, the global @acronym{ACL} is checked.
1283If it rejects the connection, no further checks are done. Then,
1284if the master TCPMUX service has an @acronym{ACL}, that @acronym{ACL}
1285is consulted. If it allows the connection, the subordinate is looked
1286up. If found, its @acronym{ACL} (if any) is consulted. Only if all
1287three @acronym{ACL}s allow the connection, is the service started.
1288
1289 A similar procedure applies for other resources, such as
1290@code{limits}, @code{umask}, @code{env}, @code{user}, @code{group}, etc.
1291
1292@node sockenv
1293@subsubsection Socket Environment Variables
1294@cindex socket environment variables
1295@kindex sockenv
1296 If the @samp{sockenv} flag is set (@pxref{flags, sockenv}), the
1297following environment variables are set prior to executing the
1298command:
1299
1300@table @env
1301@item PROTO
1302Protocol name.
1303
1304@item SOCKTYPE
1305Socket type. @xref{socket-type}, for a list of possible
1306values.
1307
1308@item LOCALIP
1309IP address of the server which is handling the connection.
1310
1311@item LOCALPORT
1312Local port number.
1313
1314@item LOCALHOST
1315Host name of the server. This variable is defined only if
1316the @samp{resolve} flag is set (@pxref{flags,resolve}).
1317
1318@item REMOTEIP
1319IP address of the remote party (client).
1320
1321@item REMOTEPORT
1322Port number on the remote side.
1323
1324@item REMOTEHOST
1325Host name of the client. This variable is defined only if
1326the @samp{resolve} flag is set (@pxref{flags,resolve}).
1327@end table
1328
1329 The variables whose names begin with @env{REMOTE} are defined only
1330for @acronym{TCP} connections.
1331
1123@node Meta1-Style Components 1332@node Meta1-Style Components
1124@subsection Meta1-Style Components 1333@subsection Meta1-Style Components
1125@cindex meta1-style components 1334@cindex meta1-style components
@@ -1157,28 +1366,50 @@ component @var{tag} @{
1157 # @xref{Component Statement, command}. 1366 # @xref{Component Statement, command}.
1158 command @var{string}; 1367 command @var{string};
1159 1368
1160 # @r{Disable this entry.}
1161 # @xref{Component Statement, disable}.
1162 disable @var{bool};
1163 # @r{Mark this entry as precious.}
1164 # @xref{Component Statement, precious}.
1165 precious @var{bool};
1166
1167 # @r{List of prerequisites.} 1369 # @r{List of prerequisites.}
1168 # @xref{Prerequisites}. 1370 # @xref{Prerequisites}.
1169 prerequisites (@var{compnames}); 1371 prerequisites (@var{compnames});
1170 # @r{List of components for which this one is a prerequisite.} 1372 # @r{List of components for which this one is a prerequisite.}
1171 # @xref{Prerequisites, dependents}. 1373 # @xref{Prerequisites, dependents}.
1172 dependents (@var{compnames}); 1374 dependents (@var{compnames});
1375
1376 # @r{List of flags.}
1377 # @xref{flags}.
1378 flags (@var{flags});
1173 1379
1174 # @r{Listen on the given url.} 1380 # @r{Listen on the given url.}
1175 # @xref{Inetd-Style Components}. 1381 # @xref{Inetd-Style Components}.
1176 socket @var{url}; 1382 socket @var{url};
1383
1384 # @r{Set socket type.}
1385 # @xref{Inetd-Style Components}.
1386 socket-type @samp{stream | dgram | raw | rdm | seqpacket};
1387
1388 # @r{Service name for built-in inetd component.}
1389 # @xref{builtin}.
1390 service @var{string};
1391
1392 # @r{Tag of master TCPMUX component, for subordinate components}.
1393 # @xref{TCPMUX}.
1394 tcpmux-master @var{string};
1177 1395
1178 # @r{Pass fd through this socket.} 1396 # @r{Pass fd through this socket.}
1179 # @xref{Meta1-Style Components}. 1397 # @xref{Meta1-Style Components}.
1180 pass-fd-socket @var{soket-name}; 1398 pass-fd-socket @var{soket-name};
1181 1399 # @r{Wait @var{number} of seconds for pass-fd socket to become available.}
1400 # @xref{Actions Before Startup, pass-fd-timeout}.
1401 pass-fd-timeout @var{number};
1402
1403 # @r{Maximum number of running instances.}
1404 # @xref{Resources, max-instances}.
1405 # @xref{Inetd-Style Components, max-instances}.
1406 max-instances @var{number};
1407
1408 # @r{Maximum number of times an inetd component can be invoked in}
1409 # @r{one minute.}
1410 # @xref{Inetd-Style Components, max-rate}.
1411 max-rate @var{number};
1412
1182 # @r{ACL for this component.} 1413 # @r{ACL for this component.}
1183 # @xref{ACL Statement, ACL Statement,, mailutils, GNU Mailutils Manual}. 1414 # @xref{ACL Statement, ACL Statement,, mailutils, GNU Mailutils Manual}.
1184 acl @{ @dots{} @} 1415 acl @{ @dots{} @}
@@ -1222,9 +1453,6 @@ component @var{tag} @{
1222 # @r{Remove @var{file-name} before starting the component.} 1453 # @r{Remove @var{file-name} before starting the component.}
1223 # @xref{Actions Before Startup, remove-file}. 1454 # @xref{Actions Before Startup, remove-file}.
1224 remove-file @var{file-name}; 1455 remove-file @var{file-name};
1225 # @r{Wait @var{number} of seconds for pass-fd socket to become available.}
1226 # @xref{Actions Before Startup, pass-fd-timeout}.
1227 pass-fd-timeout @var{number};
1228 1456
1229 # @r{Actions:} 1457 # @r{Actions:}
1230 # @xref{Exit Actions}. 1458 # @xref{Exit Actions}.
@@ -1235,6 +1463,8 @@ component @var{tag} @{
1235 notify @var{email-string}; 1463 notify @var{email-string};
1236 # @r{Notification message text (with headers).} 1464 # @r{Notification message text (with headers).}
1237 message @var{string}; 1465 message @var{string};
1466 # @r{Execute this command.}
1467 exec @var{command}
1238 @} 1468 @}
1239@} 1469@}
1240@end smallexample 1470@end smallexample
@@ -1395,7 +1625,7 @@ mailer-command-line "sendmail -f root@@domain.com -oi -t";
1395@cindex @acronym{ACL} 1625@cindex @acronym{ACL}
1396@cindex access control lists 1626@cindex access control lists
1397@dfn{Access control lists}, or @acronym{ACL}s for short, are lists of 1627@dfn{Access control lists}, or @acronym{ACL}s for short, are lists of
1398permissions that control access to @samp{inetd}, @samp{access} and 1628permissions that control access to @samp{inetd}, @samp{accept} and
1399@samp{meta1}-style components. 1629@samp{meta1}-style components.
1400 1630
1401An @acronym{ACL} is defined using @code{acl} block statement: 1631An @acronym{ACL} is defined using @code{acl} block statement:

Return to:

Send suggestions and report system problems to the System administrator.