jftpgw 0.13.3 - Configuration

Welcome to the configuration of
jftpgw 0.13.3
Last update: Mon Mar 24 11:41:25 CET 2003

Navigation
Home Features Where to use How to use How to use the tranparent proxy support The configuration access account activeportrange activeportrangeclient activeportrangeserver allowforeignaddress allowreservedports cache cachemaxsize cacheminsize cacheprefix changeroot changerootdir cmdlogfile cmdlogfile-style commandtimeout connectionlogdir controlserveraddress dataclientaddress dataport dataserveraddress debuglevel defaultforward defaultmode dnslookups dropprivileges forward forwardlookups getinternalip hostcachetimeout initialsyst limit listen logfile loginstyle logintime logstyle passallauth passiveportrange passiveportrangeclient passiveportrangeserver pidfile reverselookups runasgroup runasuser serverport strictasciiconversion syslogfacility throughput transfertimeout transparent-forward transparent-forward-include-port transparent-proxy udpport welcomeline Portability Download Todo Contribute Mailinglist
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 account activeportrange activeportrangeclient activeportrangeserver allowforeignaddress allowreservedports cache cachemaxsize cacheminsize cacheprefix changeroot changerootdir cmdlogfile cmdlogfile-style commandtimeout connectionlogdir controlserveraddress dataclientaddress dataport dataserveraddress debuglevel defaultforward defaultmode dnslookups dropprivileges forward forwardlookups getinternalip hostcachetimeout initialsyst limit listen logfile loginstyle logintime logstyle passallauth passiveportrange passiveportrangeclient passiveportrangeserver pidfile reverselookups runasgroup runasuser serverport strictasciiconversion syslogfacility throughput transfertimeout transparent-forward transparent-forward-include-port transparent-proxy udpport welcomeline
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 . 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. 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 as soon as a client connects. This is for security reasons. Keep in mind to specify cmdlogfile-options relative to that path. 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:
0 | quiet
| 1 | fatal errors
| 2 | critical errors
| 3 | errors
4 | important warnings
5 | warnings
6 | important information
7 | information
8 | program flow
9 | unimportant

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 the logfiles. So these are created with the identity of the superuser.
- 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.

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 (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) default=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