Welcome to the configuration of
jftpgw FTP proxy 0.13.5
Last update: Sat Jun 5 21:55:29 CEST 2004
Navigation
Joachim Wieland
Overview
After 0.12.x the configuration file has changed completely. This is because the old configuration system was not flexible enough. The new system is like HTML or more, like XML. You describe a connection through the proxy and set an option to some value. Now, if the criteria for that connection matches, the option is valid. The next paragraph shows a sample configuration file. The settings have no special purpose, it's just to show you how the configuration file looks like.
Sample configuration file
<global>
	logstyle		files
	listen			192.168.181.234:2370
	serverport		21
	pidfile			/var/run/jftpgw.pid
	runasuser		nobody
	passiveportrange	44000:44999
	activeportrange		55000:57999
	debuglevel		9
	logfile			/home/joe/jftpgw/jftpgw.log
	cmdlogfile		/home/joe/jftpgw/jftpgw.xferlog
	cmdlogfile-style	"time: %T, bytes: %b, status: %s"
	cmdlogfile-specs	RETR STOR
	cacheprefix		/temp/cache
</global>

# nobody should connect, except for host1 and host2
<from 0.0.0.0/0 exclude host1 host2>
	access deny
</from>

# host1, host2.domain.net and 192.168.181.234 are allowed to
# connect to some other host on port 21.
<from host1 host2.domain.net 192.168.181.234>
	<port 21>
		access allow
	</port>
</from>

# *.domain.net may not connect, this paragraph is not valid for
# host1 and host2. If the connection comes from
# .slowdomain.domain.net moreover, limit the connection to 4k/s.
<from .domain.net exclude host1 host2>
	access deny
	<from .slowdomain.domain.net>
		throughput 4
	</from>
</from>

# The host on which jftpgw runs may not connect to the proxy
# itself. Thus, the proxy may not loop by calling itself again
<to localhost 0.0.0.0 serverhost.domain.net>
	<port 2370>
		access deny
	</port>
</to>

# This paragraph is valid for all connections again
<global>
	defaultmode		passive
</global>
How the configuration is checked and applied
There are the following tags to describe a connection: 
  • <global>
  • <servertype>
  • <from>
  • <to>
  • <user>
  • <port>
  • <proxyip>
  • <proxyport>
  • <forwarded>
  • <time>
The format in the configuration file is the following: 
	<tagname   whitelist    exclude   blacklist>
		[ options ]
	</tagname>
A tag is "valid" if the connection has at least one property that matches an entry in the whitelist and no property from the blacklist. In every other case the connection is not valid. The tags may be nested to combine different properties or you can list them to test several independent connection properties. For example, in: 
		<from hosta hostb hostc>
			<to dest1 dest2 dest3>
				...
			</to>
			
			<to desta destb destc>
				...
			</to>
		</from>
we have two <to>-Tags that are nested in one <from> tag. Both <to>-Tags depend on the surrounding <from> tag since they will never be examined if the surrounding tag doesn't match.

The two <to>-Tags however are listed sequentially and so they are independent. While one of them may match or may not, this has no effect on whether the other <to>-Tag matches.

The options inside the tags tell jftpgw how to behave, the tags have the role to tell, when to do it.

Of course, an option may occur more than once and it also may be valid more than once. If so, the value that was assigned to the option name the last time is the value of the option.

If a client connects to the FTP proxy, it first checks if the client IP is allowed to connect. In this step only the <global>, the <from>, the <proxyip>, the <proxyport>, the <time> and the <from> sections are evaluated. If an "access allow" is found according to the rules described above, the client is allowed to connect.

This means that the following access scheme won't work:

		<from hosta hostb hostc>          ! wrong
			<to dest1 dest2 dest3>    ! wrong
				access allow            ! wrong
			</to>                     ! wrong
		</from>                           ! wrong
The reason is that in this case jftpgw only evaluates the <from> tag when a client connects. It doesn't know where the client wants to connect to. It doesn't find any "access allow" within the evaluated tags and thus the connection is closed before evaluating any other tags. The <to> tag never gets evaluated and the "access allow" statement is never seen.

Instead, try something like: 

		<from hosta hostb hostc>
			access allow
			<to 0/0 exclude dest1 dest2 dest3>
				access deny
			</to>
		</from>
Thereafter the client sends the login information and the proxy connects to the server. This is done by discarding the tags that do not match and creating a list of options out of the other tags.
Detailed description of jftpgw's tags
  • global: This tag matches always. Use it for general proxy setup. 
    <global>
	serverport		21
	pidfile			/var/run/jftpgw.pid
	runasuser		nobody
	[...]
</global>
  • servertype: The servertype tag can be used to distinguish between a standalone and an inetd server. Use the following configuration directives to log to files and bind to 123.123.123.123 port 2370 if the proxy is run as a daemon and to log to the syslog if it is called by the (x)inetd superserver. 
    <servertype standalone>
        listen                  123.123.123.123:2370
        logstyle                files
</servertype>

<servertype inetd>
        logstyle                syslog
</servertype>
  • from: This tag only matches for connections coming from IPs or hostnames that are listed here. You may specify single IPs (123.123.123.123), IPs with netmasks (123.123.123.0/24 as well as 123.123.123.0/255.255.255.0), hostnames (host.sub.domain.com) and domains (.sub.domain.com). Mind the leading dot in the last example.
    You may also specify certain sources you want to exclude. The tag matches if the source shows up in the first section but does not show up in the second, in the exclude section.

    Here are a few examples:

    Set some options for connections coming from client1, client.with.domain.com and from the IP 192.168.181.234. 

    <from client1 client.with.domain.com 192.168.181.234>
	transparent-proxy on
	getinternalip icmp
</from>
    Allow access from all IPs that resolve to *.localdomain.com as well as for all computers with an IP of 172.26.14.* but do not allow access from the IP 172.26.14.1. 
    <from .localdomain.com 172.26.14.0/255.255.255.0 exclude 172.26.14.1>
	access allow
</from>
    This has the same functionality as above, but it goes the other way round. It blocks all IPs except for the local ones explicitly. 
    <from 0/0 exclude 172.26.14.0/24 .localdomain.com>
	access deny
</from>
    Attention: Please note that is a bad idea to use a syntax of .domain.com since anybody who is able to add/change the PTR record for his IP is able to set it to anything.domain.com and so you might allow access to the wrong persons!
  • to: You may have already guessed it, this tag matches for connections that go to the specified IPs or hostnames. The same rules for the syntax apply as for the previous paragraph.

    Have a look at the following examples:

    Use caching for connections going to the following three ftp servers: 

    <to ftp1.server.com ftp2.server.com ftp3.server.com>
	cache on
</to>
    Do not allow anybody to use the proxy to connect anywhere except for connections to ftpintern1 and ftpintern2, the two may be your internal FTP servers. 
    <to 0/0 exclude ftpintern1 ftpintern2>
	access deny
</to>
  • user: The options in the user tag apply if one of the listed user names match the user name of the current connection. You may use the wildcard "*" to match every username. This tag is often used for forwarding special user names to another destination.

    Here are the examples:

    Allow only anonymous access: 

    <user anonymous>
	access allow
</user>
    If there is a connection to the proxy that requests 192.168.1.2 as destination and sends "anonymous" as the username for the target, forward the connection to ftp.somewhere.com on port 2121 using active and cached transfers. 
    <user anonymous>
	<to 192.168.1.2>
	       forward ftp.somewhere.com:2121,a
	       cache on
	</to>
</user>
    If the login user name for the target is anything else than "specialuser", forward the connection to ftp.newdest.com, sending secretuser as username and ierk484kf as the password. However the remote user has to send the password for his "specialuser" account that is crypted below. 
    <user * exclude specialuser>
	forward secretuser@ftp.newdest.com  KfSNwdnGzWpy. ierk484kf
</user>
  • port: The port tag compares the specified port list to the destination port of the FTP connection. This is usually port 21 but can be any other port number as well. You may specify discrete port numbers as well as port ranges (startport:endport)
    Use this to restrict access, especially to restrict the incoming traffic if you're using the proxy to enable access to a publicly available FTP server in your private network. 
    <port 0:65535 exclude 21>
        access deny
</port>
    If you're using the transparent proxy feature you could use something like this. It does not allow a connection to the local machine on port 2370. 
    <to localhost 192.168.181.234>
       access allow
       <port 2370>
               access deny
       </port>
</to>
    Here's another fancy port range specification. It has no real sense, it should just explain the syntax :-)<br> It would match for ports 21-94, 97-99 and 105-494. 
    <port 21:94 97:494 exclude 100:104>
	[...]
</port>
  • proxyip: This tag is mainly for use with the transparent proxy feature. It resembles the <from> and the <to>-tag quite a lot but it does not match on the intended connection but on the resulting connection to the proxy. With this option you can have a single jftpgw proxy for inbound and outbound traffic. If your computer has one internal IP and one for the internet, everything within 
    <proxyip 123.123.123.123>
	[...]
</proxyip>
    applies to the traffic that connected to the proxy from the outside, i.e. that addressed the IP 123.123.123.123 of your proxy. To set the configuration for outbound traffic, i.e. traffic that addressed the internal IP of your proxy goes here: 
    <proxyip 192.168.1.1>
	[...]
</proxyip>
    You may also specify devices like in the following example: 
    <proxyip eth1>
	[...]
</proxyip>
    However this works only if you see "can get IPs from interfaces" in the output of jftpgw -v.
  • proxyport: This tag is of course similar to the <proxyip> option and matches if the connection addressed the proxy at the specified port. Here is an example how this could be used: If you have several internal networks and every network should get a different bandwith, you could set up your firewall to REDIRECT the traffic from these nets to different ports on your firewall. jftpgw then listens to all of them: 
    	listen 192.168.1.1:2371 192.168.1.1:2372 192.168.1.1:2373
    If somebody from one of these nets initiates an FTP connection he will get REDIRECTed by your firewall to, say, port 2372. Now you can specify 
    <proxyport 2372>
	throughput	20.0
</proxyport>
    to give him 20 k/s.

    Of course you could achieve the same by just putting the throughput-Option in a <from>-tag but you didn't ask for a useful example :-)

  • forwarded: This tag wraps around other tags and it is valid for a forwarded connection. It does not take any extra parameters.

    The following section does not match if the user connects to ftp.fu-berlin.de directly, it does only apply if there was a forward specifying that ftp.fu-berlin.de is the new destination. Of course you can use any other tags inside the <forwarded> tag. 

    <forwarded>
        <to ftp.fu-berlin.de>
                cacheminsize    40k
                cachemaxsize    3M
        </to>
</forwarded>
  • time: The time tag compares the time you specify to the current system time and matches if the system time lies within the specified time.

    You may either specify a list of days in combination to a time range (Day1/Day2/Day3 xx:xx - yy:yy) which would match every day in the specified interval or you may want the tag to match over a longer period, starting on one day and ending on some other day. Therefore use the following syntax: Day1 xx:xx - Day2 yy:yy
    You can also leave Day2 away and say: Day xx:xx - yy:yy which means that your interval starts and ends on the same day.
    The time definition can either be xx:xx (colon) or xx.xx (dot).
    Separate different time ranges with a ";" or ",".

    Here is an example: Deny access on Mondays and Tuesdays from 12.00 to 13.44. Then again from Wednesday 19.00 until Friday 20.00. 

    <time Mon/Tue 12:00 - 13:44; Wed 19.00 - Fri 20.00>
        access deny
</time>
List of the configuration options
 
access Sections: ALL
  Default: deny
This is the most important option for access control. Set it to allow if you want to grant access or to deny to display a "You are not allowed to connect" message.

You may set this option (as all others) several times throughout the configuration file but the option that is specified last within a valid tag matches (see above)


Disallow access from the 192.168.x.x net but allow if the connection is from the 192.168.19.x net, if the user name is anonymous and if the connections go to some target machine on port 21. Note that both options may apply because both <from>-tags may be valid. If so, the last access-option is taken into account.


Example: 

<from 192.168.0.0/16>
	access deny
</from>
<from 192.168.19.0/24>
	<user anonymous>
		<port 21>
			access allow
		</port>
	</user>
</from>
 
account Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME
  Default: no default value
Specifies accounts for a user so that this user can log in to the proxy before he's able to use it. See the the loginstyle option) for information on how to set up this password checking.


Syntax: 

Account		<user>	Password	<crypt()ed pass>

You may get crypted passwords by executing 

jftpgw -e
and typing the cleartext password. The output is a crypt()ed password.


Example: Set the password "test" for the user "fwjoe" 

Account		fwjoe	Password	hFPO1IKNeeeUM

If your platform does not have the crypt() function you'll have to use cleartext passwords in this file.

 
activeportrange Sections: ALL
  Default: no default value
Port ranges configuration: You may tell jftpgw which port you want it to use for data transfers. Thus you could specify one or more port ranges you accept on your firewall and if jftpgw finds a free port in this range, this one will be used. So you do not have to open ALL unprivileged ports but only, just, err... :-)
Furthermore this option is nice if you have an FTP server behind a NAT router and just want to pass a port range back to a machine in the private network.
Active and passive ports can be configured separately and the bounds are included in the range.
Please note that the portranges also apply to the source port jftpgw will choose. If you want to configure it in a more detailed fashion, see the the activeportrangeclient, the activeportrangeserver, the passiveportrangeclient and the the passiveportrangeserver options.


Syntax: 

passiveportrange	start1:end1  [start2:end2]  [start3:end3] ...
activeportrange		start1:end1  [start2:end2]  [start3:end3] ...

Example: 
passiveportrange	38900:38999   3400:3449   64020:64020
activeportrange		25400:25499

passiveportrange	39500:39999
activeportrange		39500:39999
 
activeportrangeclient Sections: ALL
  Default: no default value
The portrange to use for active transfers. This is the portrange that is used to choose the source port for the proxy if it connects to the port the client told the proxy with the "PORT 127,0,0,1,4,13" message.

The activeportrangeclient setting overrules the activeportrange option.

See the activeportrange option for examples on portrange specification.

 
activeportrangeserver Sections: ALL
  Default: no default value
The portrange to use for active transfers. This is the portrange that is issued to the server with the "PORT 127,0,0,1,4,13" message. The proxy listens on a port in the portrange and waits for the server to connect.

The activeportrangeserver setting overrules the activeportrange option.

See the activeportrange option for examples on portrange specification.

 

 
allowforeignaddress Sections: ALL
  Default: no
allowforeignaddress allows a client to specify an IP in the PORT command that is different from the IP the connection is originating from. This is a security option but if you set it to off (which is the default), you won't be able to do FXP transfers any more.

Enable it with 

allowforeignaddress on
Instead of "on" you may also say "yes", "true" or just "1". As you may already have guessed, the opposite is "off", "no", "false" and "0". Other values are not allowed.

 

 
allowreservedports Sections: ALL
  Default: no
allowreservedports allows the specification of reserved ports in a PORT command. This is part of the "FTP bounce attack" and is therefore disabled.

See http://www.sonic.net/hypermail/security/mbox/0270.html for details

Enable it with 

allowreservedports on
Instead of "on" you may also say "yes", "true" or just "1". As you may already have guessed, the opposite is "off", "no", "false" and "0". Other values are not allowed.

 

 
cache Sections: ALL
  Default: off
This option enables or disables the cache. If you combine it with the configuration system you may dynamically switch it on or off depending on the different connection properties.


Since we are all fans of Mickeymouse, enable the cache for ftp.micky.com


Example: 

<to ftp.micky.com>
	cache on
</to>

Most people have a special account on the Mickeymouse server but it is not reasonable to cache it. Furthermore some people know secret Mickeymouse servers running on different ports, don't cache them either, they are secret :-)
Only cache anonymous access to ftp.micky.com on port 21.


Example: 

<to ftp.micky.com>
	<user anonymous>
		<port 21>
			cache on
		</port>
	</user>
</to>


Example: The same as above, but the other way round 
<global>
	cache on
</global>
<to 0/0 exclude ftp.micky.com>
	cache off
</to>
<user * exclude anonymous>
	cache off
</user>
<port 0:20 22:65535>
	cache off
</port>
Instead of "on" you may also say "yes", "true" or just "1". As you may already have guessed, the opposite is "off", "no", "false" and "0". Other values are not allowed.

 

 
cachemaxsize Sections: ALL
  Default: unlimited
Specify the maximal size of a file to be cached. It may not be reasonable to cache only a few large files but to cache more smaller files instead.

You may use the size multipliers b, k, M and G


Example: 

cachemaxsize		15M


Example: The default value is unlimited you may also specify it explicitly: 

cachemaxsize		unlimited
 
cacheminsize Sections: ALL
  Default: 0
Specify the minimal size of a file to be cached. It may not be reasonable to cache files that are too small but to cache larger files instead.

You may use the size multipliers b, k, M and G


Example: 

cacheminsize		100k
 
cacheprefix Sections: ALL
  Default: no default value
This option sets the path for the cache, i.e. the path that is prepended before every cached object. The cache lies under <cacheprefix>/user@host:port/


Example: Set the FTP cache to /var/ftpcache/ 

cacheprefix		/var/ftpcache
 
changeroot Sections: GLOBAL, SERVERTYPE
  Default: no default value
This option controls when jftpgw changes the root directory. Possible values are start, startsetup, connect, connectsetup and never.
  • start: Change the root directory right after the proxy is launched. If you use this option, your logfiles and the pid file have to be within the chroot-jail. Furthermore you cannot reread the configuration file without stopping and restarting the proxy if it is out of the chroot-jail.
  • startsetup: Change it after doing some initial setup like opening the log files and writing the pid file. If you use this setting, the same limitations apply as for start.
  • connect: Change the root directory as soon as a client connects. That means that the main jftpgw process still runs out of the chroot jail but every client runs within.
  • connectsetup: See the analogy with startsetup. With this option the root directory is changed after a client has connected, an ftp process has forked off and has opened the logfiles. So these can be outside of the chroot jail.
  • never means that the proxy never tries to do change the root directory.

Please keep in mind that you have to be root to change the root directory. So the proxy has to be launched by root and the the dropprivileges option which takes the same values must not be lower than the changeroot option.

Note as well, that after changing the root directory, you might encounter problems when trying to reload the configuration file or writing to log files. See the the changerootdir option to see how jftpgw tries to open files within a chroot jail.

You also might not be able to resolve hostnames. This affects the way you have to write your configuration file (use IP numbers) instead of names. Furthermore a login like "USER anonymous@some.ftp.server.com" might not work anymore because jftpgw is unable to look up the host name. However you can copy some files to the chroot jail. On my system I had to copy /etc/hosts and /etc/resolv.conf to the chroot-jail in order to be able to do DNS lookups.


Example: Change the root directory as soon as a jftpgw process has forked off to handle a client connection 

changeroot		connect
 
changerootdir Sections: GLOBAL, SERVERTYPE
  Default: no default value
The changerootdir option causes jftpgw to change it root directory to the specified directory. The time of the change of the root directory depends on the setting of the changeroot option.

Please note: When opening a file, jftpgw tries to strip off the chrootdir directory. That means that if you specify for example 

changerootdir		/var/chroots/ftp-proxy
logfile			/var/chroots/ftp-proxy/logfile
and jftpgw can't access /var/chroots/ftp-proxy/logfile it will try to open /logfile.

The same applies for the configuration file. If you want to be able to reload the configuration file later on and use a chroot jail at the same time, you can copy the configuration file to the jail and start the proxy with the -f option: 

jftpgw -f /var/chroots/ftp-proxy/etc/jftpgw.conf
jftpgw will open /var/chroots/ftp-proxy/etc/jftpgw.conf the first time, do the chroot change and read /etc/jftpgw.conf later on because it strips off the name of the chroot directory from the name of the configuration file.


Example: 

changerootdir		/var/chroots/ftp-proxy
 
cmdlogfile Sections: ALL
  Default: no default value
The command logfiles log the commands the client sends to us. The format is 
	cmdlogfile			<filename>
Use this setting 
	cmdlogfile-specs		<CMD1> <CMD2> <CMD3>
to specify the commands that should be logged. It may be useless to log PORT commands or thus but USER RETR STOR and the like may be interesting If you want to log the PASS command, jftpgw will substitute the password with an asterisk (`*').
This example logs some common commands
Example: 
cmdlogfile			/var/log/jftpgw.commandlog
cmdlogfile-style		commonlog
cmdlogfile-specs		USER RETR STOR CWD REST

This would log the complete FTP command set except for USER and PASS commands.
Example: 
cmdlogfile			/var/log/jftpgw.commandlog
cmdlogfile-specs		* -USER -PASS
cmdlogfile-style		commonlog

Whereas this one logs only the commands that initiate up- and downloads and writes it to a logfile in the so-called "xferlog" format like other famous FTP daemons. xferlog only makes sense with "RETR" and "STOR" in the specs-line.
Example: 
cmdlogfile			/var/log/jftpgw.xferlog
cmdlogfile-style		xferlog
cmdlogfile-specs		RETR STOR
 
cmdlogfile-style Sections: ALL
  Default: no default value
The option controls how a log message from the client should be written to the logfile 
	cmdlogfile-style			<log format>
<log format> could be one of: 
cmdlogfile-style			xferlog
cmdlogfile-style			commonlog
cmdlogfile-style			<format string>

<log string> is a %-escaped format string resembling to printf(3). The recognized format characters are: 
'c'  complete (prints 'c' or 'i' for complete/incomplete)
'D'  common log date/time format: "[18/Feb/2001:11:42:46 +0100]"
't'  date/time like in "Wed Feb 14 01:41:28 2001"
'T'  Time taken to transmit/receive file, in seconds
'b'  Bytes sent for request
'R'  throughput rate in kbyte/s
'f'  Filename stored or retrieved, absolute path
'F'  Filename stored or retrieved, as the client sees
'm'  Command (method) name received from client, e.g., RETR
'r'  Command with parameters, e.g. "RETR /misc/editors/vim/README"
'P'  pid of the jftpgw process that handles this connection
's'  Numeric FTP response code (status)
'y'  tYpe (ASCII or binary)
'w'  direction (incoming or outgoing)
'o'  anonymous? ("a" for anonymous logins, "r" for user logins)
'e'  sErvice (always "ftp" for now)
'n'  aNon-user (e-Mail address when logged in as anonymous user,
     "UNKNOWN" otherwise)
'H'  Server host name
'A'  Server host IP
'd'  Server host name as specified in the login
'h'  Client host name
'a'  Client host IP
'I'  Server interface address
'i'  Client interface address
'l'  Server user name (login)
'L'  Effective server user name
'C'  Forwarded server user name
'u'  unix time in seconds since the epoch
'U'  unix time in seconds since the epoch with milliseconds appended after a dot
'%'  percent sign itself

This is how xferlog style logging is realized:
Example: 
cmdlogfile-style	"%d %h %T %f %y %w _ %n %l %s 0 * %c"

xferlog generates this type of output: 
Dow Mon DD hh:mm:ss YYYY %d %h %T %f %y %w _ %n %l %s 0 * %c

Example: (this is actually one line) 
Sat Oct 12 11:53:26 2002 ftp.uni-stuttgart.de localhost 0 \
welcome.msg b o _ xxxcccc anonymous 226 0 * i

commonlog generates this type of output: 
	REMOTE AUTH USER [DATE] "CMD" RCODE SIZE

In fact it is just a short notation for %A %n %l %D "%M" %s %b as style argument.


Example: (lines wrapped around) 

130.133.1.100 jwieland@bigfoot.de anonymous \\
 -> [12/Feb/2003:13:34:47 +0100] "LIST" 226 1749
130.133.1.100 jwieland@bigfoot.de anonymous \\
 -> [12/Feb/2003:13:34:49 +0100] "PORT 134,130,181,112,138,150" 200 0
130.133.1.100 jwieland@bigfoot.de anonymous \\
 -> [12/Feb/2003:13:34:49 +0100] "TYPE I" 0 0
130.133.1.100 jwieland@bigfoot.de anonymous \\
 -> [12/Feb/2003:13:34:50 +0100] "RETR /editors/vim/README" 226 9158

squid style logging could be done by this:
Example: 
cmdlogfile-style	%U %b %a %w/%s %T %m ftp://%d/%f %l %e/%A %y
 
commandtimeout Sections: ALL
  Default: 300
This specifies the timeout value in seconds before a connection is closed. The commandtimeout applies to the timeout of the control connection (where the commands from the clients are read). You may probably want to set this to a higher value than the timeout for the transfertimeout since it is more likely that a user is just idle sending commands than it is likely that a transfer takes such a long time to be continued.


Example: Set the timeout to 600 seconds (i.e. 10 minutes) 

transfertimeout		600
 
connectionlogdir Sections: ALL
  Default: no default value
The connection log dir creates a logfile for each connection and writes the commands the client sends to us in that file. You must also specify a prefix and a suffix for the filenames The rest of the filename consists of date, time and the pid of the process that handled the connection.
Syntax: 
connectionlogdir			<directory>
connectionlogdir-fileprefix		<fileprefix>
connectionlogdir-filesuffix		<filesuffix>
connectionlogdir-specs			<CMD1> <CMD2> <CMD3>
connectionlogdir-syle			<style>

This example logs the most common commands in a directory where each ftp session is covered in one file called (in this example) /var/log/jftpgw-connect-2000-03-23--18:24:05-891.log Between the prefix and the suffix of the filename, jftpgw inserts the date, the time and the pid (of the jftpgw process that handles the connection).
Example: 
connectionlogdir		/var/log/jftpgw
connectionlogdir-fileprefix	jftpgw-connect-
connectionlogdir-filesuffix	.log
connectionlogdir-specs		USER PASS RETR STOR
connectionlogdir-syle		commonlog
 
controlserveraddress Sections: ALL
  Default: no default value
Set the source IP to use for the control connection to the FTP server. You may need this if you set dataserveraddress since some FTP servers decline PORT commands if the IP doesn't match the source IP of the control connection.

See also the dataserveraddress option


Example: 

controlserveraddress	212.39.39.39

You may also specify devices like in the following example: 
controlserveraddress ppp0

However this works only if you see "can get IPs from interfaces" in the output of jftpgw -v.

 
dataclientaddress Sections: ALL
  Default: no default value
Set the IP to send to the client for PORT/PASV responses. This may be useful for you if you have several interfaces that have all working routes to the client and if one of them is faster than the default interface. Furthermore, if you have a tight firewall setup and you don't want to allow the proxy to send ICMP or UDP packets to your internal network (see also the getinternalip option)

See also the dataserveraddress option


Example: 

dataclientaddress	212.39.39.39
You may also specify devices like in the following example: 
<dataclientaddress ppp0>
	[...]
</dataclientaddress>
However this works only if you see "can get IPs from interfaces" in the output of jftpgw -v.

 
dataport Sections: none
  Default: no default value
The dataport option is outdated and has been replaced by the more powerful portrange settings. See the activeportrangeclient and the passiveportrangeserver options.

 

 
dataserveraddress Sections: ALL
  Default: no default value
Set the IP to send to the server for PORT/PASV responses. This may be useful for you if you have several interfaces that have all working routes to the server and if one of them is faster than the default interface.

See also the dataclientaddress option


Example: 

dataserveraddress	212.39.39.39

You may also specify devices like in the following example: 
dataserveraddress ppp0

However this works only if you see "can get IPs from interfaces" in the output of jftpgw -v.

 
debuglevel Sections: ALL
  Default: 7
The debug level:
0quiet
1fatal errors
2critical errors
3errors
4important warnings
5warnings
6important information
7information
8program flow
9unimportant
I recommend to set it to 5 or 6. Do NOT set it below 4 unless you know what you are doing.
Example: 

debuglevel 5
 
defaultforward Sections: ALL
  Default: no default value
This option has been removed in version jftpgw-0.13.beta.i

You can do the same with the forward option.  
defaultmode Sections: ALL
  Default: asclient
Specify the default mode (active or passive ftp) between the proxy and the real server. This is useful if either the client or the server does not support the desired mode `asclient' uses the mode the client suggests on the other side to the real server as well Valid options are `active', `passive', or `asclient'
Example: 

	defaultmode		active
	defaultmode		passive
	defaultmode		asclient
 
dnslookups Sections: ALL
  Default: yes
This option enables you to switch on or off DNS lookups. If you don't want to resolve names to IPs and vice versa, you might want to turn this off. To control forward and reverse lookups seperately, see the forwardlookups option and the the reverselookups option).


Example: 

dnslookups		off
Instead of "on" you may also say "yes", "true" or just "1". As you may already have guessed, the opposite is "off", "no", "false" and "0". Other values are not allowed.

 

 
dropprivileges Sections: GLOBAL, SERVERTYPE
  Default: start
This option controls when jftpgw tries to drop its privileges. Possible values are start, startsetup, connect, connectsetup and never (yes, these are the same values as the the changeroot option)
  • start: Drop privileges right after the proxy is launched. If you use this option, your logfiles and the pid file are created with the user and group id you specified in the the runasuser option and the the runasgroup option.
  • startsetup: Change the identity after doing some initial setup like opening the log files and creating the pid file.
  • connect: Change the identity as soon as a client connects. That means that the main jftpgw process still runs with superuser identity (so it will change its effective user id as often as possible).
  • connectsetup: See the analogy with startsetup. With this option the identity is changed after a client has connected, an ftp process has forked off and has opened per-client logfiles. So these are created with the identity of the superuser. You also need to set this if your operating system needs root privileges to get the real destination of the client when using the transparent proxy feature. (Linux doesn't need this, though)
  • never means that the proxy never tries to do drop the privileges completely but still tries to change its effective user id.

If you want to change the root directory, please see the changeroot option, too.

Please note the implications of changing the identity. If you drop the privileges later than at stage start for example, you won't be able to re-open the logfile without shutting down and restarting jftpgw completely. It would open the logfile as user root, then change to the unprivileged user and as soon as the logfile is closed, jftpgw loses access to it because it has no longer the privileges to open it again. This may not be bad, maybe it is intended, but you just should know about these things.

In the very rare situations where you need to bind to a privileged port (port numbers below 1024) you will have to specify never but make sure there is really no other way to go.


Example: Drop privileges after the main logfile and the pid file have been created 

dropprivileges		startsetup
 
forward Sections: ALL
  Default: no default value
Specify user forwards here. There are several examples below how jftpgw rewrites a login (user/password combination) to the proxy into another login to the target FTP server.
Syntax: 
forward  <newlogin>  <jftpgw pass>   <destination pass>

Forward user eddie who logs in from 212.39.39.39 to eddie@ftp.micky.com and pass the password along.


Example: 

<from 212.39.39.39>
	<user eddie>
		forward ftp.micky.com
	</user>
</from>

Forward user eddie to eddie@ftp.micky.com, allow any password but send mickeymouse to the server ftp.micky.com.


Example: 

<from 212.39.39.39>
	<user eddie>
		forward ftp.micky.com	*	mickeymouse
	</user>
</from>

Forward user eddie to eddie@ftp.micky.com, allow only password goofy, but send the password mickymouse to the destination machine. (goofy may be here in a crypted version like yp8T9bQvnPoFs if you have crypt support (check with jftpgw -v). Use jftpgw -e to create crypted passwords)


Example: 

<from 212.39.39.39>
	<user eddie>
		forward ftp.micky.com	goofy	mickeymouse
	</user>
</from>
or 
<from 212.39.39.39>
	<user eddie>
		forward ftp.micky.com    yp8T9bQvnPoFs    mickeymouse
	</user>
</from>

Forward every user to anonymous@ftp.kernel.org


Example: 

<user *>
	forward    anonymous@ftp.kernel.org
</user>

Forward every user except for goofy to anonymous@ftp.kernel.org, allow any password but send mickeymouse as the new password to ftp.kernel.org.


Example: 

<user * exclude goofy>
	forward     anonymous@ftp.kernel.org    *    mickeymouse
</user>

Forward the user who logged in with anonymous@ftp.kernel.org to a secret FTP server of the real Mickeymouse where there is proof that Mickeymouse really lives! Of course, this FTP server does not run on port 21... Futhermore we have to use active FTP since the Mickeymouse has a NAT-ted FTP server and is too lame to configure it properly.


Example: 

<user anonymous>
	<to ftp.kernel.org>
		# Note that this would log on as user anonymous,
		# since I didn't specify a new user name.
		forward		mickeylives.micky.com:2121,a
	</to>
</user>
If you want to run a proxy that passes _all_ the authorisation data to another proxy/server, see the following example. If you log on to jftpgw with say user@site@site:port exactly this is passed to the server you specify here.
Pass the complete authorization to otherproxy and use port 3942 there
Example: 
forward		*@otherproxy:3942

forward		*@fileserv
If you want to set a destination for people who log in just with user and not user@remotehost you can use the defaultforward setting to specify a destination host that should be used if none is given and none can be obtained by the transparent proxy framework. The setting is ignored if a destination is given with the login (user@destination) or when jftpgw is used as a transparent proxy and can get a destination that way.
Forward users to ftp.company.com, if they log in just with their user names.
Example: 
forward		%@ftp.company.com
 
forwardlookups Sections: ALL
  Default: yes
This option enables you to switch on or off DNS forward lookups. If you don't want to resolve names to IPs, you might want to turn this off.

See also the the dnslookups option and the the reverselookups option).


Example: 

forwardlookups		off
Instead of "on" you may also say "yes", "true" or just "1". As you may already have guessed, the opposite is "off", "no", "false" and "0". Other values are not allowed.

 

 
getinternalip Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME
  Default: udp
If you have jftpgw running as a transparent proxy, the proxy has a problem: It needs to know the IP of the interface that is connected to the client in order to send it correct PASV/PORT answers. Normally, this IP is obtained by a system call. However, if the proxy works as a transparent proxy, this system call does return the target the client program wanted to connect to, not the local IP jftpgw is interested in.

So jftpgw has to find another way to obtain this IP. There are two possibilities:

  • Either to send an ICMP packet (echo request) and read the answer (echo reply) in order to see to which IP it was sent back (icmp)
  • or to send a UDP packet to the client and see how the kernel routes the packet (udp).
  • If the proxy should not try to get the address by itself, say configuration here and specify the address in the configuration file. See option dataclientaddress
If you set udp you may also want to set the port the packets go to. (see the udpport option)

You have to be root to send ICMP packets. The the dropprivileges option must not be set below connectsetup.

If you say udp or icmp here, make sure the dataclientaddress option is NOT set, since it will override your setting.


Example: Get the IP by sending an ICMP packet 

getinternalip		icmp

Example: Get the IP by sending a UDP packet 
getinternalip		udp

Example: Specify it manually 
getinternalip		configuration
dataclientaddress	192.168.10.20
 
hostcachetimeout Sections: ALL
  Default: 28800
Since jftpgw does quite a lot of DNS lookups normally (see the dnslookups option), it uses a built-in cache for every record it has looked up. The value you can specify here controls the time in seconds an item from this cache is valid before it is removed from the cache. The default value is 8 hours, that are 28800 seconds.
Example: 
hostcachetimeout	10800
 
initialsyst Sections: ALL
  Default: yes
As many other clients jftpgw sends a SYST command to the FTP server right after the connection succeeded. This is just a check if there is really an FTP server there and if it answers properly.

This shouldn't be a problem normally. However, people told me about firewalls that drop the connection if this command is sent at the very beginning. If you set this to "off", jftpgw won't send an initial SYST command anymore.


Example: 

initialsyst		off
Instead of "on" you may also say "yes", "true" or just "1". As you may already have guessed, the opposite is "off", "no", "false" and "0". Other values are not allowed.

 

 
limit Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME
  Default: no default value
Limit the number of simultaneous logins to the jftpgw proxy server. The option has no effect if you run jftpgw from inetd.
Syntax: 
limit    <maximal # of connections>

Example: 
<from 192.168.0.0/16>
	limit			4
</from>

<from 0/0 exclude 192.168.0.0/16>
	limit			20
</from>

Please note that this option is not reliable if you use it within the <time>-tag. Consider the following example: 

<time Mon 18:00 - 19:00>
	limit		10
</time>

<time Mon 19:01 - 20:00>
	limit		5
</time>
If there are 10 clients connected at 19:00, there can connect additional 5 clients a minute later. So you might have 15 clients connected though your limit is only 5 ! This limitation only applies to the <time>-tag.

Hint: If you want to use jftpgw with (x)inetd, the limit-Option does not work because there is no controlling process that could count its children. In this case you can use the per_source = x xinetd option.

 
listen Sections: GLOBAL, SERVERTYPE
  Default: 0.0.0.0:2370
Bind to the address(es) specified below You may either specify an IP or a hostname of your local machine

With this option you can specfify on which IP address jftpgw should listen. Imagine you have two ethernet devices, one for the internal network and one for the external. If you specify only the internal one here jftpgw is only accessible from the internal network. On the IP of your other ethernet device that is connected to the outside you could run a real FTP server for outside users for example... So both services would run on the same machine and may have the same port numbers assigned but they do not interfere since they listen to different devices, to different IPs. 0.0.0.0 makes jftpgw to listen on all available devices.


Example: This would listen on all interfaces on port 2370 and on the IP associated with localhost (usually 127.0.0.1) additionally on port 2380

listen			0.0.0.0:2370            localhost:2380
 
logfile Sections: ALL
  Default: /var/log/jftpgw.log
Which is the logfile jftpgw should write its log messages to?
Example: 
logfile /var/log/jftpgw.log
 
loginstyle Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME
  Default: 1
Unfortunately there is no real standard for FTP proxy access out there and thus several methods have evolved over the time. jftpgw supports most of them, below is the complete list with a description for each login style. If you use transparent proxy support, you should not have to care for this option. You only need this to connect to jftpgw with a special client. See the documentation for the client which methods it supports and then set the proper value here.
  • type 0: 
    Do NOT use a firewall
  • type 1: 
    Connect to firewall host, but send
		"USER user@real.host.name"
	USER with no login (user@host port)
	USER with no login (user@host:port)
  • type 2: 
    Connect to firewall, login with "USER fwuser"
		 and "PASS fwpassword", and then "USER user@real.host"
		 and thereafter "PASS password"
	USER with login (user@host port)
	USER with login (user@host:port)
  • type 3: 
    Connect to and login to firewall, and then use
		 "SITE real.host.name", followed by the regular
		 USER and PASS.
	SITE with login (user@host port)
	SITE with login (user@host:port)
  • type 4: 
    Connect to firewall, and then use (without login)
		 "SITE real.host.name", followed by the regular
		 USER and PASS.
	SITE without login
  • type 5: 
    Connect to and login to firewall, and then use
		 "OPEN real.host.name", followed by the regular
		 USER and PASS.
  • type 6: 
    Connect to firewall, and then use (without login)
		 "OPEN real.host.name", followed by the regular
		 USER and PASS.
  • type 7: 
    Connect to firewall host, but send
		  "USER user@fwuser@real.host.name" and
		  "PASS pass@fwpass" to login.
	CheckPoint Firewall 1
  • type 8: 
    Connect to firewall host, but send
		  "USER fwuser@real.host.name" and
		  "PASS fwpass" followed by a regular
		  "USER user" and
		  "PASS pass" to complete the login.
  • type 9: 
    Connect to firewall host, but send
		  "USER user@real.host.name fwuser" and
		  "PASS pass" followed by
		  "ACCT fwpass" to complete the login.
	User@host FireID

If there are accounts involved ("SITE/OPEN with login" for example) see the account option) for information on how to create one.


Example: The client uses the SITE command without login. 

loginstyle		4
 
logintime Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME
  Default: user
This option controls when jftpgw connects to the FTP server. Possible values are connect, user and pass.
  • connect only works with transparent proxy support or with a forward setting like "forward *@123.123.123.123" (how else should the proxy determine the destination?)
  • user connects after a "USER user@otherhost.com" and
  • pass reads the whole login and then logs in to the FTP server.
It should be okay for all cases to use user. Do not use connect if you have forwards configured (see the forward option)

If you have set this option to either user or pass you may configure the 220 welcome line with the welcomeline option.


Example: Read all the login information and then connect to the server 

logintime			pass
 
logstyle Sections: ALL
  Default: files
Here you can specify if you would like to create extra files for jftpgw log messages or if you just want to use the usual Unix logging style via a daemon (syslogd) that catches all logging messages and writes them to a file.
Syntax: 
logstyle (files|syslog)
The default value is "files".
Example: 
logstyle		syslog

Example: 
logstyle		files
 
passallauth Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME
  Default: no default value
This option has been removed in version 0.13.beta.i

Please have a look at the the forward option, you can do the same with this option now.  
passiveportrange Sections: ALL
  Default: no default value
The portrange to use for passive transfers. See the activeportrange option.

 

 
passiveportrangeclient Sections: ALL
  Default: no default value
The portrange to use for passive transfers. This is the portrange that is issued to the client with the "227 Entering Passive Mode (127,0,0,1,4,13)." message. The proxy listens on a port in the portrange and waits for the client to connect.

The passiveportrangeclient setting overrules the passiveportrange option.

See the activeportrange option for examples on portrange specification.

 

 
passiveportrangeserver Sections: ALL
  Default: no default value
The portrange to use for passive transfers. This is the portrange that is used to choose the source port for the proxy if it connects to the port the server told the proxy with the "227 Entering Passive Mode (127,0,0,1,4,13)." message.

The passiveportrangeserver setting overrules the passiveportrange option.

See the activeportrange option for examples on portrange specification.

 
pidfile Sections: GLOBAL, SERVERTYPE
  Default: /var/run/jftpgw.pid
If jftpgw should create a pidfile you can specify the location here Keep in mind that on a typical Unix-System not all the users have write access to /var/run so you might want to change the path.


Example: 

pidfile			/var/run/jftpgw.pid
 
reverselookups Sections: ALL
  Default: yes
This option enables you to switch on or off DNS reverse lookups. If you only use IPs in your configuration file and thus you don't need to resolve IPs you might want to turn this off.

See also the the dnslookups option and the the forwardlookups option).


Example: 

reverselookups		off
Instead of "on" you may also say "yes", "true" or just "1". As you may already have guessed, the opposite is "off", "no", "false" and "0". Other values are not allowed.

 

 
runasgroup Sections: GLOBAL, SERVERTYPE
  Default: no default value
The following option is the name of the group jftpgw should change to when dropping privileges (see the dropprivileges option). More important however is the setting of the runasuser option.
Example: 
runasgroup		proxy
 
runasuser Sections: GLOBAL, SERVERTYPE
  Default: no default value
The following option is the name of the user jftpgw should run with. This option is only effective if jftpgw is run as root (decide on your own if you take this risk to run jftpgw as root at all - if so, try to drop privileges as soon as possible - see the dropprivileges option).

It might be a good idea to create an own user and a own group for jftpgw.

Take a look on the the runasgroup option.
Example: 

runasuser		ftp-proxy
 
serverport Sections: ALL
  Default: 21
The default server port (usually Port 21 for FTP)
Example: 
serverport		21
 
strictasciiconversion Sections: ALL
  Default: on
When converting binary to ASCII, there is no rule how to convert a \r\n. If you do have set strictasciiconversion, you replace every \n by an \r\n, which results in an \r\r\n. If you don't, the conversion will leave this situation untouched, since it already is a proper ASCII line break.


Example: 

	strictasciiconversion		on
Instead of "on" you may also say "yes", "true" or just "1". As you may already have guessed, the opposite is "off", "no", "false" and "0". Other values are not allowed.

 

 
syslogfacility Sections: ALL
  Default: daemon
Specify the facility for the syslog logging here.
Example: 
syslogfacility		ftp
 
throughput Sections: ALL
  Default: no default value
Limit the throughput of an ftp connection. The unit of rate is kbyte per second.
Syntax: 
througput  <rate>

Example: 
<user anonymous>
	throughput       7.5
</user>

This setting limits every client to 10.00 kBytes/second. It does not mean that all hosts from this network share 10.00 kBytes/second.
Example: 
<from 123.123.0.0/16>
	throughput       10.00
</from>
 
transfertimeout Sections: ALL
  Default: 300
This specifies the timeout value in seconds before a connection is closed. The transfertimeout applies to all data transfers.


Example: Set the timeout to 180 seconds (i.e. 3 minutes) 

transfertimeout		180
 
transparent-forward Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME
  Default: no default value
Another forwarding option is the transparent-forward option. This is for people that depend on another FTP proxy but would like to use jftpgws capabilities of a transparent proxy or of access/throughput restrictions. You have to enable the transparent-proxy option in order to use transparent-forward.
Say, you define the transparent-forward host "some.host.com:2839", jftpgw would gather a connection through its transparent proxy capabilities and log in to "some.host.com" on port 2839 with a login of "user@realtarget"
Example: 
transparent-forward	some.host.com:2839
 
transparent-forward-include-port Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME
  Default: on
This option controls how jftpgw logs in to the FTP server you forward your sessions to. If you have set it to on it is: 
USER remoteuser@remotehost:remoteport
and if it is off, it looks like 
USER remoteuser@remotehost
 
transparent-proxy Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME
  Default: off
This option decides whether or not the transparent proxy support should be used. For a full description on the transparent proxy support, see Transparent proxy support


Example: 

transparent-proxy		on
Instead of "on" you may also say "yes", "true" or just "1". As you may already have guessed, the opposite is "off", "no", "false" and "0". Other values are not allowed.

 

 
udpport Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME
  Default: 2370
See the getinternalip option to learn what this option is for.

The UDP packets should go to a port where no client of your internal network listens to. No reaction of the clients that receive this packet is required. As soon as it is sent out, jftpgw knows what it was looking for. Please make sure that the packet can leave the local machine, i.e. no firewall stops it from leaving. If it is out, you may intercept it.


Example: Send UDP packets to port 49499 

udpport			49499
 
welcomeline Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME
  Default: FTP proxy (v<>) ready
If jftpgw should display a custom welcome line (the first line that is sent to the client upon connect), specify it here.

If you're forwarding all your connections to a single FTP server or if you're doing transparent proxying you might be interested in setting the logintime option to the value connect. With that setting, jftpgw logs in to the FTP server right after you have connected to the proxy and it doesn't display its own welcome message but the real welcome message of the server.


Example: 

welcomeline 		This is an unknown FTP server


Example: You may also use multiple lines: 

welcomeline		Hello\r\nHere are three\r\nlines.
<< Previous: How to use the transparent proxy support Next: Portability >>

Webpages created by Joachim Wieland © 2000, 2001, 2002, 2003
 Layout by Thomas Schultz © 2000