Manual Reference Pages - SQUEERS (8)
- File Server
Squeers is a small and fast, KQueue-based, multiplexing file server.
Squeers listens for incoming TCP connections on a specified port. After a
connection has been accepted, squeers reads one line of newline-terminated
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 control information
associated with requests or responses. If the server cannot service a
clients request, the clients connection is immediately dropped without
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.
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.
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 available
options are described in full at the end of this manual page.
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:
If you do not want squeers started on system start, then set
and use the following commands:
The following options are recognized. Only the -r option is required.
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.
The -p option specifies the port to listen on. This defaults to 1966 if not
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 specified 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).
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".
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.
The -q option, if present, specifies the backlog of client connections
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 youre
sure you havent run out of resources, try increasing the size of the
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.
The -m option specifies how many instances of squeers should be run, and
defaults to number of processors on the host machine.
.An James Bailie Aq email@example.com
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.