1.\" $OpenBSD: inetd.8,v 1.33 2008/06/28 10:54:45 sobrado Exp $ 2.\" Copyright (c) 1985, 1991 The Regents of the University of California. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. Neither the name of the University nor the names of its contributors 14.\" may be used to endorse or promote products derived from this software 15.\" without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" from: @(#)inetd.8 6.7 (Berkeley) 3/16/91 30.\" 31.Dd $Mdocdate: June 28 2008 $ 32.Dt INETD 8 33.Os 34.Sh NAME 35.Nm inetd 36.Nd internet 37.Dq super-server 38.Sh SYNOPSIS 39.Nm inetd 40.Op Fl d 41.Op Fl R Ar rate 42.Op Ar configuration_file 43.Sh DESCRIPTION 44.Nm inetd 45should be run at boot time by 46.Pa /etc/rc 47(see 48.Xr rc 8 ) . 49It then listens for connections on certain internet sockets. 50When a connection is found on one 51of its sockets, it decides what service the socket 52corresponds to, and invokes a program to service the request. 53After the program is 54finished, it continues to listen on the socket (except in some cases which 55will be described below). 56Essentially, 57.Nm inetd 58allows running one daemon to invoke several others, 59reducing load on the system. 60.Pp 61The options are as follows: 62.Bl -tag -width Ds 63.It Fl d 64Turns on debugging. 65.It Fl R Ar rate 66Specify the maximum number of times a service can be invoked 67in one minute; the default is 256. 68If a service exceeds this limit, 69.Nm 70will log the problem 71and stop servicing requests for the specific service for ten minutes. 72See also the wait/nowait configuration fields below. 73.El 74.Pp 75Upon execution, 76.Nm inetd 77reads its configuration information from a configuration 78file which, by default, is 79.Pa /etc/inetd.conf . 80There must be an entry for each field of the configuration 81file, with entries for each field separated by a tab or 82a space. 83Comments are denoted by a 84.Dq # 85at the beginning 86of a line. 87The fields of the configuration file are as follows: 88.Bd -unfilled -offset indent 89service name 90socket type 91protocol 92wait/nowait[.max] 93user[.group] or user[:group] 94server program 95server program arguments 96.Ed 97.Pp 98To specify a Sun-RPC 99based service, the entry would contain these fields. 100.Bd -unfilled -offset indent 101service name/version 102socket type 103rpc/protocol 104wait/nowait[.max] 105user[.group] or user[:group] 106server program 107server program arguments 108.Ed 109.Pp 110For internet services, the first field of the line may also have a host 111address specifier prefixed to it, separated from the service name by a 112colon. 113If this is done, the string before the colon in the first field 114indicates what local address 115.Nm 116should use when listening for that service. 117Multiple local addresses 118can be specified on the same line, separated by commas. 119Numeric IP 120addresses in dotted-quad notation can be used as well as symbolic 121hostnames. 122Symbolic hostnames are looked up using 123.Fn gethostbyname . 124If a hostname has multiple address mappings, inetd creates a socket 125to listen on each address. 126.Pp 127The single character 128.Dq \&* 129indicates 130.Dv INADDR_ANY , 131meaning 132.Dq all local addresses . 133To avoid repeating an address that occurs frequently, a line with a 134host address specifier and colon, but no further fields, causes the 135host address specifier to be remembered and used for all further lines 136with no explicit host specifier (until another such line or the end of 137the file). 138A line 139.Dl *: 140is implicitly provided at the top of the file; thus, traditional 141configuration files (which have no host address specifiers) will be 142interpreted in the traditional manner, with all services listened for 143on all local addresses. 144If the protocol is 145.Dq unix , 146this value is ignored. 147.Pp 148The 149.Em service name 150entry is the name of a valid service in 151the file 152.Pa /etc/services . 153For 154.Dq internal 155services (discussed below), the service 156name 157.Em must 158be the official name of the service (that is, the first entry in 159.Pa /etc/services ) . 160When used to specify a Sun-RPC 161based service, this field is a valid RPC service name in 162the file 163.Pa /etc/rpc . 164The part on the right of the 165.Dq / 166is the RPC version number. 167This can simply be a single numeric argument or a range of versions. 168A range is bounded by the low version to the high version - 169.Dq rusers/1-3 . 170For 171.Ux 172domain sockets this field specifies the path name of the socket. 173.Pp 174The 175.Em socket type 176should be one of 177.Dq stream , 178.Dq dgram , 179.Dq raw , 180.Dq rdm , 181or 182.Dq seqpacket , 183depending on whether the socket is a stream, datagram, raw, 184reliably delivered message, or sequenced packet socket. 185.Pp 186The 187.Em protocol 188must be a valid protocol as given in 189.Pa /etc/protocols . 190Examples might be 191.Dq tcp 192or 193.Dq udp . 194RPC based services are specified with the 195.Dq rpc/tcp 196or 197.Dq rpc/udp 198service type. 199.Dq tcp 200and 201.Dq udp 202will be recognized as 203.Dq TCP or UDP over default IP version . 204This is currently IPv4, but in the future it will be IPv6. 205If you need to specify IPv4 or IPv6 explicitly, use something like 206.Dq tcp4 207or 208.Dq udp6 . 209A 210.Em protocol 211of 212.Dq unix 213is used to specify a socket in the 214.Ux 215domain. 216.Pp 217The 218.Em wait/nowait 219entry is used to tell 220.Nm 221if it should wait for the server program to return, 222or continue processing connections on the socket. 223If a datagram server connects 224to its peer, freeing the socket so 225.Nm inetd 226can receive further messages on the socket, it is said to be 227a 228.Dq multi-threaded 229server, and should use the 230.Dq nowait 231entry. 232For datagram servers which process all incoming datagrams 233on a socket and eventually time out, the server is said to be 234.Dq single-threaded 235and should use a 236.Dq wait 237entry. 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 exception; it is a datagram server that establishes pseudo-connections. 246It must be listed as 247.Dq wait 248in order to avoid a race; 249the server reads the first packet, creates a new socket, 250and then forks and exits to allow 251.Nm inetd 252to check for new service requests to spawn new servers. 253The optional 254.Dq max 255suffix (separated from 256.Dq wait 257or 258.Dq nowait 259by a dot) specifies the maximum number of times a service can be invoked 260in one minute; the default is 256. 261If a service exceeds this limit, 262.Nm 263will log the problem 264and stop servicing requests for the specific service for ten minutes. 265See also the 266.Fl R 267option above. 268.Pp 269Stream servers are usually marked as 270.Dq nowait 271but if a single server process is to handle multiple connections, it may be 272marked as 273.Dq wait . 274The master socket will then be passed as fd 0 to the server, which will then 275need to accept the incoming connection. 276The server should eventually time 277out and exit when no more connections are active. 278.Nm 279will continue to 280listen on the master socket for connections, so the server should not close 281it when it exits. 282.Pp 283The 284.Em user 285entry should contain the user name of the user as whom the server 286should run. 287This allows for servers to be given less permission 288than root. 289An optional group name can be specified by appending a dot to 290the user name followed by the group name. 291This allows for servers to run with 292a different (primary) group ID than specified in the password file. 293If a group 294is specified and user is not root, the supplementary groups associated with 295that user will still be set. 296.Pp 297The 298.Em server program 299entry should contain the pathname of the program which is to be 300executed by 301.Nm inetd 302when a request is found on its socket. 303If 304.Nm inetd 305provides this service internally, this entry should 306be 307.Dq internal . 308.Pp 309The 310.Em server program arguments 311should be just as arguments 312normally are, starting with argv[0], which is the name of 313the program. 314If the service is provided internally, the word 315.Dq internal 316should take the place of this entry. 317.Pp 318.Nm inetd 319provides several 320.Dq trivial 321services internally by use of routines within itself. 322These services are 323.Dq echo , 324.Dq discard , 325.Dq chargen 326(character generator), 327.Dq daytime 328(human readable time), and 329.Dq time 330(machine readable time, 331in the form of the number of seconds since midnight, January 3321, 1900). 333All of these services are TCP based. 334For details of these services, consult the appropriate 335.Tn RFC 336from the Network Information Center. 337.Pp 338.Nm inetd 339rereads its configuration file when it receives a hangup signal, 340.Dv SIGHUP . 341Services may be added, deleted or modified when the configuration file 342is reread. 343.Nm inetd 344creates a file 345.Em /var/run/inetd.pid 346that contains its process identifier. 347.Ss IPv6 TCP/UDP behavior 348If you wish to run a server for IPv4 and IPv6 traffic, 349you'll need to run two separate processes for the same server program, 350specified as two separate lines in 351.Pa inetd.conf , 352for 353.Dq tcp4 354and 355.Dq tcp6 . 356.Pp 357Under various combinations of IPv4/v6 daemon settings, 358.Nm 359will behave as follows: 360.Bl -bullet -compact 361.It 362If you have only one server on 363.Dq tcp4 , 364IPv4 traffic will be routed to the server. 365IPv6 traffic will not be accepted. 366.It 367If you have two servers on 368.Dq tcp4 369and 370.Dq tcp6 , 371IPv4 traffic will be routed to the server on 372.Dq tcp4 , 373and IPv6 traffic will go to server on 374.Dq tcp6 . 375.It 376If you have only one server on 377.Dq tcp6 , 378only IPv6 traffic will be routed to the server. 379.El 380.Sh SEE ALSO 381.Xr comsat 8 , 382.Xr fingerd 8 , 383.Xr ftp-proxy 8 , 384.Xr ftpd 8 , 385.Xr identd 8 , 386.Xr rshd 8 , 387.Xr talkd 8 , 388.Xr tftpd 8 389.Sh HISTORY 390The 391.Nm 392command appeared in 393.Bx 4.3 . 394Support for Sun-RPC 395based services is modelled after that 396provided by SunOS 4.1. 397IPv6 support was added by the KAME project in 1999. 398.Sh BUGS 399Host address specifiers, while they make conceptual sense for RPC 400services, do not work entirely correctly. 401This is largely because the 402portmapper interface does not provide a way to register different ports 403for the same service on different local addresses. 404Provided you never 405have more than one entry for a given RPC service, everything should 406work correctly. 407(Note that default host address specifiers do apply to 408RPC lines with no explicit specifier.) 409