<!-- $Id: mod_ifsession.html,v 1.3 2005/06/20 02:05:28 castaglia Exp $ -->
<!-- $Source: /cvsroot/proftp/proftpd/doc/contrib/mod_ifsession.html,v $ -->
<html>
<head>
<title>ProFTPD module mod_ifsession</title>
</head>
<body bgcolor=white>
<hr>
<center>
<h2><b>ProFTPD module <code>mod_ifsession</code></b></h2>
</center>
<hr><br>
The purpose of <code>mod_ifsession</code> is to provide a flexible way of
specifying that certain configuration directives only apply to certain sessions,
based on credentials such as connection class, user, or group membership.
<p>
For class-based qualifications, <code>mod_ifsession</code> will apply
configuration directives to the current session as soon as the client has
connected to the server; for user- and group-based qualifications,
<code>mod_ifsession</code> applies configuration directives to the current
session, if applicable, only after the client has successfully authenticated.
This means that <code>mod_ifsession</code> cannot change the effect of some
user- and group-qualified configuration directives, particularly those that
influence the session prior to authentication. These directives include:
<pre>
AccessDenyMsg
AccessGrantMsg
AnonRequirePassword
<Anonymous>
AuthGroupFile
AuthUserFile
CreateHome
DefaultChdir
DefaultRoot
DefaultTransferMode
DisplayConnect
ExtendedLog
MaxInstances
RequireValidShell
RootLogin
ServerIdent
ServerName
ShowSymlinks
TransferLog
UseFtpUsers
WtmpLog
</pre>
and the directives from the <code>mod_auth_pam</code> module. All of these
<b>can</b> set on based on class qualifications, however.
<p>
While the above list of configuration directives is daunting, there <b>are</b>
still valid uses for this module, <i>e.g.</i> configuring
<code><Directory></code> and/or <code><Limit></code> for certain
sessions, <code>Filter</code> directives, transfer rates, maximum file sizes,
etc. Plus, some of the above directives (<i>e.g.</i> <code>DefaultChdir</code>,
<code>DefaultRoot</code>) already have their own configurable restrictions
(group expressions in the case of <code>DefaultChdir</code> and
<code>DefaultRoot</code>), so all is not entirely lost.
<p>
This module is contained in the <code>contrib/mod_ifsession.c</code> file for
ProFTPD 1.2.<i>x</i>/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_ifsession</code> is distributed with
the ProFTPD source.
<h2>Author</h2>
<p>
Please contact TJ Saunders <tj <i>at</i> castaglia.org> with any
questions, concerns, or suggestions regarding this module.
<h2>Directives</h2>
<ul>
<li><a href="#IfClass"><IfClass></a>
<li><a href="#IfGroup"><IfGroup></a>
<li><a href="#IfUser"><IfUser></a>
</ul>
<hr>
<h2><a name="IfClass"><IfClass></a></h2>
<strong>Syntax:</strong> <IfClass <em>["AND"|"OR"] class-expression|"regex" regexp</em>><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_ifsession<br>
<strong>Compatibility:</strong> 1.2.8rc1 and later
<p>
The <code><IfClass></code> context should contain any configuration
directives that should be in effect for any sessions that match the
<em>class-expression</em>. <code>Classes</code> must be enabled for this
context to work properly; the connecting client must be in any of the classes
listed in the expression for the directives contained to be applied. Note
that <code>!</code> notation in front of a class name in the expression is
supported.
<p>
The given <em>class-expression</em> may optionally be prefixed
with either the "AND" or "OR" keywords, which affect how
the expression is evaluated: if "AND" is used, then <b>all</b>
portions of the expression must evaluate to TRUE for the configuration context
to be applied to the current session; if "OR" is used, then <b>any</b>
portion of the expression must be TRUE for the context to be applied. The
default setting for <code><IfClass></code> is "OR".
<p>
If the "regex" keyword is used, the <em>regexp</em> should be a
regular expression to match class names.
<p>
Examples:
<pre>
# Give friends, and local users, better transfer rates
<IfClass local, friends>
TransferRate RETR 8192
</IfClass>
TransferRate RETR 4096
</pre>
<p>
See also: <a href="#IfGroup"><IfGroup></a>, <a href="#IfUser"><IfUser></a>
<p>
<hr>
<h2><a name="IfGroup"><IfGroup></a></h2>
<strong>Syntax:</strong> <IfGroup <em>["AND"|"OR"] group-expression|"regex" regexp</em>><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_ifsession<br>
<strong>Compatibility:</strong> 1.2.8rc1 and later
<p>
The <code><IfGroup></code> context should contain any configuration
directives that should be in effect for any sessions that match the
<em>group-AND-expression</em>. The authenticated user must be in <b>all</b> of
the groups listed in the expression for the directives contained to be
applied. Note that <code>!</code> notation in front of a group name in the
expression is supported.
<p>
The given <em>group-expression</em> may optionally be prefixed
with either the "AND" or "OR" keywords, which affect how
the expression is evaluated: if "AND" is used, then <b>all</b>
portions of the expression must evaluate to TRUE for the configuration context
to be applied to the current session; if "OR" is used, then <b>any</b>
portion of the expression must be TRUE for the context to be applied. The
default setting for <code><IfGroup></code> is "AND".
<p>
If the "regex" keyword is used, the <em>regexp</em> should be a
regular expression to match group names.
<p>
Example:
<pre>
# Only members of group webusers can upload/download HTML files
<IfGroup !webusers>
PathDenyFilter \.htm$|\.html$
</IfGroup>
</pre>
<p>
See also: <a href="#IfClass"><IfClass></a>, <a href="#IfUser"><IfUser></a>
<p>
<hr>
<h2><a name="IfUser"><IfUser></a></h2>
<strong>Syntax:</strong> <IfUser <em>["AND"|"OR"] user-expression|"regex" regexp</em>><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_ifsession<br>
<strong>Compatibility:</strong> 1.2.8rc1 and later
<p>
The <code><IfUser></code> context should contain any configuration
directives that should be in effect for any sessions that match the
<em>user-OR-expression</em>. The authenticated user must be one of the users
listed in the expression for the directives contained to be applied. Note
that <code>!</code> notation in front of a user name in the expression is
supported.
<p>
The given <em>user-expression</em> may optionally be prefixed
with either the "AND" or "OR" keywords, which affect how
the expression is evaluated: if "AND" is used, then <b>all</b>
portions of the expression must evaluate to TRUE for the configuration context
to be applied to the current session; if "OR" is used, then <b>any</b>
portion of the expression must be TRUE for the context to be applied. The
default setting for <code><IfUser></code> is "OR".
<p>
If the "regex" keyword is used, the <em>regexp</em> should be a
regular expression to match user names.
<p>
Example:
<pre>
# Alter the view of files for everyone except the admin
<IfUser !ftpadm>
<Directory />
DirFakeUser on ~
DirFakeGroup on ~
DirFakeMode 0440
</Directory>
</IfUser>
# Impose a PathDenyFilter on ftp users
<IfUser regex ^ftp>
PathDenyFilter \.conf$
</IfUser>
</pre>
<p>
See also: <a href="#IfClass"><IfClass></a>, <a href="#IfGroup"><IfGroup></a>
<p>
<hr>
<h2><a name="Usage">Usage</a></h2>
Expressions, AND vs OR
<p>
<hr>
<h2><a name="Installation">Installation</a></h2>
To install <code>mod_ifsession</code>, copy the <code>mod_ifsession.c</code>
file into:
<pre>
<i>proftpd-dir</i>/contrib/
</pre>
after unpacking the latest proftpd-1.2 source code. Then follow the usual
steps for using third-party modules in proftpd:
<pre>
./configure --with-modules=mod_ifsession
make
make install
</pre>
Note that <code>mod_ifsession</code> should be the <b>last</b> module
in the <code>--with-modules</code> list, if multiple modules are listed.
This makes sure that <code>mod_ifsession</code>'s changes will be seen
properly by other modules.
<p>
<hr><br>
Author: <i>$Author: castaglia $</i><br>
Last Updated: <i>$Date: 2005/06/20 02:05:28 $</i><br>
<br><hr>
<font size=2><b><i>
© Copyright 2000-2002 TJ Saunders<br>
All Rights Reserved<br>
</i></b></font>
<hr><br>
</body>
</html>
