Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
INETD(8)		    System Manager's Manual		      INETD(8)

NAME
       inetd --	internet "super-server"

SYNOPSIS
       inetd	[-d]	[-l]	[-w]	[-W]	[-c    maximum]	   [-C	 rate]
	     [-a address | hostname] [-p  filename]  [-R  rate]	 [-s  maximum]
	     [configuration file]

DESCRIPTION
       The  inetd  utility  should be run at boot time by /etc/rc (see rc(8)).
       It then listens for connections on certain internet  sockets.   When  a
       connection  is found on one of its sockets, it decides what service the
       socket corresponds to, and invokes a program to	service	 the  request.
       The  server  program is invoked with the	service	socket as its standard
       input, output and error descriptors.  After the	program	 is  finished,
       inetd  continues	 to  listen  on	the socket (except in some cases which
       will be described below).  Essentially, inetd allows running one	daemon
       to invoke several others, reducing load on the system.

       The following options are available:

       -d      Turn on debugging.

       -l      Turn on logging of successful connections.

       -w      Turn  on	 TCP  Wrapping	for  external	services.    See   the
	       "IMPLEMENTATION	NOTES"	section	 for  more  information	on TCP
	       Wrappers	support.

       -W      Turn on TCP Wrapping for	internal services which	are  built  in
	       to inetd.

       -c maximum
	       Specify	the default maximum number of simultaneous invocations
	       of each service;	the default is unlimited.  May	be  overridden
	       on a per-service	basis with the "max-child" parameter.

       -C rate
	       Specify	the  default  maximum number of	times a	service	can be
	       invoked from a single IP	address	in one minute; the default  is
	       unlimited.   May	 be overridden on a per-service	basis with the
	       "max-connections-per-ip-per-minute" parameter.

       -R rate
	       Specify the maximum number of times a service can be invoked in
	       one minute; the default is 256.	A rate of 0 allows  an	unlim-
	       ited number of invocations.

       -s maximum
	       Specify	the default maximum number of simultaneous invocations
	       of each service from a single IP	address; the default is	unlim-
	       ited.  May be overridden	on a per-service basis with the	 "max-
	       child-per-ip" parameter.

       -a      Specify	one  specific IP address to bind to.  Alternatively, a
	       hostname	can be specified, in which case	the IPv4 or  IPv6  ad-
	       dress  which  corresponds  to that hostname is used.  Usually a
	       hostname	is specified when inetd	is run inside  a  jail(8),  in
	       which case the hostname corresponds to the jail(8) environment.

	       When  hostname  specification  is  used	and both IPv4 and IPv6
	       bindings	are desired, one entry with the	 appropriate  protocol
	       type   for  each	 binding  is  required	for  each  service  in
	       /etc/inetd.conf.	 For example, a	TCP-based service  would  need
	       two  entries,  one  using "tcp4"	for the	protocol and the other
	       using "tcp6".   See  the	 explanation  of  the  /etc/inetd.conf
	       protocol	field below.

       -p      Specify an alternate file in which to store the process ID.

       Upon  execution,	 inetd reads its configuration information from	a con-
       figuration file which, by default, is /etc/inetd.conf.  There  must  be
       an  entry  for  each  field of the configuration	file, with entries for
       each field separated by a tab or	a space.  Comments are	denoted	 by  a
       "#" at the beginning of a line.	There must be an entry for each	field.
       The fields of the configuration file are	as follows:

	     service name
	     socket type
	     protocol
	     {wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]]
	     user[:group][/login-class]
	     server program
	     server program arguments

       To  specify  an	ONC  RPC-based	service, the entry would contain these
       fields:

	     service name/version
	     socket type
	     rpc/protocol
	     user[:group][/login-class]
	     server program
	     server program arguments

       There are two types of services that inetd can start: standard and TCP-
       MUX.  A standard	service	has a well-known port assigned to it;  it  may
       be  a  service  that  implements	 an official Internet standard or is a
       BSD-specific service.  As described in RFC 1078,	 TCPMUX	 services  are
       nonstandard  services  that  do	not have a well-known port assigned to
       them.  They are invoked from inetd  when	 a  program  connects  to  the
       "tcpmux"	 well-known port and specifies the service name.  This feature
       is useful for adding locally-developed servers.	 TCPMUX	 requests  are
       only accepted when the multiplexor service itself is enabled, above and
       beyond  and specific TCPMUX-based servers; see the discussion of	inter-
       nal services below.

       The service-name	entry is the name of  a	 valid	service	 in  the  file
       /etc/services,  or  the	specification of a Unix	domain socket (see be-
       low).  For "internal" services  (discussed  below),  the	 service  name
       should be the official name of the service (that	is, the	first entry in
       /etc/services).	 When  used  to	specify	an ONC RPC-based service, this
       field is	a valid	RPC service name in the	file /etc/rpc.	 The  part  on
       the  right  of the "/" is the RPC version number.  This can simply be a
       single numeric argument or a range of versions.	A range	is bounded  by
       the  low	 version  to the high version -	"rusers/1-3".  For TCPMUX ser-
       vices, the value	of the	service-name  field  consists  of  the	string
       "tcpmux"	 followed by a slash and the locally-chosen service name.  The
       service names listed in /etc/services and the name "help" are reserved.
       Try to choose unique names for your TCPMUX services by  prefixing  them
       with your organization's	name and suffixing them	with a version number.

       The  socket-type	 should	 be one	of "stream", "dgram", "raw", "rdm", or
       "seqpacket", depending on whether the socket  is	 a  stream,  datagram,
       raw,  reliably  delivered  message, or sequenced	packet socket.	TCPMUX
       services	must use "stream".

       The protocol must be a valid protocol or	"unix".	 Examples are "tcp" or
       "udp", both of which imply IPv4 for backward compatibility.  The	 names
       "tcp4" and "udp4" specify IPv4 only.  The names "tcp6" and "udp6" spec-
       ify  IPv6  only.	  The names "tcp46" and	"udp46"	specify	that the entry
       accepts both IPv4 and IPv6 connections via a wildcard AF_INET6  socket.
       If  it  is  desired that	the service is reachable via T/TCP, one	should
       specify "tcp/ttcp", which implies IPv4 for backward compatibility.  The
       name "tcp4/ttcp"	specifies IPv4 only, while "tcp6/ttcp" specifies  IPv6
       only.   The  name "tcp46/ttcp" specify that the entry accepts both IPv6
       and IPv6	connections via	a wildcard AF_INET6 socket.   Rpc  based  ser-
       vices  are specified with the "rpc/tcp" or "rpc/udp" service type.  One
       can use specify IPv4 and/or IPv6	with the 4, 6 or 46 suffix, for	 exam-
       ple "rpc/tcp6" or "rpc/udp46".  TCPMUX services must use	"tcp", "tcp4",
       "tcp6" or "tcp46".

       The  wait/nowait	 entry specifies whether the server that is invoked by
       inetd will take over the	socket	associated  with  the  service	access
       point, and thus whether inetd should wait for the server	to exit	before
       listening  for new service requests.  Datagram servers must use "wait",
       as they are always invoked with the original datagram socket  bound  to
       the  specified  service	address.  These	servers	must read at least one
       datagram	from the socket	before exiting.	 If a datagram server connects
       to its peer, freeing the	socket so inetd	can receive  further  messages
       on  the	socket,	 it is said to be a "multi-threaded" server; it	should
       read one	datagram from the socket and create a new socket connected  to
       the  peer.   It	should	fork, and the parent should then exit to allow
       inetd to	check for new service requests to spawn	new servers.  Datagram
       servers which process all incoming datagrams on a socket	and eventually
       time out	are said to be "single-threaded".   The	 comsat(8),  (biff(1))
       and talkd(8) utilities are both examples	of the latter type of datagram
       server.	 The  tftpd(8) utility is an example of	a multi-threaded data-
       gram server.

       Servers using stream sockets generally are multi-threaded and  use  the
       "nowait"	entry.	Connection requests for	these services are accepted by
       inetd, and the server is	given only the newly-accepted socket connected
       to a client of the service.  Most stream-based services operate in this
       manner.	Stream-based servers that use "wait" are started with the lis-
       tening  service socket, and must	accept at least	one connection request
       before exiting.	Such a server would normally accept and	process	incom-
       ing connection requests until a	timeout.   TCPMUX  services  must  use
       "nowait".

       The  maximum number of outstanding child	processes (or "threads") for a
       "nowait"	service	may be explicitly specified by appending  a  "/"  fol-
       lowed  by  the number to	the "nowait" keyword.  Normally	(or if a value
       of zero is specified) there is no maximum.  Otherwise, once the maximum
       is reached, further connection attempts will be queued up until an  ex-
       isting  child  process  exits.	This  also works in the	case of	"wait"
       mode, although a	value other than one  (the  default)  might  not  make
       sense  in  some cases.  You can also specify the	maximum	number of con-
       nections	per minute for a given IP address by appending a "/"  followed
       by  the	number	to  the	maximum	number of outstanding child processes.
       Once the	maximum	is reached, further connections	from this  IP  address
       will  be	 dropped  until	 the  end of the minute.  In addition, you can
       specify the maximum number of simultaneous invocations of each  service
       from  a	single IP address by appending a "/" followed by the number to
       the maximum number of outstanding child processes.  Once	the maximum is
       reached,	further	connections from this IP address will be dropped.

       The user	entry should contain the user name of the  user	 as  whom  the
       server should run.  This	allows for servers to be given less permission
       than  root.   Optional  group  part  separated by ":" allows to specify
       group name different  than  default  group  for	this  user.   Optional
       login-class part	separated by "/" allows	to specify login class differ-
       ent than	default	"daemon" login class.

       The  server-program  entry  should  contain the pathname	of the program
       which is	to be executed by inetd	when a request is found	on its socket.
       If inetd	 provides  this	 service  internally,  this  entry  should  be
       "internal".

       The  server program arguments should be just as arguments normally are,
       starting	with argv[0], which is the name	of the program.	 If  the  ser-
       vice  is	 provided internally, the service-name of the service (and any
       arguments to it)	or the word "internal" should take the place  of  this
       entry.

       Currently,  the	only  internal	service	 to  take arguments is "auth".
       Without options,	the service will always	return "ERROR :	 HIDDEN-USER".
       The available arguments to this service that alter its behavior are:

       -d fallback
	       Provide a fallback username.  If	the real "auth"	service	is en-
	       abled  (with  the -r option discussed below), return this user-
	       name instead of an error	when lookups fail  for	either	socket
	       credentials  or	the  username.	 If the	real "auth" service is
	       disabled, return	this username for every	request.  This is pri-
	       marily useful when running this service on a NAT	machine.

       -g      Instead of returning the	user's name to	the  ident  requester,
	       report  a  username  made up of random alphanumeric characters,
	       e.g. "c0c993".  The -g flag overrides not only the user	names,
	       but also	any fallback name, .fakeid or .noident files.

       -t sec[.usec]
	       Specify a timeout for the service.  The default timeout is 10.0
	       seconds.

       -r      Offer  a	real "auth" service, as	per RFC	1413.  All the remain-
	       ing flags apply only in this case.

       -i      Return numeric user IDs instead of usernames.

       -f      If the file .fakeid exists in the home directory	of the identi-
	       fied user, report the username found in that  file  instead  of
	       the real	username.  If the username found in .fakeid is that of
	       an  existing  user, then	the real username is reported.	If the
	       -i flag is also given then the username in .fakeid  is  checked
	       against existing	user IDs instead.

       -F      same  as	 -f  but  without the restriction that the username in
	       .fakeid must not	match an existing user.

       -n      If the file .noident exists in the home directory of the	 iden-
	       tified  user, return "ERROR : HIDDEN-USER".  This overrides any
	       fakeid file which might exist.

       -o osname
	       Use osname instead of the name of the  system  as  reported  by
	       uname(3).

       The inetd utility also provides several other "trivial" services	inter-
       nally  by  use  of  routines within itself.  These services are "echo",
       "discard", "chargen" (character generator), "daytime"  (human  readable
       time),  and "time" (machine readable time, in the form of the number of
       seconds since midnight, January 1, 1900).  All of  these	 services  are
       available  in  both  TCP	and UDP	versions; the UDP versions will	refuse
       service if the request specifies	a reply	port corresponding to any  in-
       ternal  service.	  (This	 is done as a defense against looping attacks;
       the remote IP address is	logged.)  For details of these services,  con-
       sult the	appropriate RFC	document.

       The  TCPMUX-demultiplexing  service  is also implemented	as an internal
       service.	 For any TCPMUX-based service to function, the following  line
       must be included	in inetd.conf:

	     tcpmux  stream  tcp     nowait  root    internal

       When  given the -l option inetd will log	an entry to syslog each	time a
       connection is accepted, noting the service selected and	the  IP-number
       of  the	remote	requester if available.	 Unless	otherwise specified in
       the configuration file, and in the absence of the -W  and  -w  options,
       inetd will log to the "daemon" facility.

       The  inetd  utility  rereads  its configuration file when it receives a
       hangup signal, SIGHUP.  Services	may be added, deleted or modified when
       the configuration file is reread.  Except  when	started	 in  debugging
       mode,  inetd  records  its process ID in	the file /var/run/inetd.pid to
       assist in reconfiguration.

IMPLEMENTATION NOTES
   TCP Wrappers
       When given the -w option, inetd will wrap  all  services	 specified  as
       "stream	nowait"	 or "dgram" except for "internal" services.  If	the -W
       option is given,	such "internal"	services will be wrapped.  If both op-
       tions are given,	wrapping for both internal and external	services  will
       be enabled.  Either wrapping option will	cause failed connections to be
       logged  to the "auth" syslog facility.  Adding the -l flag to the wrap-
       ping options will include successful connections	in the logging to  the
       "auth" facility.

       Note  that  inetd  only	wraps  requests	 for a "wait" service while no
       servers are available to	service	requests.  Once	a connection to	such a
       service has been	allowed, inetd has no control over subsequent  connec-
       tions  to the service until no more servers are left listening for con-
       nection requests.

       When wrapping is	enabled, the tcpd daemon  is  not  required,  as  that
       functionality  is  builtin.   For more information on TCP Wrappers, see
       the relevant documentation (hosts_access(5)).  When reading that	 docu-
       ment,  keep  in mind that "internal" services have no associated	daemon
       name.  Therefore, the service name as specified in inetd.conf should be
       used as the daemon name for "internal" services.

   TCPMUX
       RFC 1078	describes the TCPMUX protocol: ``A TCP client  connects	 to  a
       foreign	host  on  TCP port 1.  It sends	the service name followed by a
       carriage-return line-feed <CRLF>.  The service name is never case  sen-
       sitive.	The server replies with	a single character indicating positive
       (+) or negative (-) acknowledgment, immediately followed	by an optional
       message	of  explanation,  terminated  with a <CRLF>.  If the reply was
       positive, the selected protocol begins;	otherwise  the	connection  is
       closed.''  The program is passed	the TCP	connection as file descriptors
       0 and 1.

       If  the	TCPMUX service name begins with	a "+", inetd returns the posi-
       tive reply for the program.  This allows	you to	invoke	programs  that
       use stdin/stdout	without	putting	any special server code	in them.

       The special service name	"help" causes inetd to list TCPMUX services in
       inetd.conf.

   IPsec
       The  implementation  includes  a	tiny hack to support IPsec policy set-
       tings for each socket.  A special form of comment line,	starting  with
       "#@",  is interpreted as	a policy specifier.  Everything	after the "#@"
       will  be	 used  as  an	IPsec	policy	 string,   as	described   in
       ipsec_set_policy(3).   Each policy specifier is applied to all the fol-
       lowing lines in inetd.conf until	the next policy	specifier.   An	 empty
       policy specifier	resets the IPsec policy.

       If  an invalid IPsec policy specifier appears in	inetd.conf, inetd will
       provide an error	message	via the	syslog(3) interface and	 abort	execu-
       tion.

   Unix	Domain Sockets
       In  addition  to	 running services on IP	sockets, inetd can also	manage
       Unix domain sockets.  To	do this	you specify a protocol of  "unix"  and
       specify	the  Unix domain socket	as the service-name.  The service-type
       may be "stream" or "dgram".  The	specification of the socket must be an
       absolute	path name, optionally prefixed by an owner  and	 mode  of  the
       form :user:group:mode:.	The specification:

	     :news:daemon:220:/var/run/sock

       creates	a  socket  owned by user "news"	in group "daemon" with permis-
       sions allowing only that	user and group to connect.  The	default	 owner
       is the user that	inetd is running as.  The default mode only allows the
       socket's	owner to connect.

       WARNING:	 while creating	Unix domain socket, inetd must change the own-
       ership and permissions on the socket.  This can only be	done  securely
       if  the	directory  in  which the socket	is created is writable only by
       root.  Do NOT use inetd to create sockets in  world  writable  directo-
       ries, such as /tmp, instead use /var/run	or a similar directory.

       Internal	 services may be run on	Unix domain sockets, in	the usual way.
       In this case the	name of	the internal service is	determined  using  the
       last component of the socket's pathname.

FILES
       /etc/inetd.conf	   configuration file
       /etc/rpc		   translation of service names	to RPC program numbers
       /etc/services	   translation of service names	to port	numbers
       /var/run/inetd.pid  the pid of the currently running inetd

EXAMPLES
       Here  are several example service entries for the various types of ser-
       vices:

       ftp	    stream  tcp	  nowait root  /usr/libexec/ftpd	ftpd -l
       ntalk	    dgram   udp	  wait	 root  /usr/libexec/ntalkd	ntalkd
       telnet	    stream  tcp6  nowait root  /usr/libexec/telnetd  telnetd
       shell	    stream  tcp46  nowait root	/usr/libexec/rshd rshd
       tcpmux/+date stream  tcp	  nowait guest /bin/date		date
       tcpmux/phonebook	stream tcp nowait guest	/usr/local/bin/phonebook phonebook
       rstatd/1-3   dgram   rpc/udp wait root  /usr/libexec/rpc.rstatd	rpc.rstatd
       /var/run/echo stream unix  nowait root  internal
       #@ ipsec	ah/require
       chargen	    stream  tcp	  nowait root  internal
       #@

ERROR MESSAGES
       The inetd server	logs error messages using syslog(3).  Important	 error
       messages	and their explanations are:

       service/protocol	server failing (looping), service terminated.
       The number of requests for the specified	service	in the past minute ex-
       ceeded  the  limit.   The limit exists to prevent a broken program or a
       malicious user from swamping the	system.	 This message  may  occur  for
       several reasons:

	     1.	  There	 are  many hosts requesting the	service	within a short
		  time period.

	     2.	  A broken client program is requesting	the service  too  fre-
		  quently.

	     3.	  A  malicious user is running a program to invoke the service
		  in a denial-of-service attack.

	     4.	  The invoked service program has an error that	causes clients
		  to retry quickly.

       Use the -R rate option, as described above, to change the  rate	limit.
       Once  the limit is reached, the service will be reenabled automatically
       in 10 minutes.

       service/protocol: No such user user, service ignored
       service/protocol: getpwnam: user: No such user
       No entry	for user exists	in the passwd(5) database.  The	first  message
       occurs when inetd (re)reads the configuration file.  The	second message
       occurs when the service is invoked.

       service:	can't set uid uid
       service:	can't set gid gid
       The user	or group ID for	the entry's user field is invalid.

       setsockopt(SO_PRIVSTATE): Operation not supported
       The inetd utility attempted to renounce the privileged state associated
       with a socket but was unable to.

SEE ALSO
       ipsec_set_policy(3),  hosts_access(5), hosts_options(5),	login.conf(5),
       passwd(5),  rpc(5),  services(5),   comsat(8),	fingerd(8),   ftpd(8),
       rlogind(8), rpcbind(8), rshd(8),	telnetd(8), tftpd(8)

       Michael C. St. Johns, Identification Protocol, RFC1413.

HISTORY
       The inetd utility appeared in 4.3BSD.  TCPMUX is	based on code and doc-
       umentation  by Mark Lottor.  Support for	ONC RPC	based services is mod-
       eled after that provided	by SunOS 4.1.  The IPsec hack was  contributed
       by  the	KAME  project in 1999.	The FreeBSD TCP	Wrappers support first
       appeared	in FreeBSD 3.2.

GNU			       February	7, 1996			      INETD(8)

NAME | SYNOPSIS | DESCRIPTION | IMPLEMENTATION NOTES | FILES | EXAMPLES | ERROR MESSAGES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=inetd&manpath=FreeBSD+6.0-RELEASE+and+Ports>

home | help