echod(8)                FreeBSD System Manager's Manual               echod(8)

NAME
     echod -- KQueue-Based Echo Server

SYNOPSIS
     echod [-i <interface> -p <port> -u <user> -g <group> -x]

DESCRIPTION
     Echod is a kqueue-based, connection-multiplexing, echo server.  It was
     written to serve as an exercise in exploring the issues involved in writ-
     ing a kqueue-based multiplexer, and can serve as an example to other pro-
     grammers learning the kqueue interface.  Echod accepts both IPv4 and IPv6
     connections.

     An echo server reads whatever data a client sends to it, and spits that
     data back at the client, unchanged.  Echo servers are used to test net-
     works.  They have no other real-world use.

     By default, FreeBSD limits each process to having a maximum of 64 simul-
     taneously open descriptors.  This places a limit on the number of connec-
     tions echod may multiplex.  The sysctl settings below, allow for a gener-
     ous number of connections.  These values can be set at the command-line
     with the "sysctl" utility.  It is recommended that they be enabled perma-
     nently by placing these lines in /etc/sysctl.conf on the host machine.

     kern.maxfiles=16384
     kern.maxfilesperproc=16384
     kern.kq_calloutmax=65536
     kern.ipc.nmbclusters=25600
     kern.ipc.maxsockets=25600

     Echod writes its pid into /var/run/echod.pid, if it can (ie., it is
     started as root), and may be stopped with a SIGTERM, or any signal whose
     default behavior is to kill the process.  A rc.d script is provided and
     installed in /usr/local/etc/rc.d/.  Add the following lines to
     /etc/rc.conf to start echod on system boot-up.  Replace the items in
     brackets with values appropriate for your system, and/or add or remove
     options as suits your system.  The available options are described in
     full at the end of this manual page.

     echod_enable="YES"
     echod_flags="-u <user> -g <group>"

     Once your /etc/rc.conf is configured you may start, stop, or restart
     echod, or determine if it is running with the following commands:

     /usr/local/etc/rc.d/echod start
     /usr/local/etc/rc.d/echod stop
     /usr/local/etc/rc.d/echod restart
     /usr/local/etc/rc.d/echod status

     If you do not want echod started on system start, then set

     echod_enable="NO"

     and use the following commands:

     /usr/local/etc/rc.d/echod forcestart
     /usr/local/etc/rc.d/echod forcestop
     /usr/local/etc/rc.d/echod forcerestart
     /usr/local/etc/rc.d/echod forcestatus

     If the server encounters an error reading or writing data to or from a
     client, or runs out of memory, the particular connection which generated
     the error will be dropped.  All other errors will be logged via sys-
     log(3), and may be found in /var/log/messages.

     The following arguments are recognized.  They are all optional.

     -p  The -p option specifies the port to listen on.  This defaults to 7 if
         not specified.

     -i  By default, echod accepts connections on all interfaces it can find
         capable of IPv4 or IPv6.  The -i option, when present, overrides this
         behavior, by limiting echod to accepting connections from a specified
         interface only.  The option accepts the IP address of the desired
         interface as an argument.  The address must be expressed in the pre-
         sentation format for either IPv4 or IPv6.  The intent of this option
         is to allow the administrator to prevent the outside world from
         accessing a server during testing by making echod bind only to one
         interface (eg., the loopback address).

     -u

     -g  echod must be started as root in order to bind to port 7, but it
         tries to setuid to user "nobody" and setgid to group "nobody" after
         binding the listening socket.  If it is unsuccessful in either
         attempt, the server will exit.  The -u and the -g options may be used
         to specify a different user and group.  If you use the -p option to
         make echod listen on a port higher than port 1023, then echod can be
         started as any user, but it will not be able to change to user and
         group "nobody".  In this case, you must provide the -u and -g options
         to specify the user and group that echod will begin running as and
         stay running as, or the server will exit.

     -x  The -x option, if present, prevents echod from becoming a daemon.  It
         will then run in the foreground of the terminal where it was started,
         and may be stopped with signals (ie., Control-C).  The server also
         will not write its pid to /var/run/echod.pid when the -x option is
         used.

AUTHORS
     James Bailie <jimmy@mammothcheese.ca>
     http://www.mammothcheese.ca

                                 Jan 24, 2008