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.

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
@@ -141,13 +141,13 @@ untabify:
 
 fix-sentence-spacing:
 	for file in $(info_TEXINFOS) $(wydawca_TEXINFOS); \
 	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
 
 final: untabify fix-sentence-spacing master-menu
 
 # The rendering level is one of PUBLISH, DISTRIB or PROOF.
diff --git a/doc/macros.texi b/doc/macros.texi
index a26ad0c..bc9fd0a 100644
--- a/doc/macros.texi
+++ b/doc/macros.texi
@@ -7,25 +7,12 @@
 @set ANCHOR--\option\ 1
 @anchor{--\option\}
 @end ifclear
 @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
@@ -123,12 +123,18 @@ Component Statement
 * Exit Actions::
 * Output Redirectors::
 * Inetd-Style Components::
 * 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::
 
 Configuration Example
 
@@ -629,12 +635,13 @@ 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
 
+@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:
 
 @table @asis
 @item disable
@@ -659,13 +666,13 @@ This is a @acronym{TCPMUX+} component.  @xref{TCPMUX}.
 
 @item internal
 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
 @env{REMOTEHOST} environment variables will contain resolved host
 names, instead of IP addresses.
 @end table
@@ -1072,12 +1079,13 @@ Specifies a @acronym{UNIX} socket file name.  It is a shortcut for
 @samp{unix:@var{file-name}}.  You may use a relative file name,
 provided that @code{chdir} statement is used for this component
 (@pxref{Actions Before Startup, chdir}).
 @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},
 @samp{seqpacket}.  Default is @samp{stream}.  Notice that
 some socket types may not be implemented by all protocol
 families, e.g. @samp{seqpacket} is not implemented for
@@ -1097,32 +1105,233 @@ component.  It is equivalent to the maximum number of simultaneously
 opened connections.
 @end deffn
 
 @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
   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
@@ -1154,34 +1363,56 @@ component @var{tag} @{
   # @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{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{} @}
   
   # @r{Override default syslog facility for this component.}
   facility @var{facility};
@@ -1219,25 +1450,24 @@ component @var{tag} @{
   # @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{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}.
   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};
+    # @r{Execute this command.}
+    exec @var{command}
   @}
 @}
 @end smallexample
 
 @node Notification
 @section Notification
@@ -1392,13 +1622,13 @@ mailer-command-line "sendmail -f root@@domain.com -oi -t";
 
 @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
+permissions that control access to @samp{inetd}, @samp{accept} and
 @samp{meta1}-style components.
 
 An @acronym{ACL} is defined using @code{acl} block statement:
 
 @deffn {Config} acl
 @smallexample