/usr/share/doc/proftpd-doc/howto/Compiling.html

<!-- $Id: Compiling.html,v 1.10 2013-10-06 16:02:23 castaglia Exp $ -->
<!-- $Source: /home/proftpd-core/backup/proftp-cvsroot/proftpd/doc/howto/Compiling.html,v $ -->

<html>
<head>
<title>ProFTPD mini-HOWTO - Compiling ProFTPD</title>
</head>

<body bgcolor=white>

<hr>
<center><h2><b>Compiling ProFTPD</b></h2></center>
<hr>

<p>
The ProFTPD source code is designed to be configured for compilation on the
target system by a single shell script, named <code>configure</code>, located
in the top-level directory of the source distribution, <i>e.g.</i>:
<pre>
  # cd proftpd-<i>version</i>/
  # ls -al configure
  -rwxr--r--    1 tj       tj        1155157 Nov 18 19:54 configure
</pre>
This <code>configure</code> script, generated by the GNU <code>autoconf</code>
tool, will analyze your system and create a <code>config.h</code> file that
should allow ProFTPD to compile cleanly.

<p>
ProFTPD is designed to be very flexible, which necessarily leads to extra
compile-time and run-time configuration complexity.  The <code>configure</code>
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.

<p>
In addition to the <code>config.h</code> file generated by the
<code>configure</code> script, the file <code>include/options.h</code>:
<pre>
  # cd proftpd-<i>version</i>/
  # ls -al include/options.h
  -rw-r--r--    1 tj       tj           7212 Nov 15 14:34 include/options.h
</pre>
contains a number of easily tweakable compile-time options which will affect
ProFTPD's operation.  These options are never modified by the
<code>configure</code> script.  Changing these values is rarely needed, and
most can be overriden at run-time by directives in the
<code>proftpd.conf</code> configuration file.

<p>
To see the full list of command-line options for <code>configure</code>, run:
<pre>
  # ./configure --help
</pre>
Should you change your mind about which options to use, you will need to
re-run <code>configure</code> with the new options.  But first you will
need to clean up the previous results by doing:
<pre>
  # make clean
  # ./configure ...
</pre>
The rest of this document covers the various options of the
<code>configure</code> script in detail.

<p>
When you run the <code>configure</code> script by itself, without any
command-line options, you will get the defaults:
<pre>
  # cd proftpd-<i>version</i>/
  # ./configure
</pre>
What are the defaults?

<p>
<b>Layout Options</b><br>
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
<code>/usr/local/</code> directory.  The <code>/usr/local/</code>
directory functions as the default <i>prefix directory</i>.  Thus the
layout of installed files will look like:
<pre>
  <i>/usr/local</i>/bin/ftpcount
  <i>/usr/local</i>/bin/ftpdcount
  <i>/usr/local</i>/bin/ftptop
  <i>/usr/local</i>/bin/ftpwho
  <i>/usr/local</i>/bin/prxs
  <i>/usr/local</i>/etc/proftpd.conf
  <i>/usr/local</i>/include/proftpd/*.h
  <i>/usr/local</i>/lib/pkgconfig/proftpd.pc
  <i>/usr/local</i>/libexec/*.{a,la,so}
  <i>/usr/local</i>/sbin/ftpshut
  <i>/usr/local</i>/sbin/in.proftpd
  <i>/usr/local</i>/sbin/proftpd
  <i>/usr/local</i>/share/locale/<i>lang</i>/LC_MESSAGES/proftpd.mo
  <i>/usr/local</i>/share/man/man1/ftpcount.1
  <i>/usr/local</i>/share/man/man1/ftptop.1
  <i>/usr/local</i>/share/man/man1/ftpwho.1
  <i>/usr/local</i>/share/man/man5/xferlog.5
  <i>/usr/local</i>/share/man/man8/ftpdctl.8
  <i>/usr/local</i>/share/man/man8/ftpshut.8
  <i>/usr/local</i>/share/man/man8/proftpd.8
  <i>/usr/local</i>/var/proftpd/*
</pre>
To place all of these files under the <code>/usr/</code> directory rather
than <code>/usr/local/</code>, you would change the prefix directory using
the <code>--prefix</code> option:
<pre>
  # ./configure --prefix=/usr
</pre>

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

<p>
<table>
  <tr>
    <td><code>--bindir</code></td>
    <td>Change <code><i>prefix-dir</i>/bin/</code></td>
  </tr>

  <tr>
    <td><code>--libexecdir</code></td>
    <td>Change <code><i>prefix-dir</i>/libexec/</code></td>
  </tr>

  <tr>
    <td><code>--localstatedir</code></td>
    <td>Change <code><i>prefix-dir</i>/var/</code></td>
  </tr>

  <tr>
    <td><code>--sbindir</code></td>
    <td>Change <code><i>prefix-dir</i>/sbin/</code></td>
  </tr>

  <tr>
    <td><code>--sysconfdir</code></td>
    <td>Change <code><i>prefix-dir</i>/etc/</code></td>
  </tr>
</table>

<p>
Thus to place the configuration file in <code>/etc/</code> and the runtime
state files in <code>/var/proftpd/</code>, you would use:
<pre>
  # ./configure --sysconfdir=/etc --localstatedir=/var/proftpd
</pre>

<p><a name="InstallerOptions">
<b>Installer Options</b><br>
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 <code>/usr/local/</code> directory.

<p>
If you wish to <i>install</i> using a different user or group ownership, set the
<code>install_user</code> and <code>install_group</code> environment variables
before running <code>configure</code>.  Using a Bourne-ish style shell
(<i>e.g.</i> sh, ksh, bash), you can do this on the command line like this:
<pre>
  # install_user=root install_group=wheel ./configure
</pre>

<p>
For example, I do a lot of personal ProFTPD builds, and so I typically use:
<pre>
  # install_user=tj install_group=tj ./configure --prefix=/home/tj/proftpd/devel/build/ ...
</pre>
Note that the <code>install_user</code> and <code>install_group</code>
environment variables do <b>not</b> affect the IDs used when <i>running</i>
<code>proftpd</code>.

<p><a name="FeatureOptions">
<b>Feature Options</b><br>
There are some features which are part of the core <code>proftpd</code> engine
itself which can be configured via compile-time options.  The list below talks
about the more common of these feature options:
<ul>
  <li><code>--disable-auth-file</code><br>
    The <a href="../modules/mod_auth_file.html"><code>mod_auth_file</code></a>
    module is included in the build by default; use this option to <b>not</b>
    include the module.
  </li>

  <p>
  <li><code>--enable-autoshadow</code><br>
    Enables support for <i>autoshadow</i>
  </li>

  <p>
  <li><code>--enable-ctrls</code><br>
    Enables support for the <a href="Controls.html">Controls</a> feature; this
    is not enabled by default.
  </li>

  <p>
  <li><code>--enable-dso</code><br>
    Enables support for <a href="DSO.html">DSO</a> modules (also called "shared
    modules") by including the
    <a href="../modules/mod_dso.html"><code>mod_dso</code></a> module in the
    build.  This is not enabled by default.
  </li>

  <p>
  <li><code>--enable-facl</code><br>
    Enables support for POSX ACLs, which is not enabled by default.  Note that
    the related <a href="../modules/mod_facl.html"><code>mod_facl</code></a>
    module must be added <b>separately</b> to the build, using
    <code>--with-modules</code>.
  </li>

  <p>
  <li><code>--disable-ident</code><br>
    Disables support for IDENT
    (<a href="http://www.faqs.org/rfcs/rfc1413.html">RFC1413</a>) lookups by
    not adding the <a href="../modules/mod_ident.html"><code>mod_ident</code></a>
     module to the build.  This module is added by default.
  </li>

  <p>
  <li><code>--disable-ipv6</code><br>
    Disables IPv6 support, which is enabled by default.  Note that IPv6 support
    can be disabled <i>at run-time</i> using the <code>UseIPv6</code> directive
    in your <code>proftpd.conf</code> file.
  </li>

  <p>
  <li><code>--enable-memcache</code><br>
    Enables support for using <a href="http://memcached.org/"><code>memcached</code></a> for caching by including the
    <a href="../modules/mod_memcache.html"><code>mod_memcache</code></a>
    module in the build.  This is not enabled by default.
  </li>

  <p>
  <li><code>--enable-nls</code><br>
    Enables support for different character sets and encodings, for translated
    response messages, and for the <code>LANG</code> FTP command via the
    <a href="../modules/mod_lang.html"><code>mod_lang</code></a> module.  This
    is not enabled by default.
  </li>

  <p>
  <li><code>--enable-pcre</code><br>
    Enable use of <a href="http://www.pcre.org/">PCRE</a> for POSIX regular
    expressions, rather than the system library.  This is not enabled by
    default.  Note that pcre-7.0 or later is <b>required</b>.
  </li>

  <p>
  <li><code>--disable-sendfile</code><br>
    Disables support for the <code>sendfile(2)</code> function, which is
    enabled by default.  Read <a href="Sendfile.html">here</a> for information
    on when and why this is a Good Thing to do.
  </li>

  <p>
  <li><code>--enable-devel</code><br>
    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 <a href="#DeveloperOptions">below</a>; suffice to
    say that unless you <i>really</i> know what you are doing, you should
    <b>not</b> be using this option in your configure command.
  </li>

  <p>
  <li>--with-lastlog</code><em>=/path/to/lastlog</em><br>
    Enables support for lastlog logging; see the <code>lastlog(8)</code>
    man page.  The optional <em>/path/to/lastlog</em> 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
    <code>UseLastlog</code> configuration directive at runtime.
    This feature is not enabled by default.
  </li>

</ul>
<p>
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.

<p><a name="ModuleOptions">
<b>Module Options</b><br>
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 <i>automatically</i> included in the build:
<ul>
  <li><code>mod_core.c</code>
  <li><code>mod_xfer.c</code>
  <li><code>mod_auth_unix.c</code>
  <li><code>mod_auth.c</code>
  <li><code>mod_ls.c</code>
  <li><code>mod_log.c</code>
  <li><code>mod_site.c</code>
  <li><code>mod_delay.c</code>
  <li><code>mod_facts.c</code>
</ul>
In addition to these modules, there are some modules which <i>may</i> be
automatically added, depending on your system:
<ul>
  <li><a href="../modules/mod_auth_file.html"><code>mod_auth_file.c</code></a><br>
    This module is automatically added <i>unless</i> <code>--disable-auth-file</code> is used
  </li>

  <p>
  <li><a href="../modules/mod_auth_pam.html"><code>mod_auth_pam.c</code></a><br>
    This module is automatically added if PAM support is detected
  </li>

  <p>
  <li><a href="../modules/mod_cap.html"><code>mod_cap.c</code></a><br>
    This module is automatically added if Linux capabilities support is
    detected
  </li>

  <p>
  <li><a href="../modules/mod_ident.html"><code>mod_cap.c</code></a><br>
    This module is automatically added <i>unless</i> <code>--disable-ident</code> is used
  </li>
</ul>

<p>
The above modules all live under the <code>modules/</code> directory in
the source distribution.  So what modules are left to choose from?  All
of the modules under the
<a href="../contrib/index.html"><code>contrib/</code></a> directory.

<p>
Optional ProFTPD modules are added to the build using the 
<code>--with-modules</code> 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 <code>proftpd</code>, you
would list the appropriate modules in the <code>--with-modules</code> list:
<pre>
  # ./configure --with-modules=mod_ldap:mod_tls ...
</pre>
Do <b>not</b> include the names of any modules under the <code>modules/</code>
directory; the modules there are either mandatory or conditional.  Attempting
to include a non-optional module in the <code>--with-modules</code> list
will result in a configure error.

<p>
The <code>--with-shared</code> option works much like
<code>--with-modules</code>.  You provide a colon-delimited list of names
of modules to be compiled as shared modules.  Note that using the
<code>--with-shared</code> option <b>requires</b> the use of
<code>--enable-dso</code>.  Thus to add LDAP and SSL/TLS support as
shared modules, you would use:
<pre>
  # ./configure --enable-dso --with-shared=mod_ldap:mod_tls ...
</pre>
Failure to include the <code>--enable-dso</code> option when using
<code>--with-shared</code> results in a configure error:
<pre>
  configure: error: cannot build shared modules without DSO support -- aborting
</pre>

<p>
You can add <i>some</i> of the automatically included modules as shared
modules, but not all of them.  The following automatically included modules
<b>cannot</b> be compiled as shared/DSO modules:
<ul>
  <li><code>mod_auth.c</code>
  <li><code>mod_auth_unix.c</code>
  <li><code>mod_core.c</code>
  <li><code>mod_ls.c</code>
  <li><code>mod_xfer.c</code>
</ul>
If your <code>--with-shared</code> list includes one of the above modules,
it will result in a configure error:
<pre>
  # ./configure --enable-dso --with-shared=mod_auth_unix ...
  configure: error: cannot build mod_auth_unix as a shared module
</pre>
Why can't these be shared modules?  These modules <b>must</b> appear in the
<code>proftpd</code> binary in order for it to function as a proper FTP server.
Yes, even <code>mod_auth_unix.c</code>; it is the default/fallback mechanism
for obtaining user/group names/IDs.

<p>
Do <b>not</b> use <code>--with-modules</code> or <code>--with-shared</code>
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.

<p><a name="HeaderLibOptions">
<b>Header and Library Options</b><br>
The <code>--with-includes</code> 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 <code>--with-libraries</code> 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.

<p>
For example, on Solaris, you have to explicitly tell the compiler and linker
to use the <code>/usr/local/include</code> and <code>/usr/local/lib</code>
directories:
<pre>
  # ./configure --with-includes=/usr/local/include --with-libraries=/usr/local/lib ...
</pre>

<p>
Or you may have the MySQL or OpenSSL packages installed in custom locations,
and you need to tell <code>configure</code> about those locations:
<pre>
  # ./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
</pre>
These options are commonly used to specify the locations for LDAP, OpenSSL,
database, and other software packages used by modules.

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

<p>
<b>Environment Variables</b><br>
As with most other GNU autoconf-based build system, the ProFTPD
<code>configure</code> script honors these environment variables:
<ul>
  <li>CPPFLAGS
  <li>CFLAGS
  <li>DESTDIR
  <li>LDFLAGS
  <li>LIBS
</ul>
Use of these environment variables is for the more advanced users, system
administrators, and software developers and packagersl who know the environment
variable semantics.

<p>
<b>Putting It All Together</b><br>
Now, let's configure the build system for a <code>proftpd</code> that
does not include IDENT support, is installed under <code>/opt/proftpd/</code>
as user and group 'ftpd', has staticly linked SSL/TLS support and dynamically
loaded SQL backend modules:
<pre>
  # 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
</pre>
Hint: if your configure command becomes long or complicated, you might try
storing it in a <code>sh</code> script file, say 'proftpd-conf.sh'.

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

<p>
<b>Compiling</b><br>
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:
<pre>
  # cd proftpd-<i>version</i>/
  # make
</pre>
On some systems (<i>e.g.</i> BSDI), you may need to use GNU <code>make</code>
(often called <code>gmake</code> or <code>gnumake</code>) instead of the
default system <code>make</code>.  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.

<p>
If you are interested in testing the compiled executables, read
this <a href="Testing.html">howto</a> about the testsuite that comes with
the ProFTPD source code.

<p>
To install the compiled executables, use:
<pre>
  # cd proftpd-<i>version</i>/
  # make install
</pre>
You are now prepared to start up and use your compiled <code>proftpd</code>.

<p><a name="DeveloperOptions">
<b>Developer Options</b><br>
OK, so you think you want to use the <code>--enable-devel</code> configure
option?  You must keep in mind that this option is intended only for
development purposes; it is <b>not recommended for use in production
builds or packages</b>.  If you are using a <code>proftpd</code> installed
from a package, try this command:
<pre>
  # /usr/local/sbin/proftpd -V
</pre>
if you see "+ Developer support" in the output, it means that your
package provider used the <code>--enable-devel</code> option when they
should not have.  Let the package provider know about this, and point them
to this document.

<p>
Still here?  If so, you are ready to learn how <code>--enable-devel</code>
is used for development and debugging.  The <code>--enable-devel</code>
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:
<pre>
  # ./configure --enable-devel=coredump:nodaemon:nofork:profile:stacktrace ...
</pre>
You can also use just <code>--enable-devel</code> by itself, without any
specific option names:
<pre>
  # ./configure --enable-devel ...
</pre>
When <code>--enable-devel</code> 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.

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

<p>
Enabling coredumps using the <code>coredump</code> option is a <b>bad idea</b>.
ProFTPD goes out of its way to ensure that it does <b>not</b> generate coredump
files.  Since the <code>proftpd</code> server is usually run with root
privileges (in order to use port 21, look up passwords, <i>etc</i>), 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.
<b>Note</b> that if the <code>coredump</code> option is used, proftpd will
<b>not</b> switch the UID/GID to the <code>User</code>/<code>Group</code>
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 <b>bad idea</b> to run a proftpd built with <code>coredump</code> in
production.

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

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

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

<p>
Finally, there is the <code>stacktrace</code> 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 <code>SIGSEGV</code> signal
is received (<i>i.e.</i> 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.

<p>
Let's say you configured the build for stacktrace support:
<pre>
  # ./configure --enable-devel=stacktrace ...
</pre>
If/when a SIGSEGV occurs, the logs should show something like this:
<pre>
  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-----
</pre>
These function call symbols or "frames" are generated automatically by the C
library; the hexadecimal numbers are memory addresses.

<p>
The key for tracking down the location of the segfault is the <i>first</i>
frame; in this case, "[0] ./proftpd [0x809b1e1]" and the memory address
0x809b1e1.  Using the <code>addr2line</code> command (which you may need to
install separately on your system) and that memory address, you can determine
the location of the segfault source:
<pre>
  # addr2line -e /usr/local/sbin/proftpd 0x809b1e1
</pre>
In this particular case, I saw:
<pre>
  # addr2line -e /usr/local/sbin/proftpd 0x809b1e1
  /home/tj/proftpd/cvs/proftpd/modules/mod_auth.c:1723
</pre>
which is the location of test code I added to deliberately trigger a segfault.

<p>
There are some other noteworthy requirements for this automatic stacktrace
support.  First, each <code>proftpd</code> binary can be subtly different,
depending on the exact configure command, shared modules loaded, <i>etc</i>.
Thus the <code>addr2line</code> command <b>must</b> be run on the same
system as the segfaulting <code>proftpd</code> binary, and must be run on
that same binary.  Using the memory address and <code>addr2line</code>
on a different <code>proftpd</code>, or on a different system, will not
work.  Second, using the <code>stacktrace</code> developer option disables
the changing of the process title that <code>proftpd</code> normally does.
The obtaining of the stack symbols that is done uses the process title, and if
the <code>stacktrace</code> 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>i.e.</i>
you use the <code>DefaultRoot</code> and/or <code>&lt;Anonymous&gt;</code>
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 <code>-fomit-frame-pointer</code> 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.

<p>
The <code>stacktrace</code> 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.

<p><a name="FAQ">
<b>Frequently Asked Questions</b><br>

<p>
<font color=red>Question</font>: Why do I get a configure error about a
"duplicate build request", like this:
<pre>
  checking checking for duplicate module requests... yes
  configure: error: duplicate build request for mod_delay -- aborting
</pre>
<font color=blue>Answer</font>:  This happens when your
<code>--with-modules</code> list contains one of the automatically included
modules (see <a href="#ModuleOptions">above</a>).  In this example, the
<code>mod_delay</code> module appeared in the <code>--with-modules</code>
list.

<p>
Note that older releases of ProFTPD did not check for these types of
"duplicate build requests".  If you are having problems with your
<code>proftpd</code> and you see the same module appear multiple times in
the output from running:
<pre>
  # /usr/local/sbin/proftpd -l
</pre>
Then you should re-configure and re-compile your <code>proftpd</code>, making
sure that no automatically included modules appear in your
<code>--with-modules</code> configure option.

<p>
<font color=red>Question</font>: Why do I get a configure error like this:
<pre>
  configure: error: source file './modules/d_auth_pam.c' cannot be found -- aborting
</pre>
<font color=blue>Answer</font>: 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 <code>--with-modules</code>
or <code>--with-shared</code> module lists contain a double colon, <i>e.g.</i>:
<pre>
  # ./configure --with-modules=mod_sql<b>::</b>mod_sql_mysql:...
</pre>
or:
<pre>
  # ./configure --with-shared=mod_sql<b>::</b>mod_sql_mysql:...
</pre>
<i>Use only a single colon between module names</i>; this should fix this error.

<p>
<font color=red>Question</font>: I can't seem to compile <code>mod_tls</code>
<b>and</b> <code>mod_sql</code>.  Using one or the other works (<i>i.e.</i>
shows up in the <code>`proftpd -l`</code> list), but not both.  I'm using the
following configure command:
<pre>
  # ./configure --with-modules=mod_tls --with-modules=mod_sql:mod_sql_mysql ...
</pre>
<font color=blue>Answer</font>: The problem is that the
<code>--with-modules</code> 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 <b>one</b> colon-delimited list, <i>e.g.</i>:
<pre>
  # make clean
  # ./configure --with-modules=mod_tls:mod_sql:mod_sql_mysql ...
</pre>
And keep in mind that the same restriction holds true for the
<code>--with-includes</code> and <code>--with-libraries</code> options.

<p>
<font color=red>Question</font>: I try to start my <code>proftpd</code>,
but I get this error:
<pre>
  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.
</pre>
<font color=blue>Answer</font>: The issue here is that the
<a href="../contrib/mod_sql.html"><code>mod_sql</code></a> family of modules
(including <code>mod_sql_mysql</code>, <code>mod_sql_postgres</code>,
<code>mod_sql_odbc</code>, and <code>mod_sql_sqlite</code>) is rather
particular about the order in which they appear in the
<code>--with-modules</code> list.  The ordering affects the order in which
the modules are loaded when <code>proftpd</code> starts up.  The above
error, for example, happens when <code>--with-modules</code> looks like:
<pre>
  # ./configure --with-modules=mod_sql_mysql:<b>mod_sql</b> (<i><font color=red>wrong</font></i>)
</pre>
but the <code>mod_sql</code> module needs to be loaded first, so that later,
when <code>mod_sql_mysql</code> loads, the expected <code>mod_sql</code>
code is present.  Thus the proper ordering is to make sure that
<code>mod_sql</code> appears <i>before</i> any of the database-specific
backend modules:
<pre>
  # ./configure --with-modules=<b>mod_sql</b>:mod_sql_mysql (<i><font color=green>correct</font></i>)
</pre>

<p>
Note that this ordering issue occurs for the
<a href="../contrib/mod_quotatab.html"><code>mod_quotatab</code></a> and
<a href="../contrib/mod_wrap2.html"><code>mod_wrap2</code></a> families of
modules as well.

<p>
<font color=red>Question</font>: Why do I get a "Controls support required"
error when I try to compile <code>proftpd</code>?
<pre>
  mod_ctrls.c:49:3: #error "Controls support required (use --enable-ctrls)"
</pre>
<font color=blue>Answer</font>: The error is trying to tell you that that
module (the <a href="../modules/mod_ctrls.html"><code>mod_ctrls</code></a>
module, in this case) requires <a href="Controls.html">Controls</a> support,
and that you need to supply the <code>--enable-ctrls</code> option in
your configure command when compiling <code>proftpd</code>.

<p>
<font color=red>Question</font>: How do I get a statically linked
<code>proftpd</code> binary?<br>
<font color=blue>Answer</font>: To do this, using the following:
<pre>
  # make clean
  # ./configure LDFLAGS="-Wl,-static" ...
</pre>
Do <b>not</b> 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 <code>proftpd</code> executable:
<pre>
  # make
  # ldd ./proftpd
    not a dynamic executable
</pre>

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

<p>
<font color=red>Question</font>: What is the difference between the
<code>--enable-shadow</code> and the <code>--enable-autoshadow</code> configure
options, and when do I use them?<br>
<font color=blue>Answer</font>:  The <code>--enable-shadow</code> configure
option enables support for <em>shadow</em> files,
<i>e.g.</i> <code>/etc/shadow</code> 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
<code>--enable-autoshadow</code> option.

<p>
If you are not sure which to use, try using both <code>--enable-shadow</code>
and <code>--enable-autoshadow</code>.

<p>
<hr>
<i>$Date: 2013-10-06 16:02:23 $</i><br>

</body>
</html>
proftpd-doc 1.3.5e-1build1 / usr / share / doc / proftpd-doc / howto / Compiling.html
