ProFTPD mini-HOWTO - Compiling ProFTPD

## 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 overriden 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:

- `--disable-auth-file`
  The `mod_auth_file` module is included in the build by default; use this option to not include the module.

- `--enable-autoshadow`
  Enables support for autoshadow

- `--enable-ctrls`
  Enables support for the Controls feature; this is not enabled by default.

- `--enable-dso`
  Enables support for DSO modules (also called "shared modules") by including the `mod_dso` module in the build. This is not enabled by default.

- `--enable-facl`
  Enables support for POSX ACLs, which is not enabled by default. Note that the related `mod_facl` module must be added separately to the build, using `--with-modules`.

- `--disable-ident`
  Disables support for IDENT (RFC1413) lookups by not adding the `mod_ident` module to the build. This module is added by default.

- `--disable-ipv6`
  Disables IPv6 support, which is enabled by default. Note that IPv6 support can be disabled at run-time using the `UseIPv6` directive in your `proftpd.conf` file.

- `--enable-memcache`
  Enables support for using `memcached` for caching by including the `mod_memcache` module in the build. This is not enabled by default.

- `--enable-nls`
  Enables support for different character sets and encodings, for translated response messages, and for the `LANG` FTP command via the `mod_lang` module. This is not enabled by default.

- `--enable-pcre`
  Enable use of PCRE for POSIX regular expressions, rather than the system library. This is not enabled by default. Note that pcre-7.0 or later is required.

- `--disable-sendfile`
  Disables support for the `sendfile(2)` function, which is enabled by default. Read here for information on when and why this is a Good Thing to do.

- `--enable-devel`
  Enables code/behavior that is specifically used by developers and maintainers; this code is disabled by default. The uses for this option are covered more fully below; suffice to say that unless you really know what you are doing, you should not be using this option in your configure command.

- --with-lastlog=/path/to/lastlog
  Enables support for lastlog logging; see the `lastlog(8)` man page. The optional /path/to/lastlog argument is only needed if your lastlog file location is not a standard location. Note that this configure option is needed in order to support the `UseLastlog` configuration directive at runtime. This feature is not enabled by default.

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:

- `mod_core.c`
- `mod_xfer.c`
- `mod_auth_unix.c`
- `mod_auth.c`
- `mod_ls.c`
- `mod_log.c`
- `mod_site.c`
- `mod_delay.c`
- `mod_facts.c`

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

- `mod_auth_file.c`
  This module is automatically added unless `--disable-auth-file` is used

- `mod_auth_pam.c`
  This module is automatically added if PAM support is detected

- `mod_cap.c`
  This module is automatically added if Linux capabilities support is detected

- `mod_cap.c`
  This module is automatically added unless `--disable-ident` is used

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 staticly 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:

- `mod_auth.c`
- `mod_auth_unix.c`
- `mod_core.c`
- `mod_ls.c`
- `mod_xfer.c`

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:

- CPPFLAGS
- CFLAGS
- DESTDIR
- LDFLAGS
- LIBS

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 staticly 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 usefuly 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 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 intialized.  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`.

$Date: 2013-10-06 16:02:23 $