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.\" from: @(#)inetd.8 8.3 (Berkeley) 4/13/94 33.\" $Id: inetd.8,v 1.13 1997/02/22 16:05:51 peter Exp $ 34.\" 35.Dd February 7, 1996 36.Dt INETD 8 37.Os BSD 4.4 38.Sh NAME 39.Nm inetd 40.Nd internet 41.Dq super-server 42.Sh SYNOPSIS 43.Nm inetd 44.Op Fl d 45.Op Fl l 46.Op Fl R Ar rate 47.Op Fl a Ar address 48.Op Fl p Ar filename 49.Op Ar configuration file 50.Sh DESCRIPTION 51The 52.Nm 53program 54should be run at boot time by 55.Pa /etc/rc 56(see 57.Xr rc 8 ) . 58It then listens for connections on certain 59internet sockets. When a connection is found on one 60of its sockets, it decides what service the socket 61corresponds to, and invokes a program to service the request. 62The server program is invoked with the service socket 63as its standard input, output and error descriptors. 64After the program is 65finished, 66.Nm 67continues to listen on the socket (except in some cases which 68will be described below). Essentially, 69.Nm 70allows running one daemon to invoke several others, 71reducing load on the system. 72.Pp 73The following options are available: 74.Bl -tag -width indent 75.It Fl d 76Turn on debugging. 77.It Fl l 78Turn on logging. 79.It Fl R Ar rate 80Specify the maximum number of times a service can be invoked 81in one minute; the default is 256. 82.It Fl a 83Specify a specific IP address to bind to. 84.It Fl p 85Specify an alternate file in which to store the process ID. 86.El 87.Pp 88Upon execution, 89.Nm 90reads its configuration information from a configuration 91file which, by default, is 92.Pa /etc/inetd.conf . 93There must be an entry for each field of the configuration 94file, with entries for each field separated by a tab or 95a space. Comments are denoted by a ``#'' at the beginning 96of a line. There must be an entry for each field. The 97fields of the configuration file are as follows: 98.Pp 99.Bd -unfilled -offset indent -compact 100service name 101socket type 102protocol 103{wait|nowait}[/max-child] 104user 105server program 106server program arguments 107.Ed 108.Pp 109To specify an 110.No Tn "ONC RPC" Ns -based 111service, the entry would contain these fields: 112.Pp 113.Bd -unfilled -offset indent -compact 114service name/version 115socket type 116rpc/protocol 117user 118server program 119server program arguments 120.Ed 121.Pp 122There are two types of services that 123.Nm 124can start: standard and TCPMUX. 125A standard service has a well-known port assigned to it; 126it may be a service that implements an official Internet standard or is a 127BSD-specific service. 128As described in 129.Tn RFC 1078 , 130TCPMUX services are nonstandard services that do not have a 131well-known port assigned to them. 132They are invoked from 133.Nm 134when a program connects to the 135.Dq tcpmux 136well-known port and specifies 137the service name. 138This feature is useful for adding locally-developed servers. 139.Pp 140The 141.Em service-name 142entry is the name of a valid service in 143the file 144.Pa /etc/services . 145For 146.Dq internal 147services (discussed below), the service 148name 149.Em must 150be the official name of the service (that is, the first entry in 151.Pa /etc/services ) . 152When used to specify an 153.No Tn "ONC RPC" Ns -based 154service, this field is a valid RPC service name in 155the file 156.Pa /etc/rpc . 157The part on the right of the 158.Dq / 159is the RPC version number. This 160can simply be a single numeric argument or a range of versions. 161A range is bounded by the low version to the high version - 162.Dq rusers/1-3 . 163For TCPMUX services, the value of the 164.Em service-name 165field consists of the string 166.Dq tcpmux 167followed by a slash and the 168locally-chosen service name. 169The service names listed in 170.Pa /etc/services 171and the name 172.Dq help 173are reserved. 174Try to choose unique names for your TCPMUX services by prefixing them with 175your organization's name and suffixing them with a version number. 176.Pp 177The 178.Em socket-type 179should be one of 180.Dq stream , 181.Dq dgram , 182.Dq raw , 183.Dq rdm , 184or 185.Dq seqpacket , 186depending on whether the socket is a stream, datagram, raw, 187reliably delivered message, or sequenced packet socket. 188TCPMUX services must use 189.Dq stream . 190.Pp 191The 192.Em protocol 193must be a valid protocol as given in 194.Pa /etc/protocols . 195Examples might be 196.Dq tcp 197or 198.Dq udp . 199Rpc based services are specified with the 200.Dq rpc/tcp 201or 202.Dq rpc/udp 203service type. 204TCPMUX services must use 205.Dq tcp . 206.Pp 207The 208.Em wait/nowait 209entry specifies whether the server that is invoked by 210.Nm 211will take over 212the socket associated with the service access point, and thus whether 213.Nm 214should wait for the server to exit before listening for new service 215requests. 216Datagram servers must use 217.Dq wait , 218as they are always invoked with the original datagram socket bound 219to the specified service address. 220These servers must read at least one datagram from the socket 221before exiting. 222If a datagram server connects 223to its peer, freeing the socket so 224.Nm 225can received further messages on the socket, it is said to be 226a 227.Dq multi-threaded 228server; 229it should read one datagram from the socket and create a new socket 230connected to the peer. 231It should fork, and the parent should then exit 232to allow 233.Nm 234to check for new service requests to spawn new servers. 235Datagram servers which process all incoming datagrams 236on a socket and eventually time out are said to be 237.Dq single-threaded . 238.Xr Comsat 8 , 239.Pq Xr biff 1 240and 241.Xr talkd 8 242are both examples of the latter type of 243datagram server. 244.Xr Tftpd 8 245is an example of a multi-threaded datagram server. 246.Pp 247Servers using stream sockets generally are multi-threaded and 248use the 249.Dq nowait 250entry. 251Connection requests for these services are accepted by 252.Nm inetd , 253and the server is given only the newly-accepted socket connected 254to a client of the service. 255Most stream-based services operate in this manner. 256Stream-based servers that use 257.Dq wait 258are started with the listening service socket, and must accept 259at least one connection request before exiting. 260Such a server would normally accept and process incoming connection 261requests until a timeout. 262TCPMUX services must use 263.Dq nowait . 264.Pp 265The maximum number of outstanding child processes (or ``threads'') 266for a ``nowait'' service may be explicitly specified by appending a 267``/'' followed by the number to the ``nowait'' keyword. Normally 268(or if a value of zero is specified) there is no maximum. Otherwise, 269once the maximum is reached, further connection attempts will be 270queued up until an existing child process exits. This also works 271in the case of ``wait'' mode, although a value other than one (the 272default) might not make sense in some cases. 273.Pp 274The 275.Em user 276entry should contain the user name of the user as whom the server 277should run. This allows for servers to be given less permission 278than root. 279.Pp 280The 281.Em server-program 282entry should contain the pathname of the program which is to be 283executed by 284.Nm 285when a request is found on its socket. If 286.Nm 287provides this service internally, this entry should 288be 289.Dq internal . 290.Pp 291The 292.Em server program arguments 293should be just as arguments 294normally are, starting with argv[0], which is the name of 295the program. If the service is provided internally, the 296word 297.Dq internal 298should take the place of this entry. 299.Pp 300The 301.Nm 302program 303provides several 304.Dq trivial 305services internally by use of 306routines within itself. These services are 307.Dq echo , 308.Dq discard , 309.Dq chargen 310(character generator), 311.Dq daytime 312(human readable time), and 313.Dq time 314(machine readable time, in the form of the number of seconds since 315midnight, January 1, 1900). All of these services are available in 316both TCP and UDP versions; the UDP versions will refuse service if the 317request specifies a reply port corresponding to any internal service. 318(This is done as a defense against looping attacks; the remote IP address 319is logged.) 320For details of these services, consult the 321appropriate 322.Tn RFC 323document. 324.Pp 325When given the 326.Fl l 327option 328.Nm 329will log an entry to syslog each time an 330.Xr accept 2 331is made, which notes the 332service selected and the IP-number of the remote requestor. 333.Pp 334The 335.Nm 336program 337rereads its configuration file when it receives a hangup signal, 338.Dv SIGHUP . 339Services may be added, deleted or modified when the configuration file 340is reread. 341Except when started in debugging mode, 342.Nm 343records its process ID in the file 344.Pa /var/run/inetd.pid 345to assist in reconfiguration. 346.Sh TCPMUX 347.Pp 348.Tn RFC 1078 349describes the TCPMUX protocol: 350``A TCP client connects to a foreign host on TCP port 1. It sends the 351service name followed by a carriage-return line-feed <CRLF>. The 352service name is never case sensitive. The server replies with a 353single character indicating positive (+) or negative (\-) 354acknowledgment, immediately followed by an optional message of 355explanation, terminated with a <CRLF>. If the reply was positive, 356the selected protocol begins; otherwise the connection is closed.'' 357The program is passed the TCP connection as file descriptors 0 and 1. 358.Pp 359If the TCPMUX service name begins with a ``+'', 360.Nm 361returns the positive reply for the program. 362This allows you to invoke programs that use stdin/stdout 363without putting any special server code in them. 364.Pp 365The special service name 366.Dq help 367causes 368.Nm 369to list TCPMUX services in 370.Pa inetd.conf . 371.Sh "FILES" 372.Bl -tag -width /var/run/inetd.pid -compact 373.It Pa /etc/inetd.conf 374configuration file. 375.It Pa /etc/rpc 376translation of service names to RPC program numbers. 377.It Pa /etc/services 378translation of service names to port numbers. 379.It Pa /var/run/inetd.pid 380the pid of the currently running 381.Nm inetd . 382.El 383.Sh "EXAMPLES" 384.Pp 385Here are several example service entries for the various types of services: 386.Bd -literal 387ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l 388ntalk dgram udp wait root /usr/libexec/ntalkd ntalkd 389tcpmux/+date stream tcp nowait guest /bin/date date 390tcpmux/phonebook stream tcp nowait guest /usr/local/bin/phonebook phonebook 391rstatd/1-3 dgram rpc/udp wait root /usr/libexec/rpc.rstatd rpc.rstatd 392.Ed 393.Sh "ERROR MESSAGES" 394The 395.Nm 396server 397logs error messages using 398.Xr syslog 3 . 399Important error messages and their explanations are: 400.Pp 401.Bl -ohang -compact 402.It Xo 403.Ar service Ns / Ns Ar protocol 404.No " server failing (looping), service terminated." 405.Xc 406The number of requests for the specified service in the past minute 407exceeded the limit. The limit exists to prevent a broken program 408or a malicious user from swamping the system. 409This message may occur for several reasons: 410.Bl -enum -offset indent 411.It 412There are many hosts requesting the service within a short time period. 413.It 414A broken client program is requesting the service too frequently. 415.It 416A malicious user is running a program to invoke the service in 417a denial-of-service attack. 418.It 419The invoked service program has an error that causes clients 420to retry quickly. 421.El 422.Pp 423Use the 424.Fl R Ar rate 425option, 426as described above, to change the rate limit. 427Once the limit is reached, the service will be 428reenabled automatically in 10 minutes. 429.Pp 430.It Xo 431.Ar service Ns / Ns Ar protocol : 432.No \&No such user 433.Ar user , 434.No service ignored 435.Xc 436.It Xo 437.Ar service Ns / Ns Ar protocol : 438.No getpwnam : 439.Ar user : 440.No \&No such user 441.Xc 442No entry for 443.Ar user 444exists in the 445.Xr passwd 5 446database. The first message 447occurs when 448.Nm 449(re)reads the configuration file. The second message occurs when the 450service is invoked. 451.Pp 452.It Xo 453.Ar service : 454.No can't set uid 455.Ar uid 456.Xc 457.It Xo 458.Ar service : 459.No can't set gid 460.Ar gid 461.Xc 462The user or group ID for the entry's 463.Ar user 464field is invalid. 465.Pp 466.It "setsockopt(SO_PRIVSTATE): Operation not supported" 467The 468.Nm 469program attempted to renounce the privileged state associated with a 470socket but was unable to. 471.El 472.Sh SEE ALSO 473.Xr passwd 5 , 474.Xr rpc 5 , 475.Xr services 5 , 476.Xr comsat 8 , 477.Xr fingerd 8 , 478.Xr ftpd 8 , 479.Xr portmap 8 , 480.Xr rexecd 8 , 481.Xr rlogind 8 , 482.Xr rshd 8 , 483.Xr telnetd 8 , 484.Xr tftpd 8 485.Sh HISTORY 486The 487.Nm 488command appeared in 489.Bx 4.3 . 490TCPMUX is based on code and documentation by Mark Lottor. 491Support for 492.Tn "ONC RPC" 493based services is modeled after that 494provided by 495.Tn SunOS 4964.1. 497