ProFTPD module mod_dso



What are DSO modules?
"On modern Unix derivatives there exists a nifty mechanism usually called dynamic linking/loading of Dynamic Shared Objects (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.

This loading can usually be done in two ways: Automatically by a system program called ld.so 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 dlopen()/dlsym().

In the first way the DSO's are usually called shared libraries or DSO libraries and named libfoo.so or libfoo.so.1.2. They reside in a system directory (usually /usr/lib/) and the link to the executable program is established at build-time by specifying -lfoo 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 libfoo.so in /usr/lib/, in paths hard-coded via linker-options like -R or in paths configured via the environment variable LD_LIBRARY_PATH. It then resolves any (yet unresolved) symbols in the executable program which are available in the DSO.

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 ld.so 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.

In the second way the DSO's are usually called shared objects or DSO files and can be named with an arbitrary extension (although the canonical name is foo.so). 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 dlopen(). 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 libc.so). 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."

(Taken from http://httpd.apache.org/docs/dso.html)

The mod_dso module is ProFTPD's module for handling the dynamic loading of modules. This module is contained in the mod_dso.c file for ProFTPD 1.3.x, and is not compiled by default. Installation instructions are discussed here.

The most current version of mod_dso can be found in the ProFTPD source distribution:

  http://www.proftpd.org/

Directives

Control Actions


LoadFile

Syntax: LoadFile path
Default: None
Context: "server config"
Module: mod_dso
Compatibility: 1.3.0rc1 and later

The LoadFile directive is used to load any shared object (.so 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 LoadFile, prior to loading the module itself.

The path parameter must be the absolute path to the shared object to load.

Example:

  # Load the zlib library
  LoadFile /usr/lib/libz.so


LoadModule

Syntax: LoadModule name
Default: None
Context: "server config"
Module: mod_dso
Compatibility: 1.3.0rc1 and later

The LoadModule directive is used to dynamically load a module from the configuration file.

Example:

  LoadModule mod_test.c


ModuleControlsACLs

Syntax: ModuleControlsACLs actions|all allow|deny user|group list
Default: None
Context: "server config"
Module: mod_dso
Compatibility: 1.3.0rc1 and later

The ModuleControlsACLs directive configures access lists of users or groups who are allowed (or denied) the ability to use the actions implemented by mod_dso. The default behavior is to deny everyone unless an ACL allowing access has been explicitly configured.

If "allow" is used, then list, a comma-delimited list of users or groups, can use the given actions; all others are denied. If "deny" is used, then the list of users or groups cannot use actions all others are allowed. Multiple ModuleControlsACLs directives may be used to configure ACLs for different control actions, and for both users and groups.

The actions provided by mod_dso are "insmod" "lsmod", and "rmmod".

Example:

  # 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 *


ModuleOrder

Syntax: ModuleOrder ...
Default: None
Context: "server config"
Module: mod_dso
Compatibility: 1.3.0rc1 and later

The ModuleOrder directive can be used to explicitly set the module order. Note: do not use this directive unless you know what you are doing. It is very easy to configure a non-working server with this directive.

If you are going to use ModuleOrder, make sure it is the very first directive in your proftpd.conf file.

Example:

  # 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


ModulePath

Syntax: ModulePath path
Default: None
Context: "server config"
Module: mod_dso
Compatibility: 1.3.0rc1 and later

The ModulePath directive is used to configure an alternative directory from which mod_dso will load DSO modules. By default, mod_dso uses $prefix/libexec/, where $prefix is where you installed proftpd, e.g. /usr/local/.

The path parameter must be an absolute path.

Example:

  ModulePath /etc/proftpd/libexec


Control Actions


insmod

Syntax: ftpdctl insmod module
Purpose: Load a DSO module

The insmod control action can be used to load a DSO module into the running proftpd daemon.

A module cannot be loaded multiple times.

Example:

  ftpdctl rmmod mod_test.c
  ftpdctl: 'mod_test.c' loaded


lsmod

Syntax: ftpdctl lsmod
Purpose: Display list of all loaded modules

The lsmod control action is used to display a list of all loaded modules.

Example:

  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


rmmod

Syntax: ftpdctl rmmod module
Purpose: Unload a DSO module

The rmmod control action can be used to unload a DSO module from the running proftpd 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 proftpd will act as if the module is not present.

Example:

  ftpdctl rmmod mod_test.c
  ftpdctl: 'mod_test.c' unloaded


Usage

Note that mod_dso's control actions are only available if your proftpd has been compiled with Controls support.


Installation

The mod_dso module is distributed with ProFTPD. To enable use of DSO modules, use the --enable-dso configure option:
  ./configure --enable-dso
  make
  make install
This option causes mod_dso to be compiled into proftpd.

Frequently Asked Questions

Question: When I try to start proftpd, it fails like this:

  proftpd[1234]: mod_dso/0.5: module 'mod_radius.c' already loaded
  proftpd[1234]: Fatal: LoadModule: error loading module 'mod_radius.c': Operation not permitted on line 9 of '/etc/proftpd/proftpd.conf'
How do I fix this "module already loaded" error?
Answer: This happens when the proftpd configuration either a) uses the
LoadModule on a module which was compiled in as a static module, or b) is inadvertently using LoadModule on the same module multiple times.

To check if the module has been statically compiled into your proftpd executable, use the -l command-line parameter, e.g.:

  # proftpd -l
  Compiled-in modules:
    mod_core.c
    mod_xfer.c
    mod_auth_unix.c
    mod_auth_file.c
    mod_auth.c
    mod_ls.c
    mod_log.c
    mod_site.c
    mod_delay.c
    mod_facts.c
    mod_dso.c
    mod_ident.c
    mod_auth_pam.c
    mod_tls.c
    mod_cap.c
The modules listed via the command are the static modules. So if your LoadModule directive is used for one of the modules in this list, you can remove that LoadModule directive; that module will already be loaded.

The other cause, that of having multiple LoadModule directives for the same module, usually happens when your proftpd.conf file includes other config files, e.g.:

  Include /path/to/modules.conf
and it is those other config files which have LoadModule directives of their own.

If you find yourself needs to change the configuration to work around this error, you can use the following to see if the module has already been loaded, and if not, load it:

  <IfModule !mod_radius.c>
    LoadModule mod_radius.c
  </IfModule>

Question: When I try to start proftpd, it fails like this:

  proftpd[1234]: mod_dso/0.5: module 'mod_ctrls.c' already loaded
  proftpd[1234]: Fatal: LoadModule: error loading module 'mod_ctrls.c': Operation not permitted on line 9 of '/etc/proftpd/proftpd.conf'
I do not have any other LoadModule directives in my config, nor is the mod_ctrls module in my --with-modules configure option.

Answer: In this particular case, the mod_ctrls module is automatically compiled in, as a static module, when the --enable-ctrls configure option is used. There are only a few such modules with this special handling: All of these modules would appear in the `proftpd -l' static module list.

Question: If I use prxs to compile a module like mod_ldap, which is already built into my proftpd as a static module, and then I use:

  LoadModule mod_ldap.c
in my proftpd.conf, then which mod_ldap code is used, the static module or the shared module?
Answer: Excellent question. The short answer is: the static module wins.

When mod_dso goes to load a module, it first checks to see whether that module is already loaded -- and if so, the module will not be loaded again. Static modules, by definition, are always "already loaded". This means that your mod_ldap shared module code would not be loaded, and thus would not override the static module.



Author: $Author: castaglia $
Last Updated: $Date: 2013/05/09 03:58:40 $


© Copyright 2004-2013 TJ Saunders
All Rights Reserved