INSTALL

                ProFTPD 1.2 Installation Instructions
                =======================================

------------
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 overridden 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
------------------

        o ANSI/ISO C89/C90 C compiler, e.g. GNU gcc
        o GNU make, though most system makes should work
        o ANSI C and POSIX run-time libraries
        o BSD sockets API
        o Disk space: ~4.5 MB to unpack, 6-8 MB to build, ~2 MB to install



-------------------------
Installation Instructions
-------------------------

0.  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_auth_unix and mod_xfer.  Also, if PAM is detected by configure,
    the mod_auth_pam module will be included automatically.  However, it has
    been reported that some systems still require it to be added explicitly.

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


1.  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:

        $ ./configure CC=gcc CFLAGS='-O -g'

    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 file.
    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/proftpd

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


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


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


4.  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 <hostname> 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.


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


6.  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 1.

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


7.  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".
    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" config file, installed by
    'make install' in Step 4, has a default setting of "standalone".


8.  Modify the inetd 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            = <the-ip-you-wish-to-bind-to>
       log_on_success  = HOST PID
       log_on_failure  = HOST
    }

    More information can be found in the FAQ and Userguide and in the
    xinetd documentation for your system


9.  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".


10. 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 scoreboard
    file.  The default is '/usr/local/var/proftpd/proftpd.scoreboard', though
    it may have been changed in the configuration process in Step 1.
    The default location also can be overridden at run-time by using the
    ScoreboardFile directive in the proftpd.conf configuration file.
    If the indicated file does not exist, it will be created when the daemon
    starts up.  If you have installed from an installation package, the
    installation scripts may have created the default directory. 


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


12. 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
                 Documentation: http://www.proftpd.org/docs/
                           FAQ: http://www.proftpd.org/docs/faq/linked/faq.html

    Note that some systems will require special system-specific preparation
    of the anonymous ftp and any other chroot directories.  PLEASE NOTE
    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 <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.


T1. Compile time problems are often easy to sort out by giving the right
    options and search paths to the compiler.  However, at other times they
    can be rather difficult to debug.  Problems often result from header
    file or C preprocessor macro name conflicts.  A few packages have been
    known to install conf.h headers in /usr/local/include.  Occasionally,
    one must resort to looking at the preprocessor output.  Consult your
    compiler documentation for how to do this, though a command similar
    to `cc -E file.c` often works.

    Some common error messages include:

        o "symbol ap_signal undefined in main.o"
          This usually means that the fnmatch.h header is including
          the Apache ap_config.h header, though proftpd does not link
          with the Apache library.  This mostly happens on Solaris 8,
          though a similar problem has been reported on Red Hat 6.0
          systems with the <hsregex.h> header.


T2. If you encounter run-time problems, first check your syslog messages.
    The proftpd daemon logs all the error conditions that it encounters,
    including problems parsing the configuration file.  Authentication related
    messages are logged using the syslog facility "auth" or, if available,
    "authpriv".  All other messages use the syslog "daemon" facility, unless
    redirected by the "-n" command line switch or by the SyslogFacility or
    SystemLog directives.  Check your syslogd.conf to see what syslogd does
    with these messages.

    Some common error messages include:

        o "inet_create_connection() failed: Operation not permitted"
          This usually means that proftpd was not started as root.

        o "bind: unable to bind to port" or "Address already in use"
          This usually means that another process, either inetd, xinetd or
          another standalone ftp server, is already using the ftp port.

        o "Fatal: Socket operation on non-socket"
          This usually means that proftpd.conf ServerType directive is
          configured for inetd rather than standalone mode.

        o "received: PASS (hidden)"
          "ProFTPD terminating (signal 11)"
          This usually means that shadow passwd file support is required
          but was not compiled in.  Try starting the build over at Step 1,
          adding either '--enable-autoshadow' or '--enable-shadow' to
          the configure command line.

    If users can not login and your system uses PAM authentication, you may
    need to configure PAM to work for FTP.  For further details, consult your
    system PAM documentation.  If you have installed from a package, hopefully
    this was done automatically.  On Linux systems, the following may work:

        % cp -p contrib/dist/rpm/ftp.pamd /etc/pam.d/ftp

    If your client sees something like "server error 500, server shut down",
    that probably means that you have a stale /etc/shutmsg file, which you
    should delete.


T3. You can generate additional debugging messages by starting the proftpd
    daemon with the "-d N" command line option, where N ranges from 1 to 10,
    with higher values increase the number of debugging messages.  If you are
    running the daemon standalone, you also may wish to use the "-n" option,
    which will keep the daemon from disassociating from your terminal and
    cause all messages to display directly on your terminal rather than
    being syslogged.


T4. If you encounter problems not readily diagnosed by the error messages,
    you might check for a newer ProFTPD release at the official distribution
    sites to see if your problem has already been fixed.  Reading the
    ChangeLog file in each new distribution is often the fastest way to
    see what bugs have been fixed.


T5. If your system has a system call trace utility, you may wish to use it
    to diagnose what is failing.  Often this method is useful to spot a
    file open failures, including shared libraries.

    Some system call trace utilities:
        o truss (Solaris, SVR4 derivatives, Unixware, AIX5L, FreeBSD)
        o trace (SunOS 4.x)
        o tusc (HP/UX 11.x: ftp://ftp.cup.hp.com/dist/networking/tools/)
          trace
            http://hpux.cs.utah.edu/hppd/hpux/Sysadmin/trace-1.6/
            http://devresource.hp.com/devresource/Tools/ToolLibrary.html#perfhp
        o syscalls, trace (AIX 4.x); sctrace
        o par (IRIX)
        o alpha-trace (Digital Unix: ftp://ftp.mrc-lmb.cam.ac.uk/pub/jkb/)
        o ktrace/kdump (FreeBSD, OpenBSD, NetBSD)
        o strace, ktrace/kdump, ltrace (Linux)


T6. Another diagnostic technique is to monitor the FTP protocol communication
    between the proftpd server and the ftp client.  Many ftp clients have a
    debug or trace option.  Though requiring detailed knowledge of the FTP
    protocol, telnet can be used to connect and directly converse with the
    proftpd server.  Lastly, the FTP converstation can be traced using a
    network monitoring tool, such as tcpdump, ethereal, snoop or netsnoop.


T7. Further debugging probably will require the use of a debugger,
    which may require recompiling proftpd with debugging symbols.
    Consult your compiler and debugger documentation.



----
Help
----

H1. Before asking for help on the mailing list, look through the available
    documentation, including the FAQ and the searchable archives of the
    mailing lists.  Not only are many common questions answered in those
    documents, but they will often yield answers faster than a question
    sent to the mailing list.

    See the "Resources" section below for documentation pointers and links.


H2. When posting to the mailing list, try to be clear and concise, but give
    enough information to enable people to help.  Merely stating something
    like "It doesn't work.  Help!" is unlikely to elicit any useful answers.
    Describe your problem as completely as possible, including what you think
    is wrong, what behavior you expect, and any relevant error log messages
    or debug output.  Unless the problem occurs with the base proftpd.conf
    file or a minimal derivative, it may be useful to include part or all of
    your proftpd.conf file.

    So, at a minimum, you should include:
        o OS type and version (e.g. `uname -a`)
        o ProFTPD extended version info (`proftpd -V` and `proftpd -vv`)
        o ProFTPD module list (`proftpd -l`)

    The following may help to further identify compilation information,
    especially if you are installing a vendor supplied package rather than
    building from sources yourself:
        o `what proftpd` or `ident proftpd`

    And still more compilation information may be available if your system
    uses the ELF object file format:
        o `objdump -f proftpd` or `dump -v -f proftpd`
          or `elfdump -v -f proftpd`
        o `objdump -j .comment proftpd` or `dump -n .comment proftpd`
          or `elfdump -n .comment proftpd`
        o `mcs -p proftpd`
        o `objdump -j .note proftpd` or `dump -v -n .note proftpd`
           or `elfdump -v -n .note proftpd` or `mcs -p -n .note proftpd`


H3. Please, please, do NOT use the bug reporting system for compilation or
    configuration problems and questions.  Those should be sent to the
    mailing list.

    In order conserve development resources, please only submit bug reports
    when you have reasonable confidence that there is an actual code bug,
    a portability problem, or problems with the build and compilation system.
    Even then, please first search the bug system to see if your bug has been
    reported already.  If it has, use your own best judgement about adding
    comments to the existing report, especially either to confirm the bug's
    existence or to provide additional diagnostic and debugging information.

    For some more suggestions about reporting bugs, see:
        http://bugs.proftpd.org/bugwritinghelp.html



---------
Resources
---------

R1. Basics.

    Various Subjects: README.*, contrib/README.*
   Configuration Ref: doc/Configuration.html
  Config/Problem FAQ: doc/faq.html

                 WWW: http://www.proftpd.org
                 FTP: ftp://ftp.proftpd.org/distrib/
    Mirror Site List: http://www.proftpd.org/wwwmirror.html


R2. ProFTPD Documentation Project.
    Documents include a Configuration Reference, draft User Guide, and FAQ.
    Formats include linked and single HTML files, PostScript, PDF and text.

    Note that this Configuration Reference may refer to a newer code base
    than you are using.  So, referring to doc/Configuration.html file in
    your source distribution may be less confusing.

              (main): http://sourceforge.net/projects/pdd


R3. E-Mail Lists.

       End User List
       (submissions): proftp-user@lists.sourceforge.net
         (subscribe): proftp-user-request@lists.sourceforge.net
          (archives): http://sourceforge.net/mailarchive/forum.php?forum_name=proftp-user

      Developer List
       (submissions): proftp-devel@lists.sourceforge.net
         (subscribe): proftp-devel-request@lists.sourceforge.net
          (archives): http://sourceforge.net/mailarchive/forum.php?forum_name=proftp-devel

   Announcement List
         (subscribe): proftp-announce-request@lists.sourceforge.net
          (archives): ttp://sourceforge.net/mailarchive/forum.php?forum_name=proftp-announce

    Security Reports: security@proftpd.org


R4. Bug Tracking System (Bugzilla).

 Bug Reports/Patches: http://bugs.proftpd.org
                      proftp-devel@lists.sourceforge.net


R5. CVS Repositories.

       Anonymous CVS: cvs.proftp.sourceforge.net
      (instructions): http://www.proftpd.org/cvs.html
        CVS tarballs: ftp://ftp.stikman.com/pub/proftpd/
                      ftp://ftp.linuxceptional.com/proftpd/

     Development CVS: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/proftp/proftpd/


R6. Statement about proftpd.org and proftpd.net.

    The www.proftpd.org and www.proftpd.net sites now should be effectively
    mirrors of one another.  The official proftpd site is www.proftpd.org,
    however www.proftpd.net will remain in operation at a physically remote
    location in order to provide redundancy.