@c This is part of the GNU Pies manual.
@c Copyright (C) 2009--2025 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.

@cartouche
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
@samp{stream}.

@cartouche
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}.

@cartouche
The @samp{service-node} prefix and @samp{socket-type} field correspond
to the @code{socket} statement in @file{pies.conf}.
@xref{inetd-socket}.

For example, the following line:

@smallexample
10.0.0.1:ftp dgram   udp     wait    root  ftpd
@end smallexample

@noindent
is equivalent to

@smallexample
  socket inet+udp://10.0.0.1:ftp;
  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 limited by specifying
optional @samp{max-rate} suffix (a decimal number), e.g.:
@samp{nowait.15}. 

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}).

@cartouche
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.

@cartouche
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.

@cartouche
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.

@cartouche
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.:

@smallexample
127.0.0.1,192.168.0.5:
@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:

@smallexample
*:
@end smallexample

@noindent
causes any previous default address specifier to be forgotten.

An example of @file{inetd.conf} file with various services follows:

@smallexample
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 smallexample

     




  
