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_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.
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:
$ 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'.
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 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 <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.
o "Fatal: unknown configuration directive 'AuthPAMAuthoritative'
on line NN of '/etc/proftpd.conf'."
This means that either 'AuthPAMAuthoritative' was misspelld or
mod_pam was not compiled in to ProFTPD. If the latter, you may
need to reconfigure and recompile proftpd, explicitly adding
mod_pam with the "./configure --with-modules=mod_pam ...".
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 5,
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 (`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.
