373 lines
12 KiB
HTML
373 lines
12 KiB
HTML
<!DOCTYPE html>
|
|
<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="#IfAuthenticated"><IfAuthenticated></a>
|
|
<li><a href="#IfClass"><IfClass></a>
|
|
<li><a href="#IfGroup"><IfGroup></a>
|
|
<li><a href="#IfSessionOptions">IfSessionOptions</a>
|
|
<li><a href="#IfUser"><IfUser></a>
|
|
</ul>
|
|
|
|
<hr>
|
|
<h3><a name="IfAuthenticated"><IfAuthenticated></a></h3>
|
|
<strong>Syntax:</strong> <IfAuthenticated><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.3.5rc1 and later
|
|
|
|
<p>
|
|
The <code><IfAuthenticated></code> context should contain any
|
|
configuration directives that should be in effect for any sessions where
|
|
the client has successfully authenticated.
|
|
|
|
<p>
|
|
Examples:
|
|
<pre>
|
|
# Only configure SQL logging for authenticated users, to avoid cluttering
|
|
# database tables with fail login data
|
|
<IfAuthenticated>
|
|
SQLLog ...
|
|
</IfAuthenticated>
|
|
</pre>
|
|
|
|
<p>
|
|
See also: <a href="#IfGroup"><IfGroup></a>, <a href="#IfUser"><IfUser></a>
|
|
|
|
<hr>
|
|
<h3><a name="IfClass"><IfClass></a></h3>
|
|
<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>
|
|
<h3><a name="IfGroup"><IfGroup></a></h3>
|
|
<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>
|
|
<h3><a name="IfSessionOptions">IfSessionOptions</a></h3>
|
|
<strong>Syntax:</strong> IfSessionOptions <em>opt1 ...</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.3.9rc1 and later
|
|
|
|
<p>
|
|
The <code>IfSessionOptions</code> directive is used to configure various
|
|
optional behavior of <code>mod_ifsession</code>.
|
|
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
IfSessionOptions PerUnauthenticatedUser
|
|
</pre>
|
|
|
|
<p>
|
|
The currently implemented options are:
|
|
<ul>
|
|
<li><code>PerUnauthenticatedUser</code><br>
|
|
<p>
|
|
By default, <code>mod_ifsession</code> will only use the
|
|
<i>authenticated</i> identify of the remote client for conditional
|
|
configurations, <i>i.e.</i> after the client has successfully
|
|
authenticated.
|
|
|
|
<p>
|
|
However, some sites need to use different <i>authentication-related</i>
|
|
conditional configurations, which means using the <i>unauthenticated</i>
|
|
identity (usually the username requested). For such cases, use this
|
|
option. <b>Not recommended</b>, as such conditional configurations can
|
|
lead to timing differences, which can then be used to determine/test which
|
|
usernames are valid for the site.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="IfUser"><IfUser></a></h3>
|
|
<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>
|
|
|
|
<p>
|
|
<b>As a Shared Module</b><br>
|
|
If your <code>proftpd</code> is compiled with <code>mod_ifsession</code>
|
|
as a shared module, then you <b>must</b> make sure that
|
|
<code>mod_ifsession</code> is loaded <b>last</b>:
|
|
<pre>
|
|
<IfModule mod_dso.c>
|
|
LoadModule mod_sql.c
|
|
LoadModule mod_sql_mysql.c
|
|
LoadModule mod_tls.c
|
|
LoadModule mod_rewrite.c
|
|
<b>LoadModule mod_ifsession.c</b>
|
|
</IfModule>
|
|
</pre>
|
|
Failure to ensure that <code>mod_ifsession</code> is loaded last will mean
|
|
that the per-user/group/class functionality will not work as you expect.
|
|
|
|
<p>
|
|
<i>Todo</i><br>
|
|
Expressions, AND vs OR
|
|
|
|
<p>
|
|
<hr>
|
|
<h2><a name="Installation">Installation</a></h2>
|
|
The <code>mod_ifsession</code> module is distributed with ProFTPD. 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>
|
|
To build <code>mod_ifsession</code> as a DSO module:
|
|
<pre>
|
|
$ ./configure --enable-dso --with-shared=mod_ifsession
|
|
</pre>
|
|
Then follow the usual steps:
|
|
<pre>
|
|
$ make
|
|
$ make install
|
|
</pre>
|
|
|
|
<p>
|
|
Alternatively, if your <code>proftpd</code> was compiled with DSO support, you
|
|
can use the <code>prxs</code> tool to build <code>mod_ifsession</code> as a
|
|
shared module:
|
|
<pre>
|
|
$ prxs -c -i -d mod_ifsession.c
|
|
</pre>
|
|
|
|
<p>
|
|
<b>Logging</b><br>
|
|
The <code>mod_ifsession</code> module supports <a href="../howto/Tracing.html">trace logging</a>, via the module-specific log channels:
|
|
<ul>
|
|
<li>ifsession
|
|
</ul>
|
|
Thus for trace logging, to aid in debugging, you would use the following in
|
|
your <code>proftpd.conf</code>:
|
|
<pre>
|
|
TraceLog /path/to/ftpd/trace.log
|
|
Trace ifsession:20
|
|
</pre>
|
|
This trace logging can generate large files; it is intended for debugging use
|
|
only, and should be removed from any production configuration.
|
|
|
|
<p>
|
|
<hr>
|
|
<font size=2><b><i>
|
|
© Copyright 2000-2023 TJ Saunders<br>
|
|
All Rights Reserved<br>
|
|
</i></b></font>
|
|
<hr>
|
|
|
|
</body>
|
|
</html>
|