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 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 ------------------ 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 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'. 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 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 = 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 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 overriden 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 ' 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 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 (NetBSD, OpenBSD) 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, etherfind, 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 (subscriptions): proftpd-users-request@proftpd.org (submissions): proftpd-users@proftpd.org (archives): http://www.geocrawler.com/redir-sf.php3?list=proftp-user Developer List (subscriptions): proftpd-devel-request@proftpd.org (submissions): proftpd-devel@proftpd.org (archives): http://www.geocrawler.com/redir-sf.php3?list=proftp-devel Announcement List (subscriptions): proftpd-announce-request@proftpd.org (archives): http://www.geocrawler.com/redir-sf.php3?list=proftp-announce Security Reports: security@proftpd.org R4. Bug Tracking System (Bugzilla). Bug Reports/Patches: http://bugs.proftpd.org proftpd-devel@proftpd.org 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.