trAvis - MANAGER

Edit File: mod_ctrls.html

<html>
<head>
<title>ProFTPD module mod_ctrls</title>
</head>

<hr>
<center>
<h2>ProFTPD module <code>mod_ctrls</code></h2>
</center>
<hr>

This module is contained in the <code>mod_ctrls.c</code> and
<code>mod_ctrls.h</code> files for ProFTPD 1.2, and is not compiled by default.
Installation instructions are discussed <a href="#Installation">here</a>.

This module implements the server side of a Unix domain socket, used for
communication with a running <code>proftpd</code> daemon. The client used for
this communication is <code>ftpdctl</code>, part of the Controls API.
See the <code>ftpdctl</code> man page for details on using that program;
details on the <a href="#Usage">usage</a> of this module follow
the directive descriptions.

The most current version of <code>mod_ctrls</code> can be found in the
ProFTPD source distribution:
<pre>
 <a href="http://www.proftpd.org/">http://www.proftpd.org/</a>
</pre>

<h2>Author</h2>

Please contact TJ Saunders &lt;tj at castaglia.org&gt; with any
questions, concerns, or suggestions regarding this module.

<h2>Directives</h2>
<ul>
 <li><a href="#ControlsACLs">ControlsACLs</a>
 <li><a href="#ControlsAuthFreshness">ControlsAuthFreshness</a>
 <li><a href="#ControlsEngine">ControlsEngine</a>
 <li><a href="#ControlsInterval">ControlsInterval</a>
 <li><a href="#ControlsLog">ControlsLog</a>
 <li><a href="#ControlsMaxClients">ControlsMaxClients</a>
 <li><a href="#ControlsSocket">ControlsSocket</a>
 <li><a href="#ControlsSocketACL">ControlsSocketACL</a>
 <li><a href="#ControlsSocketOwner">ControlsSocketOwner</a>
</ul>

<h2>Control Actions</h2>
<ul>
 <li><a href="#help"><code>help</code></a>
 <li><a href="#insctrl"><code>insctrl</code></a>
 <li><a href="#lsctrl"><code>lsctrl</code></a>
 <li><a href="#rmctrl"><code>rmctrl</code></a>
</ul>

<hr>
<h1>Directives</h1>

<hr>
<h2><a name="ControlsACLs">ControlsACLs</a></h2>
Syntax: ControlsACLs actions|all allow|deny user|group list 
Default: None 
Context: server config 
Module: mod_ctrls 
Compatibility: 1.2.10rc1 and later

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

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

<hr>
<h2><a name="ControlsAuthFreshness">ControlsAuthFreshness</a></h2>
Syntax: ControlsAuthFreshness seconds 
Default: ControlsAuthFreshness 10 
Context: server config 
Module: mod_ctrls 
Compatibility: 1.2.10rc1 and later

The <code>ControlsAuthFreshness</code> directive configures the maximum age,
in seconds, for the client's end of a connection. If the client-specific file
is older than the configured age, the connection is denied.

<hr>
<h2><a name="ControlsEngine">ControlsEngine</a></h2>
Syntax: ControlsEngine on|off 
Default: ControlsEngine on 
Context: server config 
Module: mod_ctrls 
Compatibility: 1.2.10rc1 and later

The <code>ControlsEngine</code> directive enables or disables the
<code>mod_ctrls</code> module, and thus the processing of <code>ftpdctl</code>
requests.

<hr>
<h2><a name="ControlsInterval">ControlsInterval</a></h2>
Syntax: ControlsInterval seconds 
Default: ControlsInterval 10 
Context: server config 
Module: mod_ctrls 
Compatibility: 1.2.10rc1 and later

The <code>ControlsInterval</code> directives configures the interval at
which <code>mod_ctrls</code> will check and handle pending
<code>ftpdctl</code> action requests on the Controls socket. seconds
must be a positive number.

<hr>
<h2><a name="ControlsLog">ControlsLog</a></h2>
Syntax: ControlsLog file 
Default: None 
Context: server config 
Module: mod_ctrls 
Compatibility: 1.2.10rc1 and later

The <code>ControlsLog</code> directive configures a file used for logging
by <code>mod_ctrls</code> and possibly other Controls modules. The
configured file must be an absolute path.

<hr>
<h2><a name="ControlsMaxClients">ControlsMaxClients</a></h2>
Syntax: ControlsMaxClients number 
Default: ControlsMaxClients 5 
Context: server config 
Module: mod_ctrls 
Compatibility: 1.2.10rc1 and later

The <code>ControlsMaxClients</code> directive configures the maximum number
of pending client requests that will be handled when <code>mod_ctrls</code>
checks the socket. number must be a positive number.

<hr>
<h2><a name="ControlsSocket">ControlsSocket</a></h2>
Syntax: ControlsSocket file 
Default: ControlsSocket var/run/proftpd.sock 
Context: server config 
Module: mod_ctrls 
Compatibility: 1.2.10rc1 and later

The <code>ControlsSocket</code> directive configures the file to be used
as the Unix domain socket, rather than the default. file must be an
absolute path. Note that if used, <code>ftpdctl</code>'s <code>-s</code>
option will also need to be used.

<hr>
<h2><a name="ControlsSocketACL">ControlsSocketACL</a></h2>
Syntax: ControlsSocketACL allow|deny user|group list 
Default: None 
Context: server config 
Module: mod_ctrls 
Compatibility: 1.2.10rc1 and later

The <code>ControlsSocketACL</code> directive configures an access
list of users or groups who are allowed (or denied)
access to the Unix domain server socket used for receiving action requests.
The default behavior is to deny everyone unless an ACL allowing access has
been explicitly configured.

If &quot;allow&quot; is used, then list, a comma-delimited list
of users or groups, can use the control socket; all others
are denied. If &quot;deny&quot; is used, then the list of
users or groups cannot use the control socket; all others
are allowed. A <code>ControlsSocketACL</code> directive with &quot;user&quot;
and one using &quot;group&quot; may be used simultaneously.

<hr>
<h2><a name="ControlsSocketOwner">ControlsSocketOwner</a></h2>
Syntax: ControlsSocketOwner user group 
Default: ControlsSocketOwner root root 
Context: server config 
Module: mod_ctrls 
Compatibility: 1.2.10rc1 and later

The <code>ControlsSocketOwner</code> directive configures the ownership of
the Unix domain socket file created when <code>mod_ctrls</code> starts up.
The ownership of this file (and its mode) can also be used as a form of
access control.

<hr>
<h1>Control Actions</h1>

<hr>
<h2><a name="help"><code>help</code></a></h2>
Syntax: ftpdctl help 
Purpose: Display a sorted list of active controls and their descriptions

The <code>help</code> control action can be used to obtain a sorted list of all
active control actions, and their descriptions.

<hr>
<h2><a name="insctrl"><code>insctrl</code></a></h2>
Syntax: ftpdctl insctrl action|all [module] 
Purpose: Enable control actions

The <code>insctrl</code> control action can be used to enable any disabled
control action by name. The special &quot;<code>insctrl all</code>&quot; enables
all disabled control actions. Once a specific action has been enabled
(most control actions are enabled by default) , the
&quot;<a href="#rmctrl">rmctrl</a>&quot; control action can be used to disable
it.

Example:
<pre>
 ftpdctl insctrl debug
</pre>

<hr>
<h2><a name="lsctrl"><code>lsctrl</code></a></h2>
Syntax: ftpdctl lsctrl 
Purpose: Display a sorted list of all active control actions

The <code>lsctrl</code> control action can be used obtain a sorted list of all
active control actions. The list will include the name of the action as well as
the module that implements that action.

<hr>
<h2><a name="rmctrl"><code>rmctrl</code></a></h2>
Syntax: ftpdctl rmctrl action|all [module] 
Purpose: Disable control actions

The <code>rmctrl</code> control action can be used to disable any registered
control action by name, except for the actions registered by
<code>mod_ctrls</code>: &quot;insctrl&quot;, &quot;lsctrl&quot;, and
&quot;rmctrl&quot;. The exception to this is the special &quot;<code>rmctrl
all</code>&quot;, which disables all actions and effectively turns
<code>mod_ctrls</code> off. A daemon restart is then necessary to reenable
actions. Once a specific action has been disabled, the
&quot;<a href="#insctrl">insctrl</a>&quot; control action can be used to
reenable it.

Example:
<pre>
 ftpdctl rmctrl memory
</pre>
This disables all actions registered under the name &quot;memory&quot;. If
there was such an action registered by a specific module,
<code>mod_ctrls_common</code> for example, that the administor wished to
disable, but to leave the &quot;memory&quot; actions of other modules enabled:
<pre>
 ftpdctl rmctrl memory mod_ctrls_common.c
</pre>

<hr>
<h2><a name="Usage">Usage</a></h2>
The determination of &quot;freshness&quot; is part of determining client
credentials. The method used by <code>mod_ctrls</code> comes from
Stevens' Advanced Programming in the Unix Environment, chapter 15.
Admittedly having kernel-provided client credentials would be much nicer,
but portably obtaining them is next to impossible. On some flavors of Unix
it simply cannot be done. Stevens' method is the next best thing right now.

<hr>
<h2><a name="Installation">Installation</a></h2>
The <code>mod_ctrls</code> module is distributed with ProFTPD. To enable
use of Controls, use the <code>--enable-ctrls</code> configure option:
<pre>
 ./configure --enable-ctrls
 make
 make install
</pre>
This option causes <code>mod_ctrls</code> to be compiled into
<code>proftpd</code>.

<hr>
Author: $Author: castaglia $ 
Last Updated: $Date: 2013-05-17 15:04:43 $

<hr>

<hr>

</body>
</html>