summaryrefslogtreecommitdiffabout
path: root/doc
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-09 22:05:13 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2009-12-09 22:09:44 (GMT)
commite668360caeb54d64b67130f6f4f674d8738a909a (patch) (side-by-side diff)
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') (more/less context) (ignore whitespace changes)
-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:
do \
if grep -q '\. [@A-Z]' $$file; then \
mv $$file $${file}~; \
- sed -r 's/\. ([@A-Z])/. \1/g' $${file}~ > $$file; \
+ sed -r -f fix-sentence-spacing.sed $${file}~ > $$file; \
fi; \
done
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 @@
@xopindex{\option\, summary}
@end macro
-@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
@@ -126,6 +126,12 @@ Component Statement
* Meta1-Style Components::
* Component Syntax Summary::
+Inetd-Style Components
+
+* builtin:: Built-in Inetd Services
+* TCPMUX:: TCPMUX Services
+* sockenv:: Socket Environment Variables
+
Global Configuration
* Less Useful Statements::
@@ -632,6 +638,7 @@ statement. Its value will be available to the program as
@code{argv[0]}.
@end deffn
+@anchor{flags}
@deffn {Config: component} flags (@var{flag-list})
Define flags for this component. The @var{flag-list} is a
comma-separated list of flags. Valid flags are:
@@ -662,7 +669,7 @@ This is an internal inetd component. @xref{builtin}.
@item sockenv
This inetd component wants socket description variables in its
-environment. @FIXME-xref{sockenv}.
+environment. @xref{sockenv}.
@item resolve
When used with @samp{sockenv}, the @env{LOCALHOST} and
@@ -1075,6 +1082,7 @@ provided that @code{chdir} statement is used for this component
@end table
@end deffn
+@anchor{socket-type}
@deffn {Config: component} socket-type @var{type}
Sets the socket type. Allowed values for @var{type} are:
@samp{stream}, @samp{dgram}, @samp{raw}, @samp{rdm},
@@ -1100,26 +1108,227 @@ opened connections.
@menu
* builtin:: Built-in Inetd Services
* TCPMUX:: TCPMUX Services
+* sockenv:: Socket Environment Variables
@end menu
@node builtin
@subsubsection Built-in Inetd Services
@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.
@node TCPMUX
@subsubsection TCPMUX Services
@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
@deffn {Config: component} tcpmux-master @var{name}
Sets the name of the master TCPMUX service.
@end deffn
+@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
@subsection Meta1-Style Components
@cindex meta1-style components
@@ -1157,28 +1366,50 @@ component @var{tag} @{
# @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{List of flags.}
+ # @xref{flags}.
+ flags (@var{flags});
# @r{Listen on the given url.}
# @xref{Inetd-Style Components}.
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};
# @r{Pass fd through this socket.}
# @xref{Meta1-Style Components}.
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.}
# @xref{ACL Statement, ACL Statement,, mailutils, GNU Mailutils Manual}.
acl @{ @dots{} @}
@@ -1222,9 +1453,6 @@ component @var{tag} @{
# @r{Remove @var{file-name} before starting the component.}
# @xref{Actions Before Startup, remove-file}.
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};
# @r{Actions:}
# @xref{Exit Actions}.
@@ -1235,6 +1463,8 @@ component @var{tag} @{
notify @var{email-string};
# @r{Notification message text (with headers).}
message @var{string};
+ # @r{Execute this command.}
+ exec @var{command}
@}
@}
@end smallexample
@@ -1395,7 +1625,7 @@ mailer-command-line "sendmail -f root@@domain.com -oi -t";
@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
+permissions that control access to @samp{inetd}, @samp{accept} and
@samp{meta1}-style components.
An @acronym{ACL} is defined using @code{acl} block statement:

Return to:

Send suggestions and report system problems to the System administrator.