ProFTPD 1.2 INSTALL

Introduction
ProFTPD is designed to be configured for compilation on the target system by a single shell script, named configure, located in the top-level directory of the source distribution. This script, originally generated by the GNU autoconf tool, will analyze your system and create a config.h file that should allow ProFTPD to compile cleanly. On some systems it may be necessary to give certain options to configure or to tweak manually one or both of the config.h and the top-level Makefile files produced by configure.

ProFTPD is designed to be very flexible, which necessarily leads to extra compile-time and run-time configuration complexity. The configure script also can be used to customize your build, setting compile-time options based on command line options that you provide. In particular, optional software modules to be compiled into ProFTPD may be chosen this way.

In addition to those set by the configure script, the file include/options.h contains a number of easily tweakable compile-time options which will affect ProFTPD's operation. These options are never modified by the configure script. Each option is documented in the header file itself. Changing these values is rarely needed, and most can be overriden at run-time by directives in the proftpd.conf configuration file.

Note that a sample RPM spec file has been included in contrib/dist/rpm/.

NOTE TO PACKAGE MAINTAINERS: Please, do NOT remove the ELF .comment and .note sections.

If you install ProFTPD on a slightly uncommon (or really new or old) platform, please consider recording and sharing your experience.

Build Requirements

Installation Instructions

  1. Plan your installation.
    Please, read through all the installation steps before starting. There are many compile-time customizations that you may wish to make, particularly regarding user authentication. Read through README.modules and the other README.* and contrib/README.* files.

    Note that the following modules are included by default and need not be added explicitly: mod_auth, mod_core, mod_log, mod_ls, mod_site, mod_unixpw and mod_xfer. Also, if PAM is detected by configure, the mod_pam module will be included automatically. However, it has been reported that some systems still require it to be added explicitly. Further note that the contrib/mod_test module is not functional, and you should not attempt to use it.

    You may need to specify the shared library search path on your system. See your system and compiler documentation. Frequently, the -R or -rpath options are used for this operation. Be especially careful to set the path on AIX systems. See README.AIX.

    Hint: if your configure command line becomes long or complicated, you might try storing it in a sh script file, say '.configcmd'.

  2. Configure the software.
    Run the GNU autoconf configure script in the top level directory to create config.h and all the Makefiles. In addition to configuring ProFTPD to compile on your system, you can use this step to customize some parameters of or add optional features to ProFTPD. There are many configuration options. To use the default values, you would simply run: 
            $ ./configure
    By default the ProFTPD files will be installed as user root and the first group with gid 0 listed in /etc/group, usually root or wheel. If you wish to install using a different user or group ownership, set the install_user and install_group environment variables before running configure. Using a Bourne-ish style shell (e.g. sh, ksh, bash), you can do this on the command line like this: 
            $ install_user=root install_group=wheel ./configure
    Similarly, as is typical with GNU autoconf scripts, settings for the compilation system can be made, such as the compiler: 
            $ CC=gcc CFLAGS='-O -g' ./configure
    Other options can be given to configure as command line arguments. All available arguments can be listed by running: 
            $ ./configure --help
    By default proftpd and ftpshut are installed in /usr/local/sbin/, ftpcount and ftpwho in /usr/local/bin/, the configuration file in /usr/local/etc/, and the man pages in /usr/local/man/man?/. Further, /usr/local/var/proftpd/ is used to hold the runtime scoreboard files. See the "Directory and file names" section of the ./configure --help output for the arguments to change these defaults. For instance, to place all these directories under /usr/ rather than /usr/local/, you could use: 
            $ ./configure --prefix=/usr
    Or, to place the configuration file in /etc/ and the runtime state files in /var/proftpd/, you would use: 
            $ ./configure --sysconfdir=/etc --localstatedir=/var
    Optional ProFTPD modules can be included using --with-modules=LIST, where LIST is a colon-separated list of module names. This applies only to optional modules, such as those found in the contrib/ directory (the core modules in the modules/ directory are either mandatory or included by default). For example, if you wish to include both the readme and LDAP modules, you would use: 
            $ ./configure --with-modules=mod_readme:mod_ldap
    Some operating systems require you to use either --enable-autoshadow or --enable-shadow if you wish to use the system's shadow password file for user authentication. Using autoshadow allows proftpd to work with either shadow or traditional password files.

    If you wish to use SQL for user authentication, you must specify mod_sql and one SQL backend module, either mod_sql_mysql or mod_sql_postgres. Further, the backend module must be specified later in the module list, e.g. --with-modules=mod_sql:mod_sql_postgres. Otherwise, compilation will succeed, but SQL authentication will not work.

    Be aware that if you ever need to rerun the configure script, you first should run make distclean.

  3. Verify correct configure operation.
    Watch the output of the configure script. After configure has run, you may wish to inspect the config.h file to make sure configure didn't make any wrong "guesses" for your platform.

  4. Compile the software.
    Run make from the top-level directory. On some systems (e.g. BSDI), you may need to use GNU make (often gmake or gnumake) instead of the default system make. Watch the output of the compile process and make sure no errors occur. On some platforms (notably AIX and IRIX) you may see some compilation or link warnings. These generally can be ignored.

  5. Test the software.
    As of ProFTPD 1.2.0, there are no automated regression tests. However, you are encouraged to perform your own ad-hoc, manual tests.

    Note that you can start proftpd directly from your shell prompt, but do remember that it must run as root for all functions to operate properly. Nonetheless, many operations can be verified without root privileges. An alternate configuration file can be specified using the -c command line switch. In the configuration file, the TCP ports may be changed from the standard default ftp (21) and ftp-data (20) ports, and an alternate passwd file may be specified. Since such a daemon will not be able to change its uid, you also must specify the user and group names to match those used to start the daemon.

    To demonstrate this process, a set of example config files have been included in the sample-configurations subdirectory. 

            % sh sample-configurations/PFTEST.install
        Sample test files successfully installed in /tmp/PFTEST.
        % ./proftpd -n -d 5 -c /tmp/PFTEST/PFTEST.conf
    Then, in another window, connect to the unprivileged port. PFTEST.conf uses port 2021, and PFTEST.passwd defines a user "proftpd" with password "proftpd". Using the traditional Unix ftp client, it might look something like this: 
            % ftp -n -d
        ftp> open  2021
        ftp> user proftpd
        ---> USER proftpd
        331 Password required for proftpd.
        Password: [proftpd]
        ---> PASS proftpd
        230 User proftpd logged in.
        ftp>
    The supplied PFTEST.passwd is in traditional Unix format Your system may use a different file format, so you may have to create your own. Further, you may have to use another method to insert your user and group names into the PFTEST.conf file, if the PFTEST.install script fails.

    If you encounter any problems, be sure to see the Troubleshooting and Help sections below.

  6. Package the software.
    As of ProFTPD 1.2.0, no packaging procedures are provided other than the inclusion of an RPM spec file in the contrib/dist/rpm/ directory.

  7. Install the software.
    Note: this and the following steps likely require root privileges. Unless a system specific installation package was created, e.g. an RPM, run make install from the top-level build directory. This installs the ProFTPD executables, man pages, and a basic configuration file, copied from sample-configurations/basic.conf. The full path to the configuration file will be /usr/local/etc/proftpd.conf, unless it was changed in Step 2.

    If an installation package was created, install the ProFTPD package according to procedures appropriate for that packaging system.

  8. Modify the proftpd configuration file.
    If the User and Group specified in proftpd.conf do not exist on your system proftpd WILL NOT RUN. Edit and modify proftpd.conf as needed. Many systems have the group nobody instead of the group nogroup. However, it is highly recommended that you create a new user and group specifically to be used by this server. Decide how you want to run proftpd, either started by inetd (or xinetd) or as a standalone daemon. Then edit the proftpd.conf file and change the ServerType directive to match your choice, either ServerType inetd or ServerType standalone. The basic.conf configuration file, installed by make install in Step 5, has a default setting of standalone.

  9. Modify the inetd/xinetd superserver configuration file.
    Edit /etc/inetd.conf and then send the inetd process the HUP signal, so that it will reread the updated configuration file. On some systems there are other mechanisms to tell inetd to reread its configuration file, e.g. refresh -s inetd on AIX. Check your system documentation to see what command is appropriate.

    If proftpd is to be run from inetd, find the line in /etc/inetd.conf that looks something like: 

            ftp stream tcp nowait root      /usr/sbin/in.ftpd in.ftpd
    And replace it with: 
            ftp stream tcp nowait root      /usr/local/sbin/proftpd proftpd
    Or, if the tcp wrappers package is installed on your system, you may use a line something like: 
            ftp stream tcp nowait root      /usr/sbin/tcpd /usr/local/sbin/proftpd
    If proftpd is to be run in standalone mode, you should comment out any ftp line in the /etc/inetd.conf file by inserting a # at the beginning of the line. Then signal the inetd process to reread /etc/inetd.conf.

    If your system is using xinetd instead of inetd then either edit your /etc/xinetd.conf file or add a proftpd file in /etc/xinetd.d/: 

        service ftp
    {
       flags           = REUSE
       socket_type     = stream
       instances       = 50
       wait            = no
       user            = root
       server          = /usr/sbin/proftpd
       bind            = 
       log_on_success  = HOST PID
       log_on_failure  = HOST RECORD
    }
    More information can be found in the FAQ and Userguide and in the xinetd documentation for your system.

  10. Modify the system boot scripts.
    If running in standalone mode, you probably will want to edit your boot scripts to start proftpd at boot time. For systems that use SysV-style individual startup scripts, the source distribution includes an example init script, contrib/dist/rpm/proftpd.init.d.

  11. Create the runtime state directory.
    In order for the MaxClients and MaxClientsPerHost directives and the ftpwho and ftpcount utilities to work, proftpd must have a directory to hold its scoreboard files. The default is /usr/local/var/proftpd/, though it may have been changed in the configuration process in Step 2. The default location also can be overriden at run-time by using the ScoreboardPath directive in the proftpd.conf configuration file. Whatever diretory is used, it must exist prior to starting proftpd. If you have installed from an installation package, the installation scripts may have created the default directory. Nonetheless, if it does not already exist you must create it manually. No special permissions are needed on the directory, unless you wish to restrict who is allowed to run ftpwho and ftpcount.

  12. Verify operation.
    Once proftpd either has been configured to be started by inetd or has been started in standalone mode, try ftp'ing to your system to make sure that everything works. As before, if you run into any problems, see the Troubleshooting and Help sections below.

  13. Customize the proftpd configuration file.
    If you wish to add anonymous ftp or otherwise create a more sophisticated ftp configuration, read more about configuring ProFTPD: 
            Configuration Examples: sample-configurations/*.conf
       Configuration Reference: doc/Configuration.html
             Configuration FAQ: doc/FAQ-config.html
                 Documentation: http://pdd.sourceforge.net/
                                http://www.proftpd.org/docs/
                           FAQ: http://pdd.sourceforge.net/faq/proftpdfaq.html
    Note that some systems will require special system-specific preparation of the anonymous ftp and any other chroot directories. Also, be aware that the configuration directives PersistentPasswd, RequireValidShell, and UseFtpUsers may require special attention.

    To check the syntax of a new or modified configuration file, you may run proftpd -t -c /path/to/new/conf/file from the command line.

    You can test the runtime function of your configuration file without interfering with a running server, by running a separate test server on a different port. Specify the port to use with the Port directive in the configuration file, but don't forget to restore the port setting before installing the new configuration file for the production server. Good luck!

    Troubleshooting
    This section is far from comprehensive. See the FAQ and other resourses for further assistance.

    Help

    Resources