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