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