ProFTPD mini-HOWTO - Dynamic Shared Objects

Dynamic Shared Objects

What are DSOs?
DSOs (Dynamic Shared Objects) are specially built binary files that can be loaded by an application while it is running, extending the functionality of the application on-the-fly. One of the best known applications that makes use of DSOs is the Apache web server; see the Apache documentation for an in-depth description of DSOs:

  http://httpd.apache.org/docs/dso.html

DSOs and ProFTPD
ProFTPD gained the ability to use DSOs starting with the 1.3.0rc1 release. To make sure the compiled proftpd binary can load DSO modules, use the --enable-dso configure option:

  ./configure --enable-dso ...

This causes the build system to build the libltdl supporting library, which is used to handle OS-specific ways of loading and unloading DSO files, and also to include the mod_dso module in the compiled proftpd. The mod_dso module provides the LoadModule configuration directive, for loading modules via the proftpd.conf configuration file.

The contrib modules that are distributed with the ProFTPD source, e.g. mod_ldap, mod_sql, mod_quotatab, mod_ifsession, etc, can easily be built as DSO modules, rather than statically linked into the proftpd binary. Instead of using the normal --with-modules configure option, you use the --with-shared option:

  ./configure --enable-dso --with-shared=mod_sql:mod_sql_mysql --with-includes=... --with-libraries=...

These DSO modules will be installed under the libexec/ directory of your ProFTPD install location. To control the location of this libexec/ directory from which the mod_dso module will load modules, you can use the --libexecdir configure option, e.g.:

  ./configure --libexecdir=/path/to/custom/libexec --enable-dso ...

Note that ProFTPD uses the GNU libtool utility for creating shared modules. This tool creates files with .la file extensions. It is these .la files that will be installed into the libexec/ directory. This differs from the .so files that Apache's DSO support generates, so do not be surprised.

Loading Modules
There are two ways to load DSO modules into proftpd: the LoadModule configuration directive, and the insmod ftpdctl action. Note that the latter possibility is only available if your proftpd has been built with Controls support.

Loading a module using LoadModule is quite simple. Simply use the directive at the top of your proftpd.conf file, which makes sure the module is loaded by proftpd before it processes other directives:

  LoadModule mod_sql.c
  LoadModule mod_sql_mysql.c
  ...

  <IfModule mod_sql.c>
    ...
  </IfModule>

If a module fails to load properly, you might see messages like:

  Fatal: unknown configuration directive 'SQLConnectInfo' on line 86 of '/usr/local/proftpd/etc/proftpd.conf'

This can happen if you forget to use the LoadModule directive in your proftpd.conf prior to using directives from the module. If you are using LoadModule, the error message may look like:

  LoadModule: error loading module 'mod_sql_mysql.c': permission denied on line 65 of proftpd.conf

Check the libexec/ directory where you installed proftpd, to see if the appropriate .la and/or .so files are present. Then check your dynamic loader configuration file (e.g. /etc/ld.so.conf on Linux) and make sure that the libexec/ directory is configured, so that the dynamic loader knows to look in the correct locations. Note that the LD_LIBRARY_PATH and/or LD_RUN_PATH environment variables may also be used to inform the dynamic loader of proftpd's libexec/ directory.

Using ftpdctl insmod to load modules is tricky, as the loading of a module directly into the running proftpd, without restarting the server, can cause unexpected behavior. Many modules are not designed to handle being loaded directly, and may cause bugs or unexpected crashes. Support for this mode of loading modules will stabilize as the modules are updated properly.

Module Ordering
Is the order in which your LoadModule directives appear in proftpd.conf important? The short answer is: maybe. It depends on the modules. Some modules are self-sufficient, do not make use of any other modules, and so can appear in any orders. Others, like mod_sql_mysql or mod_quotatab_sql, require that the frontend module (e.g. mod_sql or mod_quotatab) be loaded first. Still others, like mod_ifsession, do not directly require other modules, yet they have effects that are dependent on the order; mod_ifsession works best when it is the last module loaded.

To achieve the necessary module order, you can make sure that your LoadModule directives appear in the correct order, or you can use the ModuleOrder directive. Note that using ModuleOrder can be difficult, as it is very easy to use ModuleOrder to configure a nonfunctional proftpd.

Compiling Custom Modules as DSOs
The --with-shared configure option can be used to build DSOs from the modules already distributed with ProFTPD, but what about building a custom ProFTPD module as a DSO? Right now, this requires the ProFTPD source, and not just an installed ProFTPD.

Once you have your custom module written (e.g. mod_custom.c), you create the Makefile that will be used to compile it as a DSO module. The following can be used as a template for the Makefile:

  PROFTPD_SRC=/path/to/proftpd
  PROFTPD_INSTALL=/usr/local/proftpd

  top_srcdir=$(PROFTPD_SRC)
  srcdir=$(PROFTPD_SRC)
  VPATH=$(PROFTPD_SRC)

  MODULE_NAME=
  MODULE_CFLAGS=
  MODULE_DEFS=
  MODULE_LDFLAGS=
  MODULE_LIBS=

  CC=gcc
  DEFS=-DPR_SHARED_MODULE $(MODULE_DEFS)
  CFLAGS=$(DEFS) -I. -I$(PROFTPD_SRC)/include -I$(PROFTPD_SRC) $(MODULE_CFLAGS)
  LDFLAGS=-L$(PROFTPD_SRC)/lib $(MODULE_LDFLAGS)
  LIBEXEC_DIR=$(PROFTPD_INSTALL)/libexec
  LIBS=$(MODULE_LIBS)

  INSTALL=/usr/bin/install -c
  INSTALL_USER=user
  INSTALL_GROUP=user
  INSTALL_BIN=$(INSTALL) -s -o $(INSTALL_USER) -g $(INSTALL_GROUP) -m 0755
  LIBTOOL=$(SHELL) $(PROFTPD_SRC)/libtool
  LTDL_FLAGS=-avoid-version -export-dynamic -module

  # Targets

  all: $(MODULE_NAME).la

  $(MODULE_NAME).lo:
          $(LIBTOOL) --mode=compile $(CC) $(CFLAGS) -c $(MODULE_NAME).c

  $(MODULE_NAME).la: $(MODULE_NAME).lo
          $(LIBTOOL) --mode=link $(CC) -o $(MODULE_NAME).la -rpath $(LIBEXEC_DIR) $(LDFLAGS) $(LTDL_FLAGS) $(MODULE_NAME).lo $(LIBS)

  install: $(MODULE_NAME).la
          $(LIBTOOL) --mode=install $(INSTALL_BIN) $(MODULE_NAME).la $(DESTDIR)$(LIBEXEC_DIR)

  clean:
          $(LIBTOOL) --mode=clean $(RM) $(MODULE_NAME).la
          $(LIBTOOL) --mode=clean $(RM) $(MODULE_NAME).lo
          $(RM) config.*

  distclean:
          $(RM) Makefile config.*
          $(RM) -r autom4te.cache

Fill in MODULE_NAME with the name of your module:

  MODULE_NAME=mod_custom

The remaining MODULE_ variables are used to specify additional compiler and linker flags. If, for example, your mod_custom.c module relied on a header file <custom.h> as well as a library libcustom.so, you might have the following:

  MODULE_CFLAGS=-I/path/to/custom/include
  MODULE_DEFS=-DUSE_LIBCUSTOM
  MODULE_LDFLAGS=-L/path/to/custom/lib
  MODULE_LIBS=-lcustom

Place the Makefile in a directory with your mod_custom.c source file, then do:

  make
  make install

The make install step will install the DSO module into the libexec/ directory of your ProFTPD install location. Note that you may need to tweak the INSTALL_USER and INSTALL_GROUP variables with the necessary user/group names for installing the DSO module.

Once installed, update your proftpd.conf to make sure your module is loaded:

  LoadModule mod_custom.c

Then restart proftpd, and your custom module will be in use.

$Date: 2006/06/12 16:03:33 $