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

FreeBSD Manual Pages


home | help
onenetd(1)			 Network Tools			    onenetd(1)

       onenetd - listen	on a TCP port and launch a program to handle requests

       onenetd [options] ADDRESS PORT COMMAND ...

       onenetd	binds a	TCP socket to port PORT	on IP address ADDRESS, listens
       for and accepts connections, and	spawns COMMAND with stdin  and	stdout
       (and optionally stderr) connected to the	accepted socket.

       onenetd	may be thought of as a minimal version of inetd, suitable only
       for listening for "stream tcp nowait" services on a  single  port.  The
       idea  is	that multiple copies of	onenetd	will be	run, one for each ser-
       vice. The advantages of onenetd over inetd include:

       o      Connections may be refused with a	fixed response after the  con-
	      nection limit is reached.

       o      TCP_NODELAY may be set on	a per-port basis.

       o      The  address  to bind to may be chosen arbitrarily, so it's easy
	      to make a	service	only listen on localhost, or run several  dif-
	      ferent  services	on  the	 same port for different interface ad-

       o      Incoming connections may be logged to stderr.

       Note that onenetd only handles TCP connections; it is not  possible  to
       run UDP services	(such as nmbd) from onenetd.

	      The  hostname  or	 IP address to bind() to. Specify 0 (or	:: for
	      IPv6) to bind to all addresses.

       PORT   The service name or port number to bind()	to. In order  to  bind
	      to a privileged port, onenetd must be initially run as root (al-
	      though you can use the -u	etc.  options  to  switch  to  another
	      user  after  the	bind  has been done). Specify 0	to bind	to any
	      available	port.

       COMMAND ...
	      The command to execute, as well as its parameters	 (all  parame-
	      ters given to onenetd after COMMAND are passed to	COMMAND	as pa-
	      rameters). argv[0] for COMMAND will be set to  COMMAND;  if  you
	      wish to specify a	different argv[0], use the argv0 tool from the
	      freedt or	daemontools packages.

       -c N   Limit the	number of connections (and thus	child processes) to N.
	      The default is 40.

       -6     Bind to an IPv6 address. IPv6 sockets will also accept IPv4 con-
	      nections,	if bound to an appropriate address (e.g. ::).

       -g GID After binding the	TCP socket, setgid(GID). GID must be numeric.

       -u UID After binding the	TCP socket, setuid(UID). UID must be numeric.

       -U     After binding the	TCP  socket,  setgid($GID)  and	 setuid($UID).
	      $GID and $UID must be numeric. This is intended for use with en-
	      vuidgid (from daemontools	or freedt).

       -1     After binding the	TCP socket, print the  local  port  number  to
	      stdout.	You  can use this when you've specified	the local port
	      as 0 to find out what port has been chosen.

       -b N   Set the listen() backlog to N. Note that on many operating  sys-
	      tems,  the  listen backlog has an	arbitrary limit, or may	be en-
	      tirely ignored. The default is 10.

       -D     Set the TCP_NODELAY option on the	accepted sockets. This	causes
	      the  operating  system's	TCP  stack to avoid coalescing smaller
	      packets  into  larger  ones,  decreasing	latency	 but  reducing

       -Q     Do not print any messages	to stderr, except in the case of a fa-
	      tal error. This is the default.

       -v     Print messages to	stderr indicating clients connecting and  dis-
	      connecting.   These  can be collected for	logging	purposes using
	      logger, multilog from daemontools, or dumblog from freedt.

       -e     Redirect the child's stderr to  the  socket.  By	default,  only
	      stdin and	stdout are redirected.

       -h     Print a brief usage message, then	exit. The same message will be
	      shown if unknown or invalid arguments are	passed.

       -r MESSAGE
	      Normally once the	number of active connections  has  passed  the
	      limit  set by -c,	further	connections will not be	accepted until
	      the number of active connections has dropped again --  that  is,
	      further  connections  will  not be refused, but will not connect
	      until free connections are available. If -r is  specified,  con-
	      nections	will  be accepted and have the constant	string MESSAGE
	      printed to them, then will be disconnected; this is done	inside
	      the  onenetd  process  without  forking,	so  it does not	use up
	      process slots. MESSAGE may contain \r, \n	or  \t	to  specify  a
	      carriage return, newline or tab character.

       onenetd	returns	 0 on success, or 20 on	failure	(for instance, invalid
       arguments). Since onenetd is intended to	run forever, the exit code  is
       generally  not  important, and stderr should be examined	for diagnostic
       messages	if it exits unexpectedly.

       Following D. J. Bernstein's UCSPI standard, onenetd sets	several	 vari-
       ables in	the child process's environment. These can be used for logging
       or access control.

       PROTO  The string "TCP" for IPv4	connections, or	"TCP6" for  IPv6  con-

	      The  local  address  of  the  connected  socket, as formatted by
	      inet_ntop	(dotted	quad for IPv4, hex for IPv6).

	      The local	port of	the connected socket, as a decimal number.

	      The remote address of the	 connected  socket,  as	 formatted  by

	      The remote port of the connected socket, as a decimal number.

       onenetd 0 echo cat
	      Simulate the standard inetd echo service.

       onenetd -v daytime date
	      Simulate	the  standard  inetd  daytime service on the interface, logging connections to stderr.

       onenetd -1 ::1 0	myprog --my-arguments
	      Bind to a	free port on the IPv6  localhost  address,  print  the
	      port  number chosen, and run "myprog --my-arguments" for connec-

       onenetd -v -c 5	-r  '421  Server  full\r\n'  0	21  /usr/sbin/ftpd  -a
	      Run  an FTP service with a limit of five concurrent connections,
	      refusing any further connections with an appropriate  FTP	 error
	      message. ftpd will be invoked as "/usr/sbin/ftpd -a /home/ftp".

       envuidgid myuser	onenetd	-v -U 0	25098 myprog --my-arguments
	      Set user and group to that of myuser, and	run "myprog --my-argu-
	      ments" for connections to	port 25098 on any IPv4 interface.

       onenetd was written by Adam Sampson <>.

       inetd(8), argv0(8), envuidgid(8), softlimit(8), dumblog(8),  logger(1),

Version	12			19th June 2014			    onenetd(1)


Want to link to this manual page? Use this URL:

home | help