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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
INETD(8)		FreeBSD	System Manager's Manual		      INETD(8)

NAME
     inetd -- internet ``super-server''

SYNOPSIS
     inetd [-d]	[-l] [-c maximum] [-C rate] [-a	address] [-p filename]
	   [-R rate] [configuration file]

DESCRIPTION
     The inetd program should be run at	boot time by /etc/rc (see rc(8)).  It
     then listens for connections on certain internet sockets.	When a connec-
     tion 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.

     -c	maximum
	     Specify the default maximum number	of services that can be
	     invoked.  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	     Specify a specific	IP address to bind to.

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

     Upon execution, inetd reads its configuration information from a configu-
     ration 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]]
	   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-spe-
     cific 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 TCP-
     MUX-based servers;	see the	discussion of internal services	below.

     The service-name entry is the name	of a valid service in the file
     /etc/services.  For ``internal'' services (discussed below), the service
     name must 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 services, the
     value of the service-name field consists of the string ``tcpmux'' fol-
     lowed 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 ser-
     vices must	use ``stream''.

     The protocol must be a valid protocol as given in /etc/protocols.	Exam-
     ples might	be ``tcp'' or ``udp''.	If it is desired that the service is
     reachable via T/TCP, one should specify ``tcp/ttcp''.  Rpc	based services
     are specified with	the ``rpc/tcp''	or ``rpc/udp'' service type.  TCPMUX
     services must use ``tcp''.

     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 listen-
     ing 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 received 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''.  Comsat(8), (biff(1)) and talkd(8)	are
     both examples of the latter type of datagram server.  Tftpd(8) is an
     example of	a multi-threaded datagram 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 incoming
     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 existing
     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 connections 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.

     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 service
     is	provided internally, the word ``internal'' should take the place of
     this entry.

     The inetd program provides	several	``trivial'' services internally	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 internal service.
     (This is done as a	defense	against	looping	attacks; the remote IP address
     is	logged.)  For details of these services, consult the appropriate RFC
     document.

     The TCPMUX-demultiplexing service is also implemented as an internal ser-
     vice.  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 an
     accept(2) is made,	which notes the	service	selected and the IP-number of
     the remote	requestor.

     The inetd program 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.

TCPMUX
     RFC 1078 describes	the TCPMUX protocol: ``A TCP client connects to	a for-
     eign host on TCP port 1.  It sends	the service name followed by a car-
     riage-return line-feed <CRLF>.  The service name is never case sensitive.
     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 pro-
     gram 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.

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
     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

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
     exceeded the limit. The limit exists to prevent a broken program or a
     malicious user from swamping the system.  This message may	occur for sev-
     eral 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 program attempted to renounce the privileged state associated
     with a socket but was unable to.

SEE ALSO
     login.conf(5), passwd(5), rpc(5), services(5), comsat(8), fingerd(8),
     ftpd(8), portmap(8), rexecd(8), rlogind(8), rshd(8), telnetd(8), tftpd(8)

HISTORY
     The inetd command appeared	in 4.3BSD.  TCPMUX is based on code and	docu-
     mentation by Mark Lottor.	Support	for ONC	RPC based services is modeled
     after that	provided by SunOS 4.1.

4.4BSD			       February	7, 1996				4.4BSD

NAME | SYNOPSIS | DESCRIPTION | TCPMUX | FILES | EXAMPLES | ERROR MESSAGES | SEE ALSO | HISTORY

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

home | help