diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-10 00:05:13 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-10 00:09:44 +0200 |
commit | e668360caeb54d64b67130f6f4f674d8738a909a (patch) | |
tree | a361085cf1fafee2afa4a89a18b2f4815736a5cd /doc | |
parent | 41c55a1a93840363c996fc9aae54329dadcf0a86 (diff) | |
download | pies-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.am | 2 | ||||
-rw-r--r-- | doc/macros.texi | 17 | ||||
-rw-r--r-- | doc/pies.texi | 260 |
3 files changed, 248 insertions, 31 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,13 +1366,6 @@ 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}); @@ -1171,13 +1373,42 @@ component @var{tag} @{ # @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}. @@ -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: |