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.
<Anonymous>
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.
<Directory>
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.
<Global>
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.
<Limit>
The
<Limit> context is used to place limits on who
and how individual FTP commands, or groups of FTP commands, may be used.
CONF_LIMIT
<VirtualHost>
<VirtualHost>
CONF_VIRTUAL
.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;
CHECK_ARGS(cmd,0);
CHECK_CONF(cmd,CONF_ROOT|CONF_VIRTUAL);
c = start_sub_config("Global");
c->config_type = CONF_GLOBAL;
return HANDLED(cmd);
}
MODRET end_global(cmd_rec *cmd)
{
CHECK_ARGS(cmd, 0);
CHECK_CONF(cmd,CONF_GLOBAL);
end_sub_config();
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.