squeers(8) BSD System Manager's Manual squeers(8)NAME
Squeers — File Server
SYNOPSISsqueers-r ⟨server-root⟩ [-m ⟨instances⟩ -i ⟨interface⟩ -p ⟨port⟩ -t
⟨timeout⟩ -u ⟨user⟩ -g ⟨group⟩ -q ⟨backlog⟩ -x]
DESCRIPTION
Squeers is a small and fast, KQueue-based, multiplexing file server.
PROTOCOL
Squeers listens for incoming TCP connections on a specified port. After
a connection has been accepted, squeers reads one line of newline-termi‐
nated characters from the client. This line must specify the name of a
file to be transferred to the client. The newline is not part of the
filename. The server sends the contents of the file to the client if
possible, and then closes the connection. There is no meta data or con‐
trol information associated with requests or responses. If the server
cannot service a client's request, the client's connection is immediately
dropped without explanation.
Squeers will reject requests for any entity which resides out of the
filesystem hierarchy rooted at the server root directory as specified by
the -r option. Squeers will reject requests for any entity which is not
a regular file nor a symbolic link to a regular file. Squeers will
reject requests for entities which are not readable by the user or group
defined by the -u and -g options.
SYSTEM CONFIGURATION
Squeers is a kqueue(2)-based multiplexer. By default, FreeBSD limits
each process to having a maximum of 64 simultaneously open descriptors.
This places a limit on the number of connections squeers may multiplex.
The sysctl settings below, allow for a generous number of connections.
These values can be set at the command-line with the "sysctl" utility.
It is recommended that they be enabled permanently 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
SQUEERS CONFIGURATION
Squeers writes its pid into /var/run/squeers.pid, if it can (ie., it is
started as root), and may be stopped with a SIGTERM. A rc.d script is
provided and installed in /usr/local/etc/rc.d/. Add the following lines
to /etc/rc.conf to start squeers on system boot-up. Replace the items in
brackets with values appropriate for your system. These are the minimal
set of options one should start with. These and all of the other avail‐
able options are described in full at the end of this manual page.
squeers_enable="YES"
squeers_flags="-r <server-root> -u <user> -g <group>"
Once your system is configured you may start, stop, or restart squeers,
or determine if it is running with the following commands:
/usr/local/etc/rc.d/squeers start
/usr/local/etc/rc.d/squeers stop
/usr/local/etc/rc.d/squeers restart
/usr/local/etc/rc.d/squeers status
If you do not want squeers started on system start, then set
squeers_enable="NO"
and use the following commands:
/usr/local/etc/rc.d/squeers forcestart
/usr/local/etc/rc.d/squeers forcestop
/usr/local/etc/rc.d/squeers forcerestart
/usr/local/etc/rc.d/squeers forcestatus
COMMAND-LINE OPTIONS
The following options are recognized. Only the -r option is required.
-r The -r option is mandatory and specifies the server root directory,
which squeers will make its current working directory and chroot(2)
to, to make it the effective root directory for the server processes.
-p The -p option specifies the port to listen on. This defaults to 1966
if not specified.
-i By default, squeers accepts connections on all interfaces it can find
capable of IPv4 or IPv6. The -i option, when present, overrides this
behavior, by limiting squeers to accepting connections from a speci‐
fied interface only. The option accepts the IP address of the
desired interface as an argument. The address must be expressed in
the presentation 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 squeers bind only to
one interface (eg., the loopback address).
-u
-g The -u and the -g options may be used to specify the user and group
identities with which Squeers runs. If not specified, both values
default to "nobody". Note that Squeers must be started as root in
order to chroot(2) to the server root directory specified by the -r
option. After it has successfully done so, it will change to the
identities specified or to the default "nobody".
-t A complete file must be transferred within 5 minutes of the server
accepting a client connection, or the connection will be dropped.
The -t option specifies the number of minutes before a timeout
occurs. Allowable values are in the range of 1 to 30.
-q The -q option, if present, specifies the backlog of client connec‐
tions queued by the OS kernel for the server to subsequently service.
This value defaults to 1000. Note that the OS kernel actually uses a
queue of 1.5 times the size of the specified value. Connections
arriving when the queue is full are dropped by the kernel. This
value should be set to a generous value. If the system starts
rejecting connections under load, and you're sure you haven't run out
of resources, try increasing the size of the backlog queue.
-x The -x option, if present, prevents squeers 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/squeers.pid when the
-x option is used.
-m The -m option specifies how many instances of squeers should be run,
and defaults to number of processors on the host machine.
AUTHORS
James Bailie ⟨jimmy@mammothcheese.ca⟩
http://www.mammothcheese.ca
Oct 05, 2013
