Unless compiled with --enable-run-as-root you must specify a non root user and group for frox to run as. It is strongly recommended that you do this rather than recompiling.
You must specify WorkingDir for frox in the config file. By default it will also chroot to this directory. If you do not wish to run chrooted you must explicitly set DontChroot to "yes" in the config file.
Access to frox is controlled by the access control lists in the config file. These take the format
ACL ACTION CLIENT - [USER@]SERVER [PORTS]
ACTION can be one of Deny or Allow.
CLIENT and SERVER are either a domain name,
a *, an ip address, or an address/netmask in either
x.x.x.x/y or x.x.x.x/y.y.y.y form.
PORTS is optional. If present it should contain one
or more port numbers or ranges of port numbers, separated by
",". There should be no whitespace within the
PORTS string. If no ports are specified then ports
are not taken into account in matching that rule.USER
is also optional. If present then note that it should be
ftp to match any anonymous connections.
Acls are checked after the client has connected to frox, but before frox connects to the server. If non-transparent proxying is enabled then the client will enter the username before the acl is checked. The acls are checked in the order they appear in the config file until one matches. If no acls match the connection is denied.
Frox has optional support for a ftp-proxy like command control program (ccp). Just to confuse things there are two different ways that this can work. The default is still the old version based on ftp-proxy, while the new version is a bit more like the squid redirector interface.
To use either method you should compile with
--enable-ccp, and set CCProgram to the
program you wish use. This must be within the chroot jail with
any libraries and/or shells it needs to run. To use the new
version you should also explicitly set UseOldCCP to
no in the config file.
The ccp will then be called for every command that the client sends. It will not be called for any commands that frox decides to send itself (eg. as part of determining whether a file is suitable for caching). It can make use of the following environment variables:
FROX_CLIENT, FROX_SERVER: Ip addresses of client and server.
FROX_SERVERNAME: Server's domain name if known.
FROX_SESSION: Unique string for this session.
FROX_COMMAND: FTP command just given.
FROX_PARAMATER: Argument to that command.
With a new connection the ccp will be called with the
special FROX_COMMAND of +NEW. The server
variables may subsequently change if a user name is given
which contains a different server to contact.
If the ccp exits with a value of 0 then the command is dealt with as normal. If it exits with 1 then the command is discarded. If it exits with 2 then the session is closed. If the ccp writes a line to stderr then it will be sent to the client over the control connection. If it writes a line to stdout it will be logged by frox. If the ccp returns a value other than 0 it is its responsibility to write a well formed ftp message to the client which tells it what is happening (eg. from a shell script by echo -ne "533 Permission denied\r\n" >&2) . Failure to do this will result in the client and proxy getting out of sync.
One copy of the ccp will be executed each time a client
connects. It should read commands and messages from
stdin and write its replies back to
stdout. Each call is a '\n' terminated string which
starts with a single char, followed optionally by a space
and a string.
If the initial char is "I" then it is followed by
"client_ip server_ip server_name",
although if the server_name is not known it will be replaced
by an "X". If the char is a "C" then it is followed by a
command from the client, and if it is a "S" it is followed
by a message from the server.
The ccp should reply with a similar string. "C" should be followed by a message to go the client, while S is followed by a command for the server. In response to an "I" a "R" can be sent where the argument is the IP address of a server to contact in place of the currently selected one. A single "X" tells frox to continue as before, while a "Q" tells frox to drop the connection. Finally the string after an "L" will be logged by frox. It should also be followed by another line giving an action to take.
Written like that is is pretty confusing, so there are two example ccp scripts in the doc/ directory. One is a simple bash script to disallow downloading of files greater than a certain size. The other is a more complicated C program which attempts to redirect users to mirrors of ftp sites. I am sure there are other applications.
There is very experimental (currently only tested with
vsftpd) support for having frox use encryption when connecting
to the ftp server. You need to give --enable-ssl to
./configure, and define UseSSL yes in the
config file. By default data connections will also be
encrypted, but you can turn this off by setting DataSSL
no. Note you will need to create /dev/urandom
and /dev/random at least in the chroot jail, and
possibly some other stuff, for the openssl libraries to work.
If you are having difficulties try defining DontChroot
yes temporarily to see if it fixes things.
Note SSL support currently only covers the connection between frox and the ftp server. Frox does not support clients connecting to it with SSL at the moment.
It is suggested to have a config file subsection which turns off SSL for anonymous connections. There is little point in having the overhead of encryption for this, and ftp servers may deny an anonymous connection once SSL has been negotiated (this is the default configuration of vsftpd). At this stage frox is not able to undo the ssl negotiation.
This is not yet rfc compliant. It should be at some point...