1.\" Copyright (c) 1985, 1991, 1993, 1994 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)inetd.8 8.3 (Berkeley) 4/13/94 33.\" 34.Dd April 13, 1994 35.Dt INETD 8 36.Os BSD 4.4 37.Sh NAME 38.Nm inetd 39.Nd internet 40.Dq super-server 41.Sh SYNOPSIS 42.Nm inetd 43.Op Fl d 44.Op Fl R Ar rate 45.Op Ar configuration file 46.Sh DESCRIPTION 47The 48.Nm inetd 49program 50should be run at boot time by 51.Pa /etc/rc 52(see 53.Xr rc 8 ) . 54It then listens for connections on certain 55internet sockets. When a connection is found on one 56of its sockets, it decides what service the socket 57corresponds to, and invokes a program to service the request. 58The server program is invoked with the service socket 59as its standard input, output and error descriptors. 60After the program is 61finished, 62.Nm inetd 63continues to listen on the socket (except in some cases which 64will be described below). Essentially, 65.Nm inetd 66allows running one daemon to invoke several others, 67reducing load on the system. 68.Pp 69The options available for 70.Nm inetd: 71.Bl -tag -width Ds 72.It Fl d 73Turns on debugging. 74.It Fl R Ar rate 75Specifies the maximum number of times a service can be invoked 76in one minute; the default is 1000. 77.El 78.Pp 79Upon execution, 80.Nm inetd 81reads its configuration information from a configuration 82file which, by default, is 83.Pa /etc/inetd.conf . 84There must be an entry for each field of the configuration 85file, with entries for each field separated by a tab or 86a space. Comments are denoted by a ``#'' at the beginning 87of a line. There must be an entry for each field. The 88fields of the configuration file are as follows: 89.Pp 90.Bd -unfilled -offset indent -compact 91service name 92socket type 93protocol 94wait/nowait 95user 96server program 97server program arguments 98.Ed 99.Pp 100There are two types of services that 101.Nm inetd 102can start: standard and TCPMUX. 103A standard service has a well-known port assigned to it; 104it may be a service that implements an official Internet standard or is a 105BSD-specific service. 106As described in 107.Tn RFC 1078 , 108TCPMUX services are nonstandard services that do not have a 109well-known port assigned to them. 110They are invoked from 111.Nm inetd 112when a program connects to the 113.Dq tcpmux 114well-known port and specifies 115the service name. 116This feature is useful for adding locally-developed servers. 117.Pp 118The 119.Em service-name 120entry is the name of a valid service in 121the file 122.Pa /etc/services . 123For 124.Dq internal 125services (discussed below), the service 126name 127.Em must 128be the official name of the service (that is, the first entry in 129.Pa /etc/services ) . 130For TCPMUX services, the value of the 131.Em service-name 132field consists of the string 133.Dq tcpmux 134followed by a slash and the 135locally-chosen service name. 136The service names listed in 137.Pa /etc/services 138and the name 139.Dq help 140are reserved. 141Try to choose unique names for your TCPMUX services by prefixing them with 142your organization's name and suffixing them with a version number. 143.Pp 144The 145.Em socket-type 146should be one of 147.Dq stream , 148.Dq dgram , 149.Dq raw , 150.Dq rdm , 151or 152.Dq seqpacket , 153depending on whether the socket is a stream, datagram, raw, 154reliably delivered message, or sequenced packet socket. 155TCPMUX services must use 156.Dq stream . 157.Pp 158The 159.Em protocol 160must be a valid protocol as given in 161.Pa /etc/protocols . 162Examples might be 163.Dq tcp 164or 165.Dq udp . 166TCPMUX services must use 167.Dq tcp . 168.Pp 169The 170.Em wait/nowait 171entry specifies whether the server that is invoked by inetd will take over 172the socket associated with the service access point, and thus whether 173.Nm inetd 174should wait for the server to exit before listening for new service 175requests. 176Datagram servers must use 177.Dq wait , 178as they are always invoked with the original datagram socket bound 179to the specified service address. 180These servers must read at least one datagram from the socket 181before exiting. 182If a datagram server connects 183to its peer, freeing the socket so 184.Nm inetd 185can received further messages on the socket, it is said to be 186a 187.Dq multi-threaded 188server; 189it should read one datagram from the socket and create a new socket 190connected to the peer. 191It should fork, and the parent should then exit 192to allow 193.Nm inetd 194to check for new service requests to spawn new servers. 195Datagram servers which process all incoming datagrams 196on a socket and eventually time out are said to be 197.Dq single-threaded . 198.Xr Comsat 8 , 199.Pq Xr biff 1 200and 201.Xr talkd 8 202are both examples of the latter type of 203datagram server. 204.Xr Tftpd 8 205is an example of a multi-threaded datagram server. 206.Pp 207Servers using stream sockets generally are multi-threaded and 208use the 209.Dq nowait 210entry. 211Connection requests for these services are accepted by 212.Nm inetd , 213and the server is given only the newly-accepted socket connected 214to a client of the service. 215Most stream-based services operate in this manner. 216Stream-based servers that use 217.Dq wait 218are started with the listening service socket, and must accept 219at least one connection request before exiting. 220Such a server would normally accept and process incoming connection 221requests until a timeout. 222TCPMUX services must use 223.Dq nowait . 224.Pp 225The 226.Em user 227entry should contain the user name of the user as whom the server 228should run. This allows for servers to be given less permission 229than root. 230.Pp 231The 232.Em server-program 233entry should contain the pathname of the program which is to be 234executed by 235.Nm inetd 236when a request is found on its socket. If 237.Nm inetd 238provides this service internally, this entry should 239be 240.Dq internal . 241.Pp 242The 243.Em server program arguments 244should be just as arguments 245normally are, starting with argv[0], which is the name of 246the program. If the service is provided internally, the 247word 248.Dq internal 249should take the place of this entry. 250.Pp 251The 252.Nm inetd 253program 254provides several 255.Dq trivial 256services internally by use of 257routines within itself. These services are 258.Dq echo , 259.Dq discard , 260.Dq chargen 261(character generator), 262.Dq daytime 263(human readable time), and 264.Dq time 265(machine readable time, 266in the form of the number of seconds since midnight, January 2671, 1900). All of these services are tcp based. For 268details of these services, consult the appropriate 269.Tn RFC 270from the Network Information Center. 271.Pp 272The 273.Nm inetd 274program 275rereads its configuration file when it receives a hangup signal, 276.Dv SIGHUP . 277Services may be added, deleted or modified when the configuration file 278is reread. 279.Sh TCPMUX 280.Pp 281.Tn RFC 1078 282describes the TCPMUX protocol: 283``A TCP client connects to a foreign host on TCP port 1. It sends the 284service name followed by a carriage-return line-feed <CRLF>. The 285service name is never case sensitive. The server replies with a 286single character indicating positive (+) or negative (\-) 287acknowledgment, immediately followed by an optional message of 288explanation, terminated with a <CRLF>. If the reply was positive, 289the selected protocol begins; otherwise the connection is closed.'' 290The program is passed the TCP connection as file descriptors 0 and 1. 291.Pp 292If the TCPMUX service name begins with a ``+'', 293.Nm inetd 294returns the positive reply for the program. 295This allows you to invoke programs that use stdin/stdout 296without putting any special server code in them. 297.Pp 298The special service name 299.Dq help 300causes 301.Nm inetd 302to list TCPMUX services in 303.Pa inetd.conf . 304.Sh "EXAMPLES" 305.Pp 306Here are several example service entries for the various types of services: 307.Bd -literal 308ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l 309ntalk dgram udp wait root /usr/libexec/ntalkd ntalkd 310tcpmux/+date stream tcp nowait guest /bin/date date 311tcpmux/phonebook stream tcp nowait guest /usr/local/bin/phonebook phonebook 312.Ed 313.Sh "ERROR MESSAGES" 314The 315.Nm inetd 316server 317logs error messages using 318.Xr syslog 3 . 319Important error messages and their explanations are: 320.Bd -literal 321\fIservice\fP/\fIprotocol\fP server failing (looping), service terminated. 322.Ed 323The number of requests for the specified service in the past minute 324exceeded the limit. The limit exists to prevent a broken program 325or a malicious user from swamping the system. 326This message may occur for several reasons: 3271) there are lots of hosts requesting the service within a short time period, 3282) a 'broken' client program is requesting the service too frequently, 3293) a malicious user is running a program to invoke the service in 330a 'denial of service' attack, or 3314) the invoked service program has an error that causes clients 332to retry quickly. 333Use the 334.Op Fl R 335option, 336as described above, to change the rate limit. 337Once the limit is reached, the service will be 338reenabled automatically in 10 minutes. 339.sp 340.Bd -literal 341\fIservice\fP/\fIprotocol\fP: No such user '\fIuser\fP', service ignored 342\fIservice\fP/\fIprotocol\fP: getpwnam: \fIuser\fP: No such user 343.Ed 344No entry for 345.Em user 346exists in the 347.Pa passwd 348file. The first message 349occurs when 350.Nm inetd 351(re)reads the configuration file. The second message occurs when the 352service is invoked. 353.sp 354.Bd -literal 355\fIservice\fP: can't set uid \fInumber\fP 356\fIservice\fP: can't set gid \fInumber\fP 357.Ed 358The user or group ID for the entry's 359.Em user 360is invalid. 361.Sh SEE ALSO 362.Xr comsat 8 , 363.Xr fingerd 8 , 364.Xr ftpd 8 , 365.Xr rexecd 8 , 366.Xr rlogind 8 , 367.Xr rshd 8 , 368.Xr telnetd 8 , 369.Xr tftpd 8 370.Sh HISTORY 371The 372.Nm 373command appeared in 374.Bx 4.3 . 375TCPMUX is based on code and documentation by Mark Lottor. 376