squeers(8) FreeBSD System Manager's Manual squeers(8)
NAME
Squeers -- File Server
SYNOPSIS
squeers -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, the server reads one line of newline-ter-
minated 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, then closes the connection. There are no headers, size counts,
checksums, error messages, or other control information associated with
requests or responses. If the server cannot understand or 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> -m <instances>"
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,
but you will probably want to include at least the -u, and -g options
when you are starting the server for production use. For optimal perfor-
mance, employ the -m option, and use the -q and -t options to match your
load levels.
-r The -r option is mandatory and specifies the server root directory,
which squeers will make its current working directory and chroot(2)
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 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 may be employed to change the value of the timeout.
Its argument is the length of time, in 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 1. This option is intended for use on multiple-core
or multiple-processor machines, where running a separate instance of
squeers for each core/processor will drastically increase the number
of requests per second squeers can process.
AUTHORS
James Bailie <jimmy@mammothcheese.ca>
http://www.mammothcheese.ca
Oct 09, 2010