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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" from: @(#)inetd.8 8.3 (Berkeley) 4/13/94 29.\" $FreeBSD: src/usr.sbin/inetd/inetd.8,v 1.46.2.13 2003/03/12 22:08:14 trhodes Exp $ 30.\" 31.Dd April 21, 2018 32.Dt INETD 8 33.Os 34.Sh NAME 35.Nm inetd 36.Nd internet 37.Dq super-server 38.Sh SYNOPSIS 39.Nm 40.Op Fl d 41.Op Fl l 42.Op Fl w 43.Op Fl W 44.Op Fl c Ar maximum 45.Op Fl C Ar rate 46.Op Fl a Ar address | hostname 47.Op Fl p Ar filename 48.Op Fl R Ar rate 49.Op Fl s Ar maximum 50.Op Ar configuration file 51.Sh DESCRIPTION 52The 53.Nm 54utility should 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 of successful connections. 79.It Fl w 80Turn on TCP Wrapping for external services. 81See the 82.Sx "IMPLEMENTATION NOTES" 83section for more information on TCP Wrappers support. 84.It Fl W 85Turn on TCP Wrapping for internal services which are built into 86.Nm . 87.It Fl c Ar maximum 88Specify the default maximum number of 89simultaneous invocations of each service; 90the default is unlimited. 91May be overridden on a per-service basis with the "max-child" 92parameter. 93.It Fl C Ar rate 94Specify the default maximum number of times a service can be invoked 95from a single IP address in one minute; the default is unlimited. 96May be overridden on a per-service basis with the 97"max-connections-per-ip-per-minute" parameter. 98.It Fl R Ar rate 99Specify the maximum number of times a service can be invoked 100in one minute; the default is 256. 101A rate of 0 allows an unlimited number of invocations. 102.It Fl s Ar maximum 103Specify the default maximum number of 104simultaneous invocations of each service from a single IP address; 105the default is unlimited. 106May be overridden on a per-service basis with the "max-child-per-ip" 107parameter. 108.It Fl a 109Specify one specific IP address to bind to. 110Alternatively, a hostname can be specified, 111in which case the IPv4 or IPv6 address 112which corresponds to that hostname is used. 113Usually a hostname is specified when 114.Nm 115is run inside a 116.Xr jail 8 , 117in which case the hostname corresponds to the 118.Xr jail 8 119environment. 120.Pp 121When hostname specification is used 122and both IPv4 and IPv6 bindings are desired, 123one entry with the appropriate 124.Em protocol 125type for each binding 126is required for each service in 127.Pa /etc/inetd.conf . 128For example, 129a TCP-based service would need two entries, 130one using 131.Dq tcp4 132for the 133.Em protocol 134and the other using 135.Dq tcp6 . 136See the explanation of the 137.Pa /etc/inetd.conf 138.Em protocol 139field below. 140.It Fl p 141Specify an alternate file in which to store the process ID. 142.El 143.Pp 144Upon execution, 145.Nm 146reads its configuration information from a configuration 147file which, by default, is 148.Pa /etc/inetd.conf . 149There must be an entry for each field of the configuration 150file, with entries for each field separated by a tab or 151a space. Comments are denoted by a 152.Dq # 153at the beginning 154of a line. There must be an entry for each field. The 155fields of the configuration file are as follows: 156.Pp 157.Bd -unfilled -offset indent -compact 158service name 159socket type 160protocol 161{wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]] 162user[:group][/login-class] 163server program 164server program arguments 165.Ed 166.Pp 167To specify an 168.Tn "ONC RPC" Ns -based 169service, the entry would contain these fields: 170.Pp 171.Bd -unfilled -offset indent -compact 172service name/version 173socket type 174rpc/protocol 175user[:group][/login-class] 176server program 177server program arguments 178.Ed 179.Pp 180There are two types of services that 181.Nm 182can start: standard and TCPMUX. 183A standard service has a well-known port assigned to it; 184it may be a service that implements an official Internet standard or is a 185.Bx Ns -specific 186service. 187As described in 188.Tn RFC 1078 , 189TCPMUX services are nonstandard services that do not have a 190well-known port assigned to them. 191They are invoked from 192.Nm 193when a program connects to the 194.Dq tcpmux 195well-known port and specifies 196the service name. 197This feature is useful for adding locally-developed servers. 198TCPMUX requests are only accepted when the multiplexor service itself 199is enabled, above and beyond and specific TCPMUX-based servers; see the 200discussion of internal services below. 201.Pp 202The 203.Em service-name 204entry is the name of a valid service in 205the file 206.Pa /etc/services , 207or the specification of a 208.Ux 209domain socket (see below). 210For 211.Dq internal 212services (discussed below), the service 213name 214should 215be the official name of the service (that is, the first entry in 216.Pa /etc/services ) . 217When used to specify an 218.Tn "ONC RPC" Ns -based 219service, this field is a valid RPC service name in 220the file 221.Pa /etc/rpc . 222The part on the right of the 223.Dq / 224is the RPC version number. 225This 226can simply be a single numeric argument or a range of versions. 227A range is bounded by the low version to the high version - 228.Dq rusers/1-3 . 229For TCPMUX services, the value of the 230.Em service-name 231field consists of the string 232.Dq tcpmux 233followed by a slash and the 234locally-chosen service name. 235The service names listed in 236.Pa /etc/services 237and the name 238.Dq help 239are reserved. 240Try to choose unique names for your TCPMUX services by prefixing them with 241your organization's name and suffixing them with a version number. 242.Pp 243The 244.Em socket-type 245should be one of 246.Dq stream , 247.Dq dgram , 248.Dq raw , 249.Dq rdm , 250or 251.Dq seqpacket , 252depending on whether the socket is a stream, datagram, raw, 253reliably delivered message, or sequenced packet socket. 254TCPMUX services must use 255.Dq stream . 256.Pp 257The 258.Em protocol 259must be a valid protocol or 260.Dq unix . 261Examples are 262.Dq tcp 263or 264.Dq udp , 265both of which imply IPv4 for backward compatibility. 266The names 267.Dq tcp4 268and 269.Dq udp4 270specify IPv4 only. 271The names 272.Dq tcp6 273and 274.Dq udp6 275specify IPv6 only. 276The names 277.Dq tcp46 278and 279.Dq udp46 280specify that the entry accepts both IPv4 and IPv6 connections 281via a wildcard 282.Dv AF_INET6 283socket. 284If it is desired that the service is reachable via T/TCP, one should 285specify 286.Dq tcp/ttcp , 287which implies IPv4 for backward compatibility. 288The name 289.Dq tcp4/ttcp 290specifies IPv4 only, while 291.Dq tcp6/ttcp 292specifies IPv6 only. 293The name 294.Dq tcp46/ttcp 295specify that the entry accepts both IPv6 and IPv6 connections 296via a wildcard 297.Dv AF_INET6 298socket. 299Rpc based services 300(for which only IPv4 is supported at this time) 301are specified with the 302.Dq rpc/tcp 303or 304.Dq rpc/udp 305service type. 306TCPMUX services must use 307.Dq tcp , 308.Dq tcp4 , 309.Dq tcp6 310or 311.Dq tcp46 . 312.Pp 313The 314.Em wait/nowait 315entry specifies whether the server that is invoked by 316.Nm 317will take over 318the socket associated with the service access point, and thus whether 319.Nm 320should wait for the server to exit before listening for new service 321requests. 322Datagram servers must use 323.Dq wait , 324as they are always invoked with the original datagram socket bound 325to the specified service address. 326These servers must read at least one datagram from the socket 327before exiting. 328If a datagram server connects 329to its peer, freeing the socket so 330.Nm 331can receive further messages on the socket, it is said to be 332a 333.Dq multi-threaded 334server; 335it should read one datagram from the socket and create a new socket 336connected to the peer. 337It should fork, and the parent should then exit 338to allow 339.Nm 340to check for new service requests to spawn new servers. 341Datagram servers which process all incoming datagrams 342on a socket and eventually time out are said to be 343.Dq single-threaded . 344.Xr Comsat 8 , 345.Pq Xr biff 1 346and 347.Xr talkd 8 348are both examples of the latter type of 349datagram server. 350.Xr Tftpd 8 351is an example of a multi-threaded datagram server. 352.Pp 353Servers using stream sockets generally are multi-threaded and 354use the 355.Dq nowait 356entry. 357Connection requests for these services are accepted by 358.Nm , 359and the server is given only the newly-accepted socket connected 360to a client of the service. 361Most stream-based services operate in this manner. 362Stream-based servers that use 363.Dq wait 364are started with the listening service socket, and must accept 365at least one connection request before exiting. 366Such a server would normally accept and process incoming connection 367requests until a timeout. 368TCPMUX services must use 369.Dq nowait . 370.Pp 371The maximum number of outstanding child processes (or 372.Dq threads ) 373for a 374.Dq nowait 375service may be explicitly specified by appending a 376.Dq / 377followed by the number to the 378.Dq nowait 379keyword. 380Normally 381(or if a value of zero is specified) there is no maximum. 382Otherwise, 383once the maximum is reached, further connection attempts will be 384queued up until an existing child process exits. 385This also works 386in the case of 387.Dq wait 388mode, although a value other than one (the 389default) might not make sense in some cases. 390You can also specify the maximum number of connections per minute 391for a given IP address by appending 392a 393.Dq / 394followed by the number to the maximum number of 395outstanding child processes. 396Once the maximum is reached, further 397connections from this IP address will be dropped until the end of the 398minute. 399In addition, you can specify the maximum number of simultaneous 400invocations of each service from a single IP address by appending a 401.Dq / 402followed by the number to the maximum number of outstanding child 403processes. Once the maximum is reached, further connections from this 404IP address will be dropped. 405.Pp 406The 407.Em user 408entry should contain the user name of the user as whom the server 409should run. This allows for servers to be given less permission 410than root. 411Optional 412.Em group 413part separated by 414.Dq \&: 415allows to specify group name different 416than default group for this user. 417Optional 418.Em login-class 419part separated by 420.Dq / 421allows to specify login class different 422than default 423.Dq daemon 424login class. 425.Pp 426The 427.Em server-program 428entry should contain the pathname of the program which is to be 429executed by 430.Nm 431when a request is found on its socket. If 432.Nm 433provides this service internally, this entry should 434be 435.Dq internal . 436.Pp 437The 438.Em server program arguments 439should be just as arguments 440normally are, starting with argv[0], which is the name of 441the program. If the service is provided internally, the 442.Em service-name 443of the service (and any arguments to it) or the word 444.Dq internal 445should take the place of this entry. 446.Pp 447Currently, the only internal service to take arguments is 448.Dq auth . 449Without options, the service will always return 450.Dq ERROR\ : HIDDEN-USER . 451The available arguments to this service that alter its behavior are: 452.Bl -tag -width indent 453.It Fl d Ar fallback 454Provide a 455.Ar fallback 456username. 457If the real 458.Dq auth 459service is enabled 460(with the 461.Fl r 462option discussed below), 463return this username instead of an error 464when lookups fail 465for either socket credentials or the username. 466If the real 467.Dq auth 468service is disabled, 469return this username for every request. 470This is primarily useful when running this service on a NAT machine. 471.It Fl g 472Instead of returning 473the user's name to the ident requester, 474report a 475username made up of random alphanumeric characters, 476e.g.\& 477.Dq c0c993 . 478The 479.Fl g 480flag overrides not only the user names, 481but also any fallback name, 482.Pa .fakeid 483or 484.Pa .noident 485files. 486.It Fl t Xo 487.Ar sec Ns Op . Ns Ar usec 488.Xc 489Specify a timeout for the service. 490The default timeout is 10.0 seconds. 491.It Fl r 492Offer a real 493.Dq auth 494service, as per RFC 1413. 495All the remaining flags apply only in this case. 496.It Fl i 497Return numeric user IDs instead of usernames. 498.It Fl f 499If the file 500.Pa .fakeid 501exists in the home directory of the identified user, report the username 502found in that file instead of the real username. 503If the username found in 504.Pa .fakeid 505is that of an existing user, 506then the real username is reported. 507If the 508.Fl i 509flag is also given then the username in 510.Pa .fakeid 511is checked against existing user IDs instead. 512.It Fl F 513same as 514.Fl f 515but without the restriction that the username in 516.Pa .fakeid 517must not match an existing user. 518.It Fl n 519If the file 520.Pa .noident 521exists in the home directory of the identified user, return 522.Dq ERROR\ : HIDDEN-USER . 523This overrides any 524.Pa fakeid 525file which might exist. 526.It Fl o Ar osname 527Use 528.Ar osname 529instead of the name of the system as reported by 530.Xr uname 3 . 531.El 532.Pp 533The 534.Nm 535utility also provides several other 536.Dq trivial 537services internally by use of 538routines within itself. These services are 539.Dq echo , 540.Dq discard , 541.Dq chargen 542(character generator), 543.Dq daytime 544(human readable time), and 545.Dq time 546(machine readable time, in the form of the number of seconds since 547midnight, January 1, 1900). All of these services are available in 548both TCP and UDP versions; the UDP versions will refuse service if the 549request specifies a reply port corresponding to any internal service. 550(This is done as a defense against looping attacks; the remote IP address 551is logged.) 552For details of these services, consult the 553appropriate 554.Tn RFC 555document. 556.Pp 557The TCPMUX-demultiplexing service is also implemented as an internal service. 558For any TCPMUX-based service to function, the following line must be included 559in 560.Pa inetd.conf : 561.Bd -literal -offset indent 562tcpmux stream tcp nowait root internal 563.Ed 564.Pp 565When given the 566.Fl l 567option 568.Nm 569will log an entry to syslog each time a connection is accepted, noting the 570service selected and the IP-number of the remote requester if available. 571Unless otherwise specified in the configuration file, 572and in the absence of the 573.Fl W 574and 575.Fl w 576options, 577.Nm 578will log to the 579.Dq daemon 580facility. 581.Pp 582The 583.Nm 584utility rereads its configuration file when it receives a hangup signal, 585.Dv SIGHUP . 586Services may be added, deleted or modified when the configuration file 587is reread. 588Except when started in debugging mode, 589.Nm 590records its process ID in the file 591.Pa /var/run/inetd.pid 592to assist in reconfiguration. 593.Sh IMPLEMENTATION NOTES 594.Ss TCP Wrappers 595When given the 596.Fl w 597option, 598.Nm 599will wrap all services specified as 600.Dq stream nowait 601or 602.Dq dgram 603except for 604.Dq internal 605services. 606If the 607.Fl W 608option is given, such 609.Dq internal 610services will be wrapped. 611If both options are given, wrapping for both 612internal and external services will be enabled. 613Either wrapping option 614will cause failed connections to be logged to the 615.Dq auth 616syslog facility. 617Adding the 618.Fl l 619flag to the wrapping options will include successful connections in the 620logging to the 621.Dq auth 622facility. 623.Pp 624Note that 625.Nm 626only wraps requests for a 627.Dq wait 628service while no servers are available to service requests. 629Once a 630connection to such a service has been allowed, 631.Nm 632has no control 633over subsequent connections to the service until no more servers 634are left listening for connection requests. 635.Pp 636When wrapping is enabled, the 637.Pa tcpd 638daemon is not required, as that functionality is builtin. 639For more information on TCP Wrappers, see the relevant documentation 640.Pq Xr hosts_access 5 . 641When reading that document, keep in mind that 642.Dq internal 643services have no associated daemon name. 644Therefore, the service name 645as specified in 646.Pa inetd.conf 647should be used as the daemon name for 648.Dq internal 649services. 650.Ss TCPMUX 651.Tn RFC 1078 652describes the TCPMUX protocol: 653``A TCP client connects to a foreign host on TCP port 1. It sends the 654service name followed by a carriage-return line-feed <CRLF>. The 655service name is never case sensitive. The server replies with a 656single character indicating positive (+) or negative (\-) 657acknowledgment, immediately followed by an optional message of 658explanation, terminated with a <CRLF>. If the reply was positive, 659the selected protocol begins; otherwise the connection is closed.'' 660The program is passed the TCP connection as file descriptors 0 and 1. 661.Pp 662If the TCPMUX service name begins with a 663.Dq + , 664.Nm 665returns the positive reply for the program. 666This allows you to invoke programs that use stdin/stdout 667without putting any special server code in them. 668.Pp 669The special service name 670.Dq help 671causes 672.Nm 673to list TCPMUX services in 674.Pa inetd.conf . 675.Ss Ux Domain Sockets 676In addition to running services on IP sockets, 677.Nm 678can also manage 679.Ux 680domain sockets. 681To do this you specify a 682.Em protocol 683of 684.Dq unix 685and specify the 686.Ux 687domain socket as the 688.Em service-name . 689The 690.Em service-type 691may be 692.Dq stream 693or 694.Dq dgram . 695The specification of the socket must be 696an absolute path name, 697optionally prefixed by an owner and mode 698of the form 699.Em :user:group:mode: . 700The specification: 701.Pp 702.Dl ":news:daemon:220:/var/run/sock" 703.Pp 704creates a socket owned 705by user 706.Dq news 707in group 708.Dq daemon 709with permissions allowing only that user and group to connect. 710The default owner is the user that 711.Nm 712is running as. 713The default mode only allows the socket's owner to connect. 714.Pp 715.Sy WARNING : 716while creating 717.Ux 718domain socket, 719.Nm 720must change the ownership and permissions on the socket. 721This can only be done securely if 722the directory in which the socket is created 723is writable only by root. 724Do 725.Em NOT 726use 727.Nm 728to create sockets in world writable directories, 729such as 730.Pa /tmp , 731instead use 732.Pa /var/run 733or a similar directory. 734.Pp 735Internal services may be run on 736.Ux 737domain sockets, in the usual way. 738In this case 739the name of the internal service 740is determined using 741the last component of the socket's pathname. 742.Sh FILES 743.Bl -tag -width /var/run/inetd.pid -compact 744.It Pa /etc/inetd.conf 745configuration file 746.It Pa /etc/rpc 747translation of service names to RPC program numbers 748.It Pa /etc/services 749translation of service names to port numbers 750.It Pa /var/run/inetd.pid 751the pid of the currently running 752.Nm 753.El 754.Sh EXAMPLES 755Here are several example service entries for the various types of services: 756.Bd -literal 757ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l 758ntalk dgram udp wait root /usr/libexec/ntalkd ntalkd 759telnet stream tcp6 nowait root /usr/libexec/telnetd telnetd 760shell stream tcp46 nowait root /usr/local/sbin/rshd rshd 761tcpmux/+date stream tcp nowait guest /bin/date date 762tcpmux/phonebook stream tcp nowait guest /usr/local/bin/phonebook phonebook 763rstatd/1-3 dgram rpc/udp wait root /usr/libexec/rpc.rstatd rpc.rstatd 764/var/run/echo stream unix nowait root internal 765.Ed 766.Sh ERROR MESSAGES 767The 768.Nm 769server 770logs error messages using 771.Xr syslog 3 . 772Important error messages and their explanations are: 773.Pp 774.Bl -ohang -compact 775.It Xo 776.Ar service Ns / Ns Ar protocol 777.No "server failing (looping), service terminated." 778.Xc 779The number of requests for the specified service in the past minute 780exceeded the limit. 781The limit exists to prevent a broken program 782or a malicious user from swamping the system. 783This message may occur for several reasons: 784.Bl -enum -offset indent 785.It 786There are many hosts requesting the service within a short time period. 787.It 788A broken client program is requesting the service too frequently. 789.It 790A malicious user is running a program to invoke the service in 791a denial-of-service attack. 792.It 793The invoked service program has an error that causes clients 794to retry quickly. 795.El 796.Pp 797Use the 798.Fl R Ar rate 799option, 800as described above, to change the rate limit. 801Once the limit is reached, the service will be 802reenabled automatically in 10 minutes. 803.Pp 804.It Xo 805.Ar service Ns / Ns Ar protocol : 806.No \&No such user 807.Ar user , 808.No service ignored 809.Xc 810.It Xo 811.Ar service Ns / Ns Ar protocol : 812.No getpwnam : 813.Ar user : 814.No \&No such user 815.Xc 816No entry for 817.Ar user 818exists in the 819.Xr passwd 5 820database. 821The first message 822occurs when 823.Nm 824(re)reads the configuration file. 825The second message occurs when the 826service is invoked. 827.Pp 828.It Xo 829.Ar service : 830.No can't set uid 831.Ar uid 832.Xc 833.It Xo 834.Ar service : 835.No can't set gid 836.Ar gid 837.Xc 838The user or group ID for the entry's 839.Ar user 840field is invalid. 841.Pp 842.It "setsockopt(SO_PRIVSTATE): Operation not supported" 843The 844.Nm 845utility attempted to renounce the privileged state associated with a 846socket but was unable to. 847.El 848.Sh SEE ALSO 849.Xr hosts_access 5 , 850.Xr hosts_options 5 , 851.Xr login.conf 5 , 852.Xr passwd 5 , 853.Xr rpc 5 , 854.Xr services 5 , 855.Xr comsat 8 , 856.Xr fingerd 8 , 857.Xr ftpd 8 , 858.Xr rlogind 8 Pq Pa net/bsdrcmds , 859.Xr rpcbind 8 , 860.Xr rshd 8 Pq Pa net/bsdrcmds , 861.Xr telnetd 8 , 862.Xr tftpd 8 863.Rs 864.%A Michael C. St. Johns 865.%T Identification Protocol 866.%O RFC 1413 867.Re 868.Sh HISTORY 869The 870.Nm 871utility appeared in 872.Bx 4.3 . 873TCPMUX is based on code and documentation by Mark Lottor. 874Support for 875.Tn "ONC RPC" 876based services is modeled after that 877provided by 878.Tn SunOS 8794.1. 880The 881.Fx 882TCP Wrappers support first appeared in 883.Fx 3.2 . 884