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.\" 4. 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
| 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.\" 4. 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
|
180user[:group][/login-class]
181server-program
182server-program-arguments
183.Ed
184.Pp
185There are two types of services that
186.Nm
187can start: standard and TCPMUX.
188A standard service has a well-known port assigned to it;
189it may be a service that implements an official Internet standard or is a
190.Bx Ns -specific
191service.
192As described in
193.Tn RFC 1078 ,
194TCPMUX services are nonstandard services that do not have a
195well-known port assigned to them.
196They are invoked from
197.Nm
198when a program connects to the
199.Dq tcpmux
200well-known port and specifies
201the service name.
202This feature is useful for adding locally-developed servers.
203TCPMUX requests are only accepted when the multiplexor service itself
204is enabled, above and beyond and specific TCPMUX-based servers; see the
205discussion of internal services below.
206.Pp
207The
208.Em service-name
209entry is the name of a valid service in
210the file
211.Pa /etc/services ,
212or the specification of a
213.Ux
214domain socket (see below).
215For
216.Dq internal
217services (discussed below), the service
218name
219should
220be the official name of the service (that is, the first entry in
221.Pa /etc/services ) .
222When used to specify an
223.Tn "ONC RPC" Ns -based
224service, this field is a valid RPC service name listed in
225the file
226.Pa /etc/rpc .
227The part on the right of the
228.Dq /
229is the RPC version number.
230This
231can simply be a single numeric argument or a range of versions.
232A range is bounded by the low version to the high version -
233.Dq rusers/1-3 .
234For TCPMUX services, the value of the
235.Em service-name
236field consists of the string
237.Dq tcpmux
238followed by a slash and the
239locally-chosen service name.
240The service names listed in
241.Pa /etc/services
242and the name
243.Dq help
244are reserved.
245Try to choose unique names for your TCPMUX services by prefixing them with
246your organization's name and suffixing them with a version number.
247.Pp
248The
249.Em socket-type
250should be one of
251.Dq stream ,
252.Dq dgram ,
253.Dq raw ,
254.Dq rdm ,
255or
256.Dq seqpacket ,
257depending on whether the socket is a stream, datagram, raw,
258reliably delivered message, or sequenced packet socket.
259TCPMUX services must use
260.Dq stream .
261.Pp
262The
263.Em protocol
264must be a valid protocol or
265.Dq unix .
266Examples are
267.Dq tcp
268or
269.Dq udp ,
270both of which imply IPv4 for backward compatibility.
271The names
272.Dq tcp4
273and
274.Dq udp4
275specify IPv4 only.
276The names
277.Dq tcp6
278and
279.Dq udp6
280specify IPv6 only.
281The names
282.Dq tcp46
283and
284.Dq udp46
285specify that the entry accepts both IPv4 and IPv6 connections
286via a wildcard
287.Dv AF_INET6
288socket.
289Rpc based services
290are specified with the
291.Dq rpc/tcp
292or
293.Dq rpc/udp
294service type.
295One can use specify IPv4 and/or IPv6 with the 4, 6 or 46 suffix, for example
296.Dq rpc/tcp6
297or
298.Dq rpc/udp46 .
299TCPMUX services must use
300.Dq tcp ,
301.Dq tcp4 ,
302.Dq tcp6
303or
304.Dq tcp46 .
305.Pp
306The
307.Em wait/nowait
308entry specifies whether the server that is invoked by
309.Nm
310will take over
311the socket associated with the service access point, and thus whether
312.Nm
313should wait for the server to exit before listening for new service
314requests.
315Datagram servers must use
316.Dq wait ,
317as they are always invoked with the original datagram socket bound
318to the specified service address.
319These servers must read at least one datagram from the socket
320before exiting.
321If a datagram server connects
322to its peer, freeing the socket so
323.Nm
324can receive further messages on the socket, it is said to be
325a
326.Dq multi-threaded
327server;
328it should read one datagram from the socket and create a new socket
329connected to the peer.
330It should fork, and the parent should then exit
331to allow
332.Nm
333to check for new service requests to spawn new servers.
334Datagram servers which process all incoming datagrams
335on a socket and eventually time out are said to be
336.Dq single-threaded .
337The
338.Xr comsat 8
339and
340.Xr talkd 8
341utilities are examples of the latter type of
342datagram server.
343The
344.Xr tftpd 8
345utility is an example of a multi-threaded datagram server.
346.Pp
347Servers using stream sockets generally are multi-threaded and
348use the
349.Dq nowait
350entry.
351Connection requests for these services are accepted by
352.Nm ,
353and the server is given only the newly-accepted socket connected
354to a client of the service.
355Most stream-based services operate in this manner.
356Stream-based servers that use
357.Dq wait
358are started with the listening service socket, and must accept
359at least one connection request before exiting.
360Such a server would normally accept and process incoming connection
361requests until a timeout.
362TCPMUX services must use
363.Dq nowait .
364.Pp
365The maximum number of outstanding child processes (or
366.Dq threads )
367for a
368.Dq nowait
369service may be explicitly specified by appending a
370.Dq /
371followed by the number to the
372.Dq nowait
373keyword.
374Normally
375(or if a value of zero is specified) there is no maximum.
376Otherwise,
377once the maximum is reached, further connection attempts will be
378queued up until an existing child process exits.
379This also works
380in the case of
381.Dq wait
382mode, although a value other than one (the
383default) might not make sense in some cases.
384You can also specify the maximum number of connections per minute
385for a given IP address by appending
386a
387.Dq /
388followed by the number to the maximum number of
389outstanding child processes.
390Once the maximum is reached, further
391connections from this IP address will be dropped until the end of the
392minute.
393In addition, you can specify the maximum number of simultaneous
394invocations of each service from a single IP address by appending a
395.Dq /
396followed by the number to the maximum number of outstanding child
397processes.
398Once the maximum is reached, further connections from this
399IP address will be dropped.
400.Pp
401The
402.Em user
403entry should contain the user name of the user as whom the server
404should run.
405This allows for servers to be given less permission
406than root.
407The optional
408.Em group
409part separated by
410.Dq \&:
411allows a group name other
412than the default group for this user to be specified.
413The optional
414.Em login-class
415part separated by
416.Dq /
417allows specification of a login class other
418than the default
419.Dq daemon
420login class.
421.Pp
422The
423.Em server-program
424entry should contain the pathname of the program which is to be
425executed by
426.Nm
427when a request is found on its socket.
428If
429.Nm
430provides this service internally, this entry should
431be
432.Dq internal .
433.Pp
434The
435.Em server-program-arguments
436entry lists the arguments to be passed to the
437.Em server-program ,
438starting with argv[0], which usually is the name of
439the program.
440If the service is provided internally, the
441.Em service-name
442of the service (and any arguments to it) or the word
443.Dq internal
444should take the place of this entry.
445.Pp
446Currently, the only internal service to take arguments is
447.Dq auth .
448Without options, the service will always return
449.Dq ERROR\ : HIDDEN-USER .
450The available arguments to this service that alter its behavior are:
451.Bl -tag -width indent
452.It Fl d Ar fallback
453Provide a
454.Ar fallback
455username.
456If the real
457.Dq auth
458service is enabled
459(with the
460.Fl r
461option discussed below),
462return this username instead of an error
463when lookups fail
464for either socket credentials or the username.
465If the real
466.Dq auth
467service is disabled,
468return this username for every request.
469This is primarily useful when running this service on a NAT machine.
470.It Fl g
471Instead of returning
472the user's name to the ident requester,
473report a
474username made up of random alphanumeric characters,
475e.g.\&
476.Dq c0c993 .
477The
478.Fl g
479flag overrides not only the user names,
480but also any fallback name,
481.Pa .fakeid
482or
483.Pa .noident
484files.
485.It Fl t Xo
486.Ar sec Ns Op . Ns Ar usec
487.Xc
488Specify a timeout for the service.
489The default timeout is 10.0 seconds.
490.It Fl r
491Offer a real
492.Dq auth
493service, as per RFC 1413.
494All the remaining flags apply only in this case.
495.It Fl i
496Return numeric user IDs instead of usernames.
497.It Fl f
498If the file
499.Pa .fakeid
500exists in the home directory of the identified user, report the username
501found in that file instead of the real username.
502If the username found in
503.Pa .fakeid
504is that of an existing user,
505then the real username is reported.
506If the
507.Fl i
508flag is also given then the username in
509.Pa .fakeid
510is checked against existing user IDs instead.
511.It Fl F
512same as
513.Fl f
514but without the restriction that the username in
515.Pa .fakeid
516must not match an existing user.
517.It Fl n
518If the file
519.Pa .noident
520exists in the home directory of the identified user, return
521.Dq ERROR\ : HIDDEN-USER .
522This overrides any
523.Pa fakeid
524file which might exist.
525.It Fl o Ar osname
526Use
527.Ar osname
528instead of the name of the system as reported by
529.Xr uname 3 .
530.El
531.Pp
532The
533.Nm
534utility also provides several other
535.Dq trivial
536services internally by use of
537routines within itself.
538These 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).
548All of these services are available in
549both TCP and UDP versions; the UDP versions will refuse service if the
550request specifies a reply port corresponding to any internal service.
551(This is done as a defense against looping attacks; the remote IP address
552is logged.)
553For details of these services, consult the
554appropriate
555.Tn RFC
556document.
557.Pp
558The TCPMUX-demultiplexing service is also implemented as an internal service.
559For any TCPMUX-based service to function, the following line must be included
560in
561.Pa inetd.conf :
562.Bd -literal -offset indent
563tcpmux stream tcp nowait root internal
564.Ed
565.Pp
566When given the
567.Fl l
568option
569.Nm
570will log an entry to syslog each time a connection is accepted, noting the
571service selected and the IP-number of the remote requester if available.
572Unless otherwise specified in the configuration file,
573and in the absence of the
574.Fl W
575and
576.Fl w
577options,
578.Nm
579will log to the
580.Dq daemon
581facility.
582.Pp
583The
584.Nm
585utility rereads its configuration file when it receives a hangup signal,
586.Dv SIGHUP .
587Services may be added, deleted or modified when the configuration file
588is reread.
589Except when started in debugging mode,
590or configured otherwise with the
591.Fl p
592option,
593.Nm
594records its process ID in the file
595.Pa /var/run/inetd.pid
596to assist in reconfiguration.
597.Sh IMPLEMENTATION NOTES
598.Ss TCP Wrappers
599When given the
600.Fl w
601option,
602.Nm
603will wrap all services specified as
604.Dq stream nowait
605or
606.Dq dgram
607except for
608.Dq internal
609services.
610If the
611.Fl W
612option is given, such
613.Dq internal
614services will be wrapped.
615If both options are given, wrapping for both
616internal and external services will be enabled.
617Either wrapping option
618will cause failed connections to be logged to the
619.Dq auth
620syslog facility.
621Adding the
622.Fl l
623flag to the wrapping options will include successful connections in the
624logging to the
625.Dq auth
626facility.
627.Pp
628Note that
629.Nm
630only wraps requests for a
631.Dq wait
632service while no servers are available to service requests.
633Once a
634connection to such a service has been allowed,
635.Nm
636has no control
637over subsequent connections to the service until no more servers
638are left listening for connection requests.
639.Pp
640When wrapping is enabled, the
641.Pa tcpd
642daemon is not required, as that functionality is builtin.
643For more information on TCP Wrappers, see the relevant documentation
644.Pq Xr hosts_access 5 .
645When reading that document, keep in mind that
646.Dq internal
647services have no associated daemon name.
648Therefore, the service name
649as specified in
650.Pa inetd.conf
651should be used as the daemon name for
652.Dq internal
653services.
654.Ss TCPMUX
655.Tn RFC 1078
656describes the TCPMUX protocol:
657``A TCP client connects to a foreign host on TCP port 1.
658It sends the
659service name followed by a carriage-return line-feed <CRLF>.
660The
661service name is never case sensitive.
662The server replies with a
663single character indicating positive (+) or negative (\-)
664acknowledgment, immediately followed by an optional message of
665explanation, terminated with a <CRLF>.
666If the reply was positive,
667the selected protocol begins; otherwise the connection is closed.''
668The program is passed the TCP connection as file descriptors 0 and 1.
669.Pp
670If the TCPMUX service name begins with a
671.Dq + ,
672.Nm
673returns the positive reply for the program.
674This allows you to invoke programs that use stdin/stdout
675without putting any special server code in them.
676.Pp
677The special service name
678.Dq help
679causes
680.Nm
681to list the TCPMUX services which are enabled in
682.Pa inetd.conf .
683.Ss IPsec
684The implementation includes a tiny hack
685to support IPsec policy settings for each socket.
686A special form of comment line, starting with
687.Dq Li #@ ,
688is interpreted as a policy specifier.
689Everything after the
690.Dq Li #@
691will be used as an IPsec policy string,
692as described in
693.Xr ipsec_set_policy 3 .
694Each
695policy specifier is applied to all the following lines in
696.Pa inetd.conf
697until the next policy specifier.
698An empty policy specifier resets the IPsec policy.
699.Pp
700If an invalid IPsec policy specifier appears in
701.Pa inetd.conf ,
702.Nm
703will provide an error message via the
704.Xr syslog 3
705interface and abort execution.
706.Ss Ux Domain Sockets
707In addition to running services on IP sockets,
708.Nm
709can also manage
710.Ux
711domain sockets.
712To do this you specify a
713.Em protocol
714of
715.Dq unix
716and specify the
717.Ux
718domain socket as the
719.Em service-name .
720The
721.Em service-type
722may be
723.Dq stream
724or
725.Dq dgram .
726The specification of the socket must be
727an absolute path name,
728optionally prefixed by an owner and mode
729of the form
730.Em :user:group:mode: .
731The specification:
732.Pp
733.Dl ":news:daemon:220:/var/run/sock"
734.Pp
735creates a socket owned
736by user
737.Dq news
738in group
739.Dq daemon
740with permissions allowing only that user and group to connect.
741The default owner is the user that
742.Nm
743is running as.
744The default mode only allows the socket's owner to connect.
745.Pp
746.Sy WARNING :
747while creating a
748.Ux
749domain socket,
750.Nm
751must change the ownership and permissions on the socket.
752This can only be done securely if
753the directory in which the socket is created
754is writable only by root.
755Do
756.Em NOT
757use
758.Nm
759to create sockets in world writable directories
760such as
761.Pa /tmp ;
762use
763.Pa /var/run
764or a similar directory instead.
765.Pp
766Internal services may be run on
767.Ux
768domain sockets, in the usual way.
769In this case
770the name of the internal service
771is determined using
772the last component of the socket's pathname.
773For example, specifying a socket named
774.Pa /var/run/chargen
775would invoke the
776.Dq chargen
777service when a connection is received on that socket.
778.Sh "FILES"
779.Bl -tag -width /var/run/inetd.pid -compact
780.It Pa /etc/inetd.conf
781configuration file
782.It Pa /etc/netconfig
783network configuration data base
784.It Pa /etc/rpc
785translation of service names to RPC program numbers
786.It Pa /etc/services
787translation of service names to port numbers
788.It Pa /var/run/inetd.pid
789the pid of the currently running
790.Nm
791.El
792.Sh "EXAMPLES"
793Here are several example service entries for the various types of services:
794.Bd -literal
795ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l
796ntalk dgram udp wait root /usr/libexec/ntalkd ntalkd
797telnet stream tcp6 nowait root /usr/libexec/telnetd telnetd
798shell stream tcp46 nowait root /usr/libexec/rshd rshd
799tcpmux/+date stream tcp nowait guest /bin/date date
800tcpmux/phonebook stream tcp nowait guest /usr/local/bin/phonebook phonebook
801rstatd/1-3 dgram rpc/udp wait root /usr/libexec/rpc.rstatd rpc.rstatd
802/var/run/echo stream unix nowait root internal
803#@ ipsec ah/require
804chargen stream tcp nowait root internal
805#@
806.Ed
807.Sh "ERROR MESSAGES"
808The
809.Nm
810server
811logs error messages using
812.Xr syslog 3 .
813Important error messages and their explanations are:
814.Pp
815.Bl -ohang -compact
816.It Xo
817.Ar service Ns / Ns Ar protocol
818.No "server failing (looping), service terminated."
819.Xc
820The number of requests for the specified service in the past minute
821exceeded the limit.
822The limit exists to prevent a broken program
823or a malicious user from swamping the system.
824This message may occur for several reasons:
825.Bl -enum -offset indent
826.It
827There are many hosts requesting the service within a short time period.
828.It
829A broken client program is requesting the service too frequently.
830.It
831A malicious user is running a program to invoke the service in
832a denial-of-service attack.
833.It
834The invoked service program has an error that causes clients
835to retry quickly.
836.El
837.Pp
838Use the
839.Fl R Ar rate
840option,
841as described above, to change the rate limit.
842Once the limit is reached, the service will be
843reenabled automatically in 10 minutes.
844.Pp
845.It Xo
846.Ar service Ns / Ns Ar protocol :
847.No \&No such user
848.Ar user ,
849.No service ignored
850.Xc
851.It Xo
852.Ar service Ns / Ns Ar protocol :
853.No getpwnam :
854.Ar user :
855.No \&No such user
856.Xc
857No entry for
858.Ar user
859exists in the
860.Xr passwd 5
861database.
862The first message
863occurs when
864.Nm
865(re)reads the configuration file.
866The second message occurs when the
867service is invoked.
868.Pp
869.It Xo
870.Ar service :
871.No can't set uid
872.Ar uid
873.Xc
874.It Xo
875.Ar service :
876.No can't set gid
877.Ar gid
878.Xc
879The user or group ID for the entry's
880.Ar user
881field is invalid.
882.Pp
883.It "setsockopt(SO_PRIVSTATE): Operation not supported"
884The
885.Nm
886utility attempted to renounce the privileged state associated with a
887socket but was unable to.
888.Pp
889.It Xo unknown
890.Ar rpc/udp
891or
892.Ar rpc/tcp
893.Xc
894No entry was found for either
895.Ar udp
896or
897.Ar tcp
898in the
899.Xr netconfig 5
900database.
901.Pp
902.It Xo unknown
903.Ar rpc/udp6
904or
905.Ar rpc/tcp6
906.Xc
907No entry was found for either
908.Ar udp6
909or
910.Ar tcp6
911in the
912.Xr netconfig 5
913database.
914.El
915.Sh SEE ALSO
916.Xr ipsec_set_policy 3 ,
917.Xr hosts_access 5 ,
918.Xr hosts_options 5 ,
919.Xr login.conf 5 ,
920.Xr netconfig 5 ,
921.Xr passwd 5 ,
922.Xr rpc 5 ,
923.Xr services 5 ,
924.Xr comsat 8 ,
925.Xr fingerd 8 ,
926.Xr ftpd 8 ,
927.Xr rlogind 8 ,
928.Xr rpcbind 8 ,
929.Xr rshd 8 ,
930.Xr talkd 8 ,
931.Xr telnetd 8 ,
932.Xr tftpd 8
933.Rs
934.%A Michael C. St. Johns
935.%T Identification Protocol
936.%O RFC1413
937.Re
938.Sh HISTORY
939The
940.Nm
941utility appeared in
942.Bx 4.3 .
943TCPMUX is based on code and documentation by Mark Lottor.
944Support for
945.Tn "ONC RPC"
946based services is modeled after that
947provided by
948.Tn SunOS
9494.1.
950The IPsec hack was contributed by the KAME project in 1999.
951The
952.Fx
953TCP Wrappers support first appeared in
954.Fx 3.2 .
| 181user[:group][/login-class]
182server-program
183server-program-arguments
184.Ed
185.Pp
186There are two types of services that
187.Nm
188can start: standard and TCPMUX.
189A standard service has a well-known port assigned to it;
190it may be a service that implements an official Internet standard or is a
191.Bx Ns -specific
192service.
193As described in
194.Tn RFC 1078 ,
195TCPMUX services are nonstandard services that do not have a
196well-known port assigned to them.
197They are invoked from
198.Nm
199when a program connects to the
200.Dq tcpmux
201well-known port and specifies
202the service name.
203This feature is useful for adding locally-developed servers.
204TCPMUX requests are only accepted when the multiplexor service itself
205is enabled, above and beyond and specific TCPMUX-based servers; see the
206discussion of internal services below.
207.Pp
208The
209.Em service-name
210entry is the name of a valid service in
211the file
212.Pa /etc/services ,
213or the specification of a
214.Ux
215domain socket (see below).
216For
217.Dq internal
218services (discussed below), the service
219name
220should
221be the official name of the service (that is, the first entry in
222.Pa /etc/services ) .
223When used to specify an
224.Tn "ONC RPC" Ns -based
225service, this field is a valid RPC service name listed in
226the file
227.Pa /etc/rpc .
228The part on the right of the
229.Dq /
230is the RPC version number.
231This
232can simply be a single numeric argument or a range of versions.
233A range is bounded by the low version to the high version -
234.Dq rusers/1-3 .
235For TCPMUX services, the value of the
236.Em service-name
237field consists of the string
238.Dq tcpmux
239followed by a slash and the
240locally-chosen service name.
241The service names listed in
242.Pa /etc/services
243and the name
244.Dq help
245are reserved.
246Try to choose unique names for your TCPMUX services by prefixing them with
247your organization's name and suffixing them with a version number.
248.Pp
249The
250.Em socket-type
251should be one of
252.Dq stream ,
253.Dq dgram ,
254.Dq raw ,
255.Dq rdm ,
256or
257.Dq seqpacket ,
258depending on whether the socket is a stream, datagram, raw,
259reliably delivered message, or sequenced packet socket.
260TCPMUX services must use
261.Dq stream .
262.Pp
263The
264.Em protocol
265must be a valid protocol or
266.Dq unix .
267Examples are
268.Dq tcp
269or
270.Dq udp ,
271both of which imply IPv4 for backward compatibility.
272The names
273.Dq tcp4
274and
275.Dq udp4
276specify IPv4 only.
277The names
278.Dq tcp6
279and
280.Dq udp6
281specify IPv6 only.
282The names
283.Dq tcp46
284and
285.Dq udp46
286specify that the entry accepts both IPv4 and IPv6 connections
287via a wildcard
288.Dv AF_INET6
289socket.
290Rpc based services
291are specified with the
292.Dq rpc/tcp
293or
294.Dq rpc/udp
295service type.
296One can use specify IPv4 and/or IPv6 with the 4, 6 or 46 suffix, for example
297.Dq rpc/tcp6
298or
299.Dq rpc/udp46 .
300TCPMUX services must use
301.Dq tcp ,
302.Dq tcp4 ,
303.Dq tcp6
304or
305.Dq tcp46 .
306.Pp
307The
308.Em wait/nowait
309entry specifies whether the server that is invoked by
310.Nm
311will take over
312the socket associated with the service access point, and thus whether
313.Nm
314should wait for the server to exit before listening for new service
315requests.
316Datagram servers must use
317.Dq wait ,
318as they are always invoked with the original datagram socket bound
319to the specified service address.
320These servers must read at least one datagram from the socket
321before exiting.
322If a datagram server connects
323to its peer, freeing the socket so
324.Nm
325can receive further messages on the socket, it is said to be
326a
327.Dq multi-threaded
328server;
329it should read one datagram from the socket and create a new socket
330connected to the peer.
331It should fork, and the parent should then exit
332to allow
333.Nm
334to check for new service requests to spawn new servers.
335Datagram servers which process all incoming datagrams
336on a socket and eventually time out are said to be
337.Dq single-threaded .
338The
339.Xr comsat 8
340and
341.Xr talkd 8
342utilities are examples of the latter type of
343datagram server.
344The
345.Xr tftpd 8
346utility is an example of a multi-threaded datagram server.
347.Pp
348Servers using stream sockets generally are multi-threaded and
349use the
350.Dq nowait
351entry.
352Connection requests for these services are accepted by
353.Nm ,
354and the server is given only the newly-accepted socket connected
355to a client of the service.
356Most stream-based services operate in this manner.
357Stream-based servers that use
358.Dq wait
359are started with the listening service socket, and must accept
360at least one connection request before exiting.
361Such a server would normally accept and process incoming connection
362requests until a timeout.
363TCPMUX services must use
364.Dq nowait .
365.Pp
366The maximum number of outstanding child processes (or
367.Dq threads )
368for a
369.Dq nowait
370service may be explicitly specified by appending a
371.Dq /
372followed by the number to the
373.Dq nowait
374keyword.
375Normally
376(or if a value of zero is specified) there is no maximum.
377Otherwise,
378once the maximum is reached, further connection attempts will be
379queued up until an existing child process exits.
380This also works
381in the case of
382.Dq wait
383mode, although a value other than one (the
384default) might not make sense in some cases.
385You can also specify the maximum number of connections per minute
386for a given IP address by appending
387a
388.Dq /
389followed by the number to the maximum number of
390outstanding child processes.
391Once the maximum is reached, further
392connections from this IP address will be dropped until the end of the
393minute.
394In addition, you can specify the maximum number of simultaneous
395invocations of each service from a single IP address by appending a
396.Dq /
397followed by the number to the maximum number of outstanding child
398processes.
399Once the maximum is reached, further connections from this
400IP address will be dropped.
401.Pp
402The
403.Em user
404entry should contain the user name of the user as whom the server
405should run.
406This allows for servers to be given less permission
407than root.
408The optional
409.Em group
410part separated by
411.Dq \&:
412allows a group name other
413than the default group for this user to be specified.
414The optional
415.Em login-class
416part separated by
417.Dq /
418allows specification of a login class other
419than the default
420.Dq daemon
421login class.
422.Pp
423The
424.Em server-program
425entry should contain the pathname of the program which is to be
426executed by
427.Nm
428when a request is found on its socket.
429If
430.Nm
431provides this service internally, this entry should
432be
433.Dq internal .
434.Pp
435The
436.Em server-program-arguments
437entry lists the arguments to be passed to the
438.Em server-program ,
439starting with argv[0], which usually is the name of
440the program.
441If 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.
539These services are
540.Dq echo ,
541.Dq discard ,
542.Dq chargen
543(character generator),
544.Dq daytime
545(human readable time), and
546.Dq time
547(machine readable time, in the form of the number of seconds since
548midnight, January 1, 1900).
549All of these services are available in
550both TCP and UDP versions; the UDP versions will refuse service if the
551request specifies a reply port corresponding to any internal service.
552(This is done as a defense against looping attacks; the remote IP address
553is logged.)
554For details of these services, consult the
555appropriate
556.Tn RFC
557document.
558.Pp
559The TCPMUX-demultiplexing service is also implemented as an internal service.
560For any TCPMUX-based service to function, the following line must be included
561in
562.Pa inetd.conf :
563.Bd -literal -offset indent
564tcpmux stream tcp nowait root internal
565.Ed
566.Pp
567When given the
568.Fl l
569option
570.Nm
571will log an entry to syslog each time a connection is accepted, noting the
572service selected and the IP-number of the remote requester if available.
573Unless otherwise specified in the configuration file,
574and in the absence of the
575.Fl W
576and
577.Fl w
578options,
579.Nm
580will log to the
581.Dq daemon
582facility.
583.Pp
584The
585.Nm
586utility rereads its configuration file when it receives a hangup signal,
587.Dv SIGHUP .
588Services may be added, deleted or modified when the configuration file
589is reread.
590Except when started in debugging mode,
591or configured otherwise with the
592.Fl p
593option,
594.Nm
595records its process ID in the file
596.Pa /var/run/inetd.pid
597to assist in reconfiguration.
598.Sh IMPLEMENTATION NOTES
599.Ss TCP Wrappers
600When given the
601.Fl w
602option,
603.Nm
604will wrap all services specified as
605.Dq stream nowait
606or
607.Dq dgram
608except for
609.Dq internal
610services.
611If the
612.Fl W
613option is given, such
614.Dq internal
615services will be wrapped.
616If both options are given, wrapping for both
617internal and external services will be enabled.
618Either wrapping option
619will cause failed connections to be logged to the
620.Dq auth
621syslog facility.
622Adding the
623.Fl l
624flag to the wrapping options will include successful connections in the
625logging to the
626.Dq auth
627facility.
628.Pp
629Note that
630.Nm
631only wraps requests for a
632.Dq wait
633service while no servers are available to service requests.
634Once a
635connection to such a service has been allowed,
636.Nm
637has no control
638over subsequent connections to the service until no more servers
639are left listening for connection requests.
640.Pp
641When wrapping is enabled, the
642.Pa tcpd
643daemon is not required, as that functionality is builtin.
644For more information on TCP Wrappers, see the relevant documentation
645.Pq Xr hosts_access 5 .
646When reading that document, keep in mind that
647.Dq internal
648services have no associated daemon name.
649Therefore, the service name
650as specified in
651.Pa inetd.conf
652should be used as the daemon name for
653.Dq internal
654services.
655.Ss TCPMUX
656.Tn RFC 1078
657describes the TCPMUX protocol:
658``A TCP client connects to a foreign host on TCP port 1.
659It sends the
660service name followed by a carriage-return line-feed <CRLF>.
661The
662service name is never case sensitive.
663The server replies with a
664single character indicating positive (+) or negative (\-)
665acknowledgment, immediately followed by an optional message of
666explanation, terminated with a <CRLF>.
667If the reply was positive,
668the selected protocol begins; otherwise the connection is closed.''
669The program is passed the TCP connection as file descriptors 0 and 1.
670.Pp
671If the TCPMUX service name begins with a
672.Dq + ,
673.Nm
674returns the positive reply for the program.
675This allows you to invoke programs that use stdin/stdout
676without putting any special server code in them.
677.Pp
678The special service name
679.Dq help
680causes
681.Nm
682to list the TCPMUX services which are enabled in
683.Pa inetd.conf .
684.Ss IPsec
685The implementation includes a tiny hack
686to support IPsec policy settings for each socket.
687A special form of comment line, starting with
688.Dq Li #@ ,
689is interpreted as a policy specifier.
690Everything after the
691.Dq Li #@
692will be used as an IPsec policy string,
693as described in
694.Xr ipsec_set_policy 3 .
695Each
696policy specifier is applied to all the following lines in
697.Pa inetd.conf
698until the next policy specifier.
699An empty policy specifier resets the IPsec policy.
700.Pp
701If an invalid IPsec policy specifier appears in
702.Pa inetd.conf ,
703.Nm
704will provide an error message via the
705.Xr syslog 3
706interface and abort execution.
707.Ss Ux Domain Sockets
708In addition to running services on IP sockets,
709.Nm
710can also manage
711.Ux
712domain sockets.
713To do this you specify a
714.Em protocol
715of
716.Dq unix
717and specify the
718.Ux
719domain socket as the
720.Em service-name .
721The
722.Em service-type
723may be
724.Dq stream
725or
726.Dq dgram .
727The specification of the socket must be
728an absolute path name,
729optionally prefixed by an owner and mode
730of the form
731.Em :user:group:mode: .
732The specification:
733.Pp
734.Dl ":news:daemon:220:/var/run/sock"
735.Pp
736creates a socket owned
737by user
738.Dq news
739in group
740.Dq daemon
741with permissions allowing only that user and group to connect.
742The default owner is the user that
743.Nm
744is running as.
745The default mode only allows the socket's owner to connect.
746.Pp
747.Sy WARNING :
748while creating a
749.Ux
750domain socket,
751.Nm
752must change the ownership and permissions on the socket.
753This can only be done securely if
754the directory in which the socket is created
755is writable only by root.
756Do
757.Em NOT
758use
759.Nm
760to create sockets in world writable directories
761such as
762.Pa /tmp ;
763use
764.Pa /var/run
765or a similar directory instead.
766.Pp
767Internal services may be run on
768.Ux
769domain sockets, in the usual way.
770In this case
771the name of the internal service
772is determined using
773the last component of the socket's pathname.
774For example, specifying a socket named
775.Pa /var/run/chargen
776would invoke the
777.Dq chargen
778service when a connection is received on that socket.
779.Sh "FILES"
780.Bl -tag -width /var/run/inetd.pid -compact
781.It Pa /etc/inetd.conf
782configuration file
783.It Pa /etc/netconfig
784network configuration data base
785.It Pa /etc/rpc
786translation of service names to RPC program numbers
787.It Pa /etc/services
788translation of service names to port numbers
789.It Pa /var/run/inetd.pid
790the pid of the currently running
791.Nm
792.El
793.Sh "EXAMPLES"
794Here are several example service entries for the various types of services:
795.Bd -literal
796ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l
797ntalk dgram udp wait root /usr/libexec/ntalkd ntalkd
798telnet stream tcp6 nowait root /usr/libexec/telnetd telnetd
799shell stream tcp46 nowait root /usr/libexec/rshd rshd
800tcpmux/+date stream tcp nowait guest /bin/date date
801tcpmux/phonebook stream tcp nowait guest /usr/local/bin/phonebook phonebook
802rstatd/1-3 dgram rpc/udp wait root /usr/libexec/rpc.rstatd rpc.rstatd
803/var/run/echo stream unix nowait root internal
804#@ ipsec ah/require
805chargen stream tcp nowait root internal
806#@
807.Ed
808.Sh "ERROR MESSAGES"
809The
810.Nm
811server
812logs error messages using
813.Xr syslog 3 .
814Important error messages and their explanations are:
815.Pp
816.Bl -ohang -compact
817.It Xo
818.Ar service Ns / Ns Ar protocol
819.No "server failing (looping), service terminated."
820.Xc
821The number of requests for the specified service in the past minute
822exceeded the limit.
823The limit exists to prevent a broken program
824or a malicious user from swamping the system.
825This message may occur for several reasons:
826.Bl -enum -offset indent
827.It
828There are many hosts requesting the service within a short time period.
829.It
830A broken client program is requesting the service too frequently.
831.It
832A malicious user is running a program to invoke the service in
833a denial-of-service attack.
834.It
835The invoked service program has an error that causes clients
836to retry quickly.
837.El
838.Pp
839Use the
840.Fl R Ar rate
841option,
842as described above, to change the rate limit.
843Once the limit is reached, the service will be
844reenabled automatically in 10 minutes.
845.Pp
846.It Xo
847.Ar service Ns / Ns Ar protocol :
848.No \&No such user
849.Ar user ,
850.No service ignored
851.Xc
852.It Xo
853.Ar service Ns / Ns Ar protocol :
854.No getpwnam :
855.Ar user :
856.No \&No such user
857.Xc
858No entry for
859.Ar user
860exists in the
861.Xr passwd 5
862database.
863The first message
864occurs when
865.Nm
866(re)reads the configuration file.
867The second message occurs when the
868service is invoked.
869.Pp
870.It Xo
871.Ar service :
872.No can't set uid
873.Ar uid
874.Xc
875.It Xo
876.Ar service :
877.No can't set gid
878.Ar gid
879.Xc
880The user or group ID for the entry's
881.Ar user
882field is invalid.
883.Pp
884.It "setsockopt(SO_PRIVSTATE): Operation not supported"
885The
886.Nm
887utility attempted to renounce the privileged state associated with a
888socket but was unable to.
889.Pp
890.It Xo unknown
891.Ar rpc/udp
892or
893.Ar rpc/tcp
894.Xc
895No entry was found for either
896.Ar udp
897or
898.Ar tcp
899in the
900.Xr netconfig 5
901database.
902.Pp
903.It Xo unknown
904.Ar rpc/udp6
905or
906.Ar rpc/tcp6
907.Xc
908No entry was found for either
909.Ar udp6
910or
911.Ar tcp6
912in the
913.Xr netconfig 5
914database.
915.El
916.Sh SEE ALSO
917.Xr ipsec_set_policy 3 ,
918.Xr hosts_access 5 ,
919.Xr hosts_options 5 ,
920.Xr login.conf 5 ,
921.Xr netconfig 5 ,
922.Xr passwd 5 ,
923.Xr rpc 5 ,
924.Xr services 5 ,
925.Xr comsat 8 ,
926.Xr fingerd 8 ,
927.Xr ftpd 8 ,
928.Xr rlogind 8 ,
929.Xr rpcbind 8 ,
930.Xr rshd 8 ,
931.Xr talkd 8 ,
932.Xr telnetd 8 ,
933.Xr tftpd 8
934.Rs
935.%A Michael C. St. Johns
936.%T Identification Protocol
937.%O RFC1413
938.Re
939.Sh HISTORY
940The
941.Nm
942utility appeared in
943.Bx 4.3 .
944TCPMUX is based on code and documentation by Mark Lottor.
945Support for
946.Tn "ONC RPC"
947based services is modeled after that
948provided by
949.Tn SunOS
9504.1.
951The IPsec hack was contributed by the KAME project in 1999.
952The
953.Fx
954TCP Wrappers support first appeared in
955.Fx 3.2 .
|