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
@@ -146,3 +146,3 @@ fix-sentence-spacing:
mv $$file $${file}~; \
- sed -r 's/\. ([@A-Z])/. \1/g' $${file}~ > $$file; \
+ sed -r -f fix-sentence-spacing.sed $${file}~ > $$file; \
fi; \
diff --git a/doc/macros.texi b/doc/macros.texi
index a26ad0c..bc9fd0a 100644
--- a/doc/macros.texi
+++ b/doc/macros.texi
@@ -12,17 +12,4 @@
-@macro xprindex{option}
-@ifclear ANCHOR-PR-\option\
-@set ANCHOR-PR-\option\ 1
-@anchor{pragma \option\}
-@end ifclear
-@end macro
-
-@macro example-output{text}
-@smallexample
-\text\
-@end smallexample
-@end macro
-
-@macro mtasimopt{option,text}
-@mtindex \option\, --\option\, @r{@command{mtasim} option, \text\}
+@macro RFC{number}
+@uref{http://tools.ietf.org/html/rfc\number\, RFC \number\}
@end macro
diff --git a/doc/pies.texi b/doc/pies.texi
index e21ea62..d5e9d02 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -128,2 +128,8 @@ Component Statement
+Inetd-Style Components
+
+* builtin:: Built-in Inetd Services
+* TCPMUX:: TCPMUX Services
+* sockenv:: Socket Environment Variables
+
Global Configuration
@@ -634,2 +640,3 @@ statement. Its value will be available to the program as
+@anchor{flags}
@deffn {Config: component} flags (@var{flag-list})
@@ -664,3 +671,3 @@ This is an internal inetd component. @xref{builtin}.
This inetd component wants socket description variables in its
-environment. @FIXME-xref{sockenv}.
+environment. @xref{sockenv}.
@@ -1077,2 +1084,3 @@ provided that @code{chdir} statement is used for this component
+@anchor{socket-type}
@deffn {Config: component} socket-type @var{type}
@@ -1102,2 +1110,3 @@ opened connections.
* TCPMUX:: TCPMUX Services
+* sockenv:: Socket Environment Variables
@end menu
@@ -1107,3 +1116,88 @@ opened connections.
@cindex builtin services
-@WRITEME
+@cindex internal services
+@dfn{Built-in} or @dfn{internal} services are such inetd-style
+components that are supported internally by @command{pies} and do not
+require external programs. In @command{pies} version @value{VERSION}
+those are:
+
+@table @asis
+@cindex echo
+@item echo
+Send back any received data. Defined in @RFC{862}.
+@cindex discard
+@item discard
+Read the data and discard them. Defined in @RFC{863}.
+@cindex time
+@item time
+Return a machine readable date and time as seconds since the Epoch.
+Defined in @RFC{868}.
+@cindex daytime
+@item daytime
+Return current date and time in human-readable format. Defined in
+@RFC{867}.
+@cindex chargen
+@item chargen
+Send a continuous stream of ASCII printable characters without regard
+to the input. Defined in @RFC{864}
+@cindex qotd
+@item qotd
+Send a @samp{quotation of the day} text without regard
+to the input. Defined in @RFC{865}.
+@cindex tcpmux
+@item tcpmux
+TCP Port Service Multiplexer. Defined in @RFC{1078}.
+@end table
+
+@cindex @code{internal} flag
+A definition of a built-in service component must
+have the @code{internal} flag (@pxref{flags}). It may not have
+@code{command} or @code{program} statements, as built-in services do
+not need external programs. Instead, it must have a @dfn{service}
+declaration:
+
+@deffn {Config: component} service @var{name}
+Set the built-in service name. Its argument is one of the keywords
+listed in the above table.
+@end deffn
+
+ For example, the following component declaration defines a standard
+TCP-based echo service:
+
+@smallexample
+@group
+component echo @{
+ socket "inet://0.0.0.0:echo";
+ service echo;
+ flags internal;
+@}
+@end group
+@end smallexample
+
+ It corresponds to the following @file{inetd.conf} line:
+
+@smallexample
+echo stream tcp nowait root internal
+@end smallexample
+
+ Another built-in services are defined in the same manner, replacing
+@samp{echo} in the @code{service} field with the corresponding service
+name.
+
+ The @samp{qotd} service reads the contents of the @dfn{qotd file}
+and sends it back to the client. By default the @samp{qotd} file
+is located in the local state directory and named
+@file{@var{instance}.qotd} (where @var{instance} is the name of the
+@command{pies} instance, @FIXME-pxref{instances}). This default location
+can be changed using the following statement:
+
+@deffn {Config} qotd-file @var{file-name}
+Set the name of the @samp{quotation-of-the-day} file.
+@end deffn
+
+ The text read from the @samp{qotd} file is preprocessed, by
+replacing each @acronym{LF} character (@acronym{ASCII} 10) with two
+characters: @acronym{CR} (@acronym{ASCII} 13) followed by
+@acronym{LF}. The resulting text is truncated to 512 characters.
+
+ The use of @samp{tcpmux} services is covered below.
@@ -1112,6 +1206,39 @@ opened connections.
@cindex TCPMUX
-@UNREVISED
+
+ TCPMUX allows to use multiple services on a single well-known TCP
+port using a service name instead of a well-known number. It is
+defined in @RFC{1078}. The protocol operation is as follows.
+The @dfn{master} TCPMUX component listens on a certain TCP port
+(usually on port 1) for incoming requests. After connecting to the
+master, the client sends the name of the service it wants, followed
+by a carriage-return line-feed (@acronym{CRLF}). @command{Pies}
+looks up this name in the list of services handled by the master
+(@dfn{subordinate services}) and reports with @samp{+} or @samp{-}
+followed by optional text and terminated with the @acronym{CRLF},
+depending on whether such service name is found or not. If the reply
+was @samp{+}, @command{pies} then starts the requested component.
+Otherwise, it closes the connection.
+
+ TCPMUX service names are case-insensitive. The special service
+@samp{help} is always defined; it outputs a list of all the
+subordinate services, one name per line, and closes the connection.
+
+ The master TCPMUX service is declared as a usual built-in service,
+e.g.:
+
+@smallexample
+component tcpmux-master @{
+ socket "inet://0.0.0.0:1";
+ service tcpmux;
+ flags internal;
+@}
+@end smallexample
+
+ Any number of subordinate services may be defined for each master.
+A subordinate server component definition must contain at least the
+following statements:
@deffn {Config: component} service @var{name}
-Sets the name of the service for TCPMUX sub-services.
+Sets the name of the subordinate service. The @var{name} will be compared
+with the first input line from the client.
@end deffn
@@ -1122,2 +1249,84 @@ Sets the name of the master TCPMUX service.
+@deffn {Config: component} flags @var{list}
+The @code{flags} statement (@pxref{flags}) must contain at least one
+of the following flags:
+
+@table @asis
+@item tcpmux
+A ``dedicated'' TCPMUX subordinate service. When invoked, it must
+output the @samp{+ CRLF} response itself.
+
+@item tcpmuxplus
+Simple service. Before starting it, @command{pies} will send the
+@samp{+ CRLF} reply.
+@end table
+@end deffn
+
+@deffn {Config: component} command @var{command-line}
+The command line for handling this service.
+@end deffn
+
+ For example:
+
+@smallexample
+component scp-to @{
+ service scp-to;
+ flags (tcpmuxplus, sockenv);
+ tcpmux-master tcpmux;
+ command "/usr/sbin/in.wydawca";
+@}
+@end smallexample
+
+@cindex ACL in TCPMUX services
+ For TCPMUX services, access control lists are handled in the
+following order. First, the global @acronym{ACL} is checked.
+If it rejects the connection, no further checks are done. Then,
+if the master TCPMUX service has an @acronym{ACL}, that @acronym{ACL}
+is consulted. If it allows the connection, the subordinate is looked
+up. If found, its @acronym{ACL} (if any) is consulted. Only if all
+three @acronym{ACL}s allow the connection, is the service started.
+
+ A similar procedure applies for other resources, such as
+@code{limits}, @code{umask}, @code{env}, @code{user}, @code{group}, etc.
+
+@node sockenv
+@subsubsection Socket Environment Variables
+@cindex socket environment variables
+@kindex sockenv
+ If the @samp{sockenv} flag is set (@pxref{flags, sockenv}), the
+following environment variables are set prior to executing the
+command:
+
+@table @env
+@item PROTO
+Protocol name.
+
+@item SOCKTYPE
+Socket type. @xref{socket-type}, for a list of possible
+values.
+
+@item LOCALIP
+IP address of the server which is handling the connection.
+
+@item LOCALPORT
+Local port number.
+
+@item LOCALHOST
+Host name of the server. This variable is defined only if
+the @samp{resolve} flag is set (@pxref{flags,resolve}).
+
+@item REMOTEIP
+IP address of the remote party (client).
+
+@item REMOTEPORT
+Port number on the remote side.
+
+@item REMOTEHOST
+Host name of the client. This variable is defined only if
+the @samp{resolve} flag is set (@pxref{flags,resolve}).
+@end table
+
+ The variables whose names begin with @env{REMOTE} are defined only
+for @acronym{TCP} connections.
+
@node Meta1-Style Components
@@ -1159,9 +1368,2 @@ component @var{tag} @{
- # @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.}
@@ -1172,2 +1374,6 @@ component @var{tag} @{
dependents (@var{compnames});
+
+ # @r{List of flags.}
+ # @xref{flags}.
+ flags (@var{flags});
@@ -1176,2 +1382,14 @@ component @var{tag} @{
socket @var{url};
+
+ # @r{Set socket type.}
+ # @xref{Inetd-Style Components}.
+ socket-type @samp{stream | dgram | raw | rdm | seqpacket};
+
+ # @r{Service name for built-in inetd component.}
+ # @xref{builtin}.
+ service @var{string};
+
+ # @r{Tag of master TCPMUX component, for subordinate components}.
+ # @xref{TCPMUX}.
+ tcpmux-master @var{string};
@@ -1180,3 +1398,16 @@ component @var{tag} @{
pass-fd-socket @var{soket-name};
-
+ # @r{Wait @var{number} of seconds for pass-fd socket to become available.}
+ # @xref{Actions Before Startup, pass-fd-timeout}.
+ pass-fd-timeout @var{number};
+
+ # @r{Maximum number of running instances.}
+ # @xref{Resources, max-instances}.
+ # @xref{Inetd-Style Components, max-instances}.
+ max-instances @var{number};
+
+ # @r{Maximum number of times an inetd component can be invoked in}
+ # @r{one minute.}
+ # @xref{Inetd-Style Components, max-rate}.
+ max-rate @var{number};
+
# @r{ACL for this component.}
@@ -1224,5 +1455,2 @@ component @var{tag} @{
remove-file @var{file-name};
- # @r{Wait @var{number} of seconds for pass-fd socket to become available.}
- # @xref{Actions Before Startup, pass-fd-timeout}.
- pass-fd-timeout @var{number};
@@ -1237,2 +1465,4 @@ component @var{tag} @{
message @var{string};
+ # @r{Execute this command.}
+ exec @var{command}
@}
@@ -1397,3 +1627,3 @@ mailer-command-line "sendmail -f root@@domain.com -oi -t";
@dfn{Access control lists}, or @acronym{ACL}s for short, are lists of
-permissions that control access to @samp{inetd}, @samp{access} and
+permissions that control access to @samp{inetd}, @samp{accept} and
@samp{meta1}-style components.

Return to:

Send suggestions and report system problems to the System administrator.