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