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