<!-- $Id: DSO.html,v 1.5 2006/06/12 16:03:33 castaglia Exp $ --> <!-- $Source: /cvsroot/proftp/proftpd/doc/howto/DSO.html,v $ --> <html> <head> <title>ProFTPD mini-HOWTO - Dynamic Shared Objects</title> </head> <body bgcolor=white> <hr> <center><h2><b>Dynamic Shared Objects</b></h2></center> <hr> <p> <b>What are DSOs?</b><br> DSOs (<b>D</b>ynamic <b>S</b>hared <b>O</b>bjects) 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: <pre> <a href="http://httpd.apache.org/docs/dso.html">http://httpd.apache.org/docs/dso.html</a> </pre> <p> <b>DSOs and ProFTPD</b><br> ProFTPD gained the ability to use DSOs starting with the 1.3.0rc1 release. To make sure the compiled <code>proftpd</code> binary can load DSO modules, use the <code>--enable-dso</code> configure option: <pre> ./configure --enable-dso ... </pre> This causes the build system to build the <code>libltdl</code> supporting library, which is used to handle OS-specific ways of loading and unloading DSO files, and also to include the <a href="../../doc/modules/mod_dso.html"><code>mod_dso</code></a> module in the compiled <code>proftpd</code>. The <code>mod_dso</code> module provides the <code>LoadModule</code> configuration directive, for loading modules via the <code>proftpd.conf</code> configuration file. <p> The <code>contrib</code> modules that are distributed with the ProFTPD source, <i>e.g.</i> <code>mod_ldap</code>, <code>mod_sql</code>, <code>mod_quotatab</code>, <code>mod_ifsession</code>, <i>etc</i>, can easily be built as DSO modules, rather than statically linked into the <code>proftpd</code> binary. Instead of using the normal <code>--with-modules</code> configure option, you use the <code>--with-shared</code> option: <pre> ./configure --enable-dso --with-shared=mod_sql:mod_sql_mysql --with-includes=... --with-libraries=... </pre> These DSO modules will be installed under the <code>libexec/</code> directory of your ProFTPD install location. To control the location of this <code>libexec/</code> directory from which the <code>mod_dso</code> module will load modules, you can use the <code>--libexecdir</code> configure option, <i>e.g.</i>: <pre> ./configure --libexecdir=/path/to/custom/libexec --enable-dso ... </pre> <p> Note that ProFTPD uses the GNU <code>libtool</code> utility for creating shared modules. This tool creates files with <code>.la</code> file extensions. It is these <code>.la</code> files that will be installed into the <code>libexec/</code> directory. This differs from the <code>.so</code> files that Apache's DSO support generates, so do not be surprised. <p> <b>Loading Modules</b><br> There are two ways to load DSO modules into <code>proftpd</code>: the <a href="../../doc/modules/mod_dso.html#LoadModule"><code>LoadModule</code></a> configuration directive, and the <a href="../../doc/modules/mod_dso.html#insmod"><code>insmod</code></a> <code>ftpdctl</code> action. Note that the latter possibility is only available if your <code>proftpd</code> has been built with <a href="Controls.html">Controls</a> support. <p> Loading a module using <code>LoadModule</code> is quite simple. Simply use the directive at the top of your <code>proftpd.conf</code> file, which makes sure the module is loaded by <code>proftpd</code> before it processes other directives: <pre> LoadModule mod_sql.c LoadModule mod_sql_mysql.c ... <IfModule mod_sql.c> ... </IfModule> </pre> If a module fails to load properly, you might see messages like: <pre> Fatal: unknown configuration directive 'SQLConnectInfo' on line 86 of '/usr/local/proftpd/etc/proftpd.conf' </pre> This can happen if you forget to use the <code>LoadModule</code> directive in your <code>proftpd.conf</code> prior to using directives from the module. If you are using <code>LoadModule</code>, the error message may look like: <pre> LoadModule: error loading module 'mod_sql_mysql.c': permission denied on line 65 of proftpd.conf </pre> Check the <code>libexec/</code> directory where you installed <code>proftpd</code>, to see if the appropriate <code>.la</code> and/or <code>.so</code> files are present. Then check your dynamic loader configuration file (<i>e.g.</i> <code>/etc/ld.so.conf</code> on Linux) and make sure that the <code>libexec/</code> directory is configured, so that the dynamic loader knows to look in the correct locations. Note that the <code>LD_LIBRARY_PATH</code> and/or <code>LD_RUN_PATH</code> environment variables may also be used to inform the dynamic loader of <code>proftpd</code>'s <code>libexec/</code> directory. <p> Using <code>ftpdctl insmod</code> to load modules is tricky, as the loading of a module directly into the running <code>proftpd</code>, 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. <p> <b>Module Ordering</b><br> Is the order in which your <code>LoadModule</code> directives appear in <code>proftpd.conf</code> important? The short answer is: <em>maybe</em>. 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 <code>mod_sql_mysql</code> or <code>mod_quotatab_sql</code>, require that the frontend module (<i>e.g.</i> <code>mod_sql</code> or <code>mod_quotatab</code>) be loaded first. Still others, like <code>mod_ifsession</code>, do not directly require other modules, yet they have effects that are dependent on the order; <code>mod_ifsession</code> works best when it is the <b>last</b> module loaded. <p> To achieve the necessary module order, you can make sure that your <code>LoadModule</code> directives appear in the correct order, or you can use the <a href="../../doc/modules/mod_dso.html#ModuleOrder"><code>ModuleOrder</code></a> directive. Note that using <code>ModuleOrder</code> can be difficult, as it is very easy to use <code>ModuleOrder</code> to configure a nonfunctional <code>proftpd</code>. <p> <b>Compiling Custom Modules as DSOs</b><br> The <code>--with-shared</code> 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. <p> Once you have your custom module written (<i>e.g.</i> <code>mod_custom.c</code>), you create the <code>Makefile</code> that will be used to compile it as a DSO module. The following can be used as a template for the <code>Makefile</code>: <pre> 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 </pre> Fill in <code>MODULE_NAME</code> with the name of your module: <pre> MODULE_NAME=mod_custom </pre> The remaining <code>MODULE_</code> variables are used to specify additional compiler and linker flags. If, for example, your <code>mod_custom.c</code> module relied on a header file <code><custom.h></code> as well as a library <code>libcustom.so</code>, you might have the following: <pre> MODULE_CFLAGS=-I/path/to/custom/include MODULE_DEFS=-DUSE_LIBCUSTOM MODULE_LDFLAGS=-L/path/to/custom/lib MODULE_LIBS=-lcustom </pre> Place the <code>Makefile</code> in a directory with your <code>mod_custom.c</code> source file, then do: <pre> make make install </pre> The <code>make install</code> step will install the DSO module into the <code>libexec/</code> directory of your ProFTPD install location. Note that you may need to tweak the <code>INSTALL_USER</code> and <code>INSTALL_GROUP</code> variables with the necessary user/group names for installing the DSO module. <p> Once installed, update your <code>proftpd.conf</code> to make sure your module is loaded: <pre> LoadModule mod_custom.c </pre> Then restart <code>proftpd</code>, and your custom module will be in use. <p> <hr> <i>$Date: 2006/06/12 16:03:33 $</i><br> </body> </html>