From b038141d8ba5e916bfa97a3c7cb08bb87af1c900 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Thu, 10 Dec 2009 13:52:43 +0200 Subject: 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. --- doc/Makefile.am | 1 + doc/inetd.texi | 204 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/pies.texi | 129 +++++++++++++++++++++++++++++++++-- doc/usr-acl.texi | 2 +- src/pies.c | 4 +- 5 files changed, 331 insertions(+), 9 deletions(-) create mode 100644 doc/inetd.texi 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 @@ info_TEXINFOS=pies.texi pies_TEXINFOS=\ fdl.texi\ + inetd.texi\ macros.texi\ rendition.texi\ usr-acl.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. + +@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 limitied 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: + +@example +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}. Appendices +* 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. +@anchor{lint} @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: + +@smallexample +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} +directory: + +@smallexample +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: + +@smallexample +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: + +@smallexample +@group +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.: + +@smallexample +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}. -@FIXME-xref{inetd}. +@xref{inetd}. @opsummary{instance} @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 diff --git a/src/pies.c b/src/pies.c index 4fe2e64..d9b5a6d 100644 --- a/src/pies.c +++ b/src/pies.c @@ -777,8 +777,10 @@ static struct tokendef socktype_xtab[] = { { "dgram", SOCK_DGRAM }, { "seqpacket", SOCK_SEQPACKET }, { "raw", SOCK_RAW }, - { "rdm", SOCK_RDM }, + { "rdm", SOCK_RDM }, +#ifdef SOCK_PACKET { "packet", SOCK_PACKET }, +#endif { NULL } }; -- cgit v1.2.1