1 .\" Copyright (c) 1985, 1991, 1993, 1994
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
28 .\" from: @(#)inetd.8 8.3 (Berkeley) 4/13/94
46 .Op Ar configuration_file
50 utility should be run at boot time by
54 It then listens for connections on certain
56 When a connection is found on one
57 of its sockets, it decides what service the socket
58 corresponds to, and invokes a program to service the request.
59 The server program is invoked with the service socket
60 as its standard input, output and error descriptors.
64 continues to listen on the socket (except in some cases which
65 will be described below).
68 allows running one daemon to invoke several others,
69 reducing load on the system.
71 The following options are available:
72 .Bl -tag -width indent
74 Specify one specific IP address to bind to.
75 Alternatively, a hostname can be specified,
76 in which case the IPv4 or IPv6 address
77 which corresponds to that hostname is used.
78 Usually a hostname is specified when
82 in which case the hostname corresponds to that of the
86 When the hostname specification is used
87 and both IPv4 and IPv6 bindings are desired,
88 one entry with the appropriate
91 is required for each service in
94 a TCP-based service would need two entries,
101 See the explanation of the
106 Specify the default maximum number of times a service can be invoked
107 from a single IP address in one minute; the default is unlimited.
108 May be overridden on a per-service basis with the
109 "max-connections-per-ip-per-minute" parameter.
111 Specify the default maximum number of
112 simultaneous invocations of each service;
113 the default is unlimited.
114 May be overridden on a per-service basis with the "max-child"
119 Turn on logging of successful connections.
121 Specify an alternate file in which to store the process ID.
123 Specify the maximum number of times a service can be invoked
124 in one minute; the default is 256.
125 A rate of 0 allows an unlimited number of invocations.
127 Specify the default maximum number of
128 simultaneous invocations of each service from a single IP address;
129 the default is unlimited.
130 May be overridden on a per-service basis with the "max-child-per-ip"
133 Turn on TCP Wrapping for internal services which are built in to
136 Turn on TCP Wrapping for external services.
138 .Sx "IMPLEMENTATION NOTES"
139 section for more information on TCP Wrappers support.
144 reads its configuration information from a configuration
145 file which, by default, is
146 .Pa /etc/inetd.conf .
147 There must be an entry for each field of the configuration
148 file, with entries for each field separated by a tab or
150 Comments are denoted by a
154 There must be an entry for each field.
156 fields of the configuration file are as follows:
158 .Bd -unfilled -offset indent -compact
162 {wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]]
163 user[:group][/login-class]
165 server-program-arguments
170 service, the entry would contain these fields:
172 .Bd -unfilled -offset indent -compact
176 {wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]]
177 user[:group][/login-class]
179 server-program-arguments
182 There are two types of services that
184 can start: standard and TCPMUX.
185 A standard service has a well-known port assigned to it;
186 it may be a service that implements an official Internet standard or is a
191 TCPMUX services are nonstandard services that do not have a
192 well-known port assigned to them.
193 They are invoked from
195 when a program connects to the
197 well-known port and specifies
199 This feature is useful for adding locally-developed servers.
200 TCPMUX requests are only accepted when the multiplexor service itself
201 is enabled, above and beyond and specific TCPMUX-based servers; see the
202 discussion of internal services below.
206 entry is the name of a valid service in
209 or the specification of a
211 domain socket (see below).
214 services (discussed below), the service
217 be the official name of the service (that is, the first entry in
218 .Pa /etc/services ) .
219 When used to specify an
221 service, this field is a valid RPC service name listed in
224 The part on the right of the
226 is the RPC version number.
228 can simply be a single numeric argument or a range of versions.
229 A range is bounded by the low version to the high version -
231 For TCPMUX services, the value of the
233 field consists of the string
235 followed by a slash and the
236 locally-chosen service name.
237 The service names listed in
242 Try to choose unique names for your TCPMUX services by prefixing them with
243 your organization's name and suffixing them with a version number.
254 depending on whether the socket is a stream, datagram, raw,
255 reliably delivered message, or sequenced packet socket.
256 TCPMUX services must use
261 must be a valid protocol or
267 both of which imply IPv4 for backward compatibility.
282 specify that the entry accepts both IPv4 and IPv6 connections
287 are specified with the
292 One can use specify IPv4 and/or IPv6 with the 4, 6 or 46 suffix, for example
296 TCPMUX services must use
305 entry specifies whether the server that is invoked by
308 the socket associated with the service access point, and thus whether
310 should wait for the server to exit before listening for new service
312 Datagram servers must use
314 as they are always invoked with the original datagram socket bound
315 to the specified service address.
316 These servers must read at least one datagram from the socket
318 If a datagram server connects
319 to its peer, freeing the socket so
321 can receive further messages on the socket, it is said to be
325 it should read one datagram from the socket and create a new socket
326 connected to the peer.
327 It should fork, and the parent should then exit
330 to check for new service requests to spawn new servers.
331 Datagram servers which process all incoming datagrams
332 on a socket and eventually time out are said to be
333 .Dq single-threaded .
338 utilities are examples of the latter type of
342 utility is an example of a multi-threaded datagram server.
344 Servers using stream sockets generally are multi-threaded and
348 Connection requests for these services are accepted by
350 and the server is given only the newly-accepted socket connected
351 to a client of the service.
352 Most stream-based services operate in this manner.
353 Stream-based servers that use
355 are started with the listening service socket, and must accept
356 at least one connection request before exiting.
357 Such a server would normally accept and process incoming connection
358 requests until a timeout.
359 TCPMUX services must use
362 The maximum number of outstanding child processes (or
366 service may be explicitly specified by appending a
368 followed by the number to the
372 (or if a value of zero is specified) there is no maximum.
374 once the maximum is reached, further connection attempts will be
375 queued up until an existing child process exits.
379 mode, although a value other than one (the
380 default) might not make sense in some cases.
381 You can also specify the maximum number of connections per minute
382 for a given IP address by appending
385 followed by the number to the maximum number of
386 outstanding child processes.
387 Once the maximum is reached, further
388 connections from this IP address will be dropped until the end of the
390 In addition, you can specify the maximum number of simultaneous
391 invocations of each service from a single IP address by appending a
393 followed by the number to the maximum number of outstanding child
395 Once the maximum is reached, further connections from this
396 IP address will be dropped.
400 entry should contain the user name of the user as whom the server
402 This allows for servers to be given less permission
408 allows a group name other
409 than the default group for this user to be specified.
414 allows specification of a login class other
421 entry should contain the pathname of the program which is to be
424 when a request is found on its socket.
427 provides this service internally, this entry should
432 .Em server-program-arguments
433 entry lists the arguments to be passed to the
435 starting with argv[0], which usually is the name of
437 If the service is provided internally, the
439 of the service (and any arguments to it) or the word
441 should take the place of this entry.
443 Currently, the only internal service to take arguments is
445 Without options, the service will always return
446 .Dq ERROR\ : HIDDEN-USER .
447 The available arguments to this service that alter its behavior are:
448 .Bl -tag -width indent
458 option discussed below),
459 return this username instead of an error
461 for either socket credentials or the username.
465 return this username for every request.
466 This is primarily useful when running this service on a NAT machine.
470 but without the restriction that the username in
472 must not match an existing user.
476 exists in the home directory of the identified user, report the username
477 found in that file instead of the real username.
478 If the username found in
480 is that of an existing user,
481 then the real username is reported.
484 flag is also given then the username in
486 is checked against existing user IDs instead.
489 the user's name to the ident requester,
491 username made up of random alphanumeric characters,
496 flag overrides not only the user names,
497 but also any fallback name,
503 Return numeric user IDs instead of usernames.
507 exists in the home directory of the identified user, return
508 .Dq ERROR\ : HIDDEN-USER .
511 file which might exist.
515 instead of the name of the system as reported by
520 service, as per RFC 1413.
521 All the remaining flags apply only in this case.
523 .Ar sec Ns Op Cm \&. Ns Ar usec
525 Specify a timeout for the service.
526 The default timeout is 10.0 seconds.
531 utility also provides several other
533 services internally by use of
534 routines within itself.
539 (character generator),
541 (human readable time), and
543 (machine readable time, in the form of the number of seconds since
544 midnight, January 1, 1900).
545 All of these services are available in
546 both TCP and UDP versions; the UDP versions will refuse service if the
547 request specifies a reply port corresponding to any internal service.
548 (This is done as a defense against looping attacks; the remote IP address
550 For details of these services, consult the
555 The TCPMUX-demultiplexing service is also implemented as an internal service.
556 For any TCPMUX-based service to function, the following line must be included
559 .Bd -literal -offset indent
560 tcpmux stream tcp nowait root internal
567 will log an entry to syslog each time a connection is accepted, noting the
568 service selected and the IP-number of the remote requester if available.
569 Unless otherwise specified in the configuration file,
570 and in the absence of the
582 utility rereads its configuration file when it receives a hangup signal,
584 Services may be added, deleted or modified when the configuration file
586 Except when started in debugging mode,
587 or configured otherwise with the
591 records its process ID in the file
592 .Pa /var/run/inetd.pid
593 to assist in reconfiguration.
594 .Sh IMPLEMENTATION NOTES
600 will wrap all services specified as
609 option is given, such
611 services will be wrapped.
612 If both options are given, wrapping for both
613 internal and external services will be enabled.
614 Either wrapping option
615 will cause failed connections to be logged to the
620 flag to the wrapping options will include successful connections in the
627 only wraps requests for a
629 service while no servers are available to service requests.
631 connection to such a service has been allowed,
634 over subsequent connections to the service until no more servers
635 are left listening for connection requests.
637 When wrapping is enabled, the
639 daemon is not required, as that functionality is builtin.
640 For more information on TCP Wrappers, see the relevant documentation
641 .Pq Xr hosts_access 5 .
642 When reading that document, keep in mind that
644 services have no associated daemon name.
645 Therefore, the service name
648 should be used as the daemon name for
653 describes the TCPMUX protocol:
654 ``A TCP client connects to a foreign host on TCP port 1.
656 service name followed by a carriage-return line-feed <CRLF>.
658 service name is never case sensitive.
659 The server replies with a
660 single character indicating positive (+) or negative (\-)
661 acknowledgment, immediately followed by an optional message of
662 explanation, terminated with a <CRLF>.
663 If the reply was positive,
664 the selected protocol begins; otherwise the connection is closed.''
665 The program is passed the TCP connection as file descriptors 0 and 1.
667 If the TCPMUX service name begins with a
670 returns the positive reply for the program.
671 This allows you to invoke programs that use stdin/stdout
672 without putting any special server code in them.
674 The special service name
678 to list the TCPMUX services which are enabled in
681 The implementation includes a tiny hack
682 to support IPsec policy settings for each socket.
683 A special form of comment line, starting with
685 is interpreted as a policy specifier.
688 will be used as an IPsec policy string,
690 .Xr ipsec_set_policy 3 .
692 policy specifier is applied to all the following lines in
694 until the next policy specifier.
695 An empty policy specifier resets the IPsec policy.
697 If an invalid IPsec policy specifier appears in
700 will provide an error message via the
702 interface and abort execution.
703 .Ss Ux Domain Sockets
704 In addition to running services on IP sockets,
709 To do this you specify a
723 The specification of the socket must be
724 an absolute path name,
725 optionally prefixed by an owner and mode
727 .Em ":user:group:mode\&:" .
730 .Dl ":news:daemon:220:/var/run/sock"
732 creates a socket owned
737 with permissions allowing only that user and group to connect.
738 The default owner is the user that
741 The default mode only allows the socket's owner to connect.
748 must change the ownership and permissions on the socket.
749 This can only be done securely if
750 the directory in which the socket is created
751 is writable only by root.
756 to create sockets in world writable directories
761 or a similar directory instead.
763 Internal services may be run on
765 domain sockets, in the usual way.
767 the name of the internal service
769 the last component of the socket's pathname.
770 For example, specifying a socket named
774 service when a connection is received on that socket.
776 .Bl -tag -width /var/run/inetd.pid -compact
777 .It Pa /etc/inetd.conf
779 .It Pa /etc/netconfig
780 network configuration data base
782 translation of service names to RPC program numbers
784 translation of service names to port numbers
785 .It Pa /var/run/inetd.pid
786 the pid of the currently running
790 Here are several example service entries for the various types of services:
792 # The first four launch the relevant daemon when a connection on a port
793 # as defined by /etc/services is opened.
794 ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l
795 ntalk dgram udp wait root /usr/libexec/ntalkd ntalkd
796 telnet stream tcp6 nowait root /usr/libexec/telnetd telnetd
797 shell stream tcp46 nowait root /usr/libexec/rshd rshd
799 # Let the system respond to date requests via tcpmux
800 tcpmux/+date stream tcp nowait guest /bin/date date
802 # Let people access the system phonebook via tcpmux
803 tcpmux/phonebook stream tcp nowait guest /usr/local/bin/phonebook phonebook
805 # Make kernel statistics accessible
806 rstatd/1-3 dgram rpc/udp wait root /usr/libexec/rpc.rstatd rpc.rstatd
808 # Use netcat as a one-shot HTTP proxy with nc (from freebsd-tips fortune)
809 http stream tcp nowait nobody /usr/bin/nc nc -N dest-ip 80
811 # Set up a unix socket at /var/run/echo that echo's back whatever is written
813 /var/run/echo stream unix nowait root internal
815 # Run chargen for IPsec Authentication Headers
817 chargen stream tcp nowait root internal
824 logs error messages using
826 Important error messages and their explanations are:
830 .Ar service Ns / Ns Ar protocol
831 .No "server failing (looping), service terminated."
833 The number of requests for the specified service in the past minute
835 The limit exists to prevent a broken program
836 or a malicious user from swamping the system.
837 This message may occur for several reasons:
838 .Bl -enum -offset indent
840 There are many hosts requesting the service within a short time period.
842 A broken client program is requesting the service too frequently.
844 A malicious user is running a program to invoke the service in
845 a denial-of-service attack.
847 The invoked service program has an error that causes clients
854 as described above, to change the rate limit.
855 Once the limit is reached, the service will be
856 reenabled automatically in 10 minutes.
859 .Ar service Ns / Ns Ar protocol :
865 .Ar service Ns / Ns Ar protocol :
878 (re)reads the configuration file.
879 The second message occurs when the
892 The user or group ID for the entry's
896 .It "setsockopt(SO_PRIVSTATE): Operation not supported"
899 utility attempted to renounce the privileged state associated with a
900 socket but was unable to.
907 No entry was found for either
920 No entry was found for either
930 .Xr ipsec_set_policy 3 ,
932 .Xr hosts_options 5 ,
948 .%A Michael C. St. Johns
949 .%T Identification Protocol
957 TCPMUX is based on code and documentation by Mark Lottor.
959 ONC RPC-based services is modeled after that
963 The IPsec hack was contributed by the KAME project in 1999.
966 TCP Wrappers support first appeared in