diff options
Diffstat (limited to 'usr.sbin/inetd/inetd.8')
| -rw-r--r-- | usr.sbin/inetd/inetd.8 | 375 |
1 files changed, 375 insertions, 0 deletions
diff --git a/usr.sbin/inetd/inetd.8 b/usr.sbin/inetd/inetd.8 new file mode 100644 index 0000000..5fe5711 --- /dev/null +++ b/usr.sbin/inetd/inetd.8 @@ -0,0 +1,375 @@ +.\" Copyright (c) 1985, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)inetd.8 8.3 (Berkeley) 4/13/94 +.\" +.Dd April 13, 1994 +.Dt INETD 8 +.Os BSD 4.4 +.Sh NAME +.Nm inetd +.Nd internet +.Dq super-server +.Sh SYNOPSIS +.Nm inetd +.Op Fl d +.Op Fl R Ar rate +.Op Ar configuration file +.Sh DESCRIPTION +The +.Nm inetd +program +should be run at boot time by +.Pa /etc/rc +(see +.Xr rc 8 ) . +It then listens for connections on certain +internet sockets. When a connection is found on one +of its sockets, it decides what service the socket +corresponds to, and invokes a program to service the request. +The server program is invoked with the service socket +as its standard input, output and error descriptors. +After the program is +finished, +.Nm inetd +continues to listen on the socket (except in some cases which +will be described below). Essentially, +.Nm inetd +allows running one daemon to invoke several others, +reducing load on the system. +.Pp +The options available for +.Nm inetd: +.Bl -tag -width Ds +.It Fl d +Turns on debugging. +.It Fl R Ar rate +Specifies the maximum number of times a service can be invoked +in one minute; the default is 1000. +.El +.Pp +Upon execution, +.Nm inetd +reads its configuration information from a configuration +file which, by default, is +.Pa /etc/inetd.conf . +There must be an entry for each field of the configuration +file, with entries for each field separated by a tab or +a space. Comments are denoted by a ``#'' at the beginning +of a line. There must be an entry for each field. The +fields of the configuration file are as follows: +.Pp +.Bd -unfilled -offset indent -compact +service name +socket type +protocol +wait/nowait +user +server program +server program arguments +.Ed +.Pp +There are two types of services that +.Nm inetd +can start: standard and TCPMUX. +A standard service has a well-known port assigned to it; +it may be a service that implements an official Internet standard or is a +BSD-specific service. +As described in +.Tn RFC 1078 , +TCPMUX services are nonstandard services that do not have a +well-known port assigned to them. +They are invoked from +.Nm inetd +when a program connects to the +.Dq tcpmux +well-known port and specifies +the service name. +This feature is useful for adding locally-developed servers. +.Pp +The +.Em service-name +entry is the name of a valid service in +the file +.Pa /etc/services . +For +.Dq internal +services (discussed below), the service +name +.Em must +be the official name of the service (that is, the first entry in +.Pa /etc/services ) . +For TCPMUX services, the value of the +.Em service-name +field consists of the string +.Dq tcpmux +followed by a slash and the +locally-chosen service name. +The service names listed in +.Pa /etc/services +and the name +.Dq help +are reserved. +Try to choose unique names for your TCPMUX services by prefixing them with +your organization's name and suffixing them with a version number. +.Pp +The +.Em socket-type +should be one of +.Dq stream , +.Dq dgram , +.Dq raw , +.Dq rdm , +or +.Dq seqpacket , +depending on whether the socket is a stream, datagram, raw, +reliably delivered message, or sequenced packet socket. +TCPMUX services must use +.Dq stream . +.Pp +The +.Em protocol +must be a valid protocol as given in +.Pa /etc/protocols . +Examples might be +.Dq tcp +or +.Dq udp . +TCPMUX services must use +.Dq tcp . +.Pp +The +.Em wait/nowait +entry specifies whether the server that is invoked by inetd will take over +the socket associated with the service access point, and thus whether +.Nm inetd +should wait for the server to exit before listening for new service +requests. +Datagram servers must use +.Dq 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 +.Nm inetd +can received further messages on the socket, it is said to be +a +.Dq 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 +.Nm inetd +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 +.Dq single-threaded . +.Xr Comsat 8 , +.Pq Xr biff 1 +and +.Xr talkd 8 +are both examples of the latter type of +datagram server. +.Xr Tftpd 8 +is an example of a multi-threaded datagram server. +.Pp +Servers using stream sockets generally are multi-threaded and +use the +.Dq nowait +entry. +Connection requests for these services are accepted by +.Nm inetd , +and the server is given only the newly-accepted socket connected +to a client of the service. +Most stream-based services operate in this manner. +Stream-based servers that use +.Dq 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. +TCPMUX services must use +.Dq nowait . +.Pp +The +.Em user +entry should contain the user name of the user as whom the server +should run. This allows for servers to be given less permission +than root. +.Pp +The +.Em server-program +entry should contain the pathname of the program which is to be +executed by +.Nm inetd +when a request is found on its socket. If +.Nm inetd +provides this service internally, this entry should +be +.Dq internal . +.Pp +The +.Em server program arguments +should be just as arguments +normally are, starting with argv[0], which is the name of +the program. If the service is provided internally, the +word +.Dq internal +should take the place of this entry. +.Pp +The +.Nm inetd +program +provides several +.Dq trivial +services internally by use of +routines within itself. These services are +.Dq echo , +.Dq discard , +.Dq chargen +(character generator), +.Dq daytime +(human readable time), and +.Dq time +(machine readable time, +in the form of the number of seconds since midnight, January +1, 1900). All of these services are tcp based. For +details of these services, consult the appropriate +.Tn RFC +from the Network Information Center. +.Pp +The +.Nm inetd +program +rereads its configuration file when it receives a hangup signal, +.Dv SIGHUP . +Services may be added, deleted or modified when the configuration file +is reread. +.Sh TCPMUX +.Pp +.Tn RFC 1078 +describes the TCPMUX protocol: +``A TCP client connects to a foreign host on TCP port 1. It sends the +service name followed by a carriage-return line-feed <CRLF>. The +service name is never case sensitive. The server replies with a +single character indicating positive (+) or negative (\-) +acknowledgment, immediately followed by an optional message of +explanation, terminated with a <CRLF>. If the reply was positive, +the selected protocol begins; otherwise the connection is closed.'' +The program is passed the TCP connection as file descriptors 0 and 1. +.Pp +If the TCPMUX service name begins with a ``+'', +.Nm inetd +returns the positive reply for the program. +This allows you to invoke programs that use stdin/stdout +without putting any special server code in them. +.Pp +The special service name +.Dq help +causes +.Nm inetd +to list TCPMUX services in +.Pa inetd.conf . +.Sh "EXAMPLES" +.Pp +Here are several example service entries for the various types of services: +.Bd -literal +ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l +ntalk dgram udp wait root /usr/libexec/ntalkd ntalkd +tcpmux/+date stream tcp nowait guest /bin/date date +tcpmux/phonebook stream tcp nowait guest /usr/local/bin/phonebook phonebook +.Ed +.Sh "ERROR MESSAGES" +The +.Nm inetd +server +logs error messages using +.Xr syslog 3 . +Important error messages and their explanations are: +.Bd -literal +\fIservice\fP/\fIprotocol\fP server failing (looping), service terminated. +.Ed +The number of requests for the specified service in the past minute +exceeded the limit. The limit exists to prevent a broken program +or a malicious user from swamping the system. +This message may occur for several reasons: +1) there are lots of hosts requesting the service within a short time period, +2) a 'broken' client program is requesting the service too frequently, +3) a malicious user is running a program to invoke the service in +a 'denial of service' attack, or +4) the invoked service program has an error that causes clients +to retry quickly. +Use the +.Op Fl R +option, +as described above, to change the rate limit. +Once the limit is reached, the service will be +reenabled automatically in 10 minutes. +.sp +.Bd -literal +\fIservice\fP/\fIprotocol\fP: No such user '\fIuser\fP', service ignored +\fIservice\fP/\fIprotocol\fP: getpwnam: \fIuser\fP: No such user +.Ed +No entry for +.Em user +exists in the +.Pa passwd +file. The first message +occurs when +.Nm inetd +(re)reads the configuration file. The second message occurs when the +service is invoked. +.sp +.Bd -literal +\fIservice\fP: can't set uid \fInumber\fP +\fIservice\fP: can't set gid \fInumber\fP +.Ed +The user or group ID for the entry's +.Em user +is invalid. +.Sh SEE ALSO +.Xr comsat 8 , +.Xr fingerd 8 , +.Xr ftpd 8 , +.Xr rexecd 8 , +.Xr rlogind 8 , +.Xr rshd 8 , +.Xr telnetd 8 , +.Xr tftpd 8 +.Sh HISTORY +The +.Nm +command appeared in +.Bx 4.3 . +TCPMUX is based on code and documentation by Mark Lottor. |
