Compiling ProFTPD

The ProFTPD source code 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, e.g.: 

  # cd proftpd-version/
  # ls -al configure
  -rwxr--r--    1 tj       tj        1155157 Nov 18 19:54 configure
This configure script, generated by the GNU autoconf tool, will analyze your system and create a config.h file that should allow ProFTPD to compile cleanly.

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, software modules to be used by ProFTPD may be chosen this way.

In addition to the config.h file generated by the configure script, the file include/options.h: 

  # cd proftpd-version/
  # ls -al include/options.h
  -rw-r--r--    1 tj       tj           7212 Nov 15 14:34 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. Changing these values is rarely needed, and most can be overridden at run-time by directives in the proftpd.conf configuration file.

To see the full list of command-line options for configure, run: 

  # ./configure --help
Should you change your mind about which options to use, you will need to re-run configure with the new options. But first you will need to clean up the previous results by doing: 
  # make clean
  # ./configure ...
The rest of this document covers the various options of the configure script in detail.

When you run the configure script by itself, without any command-line options, you will get the defaults: 

  # cd proftpd-version/
  # ./configure
What are the defaults?

Layout Options
One of the first decisions to make is where you want ProFTPD, and all of its supporting files, to be installed on your system. By default, the ProFTPD build system installs the files in a layout under the /usr/local/ directory. The /usr/local/ directory functions as the default prefix directory. Thus the layout of installed files will look like: 

  /usr/local/bin/ftpcount
  /usr/local/bin/ftpdcount
  /usr/local/bin/ftptop
  /usr/local/bin/ftpwho
  /usr/local/bin/prxs
  /usr/local/etc/proftpd.conf
  /usr/local/include/proftpd/*.h
  /usr/local/lib/pkgconfig/proftpd.pc
  /usr/local/libexec/*.{a,la,so}
  /usr/local/sbin/ftpshut
  /usr/local/sbin/in.proftpd
  /usr/local/sbin/proftpd
  /usr/local/share/locale/lang/LC_MESSAGES/proftpd.mo
  /usr/local/share/man/man1/ftpcount.1
  /usr/local/share/man/man1/ftptop.1
  /usr/local/share/man/man1/ftpwho.1
  /usr/local/share/man/man5/xferlog.5
  /usr/local/share/man/man8/ftpdctl.8
  /usr/local/share/man/man8/ftpshut.8
  /usr/local/share/man/man8/proftpd.8
  /usr/local/var/proftpd/*
To place all of these files under the /usr/ directory rather than /usr/local/, you would change the prefix directory using the --prefix option: 
  # ./configure --prefix=/usr

You can also change only portions of the layout, for just the binaries or the configuration file or other parts:

--bindir Change prefix-dir/bin/
--libexecdir Change prefix-dir/libexec/
--localstatedir Change prefix-dir/var/
--sbindir Change prefix-dir/sbin/
--sysconfdir Change prefix-dir/etc/

Thus to place the configuration file in /etc/ and the runtime state files in /var/proftpd/, you would use: 

  # ./configure --sysconfdir=/etc --localstatedir=/var/proftpd

Installer Options
When you go to install ProFTPD, the build system will install all of the files and directories as user 'root' and group 'root' (or group 'wheel', depending on your system). This user/group combination is used because on most systems, that is the user which has permissions for creating new files/directories under the /usr/local/ directory.

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

For example, I do a lot of personal ProFTPD builds, and so I typically use: 

  # install_user=tj install_group=tj ./configure --prefix=/home/tj/proftpd/devel/build/ ...
Note that the install_user and install_group environment variables do not affect the IDs used when running proftpd.

Feature Options
There are some features which are part of the core proftpd engine itself which can be configured via compile-time options. The list below talks about the more common of these feature options:

There are of course other feature-specific configure options, but most of the time, most people will not need to know about or use them.

Module Options
Now we come to the fun part: deciding which of the many different modules to include in our build. Before doing this, though, you need to know that some modules are automatically included in the build:

In addition to these modules, there are some modules which may be automatically added, depending on your system:

The above modules all live under the modules/ directory in the source distribution. So what modules are left to choose from? All of the modules under the contrib/ directory.

Optional ProFTPD modules are added to the build using the --with-modules option. The value you provide is a colon-delimited list of the module names you wish to add, as statically linked modules. Thus if you wanted to add LDAP and SSL/TLS support to your proftpd, you would list the appropriate modules in the --with-modules list: 

  $ ./configure --with-modules=mod_ldap:mod_tls ...
Do not include the names of any modules under the modules/ directory; the modules there are either mandatory or conditional. Attempting to include a non-optional module in the --with-modules list will result in a configure error.

The --with-shared option works much like --with-modules. You provide a colon-delimited list of names of modules to be compiled as shared modules. Note that using the --with-shared option requires the use of --enable-dso. Thus to add LDAP and SSL/TLS support as shared modules, you would use: 

  $ ./configure --enable-dso --with-shared=mod_ldap:mod_tls ...
Failure to include the --enable-dso option when using --with-shared results in a configure error: 
  configure: error: cannot build shared modules without DSO support -- aborting

You can add some of the automatically included modules as shared modules, but not all of them. The following automatically included modules cannot be compiled as shared/DSO modules:

If your --with-shared list includes one of the above modules, it will result in a configure error: 
  $ ./configure --enable-dso --with-shared=mod_auth_unix ...
  configure: error: cannot build mod_auth_unix as a shared module
Why can't these be shared modules? These modules must appear in the proftpd binary in order for it to function as a proper FTP server. Yes, even mod_auth_unix.c; it is the default/fallback mechanism for obtaining user/group names/IDs.

Do not use --with-modules or --with-shared multiple times in your configure command; only the last one appearing in the configure command will be used. You must consolidate all of the modules you wish to add into a single colon-delimited list.

Header and Library Options
The --with-includes option is used to add additional directories containing header files to the system-defined list of header file directories used by the compiler. Likewise, the --with-libraries option is used to add additional directories containing libraries to the list of library directories searched by the linker. Both options take colon-delimited paths as the parameter.

For example, on Solaris, you have to explicitly tell the compiler and linker to use the /usr/local/include and /usr/local/lib directories: 

  $ ./configure --with-includes=/usr/local/include --with-libraries=/usr/local/lib ...

Or you may have the MySQL or OpenSSL packages installed in custom locations, and you need to tell configure about those locations: 

  $ ./configure --with-modules=mod_sql:mod_sql_mysql:mod_tls \
    --with-includes=/usr/local/mysql/include/mysql:/usr/local/openssl/include \
    --with-libraries=/usr/local/mysql/lib/mysql:/usr/local/openssl/lib
These options are commonly used to specify the locations for LDAP, OpenSSL, database, and other software packages used by modules.

Just as using --with-modules multiple times does not work, using --with-includes or --with-libraries multiple times does not work. Consolidate all of the directories for headers (or libraries) into a single colon-delimited list, and use one --with-includes option and one --with-libraries option.

Environment Variables
As with most other GNU autoconf-based build system, the ProFTPD configure script honors these environment variables:

Use of these environment variables is for the more advanced users, system administrators, and software developers and packagersl who know the environment variable semantics.

Putting It All Together
Now, let's configure the build system for a proftpd that does not include IDENT support, is installed under /opt/proftpd/ as user and group 'ftpd', has statically linked SSL/TLS support and dynamically loaded SQL backend modules: 

  $ install_user=ftpd install_group=ftpd ./configure \
    --prefix=/opt/proftpd \
    --disable-ident \
    --enable-dso \
    --with-modules=mod_tls \
    --with-shared=mod_sql:mod_sql_mysql:mod_sql_postgres \
    --with-includes=/usr/local/openssl/include:/usr/local/mysql/include/mysql:/usr/local/postgres/include \
    --with-libraries=/usr/local/openssl/lib:/usr/local/mysql/lib/mysql:/usr/local/postgres/lib
Hint: if your configure command becomes long or complicated, you might try storing it in a sh script file, say 'proftpd-conf.sh'.

Watch the output of the configure script. After the configure command has run, you may wish to inspect the config.h file to make sure configure didn't make any wrong "guesses" for your platform. If the configure command fails, keep a copy of the generated config.log file. Include that file, and the configure error, when asking/troubleshooting the error via the mailing lists.

Compiling
Now you are ready to actually compile the source code into working executables, using all of your selected options and features and capabilities. To do this, imply run 'make' from the top-level source directory: 

  $ cd proftpd-version/
  $ make
On some systems (e.g. BSDI), you may need to use GNU make (often called 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.

If you are interested in testing the compiled executables, read this howto about the testsuite that comes with the ProFTPD source code.

To install the compiled executables, use: 

  $ cd proftpd-version/
  $ make install
You are now prepared to start up and use your compiled proftpd.

Developer Options
OK, so you think you want to use the --enable-devel configure option? You must keep in mind that this option is intended only for development purposes; it is not recommended for use in production builds or packages. If you are using a proftpd installed from a package, try this command: 

  $ /usr/local/sbin/proftpd -V
if you see "+ Developer support" in the output, it means that your package provider used the --enable-devel option when they should not have. Let the package provider know about this, and point them to this document.

Still here? If so, you are ready to learn how --enable-devel is used for development and debugging. The --enable-devel option, like many of ProFTPD's configure options, takes a colon-delimited list of option names. The full list of supported developer options is shown here: 

  $ ./configure --enable-devel=coredump:nodaemon:nofork:profile:stacktrace ...
You can also use just --enable-devel by itself, without any specific option names: 
  $ ./configure --enable-devel ...
When --enable-devel is used, the executables that are installed by the ProFTPD build system will not be stripped of their debugging symbols, as is usually done in non-developer builds.

Let's look at what each one of these developer options does.

Enabling coredumps using the coredump option is a bad idea. ProFTPD goes out of its way to ensure that it does not generate coredump files. Since the proftpd server is usually run with root privileges (in order to use port 21, look up passwords, etc), any coredump files generated could possibly contain sensitive information (such as users' passwords). The only people who should be looking at coredump files are developers, and even then there are better ways of debugging issues. Note that if the coredump option is used, proftpd will not switch the UID/GID to the User/Group defined in the config file, nor to that of the logged-in user. Unix kernels are notoriously picky about generating coredumps for processes that have changed their effective UID/GID; they won't do it. Thus the ID switching is disabled in order to make it possible to get a coredump. Again, it is a bad idea to run a proftpd built with coredump in production.

The nodaemon option makes it such that the proftpd server cannot daemonize. It cannot detach from the terminal, and cannot run in the background. This is mostly useful for running proftpd under a debugger such as gdb.

The nofork option makes a proftpd that cannot use the fork(2) system call to create a new process to handle the client connection, turning proftpd into a single-process server. Like the nodaemon option, this is useful mainly for running proftpd under a debugger.

The profile option causes a profiling library to be linked into the compiled proftpd executable. Running the executable will then automatically write out profiling information suitable for use by a profiler such as gprof.

Finally, there is the stacktrace option. It is possible, if the GNU C library is used, to have a program automatically provide a stack trace showing the function call stack, such as when the SIGSEGV signal is received (i.e. the program segfaulted). Often times when debugging issues like segfaults, the hardest part is pinpointing the exact source of the segfault, and what functions were called to reach that point. Thus seeing a stack trace (also called a "backtrace") is quite useful for developers.

Let's say you configured the build for stacktrace support: 

  $ ./configure --enable-devel=stacktrace ...
If/when a SIGSEGV occurs, the logs should show something like this: 
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - ProFTPD terminating (signal 11)
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - FTP session closed.
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - -----BEGIN STACK TRACE-----
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - [0] ./proftpd [0x809b1e1]
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - [1] ./proftpd(call_module+0x53) [0x8072c63]
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - [2] ./proftpd(strftime+0x14cf) [0x8051bef]
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - [3] ./proftpd(pr_cmd_dispatch+0x167) [0x8051f2f]
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - [4] ./proftpd(strftime+0x1fd3) [0x80526f3]
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - [5] ./proftpd [0x8053e12]
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - [6] ./proftpd [0x805484d]
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - [7] ./proftpd [0x8057975]
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - [8] ./proftpd(main+0x9d1) [0x8058625]
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - [9] /lib/i686/libc.so.6(__libc_start_main+0x93) [0x40076507]
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - [10] ./proftpd(strcpy+0x31) [0x8051001]
  golem.castaglia.org (127.0.0.1[127.0.0.1]) - -----END STACK TRACE-----
These function call symbols or "frames" are generated automatically by the C library; the hexadecimal numbers are memory addresses.

The key for tracking down the location of the segfault is the first frame; in this case, "[0] ./proftpd [0x809b1e1]" and the memory address 0x809b1e1. Using the addr2line command (which you may need to install separately on your system) and that memory address, you can determine the location of the segfault source: 

  $ addr2line -e /usr/local/sbin/proftpd 0x809b1e1
In this particular case, I saw: 
  $ addr2line -e /usr/local/sbin/proftpd 0x809b1e1
  /home/tj/proftpd/cvs/proftpd/modules/mod_auth.c:1723
which is the location of test code I added to deliberately trigger a segfault.

There are some other noteworthy requirements for this automatic stacktrace support. First, each proftpd binary can be subtly different, depending on the exact configure command, shared modules loaded, etc. Thus the addr2line command must be run on the same system as the segfaulting proftpd binary, and must be run on that same binary. Using the memory address and addr2line on a different proftpd, or on a different system, will not work. Second, using the stacktrace developer option disables the changing of the process title that proftpd normally does. The obtaining of the stack symbols that is done uses the process title, and if the stacktrace option did not disable that process title changing, the output would be much less legible. The automatic stacktrace code in the C library will not work if the process has been chrooted (i.e. you use the DefaultRoot and/or <Anonymous> directives); I suspect this has to do with hardcoded assumptions in the C library itself which are broken in a chrooted process. Finally, use of the -fomit-frame-pointer compiler option will cause the stacktrace feature to not work; those omitted frame pointers contain exactly the frame symbols/addresses that we want to capture.

The stacktrace feature is known to work on Linux platform. On FreeBSD, you need to install the libexecinfo library from the Ports collection. On Mac OSX, you must be running 10.5 in order to have the proper C library support.

Frequently Asked Questions

Question: Why do I get a configure error about a "duplicate build request", like this: 

  checking checking for duplicate module requests... yes
  configure: error: duplicate build request for mod_delay -- aborting
Answer: This happens when your --with-modules list contains one of the automatically included modules (see above). In this example, the mod_delay module appeared in the --with-modules list.

Note that older releases of ProFTPD did not check for these types of "duplicate build requests". If you are having problems with your proftpd and you see the same module appear multiple times in the output from running: 

  $ /usr/local/sbin/proftpd -l
Then you should re-configure and re-compile your proftpd, making sure that no automatically included modules appear in your --with-modules configure option.

Question: Why do I get a configure error like this: 

  configure: error: source file './modules/d_auth_pam.c' cannot be found -- aborting
Answer: Notice how the name of the module reported there is "d_auth_pam.c", rather than "mod_auth_pam.c"? If you see a mangled module name like this, it probably means that your --with-modules or --with-shared module lists contain a double colon, e.g.: 
  $ ./configure --with-modules=mod_sql::mod_sql_mysql:...
or: 
  $ ./configure --with-shared=mod_sql::mod_sql_mysql:...
Use only a single colon between module names; this should fix this error.

Question: I installed ProFTPD, and encountered this error when trying to use ftptop: 

  $ ftptop
  ftptop: no curses or ncurses library on this system
So I installed the ncurses library on my system, and compiled ProFTPD again. But the error still occurs! Why?
Answer: The ProFTPD build system discovers the libraries it needs, like curses or ncurses, as part of the running of the configure command; the results of those discoveries are recorded in the generated config.h (and other) files.

This means that if you install a needed library after building ProFTPD, you need to re-run configure, make, etc in order for ProFTPD to discover that new library and use it: 

  $ cd /path/to/proftpd/
  $ make clean
  $ ./configure ...
  $ make
  $ make install
The "make clean" step is necessary, to clean up any leftover state from the previous build.

Question: I can't seem to compile mod_tls and mod_sql. Using one or the other works (i.e. shows up in the `proftpd -l` list), but not both. I'm using the following configure command: 

  $ ./configure --with-modules=mod_tls --with-modules=mod_sql:mod_sql_mysql ...
Answer: The problem is that the --with-modules option cannot appear multiple times in the configure command. If it does, only the last one seen on the command line wins. In this case, the user would need to put all of the desired modules into one colon-delimited list, e.g.: 
  $ make clean
  $ ./configure --with-modules=mod_tls:mod_sql:mod_sql_mysql ...
And keep in mind that the same restriction holds true for the --with-includes and --with-libraries options.

Question: I try to start my proftpd, but I get this error: 

  warning: the mod_sql_mysql module has not been properly initialized.  Please
  make sure your --with-modules configure option lists mod_sql *before*
  mod_sql_mysql, and recompile.
Answer: The issue here is that the mod_sql family of modules (including mod_sql_mysql, mod_sql_postgres, mod_sql_odbc, and mod_sql_sqlite) is rather particular about the order in which they appear in the --with-modules list. The ordering affects the order in which the modules are loaded when proftpd starts up. The above error, for example, happens when --with-modules looks like: 
  $ ./configure --with-modules=mod_sql_mysql:mod_sql (wrong)
but the mod_sql module needs to be loaded first, so that later, when mod_sql_mysql loads, the expected mod_sql code is present. Thus the proper ordering is to make sure that mod_sql appears before any of the database-specific backend modules: 
  $ ./configure --with-modules=mod_sql:mod_sql_mysql (correct)

Note that this ordering issue occurs for the mod_quotatab and mod_wrap2 families of modules as well.

Question: Why do I get a "Controls support required" error when I try to compile proftpd? 

  mod_ctrls.c:49:3: #error "Controls support required (use --enable-ctrls)"
Answer: The error is trying to tell you that that module (the mod_ctrls module, in this case) requires Controls support, and that you need to supply the --enable-ctrls option in your configure command when compiling proftpd.

Question: How do I get a statically linked proftpd binary?
Answer: To do this, using the following: 

  $ make clean
  $ ./configure LDFLAGS="-Wl,-static" ...
Do not try to use the "-static" value for the CFLAGS or LDFLAGS environment variables, or try to edit the Make.rules file to tweak the options. ProFTPD's build system uses libtool, and thus the above method is the way to get a statically linked proftpd executable: 
  $ make
  $ ldd ./proftpd
    not a dynamic executable

Question: I have a very long line in my proftpd.conf, and when I try to start proftpd I see this: 

  warning: handling possibly truncated configuration data at line 17 of '/etc/proftpd.conf'
  Fatal: unknown configuration directive ')"' on line 18 of '/etc/proftpd.conf'
How can I avoid this error?
Answer: If possible, you should try to break up your long directive line into multiple lines, using a backslash. For example: 
  Allow 1.2.3.4 5.6.7.8 9.10.11.12
can also appear as: 
  Allow \
    1.2.3.4 \
    5.6.7.8 \
    9.10.11.12
However, if this approach cannot be used (e.g. your configuration has a single parameter which exceeds the 1024 byte buffer limit, and which cannot be broken up), then you will have to recompile proftpd with a larger buffer size. To do this, use the --enable-buffer-size configure option, e.g.: 
  $ ./configure --enable-buffer-size=2048 ...

Question: What is the difference between the --enable-shadow and the --enable-autoshadow configure options, and when do I use them?
Answer: The --enable-shadow configure option enables support for shadow files, e.g. /etc/shadow and the related C library functions. On other Unix platforms, though, use "transparent shadow" support, where the normal C library functions are used; only when root privileges are used to call those functions will the actual password be obtained from the shadow files. Support for this approach is enabled by the --enable-autoshadow option.

If you are not sure which to use, try using both --enable-shadow and --enable-autoshadow.

Question: Why can't I compile ProFTPD from source using directory names that contain spaces?

  $ cd /path/to/ProFTPD Source/
  $ ./configure ...

  configure: WARNING: Libtool does not cope well with whitespace in `pwd`
Answer: Unfortunately, the autoconf and libtool tools do not work with such directory names. The solution is to rename the directories, to names that do not have whitespace in them.

© Copyright 2017-2020 The ProFTPD Project
All Rights Reserved