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.\" $FreeBSD$ 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 104{wait|nowait}[/max-child] 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 maximum number of outstanding child processes (or ``threads'') 265for a ``nowait'' service may be explicitly specified by appending a 266``/'' followed by the number to the ``nowait'' keyword. Normally 267(or if a value of zero is specified) there is no maximum. Otherwise, 268once the maximum is reached, further connection attempts will be 269queued up until an existing child process exits. This also works 270in the case of ``wait'' mode, although a value other than one (the 271default) might not make sense in some cases. 272.Pp 273The 274.Em user 275entry should contain the user name of the user as whom the server 276should run. This allows for servers to be given less permission 277than root. 278.Pp 279The 280.Em server-program 281entry should contain the pathname of the program which is to be 282executed by 283.Nm inetd 284when a request is found on its socket. If 285.Nm inetd 286provides this service internally, this entry should 287be 288.Dq internal . 289.Pp 290The 291.Em server program arguments 292should be just as arguments 293normally are, starting with argv[0], which is the name of 294the program. If the service is provided internally, the 295word 296.Dq internal 297should take the place of this entry. 298.Pp 299The 300.Nm inetd 301program 302provides several 303.Dq trivial 304services internally by use of 305routines within itself. These services are 306.Dq echo , 307.Dq discard , 308.Dq chargen 309(character generator), 310.Dq daytime 311(human readable time), and 312.Dq time 313(machine readable time, in the form of the number of seconds since 314midnight, January 1, 1900). All of these services are available in 315both TCP and UDP versions; the UDP versions will refuse service if the 316request specifies a reply port corresponding to any internal service. 317(This is done as a defense against looping attacks; the remote IP address 318is logged.) 319For details of these services, consult the 320appropriate 321.Tn RFC 322document. 323.Pp 324When given the 325.Fl l 326option 327.Nm Inetd 328will log an entry to syslog each time an 329.Xr accept 2 330is made, which notes the 331service selected and the IP-number of the remote requestor. 332.Pp 333The 334.Nm inetd 335program 336rereads its configuration file when it receives a hangup signal, 337.Dv SIGHUP . 338Services may be added, deleted or modified when the configuration file 339is reread. 340Except when started in debugging mode, 341.Nm 342records its process ID in the file 343.Pa /var/run/inetd.pid 344to assist in reconfiguration. 345.Sh TCPMUX 346.Pp 347.Tn RFC 1078 348describes the TCPMUX protocol: 349``A TCP client connects to a foreign host on TCP port 1. It sends the 350service name followed by a carriage-return line-feed <CRLF>. The 351service name is never case sensitive. The server replies with a 352single character indicating positive (+) or negative (\-) 353acknowledgment, immediately followed by an optional message of 354explanation, terminated with a <CRLF>. If the reply was positive, 355the selected protocol begins; otherwise the connection is closed.'' 356The program is passed the TCP connection as file descriptors 0 and 1. 357.Pp 358If the TCPMUX service name begins with a ``+'', 359.Nm inetd 360returns the positive reply for the program. 361This allows you to invoke programs that use stdin/stdout 362without putting any special server code in them. 363.Pp 364The special service name 365.Dq help 366causes 367.Nm inetd 368to list TCPMUX services in 369.Pa inetd.conf . 370.Sh "FILES" 371.Bl -tag -width /var/run/inetd.pid -compact 372.It Pa /etc/inetd.conf 373configuration file. 374.It Pa /etc/rpc 375translation of service names to RPC program numbers. 376.It Pa /etc/services 377translation of service names to port numbers. 378.It Pa /var/run/inetd.pid 379the pid of the currently running 380.Nm inetd . 381.El 382.Sh "EXAMPLES" 383.Pp 384Here are several example service entries for the various types of services: 385.Bd -literal 386ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l 387ntalk dgram udp wait root /usr/libexec/ntalkd ntalkd 388tcpmux/+date stream tcp nowait guest /bin/date date 389tcpmux/phonebook stream tcp nowait guest /usr/local/bin/phonebook phonebook 390rstatd/1-3 dgram rpc/udp wait root /usr/libexec/rpc.rstatd rpc.rstatd 391.Ed 392.Sh "ERROR MESSAGES" 393The 394.Nm inetd 395server 396logs error messages using 397.Xr syslog 3 . 398Important error messages and their explanations are: 399.Pp 400.Bl -ohang -compact 401.It Xo 402.Ar service Ns / Ns Ar protocol 403.No " server failing (looping), service terminated." 404.Xc 405The number of requests for the specified service in the past minute 406exceeded the limit. The limit exists to prevent a broken program 407or a malicious user from swamping the system. 408This message may occur for several reasons: 409.Bl -enum -offset indent 410.It 411There are many hosts requesting the service within a short time period. 412.It 413A broken client program is requesting the service too frequently. 414.It 415A malicious user is running a program to invoke the service in 416a denial-of-service attack. 417.It 418The invoked service program has an error that causes clients 419to retry quickly. 420.El 421.Pp 422Use the 423.Fl R Ar rate 424option, 425as described above, to change the rate limit. 426Once the limit is reached, the service will be 427reenabled automatically in 10 minutes. 428.Pp 429.It Xo 430.Ar service Ns / Ns Ar protocol : 431.No \&No such user 432.Ar user , 433.No service ignored 434.Xc 435.It Xo 436.Ar service Ns / Ns Ar protocol : 437.No getpwnam : 438.Ar user : 439.No \&No such user 440.Xc 441No entry for 442.Ar user 443exists in the 444.Xr passwd 5 445database. The first message 446occurs when 447.Nm inetd 448(re)reads the configuration file. The second message occurs when the 449service is invoked. 450.Pp 451.It Xo 452.Ar service : 453.No can't set uid 454.Ar uid 455.Xc 456.It Xo 457.Ar service : 458.No can't set gid 459.Ar gid 460.Xc 461The user or group ID for the entry's 462.Ar user 463field is invalid. 464.Pp 465.It "setsockopt(SO_PRIVSTATE): Operation not supported" 466The 467.Nm 468program attempted to renounce the privileged state associated with a 469socket but was unable to. 470.El 471.Sh SEE ALSO 472.Xr passwd 5 , 473.Xr rpc 5 , 474.Xr services 5 , 475.Xr comsat 8 , 476.Xr fingerd 8 , 477.Xr ftpd 8 , 478.Xr portmap 8 , 479.Xr rexecd 8 , 480.Xr rlogind 8 , 481.Xr rshd 8 , 482.Xr telnetd 8 , 483.Xr tftpd 8 484.Sh HISTORY 485The 486.Nm 487command appeared in 488.Bx 4.3 . 489TCPMUX is based on code and documentation by Mark Lottor. 490Support for 491.Tn "ONC RPC" 492based services is modeled after that 493provided by 494.Tn SunOS 4954.1. 496