path: root/doc
diff options
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-10 13:52:43 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2009-12-10 13:52:43 +0200
commitb038141d8ba5e916bfa97a3c7cb08bb87af1c900 (patch)
treede4e5f8db20c6d20dae09f2b6bfda490fec66b25 /doc
parente668360caeb54d64b67130f6f4f674d8738a909a (diff)
Improve docs + bugfix.
* doc/inetd.texi: New file. * doc/Makefile.am: Add inetd.texi. * doc/pies.texi, doc/usr-acl.texi: Update. * src/pies.c (socktype_xtab): SOCK_PACKET not always defined.
Diffstat (limited to 'doc')
4 files changed, 328 insertions, 8 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 21618f0..1653bc6 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -17,6 +17,7 @@
+ inetd.texi\
diff --git a/doc/inetd.texi b/doc/inetd.texi
new file mode 100644
index 0000000..a1c5f8a
--- /dev/null
+++ b/doc/inetd.texi
@@ -0,0 +1,204 @@
+@c This is part of the GNU Pies manual.
+@c Copyright (C) 2009 Sergey Poznyakoff
+@c This file is distributed under GFDL 1.3 or any later version
+@c published by the Free Software Foundation.
+ This appendix describes the format of @command{inetd} compatible
+configuration files. @xref{inetd}, for the discussion on how to
+use such files with GNU @command{pies}.
+ The @command{inetd} configuration file has line oriented format.
+Comments are denoted by a @samp{#} at the beginning of a line. Empty
+lines and comments are ignored. Each non-empty line must be either
+a service definition, or address specification.
+ @dfn{Service definition} consists of at least 6 fields separated by
+any amount of the white space. These fields are described in the
+following table (optional parts are enclosed in
+square brackets):
+@table @asis
+@item [service-node:]service-name
+@flindex /etc/services
+The service-name entry is the name of a valid service in the file
+@file{/etc/services}. For built-in services (@pxref{builtin}),
+the service name must be the official name of the service
+(that is, the first entry in @file{/etc/services}), or a numeric
+representation thereof. For TCPMUX services, the value of the
+@samp{service name} field consists of the string @samp{tcpmux}
+followed by a slash and the locally-chosen service name
+(@pxref{TCPMUX}). Optionally, a plus sign may be inserted after the
+slash, indicating that @command{pies} must issue a @samp{+} response
+before starting this server.
+The @samp{service-name} part corresponds to component tag
+in @file{pies.conf} (@pxref{Component Statement}). For built-in
+components, it corresponds to the @code{service} statement
+(@pxref{builtin, service}).
+@end cartouche
+Optional @samp{service-node} prefix is allowed for internet services.
+When present, it supplies the local addresses @command{inetd} should
+listen on for that service. @samp{Service-node} consists of
+a comma-separated list of addresses. Both symbolic host names and
+numeric IP addresses are allowed. Symbolic hostnames are looked up in
+DNS service. If a hostname has multiple address mappings, a socket
+is created to listen on each address. A special hostname @samp{*}
+stands for @code{INADDR_ANY}.
+@item socket type
+The socket type should be one of @samp{stream}, @samp{dgram},
+@samp{raw}, @samp{rdm}, or @samp{seqpacket}. TCPMUX services must use
+This field corresponds to the @code{socket-type} statement in
+@file{pies.conf}. @xref{socket-type}.
+@end cartouche
+@item protocol
+@flindex /etc/protocols
+The protocol must be a valid protocol as given in
+@file{/etc/protocols}. Examples might be @samp{tcp} or @samp{udp}.
+TCPMUX services must use @samp{tcp}.
+The @samp{service-node} prefix and @samp{socket-type} field correspond
+to the @code{socket} statement in @file{pies.conf}.
+For example, the following line:
+ dgram udp wait root ftpd
+@end smallexample
+is equivalent to
+ socket inet+udp://;
+ socket-typle dgram;
+@end smallexample
+@end cartouche
+@item wait/nowait[.max-rate]
+The @samp{wait/nowait} entry specifies whether the invoked component
+will take over the socket associated with the service access point,
+and thus whether @command{pies} should wait for the server to exit
+before listening for new service requests. Datagram servers must use
+@samp{wait}, as they are always invoked with the original datagram
+socket bound to the specified service address. These servers must
+read at least one datagram from the socket before exiting. If a
+datagram server connects to its peer, freeing the socket so that
+@command{pies} can go on receiving further messages from the socket,
+it is said to be a @dfn{multi-threaded} server; it should read one
+datagram from the socket and create a new socket connected to the
+peer. It should fork, and the parent should then exit to allow
+@command{pies} to check for new service requests to spawn new servers.
+Datagram servers which process all incoming datagrams on a socket and
+eventually time out are said to be @dfn{single-threaded}. Examples of
+such servers are @command{comsat} and @command{talkd}.
+@command{tftpd} is an example of a multi-threaded datagram server.
+Servers using stream sockets generally are multi-threaded and use the
+@samp{nowait} entry. Connection requests for these services are
+accepted by @command{pies}, and the server is given only the
+newly-accepted socket connected to a client of the service. Most
+stream-based services and all TCPMUX services operate in this manner.
+For such services, the invocation rate may be limitied by specifying
+optional @samp{max-rate} suffix (a decimal number), e.g.:
+Stream-based servers that use @samp{wait} are started with the
+listening service socket, and must accept at least one connection
+request before exiting. Such a server would normally accept and
+process incoming connection requests until a timeout. Datagram
+services must use @samp{nowait}. The only stream server marked as
+@samp{wait} is @command{identd} (@pxref{identd,,,identd(1),identd manual}).
+The @samp{wait} field corresponds to @code{flags wait} in the
+@file{pies.conf} file. The @samp{nowait} corresponds to @code{flags
+nowait}. @xref{flags}.
+The @samp{max-rate} suffix corresponds to the @code{max-rate}
+statement. @xref{max-rate}.
+@end cartouche
+@item user
+The user entry contains the name of the user as whom the
+component should run. This allows for components to be given less
+permission than root.
+This corresponds to the @code{user} statement in @file{pies.conf}.
+@xref{Component Privileges, user}.
+@end cartouche
+@item program
+The program entry contains the full file name of the program
+which is to be executed by @command{pies} when a request arrives
+on its socket. For built-in services, this entry should
+be @samp{internal}.
+It is common usage to specify @file{/usr/sbin/tcpd} in this field.
+This field corresponds to the @code{program} statement in @file{pies.conf}.
+@xref{Component Statement, program}.
+@end cartouche
+@item server program arguments
+The server program arguments should be just as arguments normally are,
+starting with @code{argv[0]}, which is the name of the program. For
+built-in services, this entry must contain the word @samp{internal},
+or be empty.
+This corresponds to the @code{command} statement. @xref{Component
+Statement, command}.
+@end cartouche
+@end table
+ @dfn{Address specification} is a special statement that declares the
+@samp{service-node} part (see above) for all the services declared
+below it. It consists of a host address specifier
+followed by a colon on a single line, e.g.:
+@end smallexample
+The address specifier from such a line is remembered and used for all
+further lines lacking an explicit host specifier. It remains in
+effect until another address specification or end of the
+configuration is encountered, whichever occurs first.
+The following address specification:
+@end smallexample
+causes any previous default address specifier to be forgotten.
+An example of @file{inetd.conf} file with various services follows:
+ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l
+ntalk dgram udp wait root /usr/libexec/ntalkd ntalkd
+tcpmux stream tcp nowait root internal
+tcpmux/+scp-to stream tcp nowait guest /usr/sbin/in.wydawca wydawca
+tcpmux/docref stream tcp nowait guest /usr/bin/docref docref
+@end example
diff --git a/doc/pies.texi b/doc/pies.texi
index d5e9d02..7008ce6 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -92,6 +92,7 @@ documents @command{pies} Version @value{VERSION}.
+* inetd.conf:: @file{Inetd.conf} Format.
* User-Group ACLs::
* Copying This Manual:: The GNU Free Documentation License.
* Concept Index:: Index of Concepts.
@@ -105,7 +106,8 @@ Pies Configuration File
* Component Statement::
* Notification:: Mail Notification
* ACL:: Access Control Lists
-* include-meta1::
+* inetd:: Using @command{inetd} Configuration Files
+* include-meta1:: Using @command{meta1} Configuration Files
* Global Configuration::
Configuration File Syntax
@@ -263,7 +265,7 @@ option. This option instructs @command{pies} that any configuration
files given after it have are written in the specified @var{format}.
Valid formats are: @samp{pies}, @samp{inetd} and @samp{meta1}, which
stand for pies native format, inetd-style configuration files
-(@FIXME-pxref{inetd-format} and MeTA1-style configuration files. The
+(@pxref{inetd.conf}) and MeTA1-style configuration files. The
configuration file format set by the @option{--syntax} option remains
in effect for all @option{--config-file} options that follow it, up to
the end of the command line or the next occurrence of the
@@ -281,12 +283,13 @@ pies /etc/pies.conf \
The rest of this chapter concerns the @command{pies} native
configuration file format. The use of inetd configuration files is
-covered in @FIXME-ref{inetd} and the use of meta1 configuration files
-is described in @FIXME-ref{meta1}
+covered in @ref{inetd} and the use of meta1 configuration files
+is described in @ref{include-meta1}
If any errors are encountered in the configuration file, the program
reports them on the standard error and exits with status 78.
@xopindex{lint, introduced}
To test the configuration file without actually starting the server, the
@option{--lint} (@option{-t}) command line option is provided. It causes
@@ -309,6 +312,7 @@ directives any time by running @command{pies --config-help}.
* Component Statement::
* Notification:: Mail Notification
* ACL:: Access Control Lists
+* inetd::
* include-meta1::
* Global Configuration::
@end menu
@@ -656,7 +660,7 @@ disabled by @command{pies}, even if they respawn too fast.
This flag is valid only for @samp{inetd} components. It has the same
meaning as @samp{wait} in @file{inetd.conf} file, i.e. it tells
@command{pies} to wait for the server program to
-return. @FIXME-xref{inetd}.
+return. @xref{inetd.conf, wait}.
@item tcpmux
This is a @acronym{TCPMUX} component. @xref{TCPMUX}.
@@ -1766,6 +1770,113 @@ acl @{
@end group
@end smallexample
+@node inetd
+@section Using @command{inetd} Configuration Files
+@cindex inetd.conf
+@flindex /etc/inetd.conf
+ In addition to its native configuration file format, GNU
+@command{pies} is able to read configuration files of several other
+widely-used utilities. One of these is @command{inetd}. The simplest
+way to use such configuration files is by including them to your main
+@file{pies.conf} using the @dfn{include-inetd} statement:
+@deffn {Config} include-inetd @var{file}
+Read components from @command{inetd}-style configuration file
+@var{file}. The argument may also be a directory, in which case
+all regular files from that directory will be read and parsed
+as @command{inetd}-style configuration files.
+The components read from @var{file} are appended to the @command{pies}
+list of components in order of their appearance.
+For example, the following statement reads components from the
+standard @command{inetd} configuration file:
+include-inetd /etc/inetd.conf;
+@end smallexample
+Any number of @code{include-inetd} may be specified. For example, the
+following reads the contents of the @file{/etc/inetd.conf}
+configuration file and all files from the @file{/etc/inetd.d}
+include-inetd /etc/inetd.conf;
+include-inetd /etc/inetd.d;
+@end smallexample
+@end deffn
+ Another way to read @command{inetd} configuration files is to supply
+them in the command line, like this:
+pies --syntax=inetd --config-file /etc/inetd.conf
+@end smallexample
+Notice the @option{--syntax} option (@pxref{config syntax}). It
+informs @command{pies} that the following files are in @command{inetd}
+format. Of course, several configuration file may be given:
+pies --syntax=inetd \
+ --config-file /etc/inetd.conf --config-file /etc/inetd.d
+@end group
+@end smallexample
+A special option is provided that instructs @command{pies} to behave
+as @command{inetd}:
+@table @option
+@xopindex{inetd, described}
+@item --inetd
+Read configuration from @file{@var{sysconfdir}/inetd.conf} and make
+sure @command{pies} state files (@FIXME-pxref{state files}) do not
+conflict with those from other @command{pies} instances.
+@end table
+The GNU Pies package also provides a wrapper that allows to use
+@command{pies} instead of @command{inetd}. It is built if the package
+is configured with the @option{--enable-inetd} option. The wrapper
+is then installed in @var{sbindir} as @file{inetd}, possibly replacing
+the system binary of that name.
+The command line usage of the @command{inetd} wrapper is entirely
+compatible with that of the usual @command{inetd} utility, i.e.:
+inetd [@var{option}] [@var{config} [@var{config}...]] [-- @var{pies-options}]
+@end smallexample
+Options are:
+@table @option
+@item -d
+Increase debug level.
+@item -R @var{rate}
+Set maximum rate (@pxref{max-rate}).
+@end table
+For convenience, the following additional options are understood:
+@table @option
+@item -t
+@itemx --lint
+Parse configuration file or files and exit. @xref{lint}.
+@item -s
+@itemx --status
+Display info about the running instance. @xref{pies-status}.
+@item -S
+@itemx --stop
+Stop the running instance.
+@end table
+ Finally, any additional options @command{pies} understands may be
+given to @command{inetd} after the @samp{--} separator.
@node include-meta1
@section Using MeTA1 Configuration File
@flindex /etc/meta1/meta1.conf
@@ -2245,7 +2356,7 @@ Display a short usage summary and exit.
@itemx -i
Run in @command{inetd}-compatibility mode. It is roughly
equivalent to @command{pies --instance=inetd --syntax=inetd}.
@item --instance=@var{name}
@@ -2284,7 +2395,7 @@ for @var{type} are:
Native @command{pies} configuration. @xref{Pies Configuration File}.
@item inetd
-@samp{Inetd}-style configuration files. @FIXME-xref{inetd}.
+@samp{Inetd}-style configuration files. @xref{inetd.conf}.
@item meta1
@samp{meta1}-style configuration files. @FIXME-xref{meta1}.
@@ -2343,6 +2454,10 @@ line options used).
@item Conditions under which the bug appears.
@end itemize
+@node inetd.conf
+@appendix @file{Inetd.conf} Format
+@include inetd.texi
@node User-Group ACLs
@appendix User-Group ACLs
@include usr-acl.texi
diff --git a/doc/usr-acl.texi b/doc/usr-acl.texi
index 2f4bcd3..9d6fc74 100644
--- a/doc/usr-acl.texi
+++ b/doc/usr-acl.texi
@@ -1,6 +1,6 @@
@c This is part of the GNU Pies manual.
@c Copyright (C) 2009 Sergey Poznyakoff
-@c This file is distributed under GFDL 1.1 or any later version
+@c This file is distributed under GFDL 1.3 or any later version
@c published by the Free Software Foundation.
This appendix describes the @samp{user-group} extension for

Return to:

Send suggestions and report system problems to the System administrator.