path: root/doc/inetd.texi
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/inetd.texi
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/inetd.texi')
1 files changed, 204 insertions, 0 deletions
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

Return to:

Send suggestions and report system problems to the System administrator.