<!-- $Id: mod_dso.html,v 1.2 2004/10/29 22:33:42 castaglia Exp $ --> <!-- $Source: /cvsroot/proftp/proftpd/doc/modules/mod_dso.html,v $ --> <html> <head> <title>ProFTPD module mod_dso</title> </head> <body bgcolor=white> <hr> <center> <h2><b>ProFTPD module <code>mod_dso</code></b></h2> </center> <hr><br> <p> <b>What are DSO modules?</b><br> "On modern Unix derivatives there exists a nifty mechanism usually called dynamic linking/loading of <i>Dynamic Shared Objects</i> (DSO) which provides a way to build a piece of program code in a special format for loading it at run-time into the address space of an executable program. <p> This loading can usually be done in two ways: Automatically by a system program called <code>ld.so</code> when an executable program is started, or manually from within the executing program via a programmatic system interface to the Unix loader through the system calls <code>dlopen()/dlsym()</code>. <p> In the first way the DSO's are usually called <i>shared libraries</i> or <i>DSO libraries</i> and named <code>libfoo.so</code> or <code>libfoo.so.1.2</code>. They reside in a system directory (usually <code>/usr/lib/</code>) and the link to the executable program is established at build-time by specifying <code>-lfoo</code> to the linker command. This hard-codes library references into the executable program file so that at start-time the Unix loader is able to locate <code>libfoo.so</code> in <code>/usr/lib/</code>, in paths hard-coded via linker-options like <code>-R</code> or in paths configured via the environment variable <code>LD_LIBRARY_PATH</code>. It then resolves any (yet unresolved) symbols in the executable program which are available in the DSO. <p> Symbols in the executable program are usually not referenced by the DSO (because it's a reusable library of general code) and hence no further resolving has to be done. The executable program has no need to do anything on its own to use the symbols from the DSO because the complete resolving is done by the Unix loader. (In fact, the code to invoke <code>ld.so</code> is part of the run-time startup code which is linked into every executable program which has been bound non-static.) The advantage of dynamic loading of common library code is obvious: the library code needs to be stored only once, in a system library like libc.so, saving disk space for every program. <p> In the second way the DSO's are usually called <i>shared objects</i> or <i>DSO files</i> and can be named with an arbitrary extension (although the canonical name is <code>foo.so</code>). These files usually stay inside a program-specific directory and there is no automatically established link to the executable program where they are used. Instead the executable program manually loads the DSO at run-time into its address space via <code>dlopen()</code>. At this time no resolving of symbols from the DSO for the executable program is done. Instead the Unix loader automatically resolves any (yet unresolved) symbols in the DSO from the set of symbols exported by the executable program and its already loaded DSO libraries (especially all symbols from the ubiquitous <code>libc.so</code>). This way the DSO gets knowledge of the executable program's symbol set as if it had been statically linked with it in the first place." <p> <i>(Taken from <a href="http://httpd.apache.org/docs/dso.html">http://httpd.apache.org/docs/dso.html</a>)</i> <p> The <code>mod_dso</code> module is ProFTPD's module for handling the dynamic loading of modules. This module is contained in the <code>mod_dso.c</code> file for ProFTPD 1.3.<i>x</i>, and is not compiled by default. Installation instructions are discussed <a href="#Installation">here</a>. <p> The most current version of <code>mod_dso</code> can be found in the ProFTPD source distribution: <pre> <a href="http://www.proftpd.org/">http://www.proftpd.org/</a> </pre> <h2>Directives</h2> <ul> <li><a href="#LoadFile">LoadFile</a> <li><a href="#LoadModule">LoadModule</a> <li><a href="#ModuleControlsACLs">ModuleControlsACLs</a> <li><a href="#ModuleOrder">ModuleOrder</a> <li><a href="#ModulePath">ModulePath</a> </ul> <p> <h2>Control Actions</h2> <ul> <li><a href="#insmod">insmod</a> <li><a href="#lsmod">lsmod</a> <li><a href="#rmmod">rmmod</a> </ul> <p> <hr> <h2><a name="LoadFile">LoadFile</a></h2> <strong>Syntax:</strong> LoadFile <em>path</em><br> <strong>Default:</strong> None<br> <strong>Context:</strong> "server config"<br> <strong>Module:</strong> mod_dso<br> <strong>Compatibility:</strong> 1.3rc1 <p> The <code>LoadFile</code> directive is used to load any shared object (<code>.so</code> file extension), such as shared libraries. On some platforms, it may be necessary to load all of the libraries needed by a DSO module, using <code>LoadFile</code>, prior to loading the module itself. <p> The <em>path</em> parameter must be the absolute path to the shared object to load. <p> Example: <pre> # Load the zlib library LoadFile /usr/lib/libz.so </pre> <p> <hr> <h2><a name="LoadModule">LoadModule</a></h2> <strong>Syntax:</strong> LoadModule <em>name</em><br> <strong>Default:</strong> None<br> <strong>Context:</strong> "server config"<br> <strong>Module:</strong> mod_dso<br> <strong>Compatibility:</strong> 1.3rc1 <p> The <code>LoadModule</code> directive is used to dynamically load a module from the configuration file. <p> Example: <pre> LoadModule mod_test.c </pre> <p> <hr> <h2><a name="ModuleControlsACLs">ModuleControlsACLs</a></h2> <strong>Syntax:</strong> ModuleControlsACLs <em>>actions|all allow|deny user|group list</em><br> <strong>Default:</strong> None<br> <strong>Context:</strong> "server config"<br> <strong>Module:</strong> mod_dso<br> <strong>Compatibility:</strong> 1.3rc1 <p> The <code>ModuleControlsACLs</code> directive configures access lists of <em>users</em> or <em>groups</em> who are allowed (or denied) the ability to use the <em>actions</em> implemented by <code>mod_dso</code>. The default behavior is to deny everyone unless an ACL allowing access has been explicitly configured. <p> If "allow" is used, then <em>list</em>, a comma-delimited list of <em>users</em> or <em>groups</em>, can use the given <em>actions</em>; all others are denied. If "deny" is used, then the <em>list</em> of <em>users</em> or <em>groups</em> cannot use <em>actions</em> all others are allowed. Multiple <code>ModuleControlsACLs</code> directives may be used to configure ACLs for different control actions, and for both users and groups. <p> The <em>actions</em> provided by <code>mod_dso</code> are "insmod" "lsmod", and "rmmod". <p> Example: <pre> # Allow only user root to load and unload modules, but allow everyone # to see which modules have been loaded ModuleControlsACLs insmod,rmmod allow user root ModuleControlsACLs lsmod allow user * </pre> <p> <hr> <h2><a name="ModuleOrder">ModuleOrder</a></h2> <strong>Syntax:</strong> ModuleOrder <em>...</em><br> <strong>Default:</strong> None<br> <strong>Context:</strong> "server config"<br> <strong>Module:</strong> mod_dso<br> <strong>Compatibility:</strong> 1.3rc1 <p> The <code>ModuleOrder</code> directive can be used to explicitly set the module order. <b>Note</b>: do not use this directive unless you know what you are doing. It is <i>very</i> easy to configure a non-working server with this directive. <p> If you <i>are</i> going to use <code>ModuleOrder</code>, make sure it is the very first directive in your <code>proftpd.conf</code> file. <p> Example: <pre> # Make this one the very first things, if you're going to use it. ModuleOrder \ mod_core.c \ mod_cap.c \ mod_auth_unix.c \ mod_auth_pam.c \ mod_ls.c \ mod_log.c \ mod_site.c \ mod_xfer.c \ mod_auth.c \ mod_ifsession.c \ mod_auth_file.c </pre> <p> <hr> <h2><a name="ModulePath">ModulePath</a></h2> <strong>Syntax:</strong> ModulePath <em>path</em><br> <strong>Default:</strong> None<br> <strong>Context:</strong> "server config"<br> <strong>Module:</strong> mod_dso<br> <strong>Compatibility:</strong> 1.3rc1 <p> The <code>ModulePath</code> directive is used to configure an alternative directory from which <code>mod_dso</code> will load DSO modules. By default, <code>mod_dso</code> uses <em>$prefix</em>/<code>libexec/</code>, where <em>$prefix</em> is where you installed <code>proftpd</code>, <i>e.g.</i> <code>/usr/local/</code>. <p> The <em>path</em> parameter must be an absolute path. <p> Example: <pre> ModulePath /etc/proftpd/libexec </pre> <p> <hr> <h1>Control Actions</h1> <p> <hr> <h2><a name="insmod"><code>insmod</code></a></h2> <strong>Syntax:</strong> ftpdctl insmod <em>module</em><br> <strong>Purpose:</strong> Load a DSO module <p> The <code>insmod</code> control action can be used to load a DSO module into the running <code>proftpd</code> daemon. <p> A module cannot be loaded multiple times. <p> Example: <pre> ftpdctl rmmod mod_test.c ftpdctl: 'mod_test.c' loaded </pre> <p> <hr> <h2><a name="lsmod"><code>lsmod</code></a></h2> <strong>Syntax:</strong> ftpdctl lsmod<br> <strong>Purpose:</strong> Display list of all loaded modules <p> The <code>lsmod</code> control action is used to display a list of all loaded modules. <p> Example: <pre> ftpdctl lsmod ftpdctl: Loaded Modules: ftpdctl: mod_core.c ftpdctl: mod_xfer.c ftpdctl: mod_auth_unix.c ftpdctl: mod_auth_file.c ftpdctl: mod_auth.c ftpdctl: mod_ls.c ftpdctl: mod_log.c ftpdctl: mod_site.c ftpdctl: mod_dso.c ftpdctl: mod_ctrls.c ftpdctl: mod_auth_pam.c ftpdctl: mod_cap.c </pre> <p> <hr> <h2><a name="rmmod"><code>rmmod</code></a></h2> <strong>Syntax:</strong> ftpdctl rmmod <em>module</em><br> <strong>Purpose:</strong> Unload a DSO module <p> The <code>rmmod</code> control action can be used to unload a DSO module from the running <code>proftpd</code> daemon. Note that it is also possible to "unload" one of the staticly-linked modules; this does not remove that module from the process' memory space, but does remove that module from the core engine, such that <code>proftpd</code> will act as if the module is not present. <p> Example: <pre> ftpdctl rmmod mod_test.c ftpdctl: 'mod_test.c' unloaded </pre> <p> <hr> <h2><a name="Usage">Usage</a></h2> Note that <code>mod_dso</code>'s control actions are only available if your <code>proftpd</code> has been compiled with Controls support. <p> <hr> <h2><a name="Installation">Installation</a></h2> The <code>mod_dso</code> module is distributed with ProFTPD. To enable use of DSO modules, use the <code>--enable-dso</code> configure option: <pre> ./configure --enable-dso make make install </pre> This option causes <code>mod_dso</code> to be compiled into <code>proftpd</code>. <p> <hr><br> Author: <i>$Author: castaglia $</i><br> Last Updated: <i>$Date: 2004/10/29 22:33:42 $</i><br> <br><hr> <font size=2><b><i> © Copyright 2004 TJ Saunders<br> All Rights Reserved<br> </i></b></font> <hr><br> </body> </html>