Welcome to the configuration of
jftpgw FTP proxy 0.14.0
Last update: GENERATED
Navigation
Joachim Wieland
About this page - Read me first!

This page explains the configuration of the jftpgw FTP proxy. It first explains how the configuration file is structured, how you use this structure to tell the proxy when to apply which option and at the end there is the complete list of the available options of the proxy itself and thereafter the options of the different modules of jftpgw.

On your left side there is a patented quick navigation list[tm] that allows you to easily jump to the description of an option. Each option has a "back to top" link that brings you back here.

At the moment there are about 70 options for jftpgw. In order to give you some help, I've marked them with the degree of their importance. There are some options that are really important to everybody and there are others that control only one nifty small detail.

There are the following levels of importance: essential / important / useful / nice / expert. The most essential options are marked with a (*) sign on the left side, options that are still important have a (+) sign and options that are useful or nice to know about have a (-) sign and all the untagged options are for some special settings.

For every option you can see its default value, its importance and the section in which you are allowed to set the respective option.

  1. Overview
  2. Sample configuration file
  3. How the configuration is checked and applied
  4. Detailed description of jftpgw's tags
  5. Defining macros/variables
  6. The list of the modules and their options

Overview
The configuration system of jftpgw is very flexible. It uses XML-style tags. You describe a connection through the proxy and set an option to some value. Now, if the criteria for that connection are matched, the value of the option will be evaluated and applied . 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
</global>

# nobody should be able to use the proxy, 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 taken into account 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 can 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. That means, that the value of an option in say, line 20 of the configuration file overwrites the value of the same option in line 15 for example.

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 so it won't look inside the <to> tag. However the only "access allow" is inside this tag and thus it can't be seen at this moment. Consequently the connection gets closed (no "access allow" has been found within the evaluated 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.

Another (maybe more intuitive) way to put it would be something like this:

                <from hosta hostb hostc>
                        access allow
                        <to 0/0>
                                access deny
                        </to>
                        <to dest1 dest2 dest3>
                                access allow
                        </to>
                </from>
That way, for every client, the proxy only sees the first "access allow" at the time this client connects. As soon as it has sent the destination, jftpgw will go on and evaluate the <to> tags as well. The "access deny" from the first subtag overwrites the previously defined "access allow" but gets overwritten itself by the second subtag. However the "access allow" from this second subtag only applies in the case that the client is connecting to one of the three specified destinations.

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 consequently you 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 bandwidth limits for connects to the following three ftp servers:

    <to ftp1.server.com ftp2.server.com ftp3.server.com>
            limit 4.5
    </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 transfer mode and cached transfers.

    <user anonymous>
            <to 192.168.1.2>
                   forward ftp.somewhere.com:2121,a
                   diskcache.enable yes
            </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 should 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. The example is kind of nonsense, but it should just explain the syntax :-)
    The tag would be evaluated 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 (FTP) connection but on the resulting connection to the proxy machine. The IP that you specify here has to be assigned to the proxy machine. With this option you can have a single jftpgw proxy for inbound and outbound traffic. Assuming that your external IP is 123.123.123.123, the tag

    <proxyip 123.123.123.123>
            [...]
    </proxyip>
    
    applies to the connections to the proxy from the outside, i.e. connections that access your proxy machine via the IP 123.123.123.123 (inbound connections).

    To set the configuration options for outbound traffic, i.e. traffic that hits your proxy machine on its internal IP, you can use something like that:

    <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 networks 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 kb/s.

    Of course you could achieve the same by just putting the throughput-Option in a <from>-tag where you specify the relevant networks 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 such 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 is 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).
    You can separate different time ranges with a ";" or a ",".

    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>
    

Defining macros/variables

There is an easy macro meachanism that can ease the readability of the configuration a lot. Basically you define variables and whenever they show up they will get replaced by the value you assigned to them previously.

Look at the following example:

INTERNALNET=192.168.14.0/255.255.255.0
EXTERNALNET=0.0.0.0/0 exclude 192.168.14.0/255.255.255.0

<global>
[...]
       <from INTERNALNET>
               access allow
       </from>
       <from EXTERNALNET>
               [...]
       </from>
[...]
</global>

Please keep in mind the following rules for your macro definitions

  • macro names have to consist entirely of upper case letters
  • the name is separated from a value with the "=" sign
  • there must be no space between the name and the "=" sign

Look at the definition of the EXTERNALNET variable. You can use spaces in the definition part without any problems.

jftpgw
jftpgw configuration options
Here you'll see the configuration settings for jftpgw.

This module can be configured with the following options:

access(back to top)Default: deny
Importance: essential
Sections: ALL

This is the most important option for access control. Set it to allow if you want to grant access or to deny in order 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)

NOTE: Set this option as tightly as possible, be careful when allowing access, especially if you're allowing access from outside to your LAN. Use not only restrictions with <from>, <to> and <user> but also with <port>!

Example: 
<global>
        # this is the default anyway...
        access deny
</global>

<from 192.168.19.0/24>
        access allow
</from>>
Disallow access from everywhere except for the 192.168.19.x network.
Example: Keep in mind that tags can only be evaluated if the proxy has the corresponding information
# WRONG!
<from 192.168.19.0/24>
        <user anonymous>
              access allow
        </user>
</from>>
This won't work because at the time of the client's connection, the proxy can only evaluate the <from...>-Tag but it will skip the <user...>-Tag (it has no username at that moment). Consequently, there won't be a line that allows access and so the connection is refused right from the beginning.
Example: The correction of the previous example
# RIGHT - alternative 1 :-)
<from 192.168.19.0/24>
        access allow
        <user * exclude anonymous>
              access deny
        </user>
</from>>

# RIGHT - alternative 2 :-)
<from 192.168.19.0/24>
        access allow
        <user *>
              access deny
        </user>
        <user anonymous>
              access allow
        </user>
</from>>

Here, I have rewritten the previous example in order to make it work.

When the client connects, the proxy will check all the <from...>-tags (among others). It won't check the <user...>-tags because it has no information about the user at that time. When the client sends "USER anonymous" or "USER anonymous@remotehost", the proxy will evaluate the <user...>-tags as well.

In the first of the two alternatives shown here, it will deny access for all users except for anonymous.

In the second it will first allow access for everybody from the subnet, then it will deny access for all users and then it will allow access only for the user anonymous. As stated before, the last value of an option is the one that is applied, but you can "redefine" it as often as you wish.

Example: A tight setup
            <from 140.130.120.0/24>
                  access allow
            </from>
            <to 0/0>
                  access deny
            </to>
            <from 140.130.120.0/24>
                  <to ftpserver1 ftpserver2>
                        <port 21>
                              <user anonymous>
                                    access allow
                              </user>
                        </port>
                  </to>
            </from>
Here you can see quite a tight setup. We need the first <from>-Tag to accept connections from jftpgw at all. As soon as jftpgw knows about the target (hostname and port) and the user name it will evaluate other tags as well. At the end we have set "access allow" for everybody from 140.130.120.0/24. Then we forbid these guys to connect anywhere but we allow them to connect to either ftpserver1 or ftpserver2 on port 21 using the user name "anonymous". If any condition in the second <from>-Tag didn't match, the "access deny" from the <to>-Tag would stay in action and would forbid further access.

account(back to top)Default: (none)
Importance: nice
Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME

Sometimes you want the user of the proxy to authenticate itself, i.e. he has to provide a username and a password to be able to use the proxy. This authentication has nothing to do with the destination this user wants to connect to or the user name he wants to use there. See the the loginstyle option) for information on how to modify the login procedure to ask the user for a username and a password.

At the moment you have two possibilities for defining an account (i.e. a user/password combination that is allowed to use the proxy).

You can define a single account right within the configuration file. Therefore you set the type of this account to "Single" and specify a username and a password. If jftpgw is compiled with crypt support (that's for most of the installations) you can use a crypted password here. If not, you have to use a cleartext password. (Run

jftpgw --version
to see if it is compiled with crypt support).

You can also specify an external program that will do the username/password checking for you. This feature is stolen from the squid proxy. Therefore you can use all of the squid authenticating programs for jftpgw as well. Such a program reads the username, a space and the password from standard input, checks them and if the user has successfully authenticated with the right password, the checking program writes "OK" to standard output. In contrast to squid, jftpgw will start a new instance of the authenticating program every time and won't re-use an existing authenticating program for another username/password combination.

Syntax:
Account Single username cleartext password
Account Single username crypted password
Account AuthProgramSimple /path/to/the/program arg1 arg2

You can get crypted passwords by executing

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

Example: Set a crypted password
Account    Single   fwjoe    hFPO1IKNeeeUM

This will set the password "test" for the user "fwjoe".

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

Example: Use an external authenticator
Account  AuthProgramSimple  /usr/local/bin/ldap_auth -s jftpgw

With the setting above, jftpgw runs the program

/usr/local/bin/ldap_auth
with the parameters
-s jftpgw
and writes the username, a space sign and the password to the standard input of this program. If this program wirtes "OK" to its standard output, verification succeeded and jftpgw will allow the user to use the proxy.

activeportrange(back to top)Default: (none)
Importance: nice
Sections: ALL

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: Configure an active portrange with a single range
activeportrange      25400:25499
Example: Configure an active portrange with several ranges
activeportrange     38900:38999   3400:3449   64020:64020

activeportrangeclient(back to top)Default: (none)
Importance: expert
Sections: ALL

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.

allowforeignaddress(back to top)Default: no
Importance: expert
Sections: ALL
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.

Example: Allow the client to send foreign addresses
allowforeignaddress yes

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
allowforeigndataconnect(back to top)Default: no
Importance: expert
Sections: ALL

There are two times when the proxy waits for a data connection. Either when a client requests passive FTP transfers, in this case jftpgw waits for the connection of the client or after sending an IP and a port number to the server, here the proxy waits for a connection of the server. However basically anybody who knows the IP addresses and port numbers can establish the connection. If this is done in the right time, there is the chance of data being sent to the wrong person.

This option enables the checking of the source IP of an incoming connection. If for example the client is expected to connect but the connection is coming from another IP address, jftpgw will log an error and close the connection instead of sending the data.

If you want to do wild'n'crazy[tm] things like FXP, you might want to enable this option in order to allow connections from everywhere.

Example: Enable foreign data connections
allowforeigndataconnect   yes
With the option enabled, data connections can be established from everywhere, not only from the IP of the client (passive mode) or the server (active mode).

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
allowreservedports(back to top)Default: no
Importance: expert
Sections: ALL

allowreservedports allows the client to use reserved ports in a PORT command (i.e. portnumbers from 1 to 1024). This is part of the "FTP bounce attack" and is therefore disabled.

See http://www.sonic.net/hypermail/security/mbox/0270.html for details on the "FTP bounce attack".

Example: Enable reserved ports
allowreservedports   yes
With this setting an FTP client talking to the server can ask the proxy to connect to one of its privileged ports.

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
changeroot(back to top)Default: start
Importance: important
Sections: STARTUP

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(back to top)Default: (none)
Importance: important
Sections: STARTUP

The changerootdir option causes jftpgw to change its root directory to the specified directory. The time of this change depends on the setting of the changeroot option.

Please note: When opening a file, jftpgw tries to strip off the changerootdir 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. In this case you might want to use the -f option:

            jftpgw -f /var/chroots/ftp-proxy/etc/jftpgw.conf
            
jftpgw will try to open /var/chroots/ftp-proxy/etc/jftpgw.conf and that will succeed as long as jftpgw has not changed the root directory. Then it will do the changeroot and if you request that the configfile be reread, jftpgw will try to open /var/chroots/ftp-proxy/etc/jftpgw.conf again but that time it will fail. Then jftpgw will strip off the path of the new root directory and will open /etc/jftpgw.conf.

Example: Set the new root directory to /var/chroots/ftp-proxy
changerootdir           /var/chroots/ftp-proxy

cmdlogfile(back to top)Default: (none)
Importance: nice
Sections: ALL

The command logfiles log the commands the client sends to us. The format is

cmdlogfile    <filename>
If you want to log the command log messages to syslog, use the following syntax:
cmdlogfile    syslog:<prefix>
See the section below about the various implications of logging to syslog.

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 the like but USER RETR STOR and other transfer related commands could be quite interesting. If you want to log the PASS command, jftpgw will substitute the password with asterisks (`*****').

You can also use * to say "log all commands" in the

cmdlogfile-specs
option. If you prefix a command with the - sign in the same option, the meaning is: do not log this command, even if it was included previously.

If you log to files and you want to change jftpgw's root directory (see the changerootdir option) please note that your log files have to be within the chroot jail if you want to be able to reload jftpgw's configuration and you want jftpgw to continue logging to the same files.

When logging to syslog, there is another detail you should know about. Normally each program can only open the connection to syslog once with only one facility (see the syslogfacility option). So if you log to syslog for debug output already (that means that you have set the logstyle option to "syslog", you get everything in the same logfile. This can be quite annoying. Furthermore you couldn't have two or more different command log file entries... if there was no other nifty feature for solving this problem.

First, in order to separate different command log entries, you can specify the priority. Use this syntax:

cmdlogfile        syslog(<priority>):<prefix>
Ok. Now you have different priorities and you can sort your log messages in the syslog.conf with a setting like this one:
            daemon.=info            -/var/log/jftpgw/cmdlog1.log
            daemon.=warn            -/var/log/jftpgw/cmdlog2.log
            daemon.=err             -/var/log/jftpgw/cmdlog3.log
            
The problem is, however, that the debug log also uses different priorities. This is done so that you can sort the log messages according to their importance (that is actually what different priorities are for). There is another parameter with which you can force the debug logging to use just one fixed priority. You can limit log messages to a specific level of importance with the debuglevel option within jftpgw itself and log everything else to one fixed priority. You can set this priority with the syslogdebugpriority option . There is also a similar option for the command log priority, the syslogcmdlogpriority. This option sets the default priority used for sending individual log messages to syslog if you haven't specified a priority for a cmdlogfile entry, i.e. if you used the
cmdlogfile        syslog:<prefix>
instead of the
cmdlogfile        syslog(<priority>):<prefix>
format instead.

Pretty complicated, huh?

Example: Log some common commands
cmdlogfile                      /var/log/jftpgw.commandlog
cmdlogfile-style                commonlog
cmdlogfile-specs                USER RETR STOR CWD REST

This command logs the commands USER RETR STOR CWD and REST in the commonlog log format to the file /var/log/jftpgw.commandlog.

Example: This example shows how to exclude commands
cmdlogfile                      /var/log/jftpgw.commandlog
cmdlogfile-specs                * -USER -PASS
cmdlogfile-style                commonlog
This would log the complete FTP command set except for USER and PASS commands (again with the commonlog logging format to the file /var/log/jftpgw.commandlog.
Example: An example with another logging style
cmdlogfile                      /var/log/jftpgw.xferlog
cmdlogfile-style                xferlog
cmdlogfile-specs                RETR STOR APPE STOU

This setting logs only the commands that initiate up- and downloads and writes it to a logfile in the so-called "xferlog" format that is also used by other FTP daemons or webservers. xferlog only makes sense with file transferring commands (like RETR or STOR) in the specs-line.

Example: Output messages from the command log to syslog
syslogdebugpriority             debug
syslogcmdlogpriority            crit
cmdlogfile                      "syslog:xferlog output: "
cmdlogfile-style                xferlog
cmdlogfile-specs                RETR STOR APPE STOU

This example logs the same output as the one before but it sends its output to syslog this time. Note that we have forced all debug messages that go to syslog as well to be logged with the "debug" priority and all messages from the command log will be logged with the "crit" priority. Furthermore every message will have the prefix "xferlog output: ". Mind the quotes if you want to have a trailing space.

Example: Log to syslog with a specific priority
syslogdebugpriority             debug
cmdlogfile                      "syslog(info):xferlog output: "
cmdlogfile-style                xferlog
cmdlogfile-specs                RETR STOR APPE STOU

The same thing as we did before but this time we don't use the default command log priority for logging to syslog but we specify the "info"-priorities to be used for logging messages from this entry.

cmdlogfile-style(back to top)Default: (none)
Importance: nice
Sections: ALL

This 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 (if given as
             absolute path)
        'F'  Filename stored or retrieved, in any case without a path name
        '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)
        'u'  user-id (UNKNOWN for anonymous login, the username that
             was sent to the proxy if otherwise)
        'U'  authenticated user-id. If there was a loginstyle with a
             user/password login in order to use the proxy, we can log
             the user name. If not, this is just a '-'.
        'H'  Server host name
        'A'  Server host IP
        'h'  Client host name
        'a'  Client host IP
        'I'  Server interface address
        'i'  Client interface address
        'l'  Proxy user name (login)
        'L'  Effective server user name (i.e. user name that the proxy sends
             to the server. It sends USER x to the FTP server in question, and
             x is what gets logged here)
        'C'  Forwarded server user name (i.e. the user name that forwarding
             rules constructed
        'S'  Seconds since the epoch (1970-01-01)
        'M'  Seconds since the epoch, including microseconds
        '%'  percent sign itself

Example: xferlog logstyle
cmdlogfile-style   xferlog

This is how xferlog style logging is realized:

   %t %T %H %b \"%f\" %y _ %w %o %u %e 0 * %c

xferlog generates this type of output:

Dow Mon DD hh:mm:ss YYYY %T %H %b \"%f\" %y _ %w %o %u %e 0 * %c

(this is actually one line)

Sun Aug 29 21:52:34 2004 0 ftp.uni-stuttgart.de \
   447 "welcome.msg" a _ i a joe@mcknight.de ftp 0 * c

Example: commonlog logstyle
cmdlogfile-style   commonlog

This is how commonlog style logging is realized:

   %a - %l %D \"%r\" %s %b

commonlog generates this type of output:

REMOTE AUTH USER [DATE] "CMD" RCODE SIZE

Here's an example (lines wrapped - the arrows indicate the wraparound)

127.0.0.1 - anonymous@ftp.fu-berlin.de \\
  -> [29/Aug/2004:22:39:44 CEST] "USER anonymous@ftp.fu-berlin.de" 331 0
127.0.0.1 - anonymous@ftp.fu-berlin.de \\
  -> [29/Aug/2004:22:39:49 CEST] "PASS joe@mcknight.de" 230 0
127.0.0.1 - anonymous@ftp.fu-berlin.de \\
  -> [29/Aug/2004:22:39:50 CEST] "PORT 127,0,0,1,128,131" 200 0
127.0.0.1 - anonymous@ftp.fu-berlin.de \\
  -> [29/Aug/2004:22:39:50 CEST] "LIST" 226 1088
127.0.0.1 - anonymous@ftp.fu-berlin.de \\
  -> [29/Aug/2004:22:40:07 CEST] "PORT 127,0,0,1,128,139" 200 0
127.0.0.1 - anonymous@ftp.fu-berlin.de \\
  -> [29/Aug/2004:22:40:10 CEST] "RETR README" 226 7932
127.0.0.1 - anonymous@ftp.fu-berlin.de \\
  -> [29/Aug/2004:22:40:12 CEST] "QUIT" 221 0

commandtimeout(back to top)Default: 300
Importance: expert
Sections: ALL
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(back to top)Default: (none)
Importance: expert
Sections: ALL

The connection log dir creates a logfile for each connection and writes the commands the client sends to us in that file.

You must specify a prefix and a suffix for the filenames and the rest of the filename consists of date, time and of the pid of the process that handled the connection.

Syntax:

connectionlogdir                        <directory>
connectionlogdir-fileprefix             <fileprefix>
connectionlogdir-filesuffix             <filesuffix>
connectionlogdir-specs                  <CMD1> <CMD2> <CMD3>
connectionlogdir-style                  <style>

Example: 
connectionlogdir                /var/log/jftpgw
connectionlogdir-fileprefix     jftpgw-connect-
connectionlogdir-filesuffix     .log
connectionlogdir-specs          USER PASS RETR STOR
connectionlogdir-syle           commonlog

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).

controlserveraddress(back to top)Default: (none)
Importance: expert
Sections: ALL

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. The explanation there is more detailed.

Example: Specify an IP address
controlserveraddress    212.39.39.39
Example: Specify an interface
controlserveraddress    ppp0
Note: this works only if you see "can get IPs from interfaces" in the output of jftpgw -v.

dataclientaddress(back to top)Default: (none)
Importance: expert
Sections: ALL

Set the IP to send to the client for PASV responses (in passive mode) or to use as the source IP (for active mode). This option is useful 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, you'll want to define this option if you use the transparent proxy support but you don't want to allow the proxy to send ICMP or UDP packets to your internal network (see also the getinternalip option)

Note that jftpgw will try to bind to this address, which means that it has to be available on the system. If it is not, there will be an error. If this option is not specified, jftpgw will guess the address from the control connection. If you want to bind to any address, meaning to all available interfaces, you can specify 0.0.0.0 in this option.

If you just want to display another address than you want to bind to (for example if you have a DSL router that forwards all the traffic to your firewall - but your firewall has only an internal IP), see the displayclientaddress option.

See also the dataserveraddress option.

Example: Specify an IP address
dataclientaddress       212.39.39.39
Example: Specify an interface
dataclientaddress       eth1
Note: this works only if you see "can get IPs from interfaces" in the output of jftpgw -v.

dataserveraddress(back to top)Default: (none)
Importance: expert
Sections: ALL

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: Specify an IP address
dataserveraddress      212.39.45.129
Example: Specify an interface
dataserveraddress     ppp0
Note: this works only if you see "can get IPs from interfaces" in the output of jftpgw -v.

debuglevel(back to top)Default: 7
Importance: essential
Sections: ALL

The debug level:

0quiet
1fatal errors
2critical errors
3errors
4important warnings
5warnings
6important information
7information
8program flow
9unimportant for the user

I recommend to set it to 5 or 6. Do NOT set it below 4 unless you know what you are doing.

Example: Log in a very verbose way
debuglevel 9

defaultmode(back to top)Default: asclient
Importance: useful
Sections: ALL

Specify the default mode (active or passive ftp) between the proxy and the FTP server the proxy is connected to.

Valid options are `active', `passive', or `asclient'

`asclient' uses the mode the same mode between the proxy and the server as the client requests for transfers between the client and the proxy.

Example: Use passive mode between the proxy and the FTP server
defaultmode    passive
Example: Use the same mode as the client
defaultmode    asclient
Use the mode that the client requests for tranfers between the client and the proxy for transfers between the proxy and the FTP server as well

displayclientaddress(back to top)Default: (none)
Importance: expert
Sections: ALL

This option sets the IP that is sent out to the client when it requests the proxy to enter passive transfer mode. This option however does no binding nor checking if the IP is available. It binds to the respective IP(s) as if this option didn't exist and when the answer is actually sent to the client, the IP of this option will be sent if it is defined.

If you want to bind to a special IP, see the the dataclientaddress option.

For the server side, see the displayserveraddress option

Example: Change the IP that will be displayed to the client
displayclientaddress  123.123.123.123
With this option the client will see the IP address 123.123.123.123 when it requests a passive FTP transfer from the proxy.

displayserveraddress(back to top)Default: 
Importance: expert
Sections: ALL

This option sets the IP that is displayed to the server when an IP address and a port number is sent to it for active FTP transfers.

See the displayclientaddress option for a more detailed description on this feature.

Example: Change the IP that will be displayed to the server
displayserveraddress  123.123.123.123
With this option the server will see the IP address 123.123.123.123 when we send an IP address and a port number to it in order to initiate an active FTP transfer.

dnslookups(back to top)Default: yes
Importance: expert
Sections: ALL

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 can set this option to "off". To control forward and reverse lookups separately, see the forwardlookups option and the reverselookups option.

jftpgw uses DNS lookups in order to evaluate the <to> and <from> tags. If you configure a hostname there, it will look up every IP address to see if it matches this hostname and it will look up the hostname for the IP address to see if it matches the hostname you specified. It does also look up aliases for hostnames.

Example: Switch off DNS lookups completely
dnslookups    off

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
dropprivileges(back to top)Default: start
Importance: essential
Sections: STARTUP

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 ist 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) as your DATAport 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

filterorderdownstream(back to top)Default: throughput diskcachewrite asciiconversion
Importance: expert
Sections: ALL

jftpgw has the concept of "filters". Filters may transform the datastream while it passes the proxy. But they don't have to. There are filters that don't do any changes but that are just interested in the contents of the stream (like caching modules for example, they hook in as filters as well).

If you have several filters, there is a problem: Which filter runs at which time? If a filter alters the data, the filter after this does not see the original data anymore. So you have to define the order of the filters.

The Binary/ASCII transformation is a filter as well. jftpgw requests all the files in binary mode. This is done for the cache module not to have to deal with two different formats coming from the FTP server. Now imagine that you requested an ASCII transfer with your FTP client and your caching module is active as well and is writing the data to the hard disk. You certainly want to run the filter for the caching BEFORE converting the data to the ASCII format for your client.

At the moment, the following filters exist:

  • throughput
  • asciiconversion
  • diskcachewrite
So it's quite easy: The throughput filter doesn't change anything. The asciiconversion filter changes data and the diskcachewrite filter is interested in the original data. So you set asciiconversion behind diskcachewrite.

For the corresponding upstream option it doesn't matter at all because we do not cache uploads at the moment (diskcachewrite is only a downstream filter).

Example: Set some filter ordering
filterorderdownstream   throughput diskcachewrite asciiconversion
See above for a discussion of this order. This one is also the default if you are using the "caching to disk"-module.

filterorderupstream(back to top)Default: (none)
Importance: expert
Sections: ALL

This is the upstream version of the filterorderdownstream option. You'll learn from the description there that you don't need to care about this option. ;-)

forward(back to top)Default: (none)
Importance: nice
Sections: ALL

Specify user forwards here. There are several examples below on how jftpgw rewrites a login (user/password combination) to the proxy into another login to the target FTP server.

Note: You only specify WHERE to forward somebody but not WHO. In order to select this somebody, use the configuration tags.

Syntax:

forward  <newlogin>  <jftpgw pass>  <destination pass>

If you want to match on new destinations or the like, use the <forwarded> ... </forwarded> tag. For example:

            <from 192.168.0.0/16>
                  forward *@ftp.fu-berlin.de
            </from>
            <to 0/0>
                  access deny
            </to>
            <forwarded>
                  <to ftp.fu-berlin.de>
                        access allow
                  </to>
            </forwarded>

Example: A simple forward
        <from 212.39.39.39>
                <user eddie>
                        forward ftp.somewhere.com
                </user>
        </from>
Forward user eddie who logs in from 212.39.39.39 to eddie@ftp.somewhere.com and pass the password along.
Example: A forward with a new password
        <from 212.39.39.39>
                <user eddie>
                        forward ftp.somewhere.com   *       mickeymouse
                </user>
        </from>
Forward user eddie to eddie@ftp.micky.com, allow any password but send mickeymouse to the server ftp.somewhere.com.
Example: Another forward with a new password
        <from 212.39.39.39>
                <user eddie>
                        forward ftp.somewhere.com   goofy   mickeymouse
                </user>
        </from>>
        
        or
        
        <from 212.39.39.39>>
                <user eddie>
                        forward ftp.somewhere.com    yp8T9bQvnPoFs    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 has to be in the crypted form like yp8T9bQvnPoFs if you have crypt support (check with jftpgw -v). You can create crypted passwords with jftpgw -e)
Example: Forward every user to anonymous@ftp.kernel.org
        <user *>
                forward  anonymous@ftp.kernel.org
        </user>
         
Example:  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.
        <user * exclude goofy>
                forward  anonymous@ftp.kernel.org  *  mickeymouse
        </user>
         
Example: A forward to another port
        <user anonymous>
                <to ftp.kernel.org>
                        # Note that this would log on as user anonymous,
                        # since I didn't specify a new user name. (jftpgw would keep
                        # the old one, which is "anonymous")
                        forward        ftp.somewhere.com:2121,a
                </to>
        </user>
         
Forward the user who logged in with anonymous@ftp.kernel.org to an FTP server of the on a different port than 21. This one runs on port 2121... Futhermore we want to use active FTP mode between the proxy and the FTP server.
Example: Pass the complete authorization to otherproxy and use port 3942 there (loginstyle 1 only)
        forward         *@otherproxy:3942

        forward         *@fileserv
            

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.

Please note that you have to select loginstyle 1 for this to work.

Example:  Forward users to ftp.company.com, if they log in just with their user names (loginstyle 1 only).
        forward         %@ftp.company.com

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.

Please note that you have to select loginstyle 1 for this to work.

If you're using a reverse proxy, you should limit access to your internal hosts very thoroughly. A user can still log in with "user someuser@mailserver:25" or something like that. So you should have firewalls in place and configure tight access restrictions in jftpgw as well. See this example:

            <from 140.130.120.0/24>
                  forward %@fileserver
            </from>
            <to 0/0>
                  access deny
            </to>
            <from 140.130.120.0/24>
                  <to ftpserver1 ftpserver2>
                        <port 21>
                              <user anonymous>
                                    access allow
                              </user>
                        </port>
                  </to>
            </from>
            <forwarded>
                  <to fileserver>
                        <port 21>
                              access allow
                        </port>
                  </to>
            </forwarded>
Here, a user can log in with anonymous@ftpserver1, anonymous@ftpserver2 or just with a username. He cannot log in to user@fileserver however. He can connect to fileserver only if he got forwarded there! Furthermore he cannot connect to ftpserver1:25 because we have restricted access to port 21 and he can not use any other usernames for ftpserver1 and ftpserver2 than "anonymous".

forwardcmds(back to top)Default: (none)
Importance: nice
Sections: ALL

This option allows an unknown command to pass jftpgw, the command will be forwarded to the server and the output will be sent back.

In previous versions of jftpgw the handling of commands was the following: A command came in and if there was some special action required (PORT/PASV for example), jftpgw handled that command in some way. All the other commands just got forwarded and the answer was sent back.

Now we have a set of commands that are used for FTP. However your FTP server might support a command that I haven't added to the list. Then you'll have a problem because jftpgw will refuse unknown commands. So what you do is that you add this command to the list of commands that are allowed to be forwarded by the proxy.

Example: Allow the QUOTA and the LIMIT commands to pass
forwardcmds   QUOTA LIMIT
This command will allow a command "QUOTA" and a command "LIMIT" to be passed on to the server. Their output will be sent back in the same way.

forwardlookups(back to top)Default: yes
Importance: expert
Sections: ALL

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: Switch off DNS forward lookups
forwardlookups   no

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
getinternalip(back to top)Default: udp
Importance: expert
Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME

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 the dataclientaddress option
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 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(back to top)Default: 28800
Importance: expert
Sections: ALL

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.

This parameter is not really relevant to the normal user. The cache might help administrators however who have lots of lists of domains / subdomains and ip addresses, lists of hosts that have full access and those that have restricted access and those that do not have access at all and so on. It turned out that especially on firewalls with restrictions on DNS usage (and no caching daemon installed), doing lots of lookups might take quite a long time.

Example: DNS lookups should be cached for 3 hours
hostcachetimeout   10800

initialsyst(back to top)Default: yes
Importance: expert
Sections: ALL

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 "no", jftpgw won't send an initial SYST command anymore.

Example: Switch off the initial SYST command
initialsyst   no

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
libwrapservicenames(back to top)Default: ftp-gw jftpgw
Importance: expert
Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME

This option specifies the libwrap service names. You don't have to care for this option if you don't use libwrap (tcp wrapper). With libwrap you can use the files /etc/hosts.allow and /etc/hosts.deny to control access to the proxy.

Note that you can define multiple names. Separate them by spaces.

Use

jftpgw --version
to see if you have libwrap support compiled in.

Example: change the service name
libwrapservicename ftp-proxy

# in your /etc/hosts.allow you can then write:

ftp-proxy:192.168.12.2
Example: change the service name, use three names
libwrapservicename ftp-proxy ftpproxy ftpgw

limit(back to top)Default: (none)
Importance: nice
Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME

Limit the number of simultaneous logins to the jftpgw proxy server. The option has no effect if you run jftpgw from inetd.

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>

With this configuration, four clients can connect from the network 192.168.0.0/16 at the same time and 20 clients can connect from elsewhere. So there can be 24 parallel connections at most.

Example: Incompatibility with <time>-tag
<time Mon 18:00 - 19:00>
      limit           10
</time>

<time Mon 19:01 - 20:00>
      limit           5
</time>

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

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(back to top)Default: 0.0.0.0:2370
Importance: essential
Sections: STARTUP

With this option you can specfify on which IP address(es) and ports 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 will only be 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 IP addresses.

If you change this parameter and signal jftpgw to reload the configuration, it will close all the ports it listens on and will re-listen on them. So there is a small time frame where another program could interfere and bind to an IP/port combination that was assigned to jftpgw previously.

If jftpgw fails to listen on a specified IP/port combination, it will log an error and terminate.

0.0.0.0:2370 makes jftpgw to listen on all available addresses on port 2370.

Example:  Listen on all IP addresses on port 2370 and on localhost on port 2380
listen  0.0.0.0:2370  localhost:2380
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

logfile(back to top)Default: /var/log/jftpgw.log
Importance: essential
Sections: ALL

This option specifies the location of the logfile to use. It will only be used if you set the logstyle option to "files".

If you intend to run the proxy as an unprivileged user, you have to change the default setting because a normal user does not have the right to write to /var/log.

Example: Set it to the homedir of a user
logfile  /home/joe/jftpgw.log

loginstyle(back to top)Default: 1
Importance: essential
Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME

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

    Note that you can't use the default logintime user for this option (see the logintime option).

  • 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

    Note that you can't use the default logintime user for this option (see the logintime option).

fwuser and fwpass correspond to accounts. See the the account option for further details.

Example: Use the SITE command without login
loginstyle     4

logintime(back to top)Default: user
Importance: essential
Sections: CONNECTED, TO

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.

Actually there are some limitations in combination with the loginstyles. As a rule of thumb, you can use connect only with the transparent proxy (or forwards) and loginstyle 1. You can use user with every loginstyle except for 7 and 9 (the problem here is that you first have to send the password for being able to use the proxy at all). Logintime pass works with all login styles.

Example:  Read all the login information and then connect to the server
logintime   pass
Example:  If the client connects to us, we connect to the server, read its first line (the greeting) and send it back to the client.
logintime   connect

logstyle(back to top)Default: files
Importance: essential
Sections: ALL

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.

If you set this parameter to "files", see the logfile option in order to specify the location of your log file.

Syntax:

           logstyle (files|syslog)
           

The default value is "files".

Example: Log to syslog
logstyle   syslog

passiveportrange(back to top)Default: (none)
Importance: nice
Sections: ALL
The portrange to use for passive transfers. See the activeportrange option.

Example: Configure a passive portrange with several ranges
passiveportrange     38900:38999   3400:3449    64020:64020

passiveportrangeclient(back to top)Default: (none)
Importance: expert
Sections: ALL

The portrange to use for passive transfers. This is the portrange that is issued to the client with the "227 Entering Passive Mode (192,168,15,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.

pidfile(back to top)Default: /var/run/jftpgw.pid
Importance: important
Sections: STARTUP

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 if you want to run the proxy as an unprivileged user.

See also the dropprivileges option. This option lets you create the pidfile as the root user and drop the privileges of the proxy after the pidfile has been created.

Example: Create the pidfile in /home/joe/run
pidfile  /home/joe/run/jftpgw.pid

protocolviolations(back to top)Default: 10
Importance: expert
Sections: ALL

You can specify a number of protocol violations after which the proxy will terminate the connection to the client. A "protocol violation" is basically an unknown or unexpected command. The number here counts the protocol violations that are sent in a row however. The counter will be reset when a command gets accepted.

Here it's set to 3. Meaning that the proxy allows 3 such unexpected commands in a row and at the fourth it will close the connection.

220 FTP proxy (v0.14.0.beta.5) ready
abc
500 ABC not understood. Expecting USER.
second unknown command
500 SECOND not understood. Expecting USER.
Hum, what's that?
500 HUM, not understood. Expecting USER.
Men, what are you doing here?
500-MEN, not understood. Expecting USER.
500 Too many consequent protocol violations - Closing connection
Connection closed by foreign host.

The option is useful if you want to get rid of programs that connect to your proxy and send garbage data.

Keep in mind however, that real FTP programs also send commands that the proxy doesn't know, for example they might try IPv6 commands (EPSV), a client might send a SYST command at the beginning and so on. So it is definitely not a good idea to set it to 1 or even 0.

Example: Set the number of allowed protocol violations to 3
protocolviolations   3
With this setting, the proxy allows 3 protocol violations and will drop the connection at the 4th unknown or unexpected command.

reverselookups(back to top)Default: yes
Importance: expert
Sections: ALL

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 to hostnames, you can safely turn off DNS reverse lookups.

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

Example: Turn DNS reverse lookups off
reverselookups    no

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
runasgroup(back to top)Default: (none)
Importance: useful
Sections: STARTUP

This option specifies the name of the group jftpgw should change to when dropping privileges (see the dropprivileges option). See also the runasuser option.

Example: Run as the group "nogroup"
runasgroup   nogroup

runasuser(back to top)Default: (none)
Importance: important
Sections: STARTUP

This option specifies the name of the user jftpgw should run as. This option is only effective if jftpgw is started 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 an own group for jftpgw.

Take a look at the the runasgroup option as well.

Example: Run as the user "nobody"
runasuser  nobody

sendcapa(back to top)Default: on
Importance: expert
Sections: ALL

In order to check for FTP extensions of the server (currently this is only the SPP transfer mode), the proxy sends a CAPA command to the server. If the server doesn't know about any extensions, it would reply with an error saying that it didn't understand the command. However there might be problems. For example if the server closes the connection as soon as it receives an unknown command. For this purpose you can tell jftpgw not to send these CAPA commands. However then you cannot use jftpgw's extensions.

Example: switch off sending CAPA commands
sendcapa  no

This example shows how to switch off sending the CAPA command.

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
serverport(back to top)Default: 21
Importance: nice
Sections: 
The default server port (usually Port 21 for FTP)

Example: Set the default server port to 2121
serverport   2121
From now on whenever jftpgw receives a connection request without a port number it will connect to the port 2121.

strictasciiconversion(back to top)Default: yes
Importance: expert
Sections: ALL
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: Switch strict ascii conversion off
strictasciiconversion   no

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
syslogcmdlogpriority(back to top)Default: 
Importance: expert
Sections: ALL

This option sets the default priority used for log messages from the command log. You don't need to specify it if you're not using the command log at all.

For a complete discussion, see the cmdlogfile option, as well as the syslogdebugpriority option.

The following priorities are defined:

  • debug
  • info
  • notice
  • warning
  • err
  • crit
  • alert
  • emerg

Example: Set a default command log priority
syslogcmdlogpriority   crit
Set the default syslog priority for messages from the command log to "crit".

syslogdebugpriority(back to top)Default: (none)
Importance: expert
Sections: ALL

This option forces debug messages to be sent to syslog with a fixed priority.

You probably only want to set this option if you're using command log entries (see the cmdlogfile option) logging to syslog.

Normally when you enabled logging to syslog by setting

logstyle syslog
(see the logstyle option), jftpgw will use different priorities according to the level of importance of the log message. However, if you also want to use the command log to log to syslog, you can only sort log lines from different command log entries according to their priority. If the debug log then uses different priorities as well - you're in a complete mess and you'll get log files from the command log mixed with log messages from the debug log. In this case you can set a fixed priority here to separate debug log messages from command log messages.

See the syslogcmdlogpriority option, the similar option for the command log. It sets the default priority for messages from the command log.

The following priorities are defined:

  • debug
  • info
  • notice
  • warning
  • err
  • crit
  • alert
  • emerg

Example: Separate debug log messages from command log messages
syslogdebugpriority        info
syslogcmdlogpriority        warn

With this setting the messages from the command log will be logged with the priority "warn" whereas the messages from the debug log will be logged with the priority "info". Please note that you can also set a different priority on each command log entry. See the cmdlogfile option on information about how to do this.

syslogfacility(back to top)Default: daemon
Importance: nice
Sections: ALL
Specify the facility for the syslog logging here.

Example: Use the facility "ftp"
syslogfacility   ftp

throughput(back to top)Default: (none)
Importance: nice
Sections: ALL

Limit the throughput of an ftp connection. The unit of rate is kbyte per second.

Syntax:

througput  <rate>

If you want to set different limits for uploads and downloads see the throughput-up and the throughput-down options.

Example: 
<from 123.123.0.0/16>
        throughput       10.00
</from>

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.

throughput-down(back to top)Default: (none)
Importance: expert
Sections: ALL

Limit the throughput for downloads from an ftp server. The unit of rate is kbyte per second. This option overrules a "normal" throughput option

Syntax:

througput-down  <rate>

throughput-up(back to top)Default: (none)
Importance: expert
Sections: ALL

Limit the throughput for uploads to an ftp server. The unit of rate is kbyte per second. This option overrules a "normal" throughput option

Syntax:

througput-up  <rate>

transfertimeout(back to top)Default: 300
Importance: expert
Sections: ALL
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(back to top)Default: (none)
Importance: expert
Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME

The transparent-forward option is yet another forwarding option. This is for people who 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.

Example: Forward connections to some.host.com:2839
transparent-forward     some.host.com:2839
Say, you define the transparent-forward option as shown here, jftpgw would get a connection through its transparent proxy capabilities and log in to "some.host.com" on port 2839 with a login of "user@realtarget".

transparent-forward-include-port(back to top)Default: yes
Importance: expert
Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME

This option controls how jftpgw logs in to the FTP server you forward your sessions to. If you have set it to yes it is:

USER remoteuser@remotehost:remoteport

and if it is set to "no", it looks like

USER remoteuser@remotehost

Example: Switch it off
transparent-forward-include-port   no

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
transparent-proxy(back to top)Default: no
Importance: important
Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME

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: Enable the transparent proxy
transparent-proxy     yes

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
udpport(back to top)Default: 2370
Importance: expert
Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME

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(back to top)Default: FTP proxy 0.14.0 ready
Importance: nice
Sections: GLOBAL, SERVERTYPE, FROM, PROXYIP, PROXYPORT, TIME

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: Send "This is an unknown FTP server"
welcomeline   This is an unknown FTP server
Example: You may also use multiple lines
welcomeline   Hello\r\nHere are three\r\nlines


ftp_cmdcheck
Checks ftp commands syntactically

This module checks ftp commands for correctness according to parameters you can set as well. It should protect the ftp server behind. This ranges from simple allow/forbid specifications of commands that are allowed to pass or that are blocked by the proxy up to the possibility to disable relative pathnames alltogether since there were quite a few ftp server attacks in the past that were based on a broken handling of relative pathnames in ftp servers.

The checker works such:

  1. If the command is among the allowed commands (see the cmdcheck.allowed option) it may pass without being checked further.
  2. If the command is among the forbidden commands (see the cmdcheck.forbidden option) it will be refused.
  3. If the command fails to pass the tests for maximal command length, minimal command length or maximal argument length it will be refused.
  4. If the command fails to pass one of the command dependant tests, it will be refused.
  5. If the command has not been refused so far, it will be accepted

If there is a test that fails for you and you think that is too rigorous, please tell me about it. You can still circumvent the ftp checker module for this special case or you can allow this single command. So you can either disable the command check completely for a special combination, for example:

        <from 192.168.0.0/16>
          <to ftp.gnu.org>
            cmdcheck.enabled   no
          </to>
        </from>
or you can just allow the command without disabling the command checks completely. (Let's imagine that your CWD command did not pass because of some test)
        <from 192.168.0.0/16>
          <to ftp.gnu.org>
            cmdcheck.allow   CWD XCWD
          </to>
        </from>

Note that a command will also be refused by the command handler if it is unknown, i.e. if there is no handler defined for it. So a command called, say "EXAMPLECOMMAND" may pass the command checking module but since there won't be a handling function defined, it will not be forwarded to the server.

This module can be configured with the following options:

cmdcheck.allowed(back to top)Default: (none)
Importance: nice
Sections: ALL

This option takes a list of ftp commands you want to allow to pass. This command is then not checked any further.

Note that the command can pass the command checker than. This option is not about unknown commands it's about commands that cannot pass if the command checker is active. Please tell me about the offending command if you need to allow one with that option.

If you're concern is unknown commands that jftpgw doesn't know because they are no usual FTP commands, see the forwardcmds option.

cmdcheck.enabled(back to top)Default: yes
Importance: useful
Sections: STARTUP
Switch to enable or disable the ftp cmdcheck

Example: Switch cmdcheck off
cmdcheck.enabled   no
This setting disables the ftp cmdcheck module

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
cmdcheck.forbidden(back to top)Default: (none)
Importance: nice
Sections: ALL
This option takes a list of ftp commands you want to forbid, i.e. commands that will not get forwarded to the FTP server but that are rejected from the proxy. You might for example reject commands to create subdirectories or commands to create/change/delete files and so on.

Example: forbid STOR, APPE and STOU commands
cmdcheck.forbidden STOR APPE STOU
With this setting, the proxy will not forward these three commands to the FTP server but reject them
Example: reject the IPv6 command that requests passive mode
cmdcheck.forbidden EPSV
With this setting, the proxy will not forward the EPSV commands to the FTP server.

cmdcheck.maxarglength(back to top)Default: 256
Importance: expert
Sections: ALL
The maximal allowed length for the argument of any command can be set with this option. This setting does not include the length of the command.

Example: Set the maximum argument length to 150
cmdcheck.maxarglength    150
jftpgw will not accept commands that have a longer argument than 150 characters with this setting.

cmdcheck.maxcmdlength(back to top)Default: 5
Importance: expert
Sections: ALL

Set the maximum length for any command, not including its arguments. Thus, the command "RETR /some/file" has a length of 4, because "RETR" has a length of 4.

Please note that no command will pass that the command handler does not know. Thus this option is not really important.

Example: Set cmdcheck.maxcmdlength to 10
cmdcheck.maxcmdlength   10
With this option, the maximal length for an FTP command is 10.

cmdcheck.mincmdlength(back to top)Default: 3
Importance: expert
Sections: ALL

Set the minimal allowed length for any command, not including its arguments. (See the description for cmdcheck.maxcmdlength as well)


ftp_diskcache
Cache transfers locally

This module enables jftpgw to cache transfers to disk. Whenever you download a file via the proxy (and the requirements are met) jftpgw will write the file to the disk in order to be able to deliver it later on again without having to do the transfer from the remote host.

jftpgw will check for the size and the modification date of the file on the remote server. If both are fine (i.e. if the remote file has the same size and modification date as the file in the cache), jftpgw will not retrieve the file from the remote host but send the file in the cache.

Please note that for security reasons the cache is user based. For anonymous logins, there is no problem, but if you have a real login on a remote server, you normally don't want somebody else to retrieve your files from the cache.

The directory will be $DIR/user@host:port/path/file.name
See the option "diskcache.directory" for configuring the directory $DIR.

This module can be configured with the following options:

diskcache.directory(back to top)Default: /tmp
Importance: essential
Sections: ALL

This option sets the directory basic directory to the path you specify as the argument.

Example: Set the directory to /var/cache/jftpgw
diskcache.directory     /var/cache/jftpgw

This will set the "root directory" for caching to /var/cache/jftpgw.

diskcache.enabled(back to top)Default: no
Importance: useful
Sections: ALL

Set this to "yes" if you want to enable the local cache.

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
diskcache.maxfilesize(back to top)Default: 1000M
Importance: useful
Sections: ALL

The maximum size for files that will get cached can be specified here. If you are short on diskspace you might not want to cache really large files. Furthermore it might be unlikely that large files will be requested very often - but that depends on your installation and your users of course.

Example: Do not cache files larger than 100 MB
diskcache.maxfilesize     100M

Disable caching for files that are larger than 100 MB.

Hint: You may use the size multipliers b, k, M and G.
Thus 1 means 1 Byte. 1b means 1 Byte as well. 3k means 3 Kilobytes and 4M would be 4 Megabytes.
diskcache.minfilesize(back to top)Default: 200
Importance: useful
Sections: ALL

The minimum size of a file to be cached. Normally it is not really efficient to cache all the small files, you might rather think about caching large files that would need a long time to download.

Example: Cache files regardless of their size
diskcache.minfilesize    0
Setting this value to 0 will enable caching for every file.
Example: Cache files larger than 1 MB
diskcache.minfilesize    1M
Files that are larger than 1 MB will get cached. Smaller files will not be written to the local disk.

Hint: You may use the size multipliers b, k, M and G.
Thus 1 means 1 Byte. 1b means 1 Byte as well. 3k means 3 Kilobytes and 4M would be 4 Megabytes.


ftp_nodatarelay
do not rewrite PORT/PASV commands
With this module enabled, jftpgw will not rewrite the IP addresses and port numbers in PORT commands or PASV responses. They will just be copied through.
You won't need this module in normal proxy use, i.e. it actually breaks the idea of a protocol-aware proxy program. However people came to me and asked me to implement this option because in their case, neither the FTP server nor the client were behind a NATing router but they just wanted to regulate access or use FXP with the proxy.

This module can be configured with the following options:

nodatarelay.enabled(back to top)Default: no
Importance: useful
Sections: ALL
Set this to "yes" if you want jftpgw not to rewrite PORT commands from the client or PASV responses from the server.
Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".


ftp_spp
Module for Single Port Protocol transfers

The Single Port Protocol is a protocol that can be used to do FTP transfers with jftpgw. The advantage is the possibility to use only one data port - in contrast to the normal FTP protocol that uses an own data port for each new connection. With the Single Port Protocol the data connection is multiplexed on the command connection.

However a normal FTP server or FTP client would get quite confused if it received the data connection on the control connection as well. Therefore you can only use the Single Port Protocol with another jftpgw proxy.

The typical setup is an FTP client connecting to a jftpgw proxy (maybe both are behind a firewall). The jftpgw proxy connects to another jftpgw proxy and opens up a single tcp connection to the remote proxy. The remote proxy forwards the connection to a real FTP server.
With this setup, as soon as you transfer a file or a directory listing, the two proxies in the middle use the control connection to transfer the data. Let's imagine that you do a file upload. Your FTP client sends the file with the regular FTP protocol to the first instance of jftpgw on the side of the client. This one asks the remote proxy if the Single Port Protocol is ok and if the other side confirms, the data is transferred on the control connection as well. On the other side, the jftpgw process there reads the file with the single port protocol and forwards it using the regular FTP protocol to the FTP server where you wanted to upload the file to.

This module can be configured with the following options:

spp.enabled(back to top)Default: no
Importance: expert
Sections: STARTUP
Say "yes" here to enable this module.
Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
spp.useforclient(back to top)Default: yes
Importance: expert
Sections: STARTUP
This option is normally enabled but if you disable it, jftpgw will not use the Single Port Protocol for a client. That means that if this option is disabled, jftpgw will not advertise it's Single Port Protocol features to a client (that may be another proxy as well) but it will still ask the FTP server it is connected to (that might be another jftpgw instance) if it supports the Single Port Protocol.

Example: Disable SPP for the client
spp.useforclient    no
If a client or another proxy instance asks the jftpgw proxy if it accepts transfers with the Single Port Protocol, it will deny this request.

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
spp.useforserver(back to top)Default: yes
Importance: expert
Sections: STARTUP
This option is normally enabled but if you disable it, jftpgw will not use the Single Port Protocol for a server. However, if spp.useforclient is still enabled, jftpgw will accept a transfer from a client that uses the Single Port Protocol. However it will not ask the remote server whether or not it supports the Single Port Protocol.

Example: Disable SPP for the server
spp.useforserver    no
jftpgw will not ask the server if it supports the Single Port Protocol.

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".


ftp_squidcache
Use a squid caching proxy for downloading files

This module adds support for a squid caching proxy. If this module is enabled, jftpgw will request files through the squid proxy you specify. However - since the squid proxy is an http proxy - jftpgw has to request downloads through the http protocol and therefore it cannot do uploads through the proxy. Make sure that jftpgw has the right to access the cache. You might need to reconfigure squid in order to allow the host where jftpgw runs to use the cache.

Please note that there is also the "diskcache" module that you can use to cache transfers to the disk without the need for a squid proxy.

This module can be configured with the following options:

squidcache.enabled(back to top)Default: no
Importance: useful
Sections: ALL
Set this to "yes" if you want jftpgw to use a squid proxy when downloading files.

Hint: Instead of "yes" you can also write "1", "true" or "on".
And instead of "no" you can also write "0", "false" or "off".
squidcache.proxyname(back to top)Default: (none)
Importance: essential
Sections: ALL
Specify the hostname of the proxy here

Example: Use the squid proxy in the DMZ
squidcache.proxyname squid.dmz.company.com
Set the hostname of the squid cache here. Don't forget to set the correct port with the squidcache.proxyport option.

squidcache.proxyport(back to top)Default: 8080
Importance: essential
Sections: ALL
Specify the port number of the proxy here

Example: Set the proxyport to 3128
squidcache.proxyport 3128
Set the port of the squid cache here. Don't forget to set the correct name with the squidcache.proxyname option.


<< Previous: ... Next: ... >>

Webpages created by Joachim Wieland © 2000-2004
Layout by Thomas Schultz © 2000