ProFTPD Developer's Guide: Configuration Contexts

ProFTPD Version 1.2

Table of Contents

Configuration Contexts
At present, ProFTPD has seven different configuration contexts: "main" server, <Anonymous>, <Directory>, <Global>, <Limit>, <VirtualHost>, and .ftpaccess files. These contexts are checked for in configuration handlers using the CHECK_CONF macro.

"Main" server
The "main" server context, listed as "server config" in the configuration directive documentation, encompasses everything outside of the other contexts (i.e. every configuration directive that is not explicitly contained within another configuration context), and signalled by the macro CONF_ROOT in a configuration directive handler.

The <Anonymous> section is used to set up the very common configuration of an anonymous FTP server. It does a chroot() to the anonymous FTP directory by default, and turns off the requirement for a valid password, requesting only a valid email address as the password. Other system binaries or files need not be contained within the <Anonymous> directory.

The CONF_ANON macro is used to define the <Anonymous> context. Note that since an <Anonymous> section is not considered a separate server, but rather a "subset" of its containing server, any configuration directives set for that server will be in effect for the <Anonymous> as well, unless overridden by a directive of the same name in the <Anonymous> context itself.

Context checks via CHECK_CONF in configuration handlers should check for this CONF_ANON macro if the configuration directive is to be allowed in the <Anonymous> context.

The <Directory> context is for configurations specific to directories, of course. This includes views of the contained files based on the logged-in user's username or group membership or on the name of the files (e.g. Unix-style "hidden" files), and on whether the user has permission to see the files. .ftpaccess files occur within this context by definition; <Limit> sections often appear in a <Directory> section as well.

Configuration handlers would check for the CONF_DIR macro in order to make sure that the configuration directive in question is occurring in an allowed context.

The description in the documentation for the <Global> context is good. Another point to know is that if a directive is set in this context, and then the same directive is used in the main or <VirtualHost> contexts with different parameters, those parameters take precedence over the <Global> parameters. This allows you to configure things for everyone equally, then tweak specific ervers individually, on a per-server basis.

In configuration directive handlers and context checks, this context uses the CONF_GLOBAL macro.

The <Limit> context is used to place limits on who and how individual FTP commands, or groups of FTP commands, may be used.


.ftpaccess files
These files are akin to Apache's .htaccess files, which are parsed-on-the-fly configuration files -- with restricted scopes -- that users can place in their own directories. Note that .ftpaccess are similar to Apache's .htaccess files, they are not the same. For example, ProFTPD's .ftpaccess files do not support a "require" directive, nor Apache's AuthRealm directive. That particular area of Apache configuration is targetted for restricting access to anonymous connections; by its nature, ProFTPD handles anonymous connections as special cases of the normal authenticated connections.

Configuration directive handlers that wish to allow their configuration directive to be placed in this context do so via the CONF_DYNDIR macro.

Configuration Flags
The config_rec structure defines a flags member that is used for signalling different configuration types. At present, these configuration types include:

The CF_MERGEDOWN flag is the most interesting of the flags, and the one the developer is most likely to encounter. It is used within a configuration directive handler like so:

  config_rec *c = NULL;

  c = add_config_param(...);
  c->flags |= CF_MERGEDOWN;
This flag tells the context-processing functions that configuration sub-contexts are to inherit this config_rec setting, unless the sub-context already has a config_rec of the same name.

The other two flags, CF_DEFER and CF_DYNAMIC, are set automatically for <Anonymous> and .ftpacces contexts, respectively.

Creating your own contexts
At present, there is no way for module to declare and process its own custom configuration contexts. Changes to the core context processing functions are needed, should you need to have your own context.

First, you'll need two configuration directives, one to handle the opening <MyContextName> directive, and one to handle the closing </MyContextName> directive. In the opening context handler, you'll need to call start_sub_config(). The closing context handler will need to call, appropriately enough, end_sub_config().

Here are the add_global() and end_global() configuration handlers, from mod_core.c, which illustrate these mentioned sub-configuration functions:

MODRET add_global(cmd_rec *cmd)
  config_rec *c;


  c = start_sub_config("Global");
  c->config_type = CONF_GLOBAL;

  return HANDLED(cmd);

MODRET end_global(cmd_rec *cmd)
  CHECK_ARGS(cmd, 0);

  return HANDLED(cmd);

In addition to some configuration directive handlers, you'll need to add some code to the get_section_name() internal function, so that the name of your custom context (or section) is correctly reported in the case of an error. Adding new code to this function is trivial, but will require that you #define a CONF_ macro for your context:

  #define CONF_MYCTX

Caveat Emptor
The configuration subsystem is one of the areas targeted for change in the 1.3.x series, so expect this information to become obsolete in the future.

Table of Contents

Author: $Author: castaglia $
Last Updated: $Date: 2003/01/02 17:39:33 $

© Copyright 2000-2003 TJ Saunders
All Rights Reserved