Copyright (c) 1999,2000 WU-FTPD Development Group. All rights reserved. Portions Copyright (c) 1980, 1985, 1988, 1989, 1990, 1991, 1993, 1994 The Regents of the University of California. Portions Copyright (c) 1993, 1994 Washington University in Saint Louis. Portions Copyright (c) 1996, 1998 Berkeley Software Design, Inc. Portions Copyright (c) 1989 Massachusetts Institute of Technology. Portions Copyright (c) 1998 Sendmail, Inc. Portions Copyright (c) 1983, 1995, 1996, 1997 Eric P. Allman. Portions Copyright (c) 1997 by Stan Barber. Portions Copyright (c) 1997 by Kent Landfield. Portions Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997 Free Software Foundation, Inc. Use and distribution of this software and its source code are governed by the terms and conditions of the WU-FTPD Software License ("LICENSE"). If you did not receive a copy of the license, it may be obtained online at http://www.wu-ftpd.org/license.html. $Id: VIRTUAL.FTP.SUPPORT,v 1.3 2000/07/01 18:49:32 wuftpd Exp $ [----] Method for Supporting Virtual FTP Servers in WU-FTPD [----] Table of Contents 1. Introduction 2. What is virtual FTP server support ? 3. Setup Overview 4. Configuring IP Address Aliases 4.1. Configuring IP Aliases on Sun Solaris 2.5 4.2. Configuring IP Aliases on SGI 4.3. Configuring IP Aliases on FreeBSD 4.4. Configuring IP Aliases on AIX 4.5. After system configuration 4.6. Testing interfaces 5. Building the software 6. Setting up the directory structure for virtual server support 7. Configuring to support Virtual FTP Server Support 7.1. Background 7.1.1. Limited Virtual Hosting Support: 7.1.2. Complete Virtual Hosting Support: 7.2. Create an ftpservers file: 7.3. Virtual ftpaccess files: 7.4. Master ftpaccess file Modifications: 7.5. Adding other virtual domain files 8. Setting up other support files 9. Supporting virtual logging 10. Shutting down your virtual FTP servers 11. Restarting your shutdown virtual FTP servers 12. Testing Your New Shiny Virtual Server Setup [----] 1. Introduction --------------- So you want to setup more than one FTP server on the same machine.... To make it work you will need to use the virtual server support in wu-ftpd. What follows are instructions for building the software and configuring it to use virtual servers. [----] 2. What is virtual FTP server support ? --------------------------------------- If you wish to manage an ftp server for two separate domains on the same machine then you need to be able to support virtual FTP servers. Basically, this allows an administrator to configure their system so a user ftping to ftp.domain1.com gets one ftp banner and one ftp directory and a user ftping to ftp.domain2.com gets another banner and directory even though they are on the same machine and use the same ports. Virtual ftp servers make supporting multiple domains a lot less costly and are easier to maintain than multiple ftp servers on multiple machines. [----] 3. Setup Overview ----------------- In order to set up a virtual ftp server environment you need to understand what it is you're about to do. What follows is a brief overview of the process ahead. * You will be configuring your machine to respond to multiple IP addresses. This is done via IP Address Aliases described below. First, you need to acquire the IP addresses you'll need. Once you have an IP address for each virtual server you wish to setup, you are ready to proceed. * Once you can see both addresses from the network, you will need to build and install the wu-ftpd software to support virtual servers. * Next you need to setup up the ftp directory structure for each virtual server you wish to support. You will need to customize the banner and message files in each of the virtual server areas. * With the directories in place you are ready to configure the configuration files and specify the virtual server specific information. * In order to be able to separate out who is logging in to what virtual server, you'll need to configure the system logging. This allows you to maintain separate logfiles depicting the activity of each virtual server. * And finally, you need to test your configuration. Once that is accomplished you can feel pleased with yourself and begin populating the individual ftp directories with data as appropriate. Additionally, you need to know how to shutdown and restart access to your real, anonymous and virtual servers in the event you need to. [----] 4. Configuring IP Address Aliases --------------------------------- You have to be able to setup IP address aliases in order for the virtual server support in wu-ftpd to work. Linux and BSDI, FreeBSD, SGI, Solaris 2.5*, AIX and others support this. What follows are "general" instructions on how to configure IP address aliases for the specified systems. Please check your system's 'ifconfig' documentation for specific instructions. In order to make the changes to the required system files you will first need to login as root. 4.1. Configuring IP Aliases on Sun Solaris 2.5: ----------------------------------------------- 1. Assure/place the system's normal hostname/IP address in the file /etc/hostname.le0. 2. Insert the following in the system initialization file /etc/init.d/rootuser just after the if/fi test for interface_names. # # configure virtual host interfaces quietly. # /sbin/ifconfig le0:1 inet XXX.XXX.XXX.XXX netmask + broadcast + -trailers up 2>&1 > /dev/null Replace XXX.XXX.XXX.XXX with the IP address that you wish to alias. 4.2. Configuring IP Aliases on SGI: ----------------------------------- 1. Edit /etc/hosts to include IP address and the name of the virtual server 2. Edit /etc/config/ipaliases.options using comments in that file as a template: ec0 XXX.XXX.XXX.xxx netmask 0xffffff00 broadcast XXX.XXX.XXX.255 or ec0 foobar netmask 0xffffff00 broadcast XXX.XXX.XXX.255 3. /etc/chkconfig -f ipaliases on Replace XXX.XXX.XXX.xxx with the IP address that you wish to alias. Replace XXX.XXX.XXX.255 with the network's broadcast address. 4.3. Configuring IP Aliases on FreeBSD: --------------------------------------- 1. If you are using a recent version of FreeBSD (3.x or 4.x): Edit /etc/rc.conf and put something like the following in. ifconfig_ed1_alias0="inet XXX.XXX.XXX.XXX netmask 0xffffffff" (You might have to change the device name from ed1) 2. If you are using an old version of FreeBSD (1.x or 2.x): Edit /etc/netstart and put something like the following in. ifconfig de0 alias XXX.XXX.XXX.XXX netmask 0xffffffff (or use ed0 or some other netmask if appropriate) 4.4. Configuring IP Aliases on AIX: ----------------------------------- In the way AIX is shipped, there is no direct support for IP aliases in the ODM. This does not mean that AIX does not support IP aliases, it means that IP alias info is stored in an ASCII file rather than in the ODM. 1. Edit the proper /etc/rc* file. If you are currently using an ODM TCP/IP configuration, edit the file /etc/rc.net. If you are using the traditional "BSD-style bootup method", edit the file /etc/rc.bsdnet instead. 2. Add a line such as the following example. /usr/sbin/ifconfig tr0 inet xx.xx.xx.xx netmask yy.yy.yy.yy alias 1>/dev/null 2>&1 Be sure to set the interface to the correct type if you are not using token ring (tr0) as the example shows. Refer to the ifconfig man pages. For more info on TCP/IP configuration and tuning, review the "no" command. 4.5. After system configuration: -------------------------------- In order to test your new configuration it is wise to reboot your system. This assures that your system is properly configured in the event of an non-planned system halt/reboot. A problem here is that the system is probably a production server for someone else... It is recommended that you add virtual www/ftp servers to your system at a scheduled maintenance time. Also, if you are adding more than one virtual server, add them all and simply reboot a single time. If you cannot reboot then execute the appropriate ifconfig (or chkconfig) command and test the reboot when you can. Also, if not immediately rebooting, it's not a bad idea to arp -s XXX.XXX.XXX.XXX x:x:xx:xx:xx:xx pub where XXX.XXX.XXX.XXX is the IP Address and where x:x:xx:xx:xx:xx is the Ethernet/whatever hardware physical address. 4.6. Testing interfaces: ------------------------ You need to assure you can see the interfaces using netstat and then try to ping the interface to assure it is responding. If so, your system is now ready. Now it's time to setup the FTPD server software and virtual server directories. [----] 5. Building the software ------------------------ 1. In order to compile in virtual hosting support it is necessary to assure "VIRTUAL" is defined. This is normally set in the src/config.h file that is created when you run 'build'. You should find the line #define VIRTUAL If it is not there, you will need to add it to your copy of config.h. 2. Check pathnames.h. Make sure you know where you want to put things on the system. If you change the install paths, check and change the top level makefile as well. 3. "build system-type". 4. "make install". At this point do a "make install" in the wu-ftpd top-level source directory and things will be installed. [----] 6. Setting up the directory structure for virtual server support ---------------------------------------------------------------- You will need to make sure the proper files/directories are in-place. Here is my structure. (Note: I put everything in a single directory structure for testing convenience. Actually I do that when I'm not testing as well...) From my pathnames.h /* ** Master Copies - Possibly overridden by VIRTUAL Hosting Configuation */ #define _PATH_FTPACCESS "/etc/ftpd/ftpaccess" #define _PATH_CVT "/etc/ftpd/ftpconversions" #define _PATH_FTPUSERS "/etc/ftpd/ftpusers" #define _PATH_PRIVATE "/etc/ftpd/ftpgroups" #define _PATH_FTPSERVERS "/etc/ftpd/ftpservers" #define _PATH_FTPHOSTS "/etc/ftpd/ftphosts" /* site-wide */ #define _PATH_PIDNAMES "/etc/ftpd/ftp.pids-%s" LS Listing: rkive-19:43-kent ls -lR /etc/ftpd /etc/ftpd: total 36 drwxrwsr-x 2 root sys 512 Jun 26 19:22 bin drwxrwsr-x 4 root sys 512 Jun 26 15:48 config -rw-r--r-- 1 root sys 4096 Jun 26 19:23 ftp.pids-local -rw-r--r-- 1 root sys 4096 Jun 26 19:33 ftp.pids-remote -rw------- 1 root sys 2046 Jun 26 14:55 ftpaccess -rw------- 1 root sys 873 Jun 26 14:55 ftpconversions -rw------- 1 root sys 37 Jun 26 14:55 ftpgroups -rw------- 1 root sys 277 Jun 26 14:55 ftphosts -rw------- 1 root sys 429 Jun 26 16:03 ftpservers -rw------- 1 root sys 151 Jun 26 14:55 ftpusers drwxrwsr-x 6 root sys 512 Jun 26 14:56 man /etc/ftpd/bin: total 1848 -rwxr-xr-x 1 bin bin 28312 Jun 26 19:22 ftpcount -rwxr-xr-x 1 bin bin 37512 Jun 26 19:22 ftprestart -rwxr-xr-x 1 bin bin 47264 Jun 26 19:22 ftpshut -rwxr-xr-x 1 bin bin 28312 Jun 26 19:22 ftpwho -rwxr-xr-x 1 bin bin 385568 Jun 26 19:22 in.ftpd /etc/ftpd/config: total 12 drwxrwsr-x 2 root sys 512 Jun 26 16:04 some.domain drwxrwsr-x 2 root sys 512 Jun 26 16:06 some.other.domain drwxrwsr-x 2 root sys 512 Jun 26 15:01 landfield.com /etc/ftpd/config/some.domain: total 6 -rw------- 1 root sys 1891 Jun 26 16:03 ftpaccess -rw------- 1 root sys 146 Jun 26 16:05 ftpusers /etc/ftpd/config/some.other.domain: total 6 -rw------- 1 root sys 1891 Jun 26 16:03 ftpaccess -rw------- 1 root sys 146 Jun 26 16:05 ftpusers /etc/ftpd/config/landfield.com: total 4 -rw------- 1 root sys 2046 Jun 26 15:01 ftpaccess /etc/ftpd/man: total 8 drwxrwsr-x 2 root sys 512 Jun 26 19:22 man1 drwxrwsr-x 2 root sys 512 Jun 26 19:22 man1m drwxrwsr-x 2 root sys 512 Jun 26 19:22 man5 drwxrwsr-x 2 root sys 512 Jun 26 14:56 man8 /etc/ftpd/man/man1: total 4 -r--r--r-- 1 bin bin 374 Jun 26 19:22 ftpcount.1 -r--r--r-- 1 bin bin 450 Jun 26 19:22 ftpwho.1 /etc/ftpd/man/man1m: total 28 -r--r--r-- 1 bin bin 2177 Jun 26 19:22 ftpshut.1m -r--r--r-- 1 bin bin 805 Jun 26 19:22 ftprestart.1m -r--r--r-- 1 bin bin 10813 Jun 26 19:22 in.ftpd.1m /etc/ftpd/man/man5: total 40 -r--r--r-- 1 bin bin 15341 Jun 26 19:22 ftpaccess.5 -r--r--r-- 1 bin bin 1004 Jun 26 19:22 ftpconversions.5 -r--r--r-- 1 bin bin 683 Jun 26 19:22 ftphosts.5 -r--r--r-- 1 bin bin 2531 Jun 26 19:22 xferlog.5 [----] 7. Configuring to support Virtual FTP Server Support ---------------------------------------------------- -------------- 7.1 Background -------------- This version provides two different means for supporting virtual hosting. You can choose to use the limited virtual hosting support or you can use complete virtual support by having completely different ftpaccess files. In the limited support version, virtual servers are only partially supported. This implementation of virtual servers only supports setting - the root ftp directory, - the log file, - the banner, - the hostname, and - the email address to contact. All other directives in the ftpaccess file have to be shared globally across all virtual servers. Below is the original message that described how to setup limited virtual support. --------------------------------------- 7.1.1. Limited Virtual Hosting Support: --------------------------------------- Date: Fri, 26 May 1995 21:33:23 -0400 (EDT) From: Brian Kramer To: wu-ftpd@wugate.wustl.edu Subject: Virtual FTP Servers [Modifications to provide for discrete xferlogs for each server provided by Marc G. Fournier -- sob.] I'm attaching a patch for wu-ftpd 2.4 to allow virtual ftp servers to be setup. Basically so a user ftping to ftp1.domain.com gets one ftp banner and one ftp directory and a user ftping to ftp2.domain.com gets another banner and directory even though they are on the same machine and port. I was the person who originally asked how to do it, and got enough answers to write a patch that would allow it. You have to be able to setup alias IP addresses in order for this to work. I know linux and bsdi support this. I do not warrant this code at all. Use it AT YOUR OWN RISK. If it causes your computer to blow up, TOUGH! Here's the steps. Compile the software with -DVIRTUAL added to the CFLAGS in the Makefile Add lines similar to the following for each virtual server to ftpaccess: # Virtual Server at 10.10.10.10 virtual 10.10.10.10 root /var/ftp/virtual/ftp-serv virtual 10.10.10.10 banner /var/ftp/virtual/ftp-serv/banner.msg virtual 10.10.10.10 logfile /var/log/ftp/virtual/ftp-serv/xferlog The first arg is the ip address of the virtual server. The second arg is either "root", "banner" or "logfile" (without the quotes) for that virtual server. The third arg is the file system location for the item specified in the second arg. Note: all the other message files, etc, and permissions and other settings in the ftpaccess file apply to all virtual servers. ---------------------------------------- 7.1.2. Complete Virtual Hosting Support: ---------------------------------------- Now you can use the previous method or you can create a separate ftpaccess to provide support for all ftpaccess directives. The ftpaccess, ftpusers, ftpgroups, ftphosts and ftpconversions files can all be specified on a per-domain basis. You now have the ability to override the Master WU-FTPD config files with a local copy specific to that domain. If you do not wish to place a copy of one or all files listed above in the virtual host directory for that specific host then the master copy is used. Supported on a virtual host basis: ---------------------------------- _PATH_FTPACCESS _PATH_FTPUSERS _PATH_PRIVATE _PATH_FTPHOSTS _PATH_CVT Set in a virtual site's ftpaccess file or master ftpaccess file --------------------------------------------------------------- _PATH_XFERLOG Supported on a site-wide basis: ------------------------------- _PATH_FTPSERVERS _PATH_EXECPATH _PATH_PIDNAMES _PATH_UTMP _PATH_WTMP _PATH_LASTLOG _PATH_BSHELL _PATH_DEVNULL ------------------------------ 7.2 Create an ftpservers file: ------------------------------ If you wish to take advanage of the extended virtual support it is necessary to create an ftpservers file. A real simple sample is shown below. # # ftpservers file # # Format: # IP Address Path to directory holding configuration # or hostname files for this virtual domain # # ftpaccess file for the landfield.com domain # landfield.com /etc/ftpd/config/landfield.com # # ftpaccess file for the some.domain # some.domain /etc/ftpd/config/some.domain # # ftpaccess file for the some.other.domain # 208.196.145.140 /etc/ftpd/some.other.domain # Make sure to create the directories you have listed. ---------------------------- 7.3 Virtual ftpaccess files: ---------------------------- For each virtual domain that you want to support, you have the option to create a ftpaccess file specific for that domain. This will override completely what you have in the Master ftpaccess file. This file must contain all directives. If you do not create an ftpaccess file for a specific domain, the domain will use the Master ftpaccess file settings. The only additions to the ftpaccess file that you need to make over a non-virtual version is the "root" and "logfile" directives. These act to assure the proper ftpd root directory is used for each of the supported virtual domains. The logfile directive is used to specify where you want the transfer logs recorded for that specific virtual domain. A sample is specfied below. root /ftp logfile /var/log/xferlog ----------------------------------------- 7.4. Master ftpaccess file Modifications: ----------------------------------------- If you do not want to setup a completely different ftpaccess file for a virtual domain, you can specify five separate things for the virtual server you want to setup in the master ftpaccess file. 1. root - This it the path to the ftp directory that you previously setup for this virtual server. 2. banner - This it the path to banner you wish displayed when a user connects to the virtual server. 3. logfile - This is the path to the logfile that is setup specifically for this virtual server. 4. hostname - This is the hostname of the virtual server. specifically for this virtual server. 5. email - This is the email address to direct comments to specifically for this virtual server. The format of a virtual server entry is virtual
is the IP address of the virtual server. The second argument specifies the is either the path to the root of the filesystem for this virtual server, the banner presented to the user when connecting to this virtual server, or the logfile where transfers are recorded for this virtual server. If the logfile is not specified the default logfile will be used. For example, add lines similar to the following for each virtual server you are trying to set up. # Virtual Server at 10.10.10.10 virtual 10.10.10.10 root /var/ftp/virtual/ftp-serv virtual 10.10.10.10 banner /var/ftp/virtual/ftp-serv/banner.msg virtual 10.10.10.10 logfile /var/log/ftp/virtual/ftp-serv/xferlog virtual 10.10.10.10 hostname froggy virtual 10.10.10.10 email ftp-admin@froggy.some.domain Done this way, all other message files and permissions as well as any other settings in the Master ftpaccess file apply to all listed virtual servers. --------------------------------------- 7.5. Adding other virtual domain files: --------------------------------------- With this release you have the ability to create other configuration files on a per-virtual-domain basis. Currently, the files you put into the virtual domain directory you have listed in the ftpservers file MUST be named: ftpaccess - virtual domain's access file ftpusers - restrict the accounts that can use the web server, ftpgroups - SITE GROUP and SITE GPASS support, ftphosts - allow or deny usernames access to that virtual server, ftpconversions - customize conversions available in the virtual domain. NOTE!!!: If you misspell any of them or name them something else, the server WILL NOT find them and the master copy of them will be used instead. [----] 8. Setting up other support files --------------------------------- You will need to make sure that any file referenced after the chroot(~ftp) are in the virtual server directories. Those files are * all messages (deny, welcome, etc.) * _PATH_EXECPATH files You will need to customize the banner, welcome and other message files for each virtual server directory. [----] 9. Supporting virtual logging ----------------------------- There are two different types of logging, the standard syslog logging and transfer logging. In order to separate transfer (or xferlog) logging it is necessary to use the "logfile" entry as described above. To enable logging via syslog, follow the standard syslog configuration instructions found in your system's documentation. Make sure you are using the same syslog 'facility' as is compiled into your wu-ftpd software. By default, 'daemon' is used. If you would like to change this, change the 'FACILITY' define in config.h. If you have syslog logging enabled you will see entries such as Mar 3 15:26:30 rkive ftpd[27207]: VirtualFTP Connect to: xxx.xxx.xxx.xxx This enables you to determine which virtual server the log records pertain to. [----] 10. Shutting down your virtual FTP servers ------------------------------------------- In order to support the proper shutting down of your server, you need to assure the shutdown message file is created in both the real user and anonymous user ftp areas. The location of the shutdown message file is specified in the ftpaccess file "shutdown" directive. In previous versions of wu-ftpd it was recommended to create a link to where the shutdown message file would be in order for shutdown to work properly for real and anonymous user. The problem was the supplied utility, 'ftpshut', only created the shutdown message file in the actual location as indicated in the shutdown directive and not in the anonymous FTP area. It also did not have support for virtual server shutdown. And when you were ready to restart your servers, you need to remove the shutdown message file manually. In order to overcome this, wu-ftpd has been modified to support shutting down the server for real users and guest/anonymous accounts and also for virtual FTP servers. It creates shutdown message files in all appropriate locations. [----] 11. Restarting your shutdown virtual FTP servers ------------------------------------------------- When you are ready to restart your ftp servers you will need to remove the shutdown message files. ftprestart is used when you are ready to re-enable your FTP server. It does the opposite of ftpshut and removes shutdown message files that were created by ftpshut. It will remove the system-wide shutdown message file as well as the shutdown message files in the anonymous ftp areas and any virtual ftp server areas. NOTE: At present it is either all-or-nothing when it comes to ftpshut and ftprestart. You cannot shutdown just a single server. If you need to do that you will have to do it manually at present. [----] 12. Testing Your New Shiny Virtual Server Setup ----------------------------------------------- A good test strategy is to create an entire runtime directory dedicated to wu-ftpd such as /usr/local/wu-ftpd-test/ or /etc/ftpd/ and make sure all the files and executables go there. In that manner you will be able to do a hot swap if you ever want to/need to (shouldn't be necessary but please CYA... ;)) You will need to test each and every new virtual server you install. Make sure that you have the appropriate permissions and are getting the right results. Only you will know what is right for you. Also, if you have existing FTP server areas on your system, test and make sure that something you did to the ftpaccess file did not break what use to work. If you want to see what set of configuration files are being used you can set '-DVIRTUAL_DEBUG' in the makefile. Build and install the new version and see what prints out. Please don't run with this debug option enabled as it give much to much information out to those that have no 'need to know'. [----]