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