## ProFTPD module `mod_ctrls`

This module is contained in the `mod_ctrls.c` and `mod_ctrls.h` files for ProFTPD 1.2, and is not compiled by default. Installation instructions are discussed here.

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

The most current version of `mod_ctrls` can be found in the ProFTPD source distribution:

      http://www.proftpd.org/

## Author

Please contact TJ Saunders <tj at castaglia.org> with any questions, concerns, or suggestions regarding this module.

## Directives

- ControlsACLs
- ControlsAuthFreshness
- ControlsEngine
- ControlsInterval
- ControlsLog
- ControlsMaxClients
- ControlsSocket
- ControlsSocketACL
- ControlsSocketOwner

## Control Actions

- `help`
- `insctrl`
- `lsctrl`
- `rmctrl`

# Directives

### ControlsACLs

Syntax: ControlsACLs actions|all allow|deny user|group list
Default: None
Context: server config
Module: mod_ctrls
Compatibility: 1.2.10rc1 and later

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

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

### ControlsAuthFreshness

Syntax: ControlsAuthFreshness seconds
Default: ControlsAuthFreshness 10
Context: server config
Module: mod_ctrls
Compatibility: 1.2.10rc1 and later

The `ControlsAuthFreshness` 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.

### ControlsEngine

Syntax: ControlsEngine on|off
Default: ControlsEngine on
Context: server config
Module: mod_ctrls
Compatibility: 1.2.10rc1 and later

The `ControlsEngine` directive enables or disables the `mod_ctrls` module, and thus the processing of `ftpdctl` requests.

### ControlsInterval

Syntax: ControlsInterval seconds
Default: ControlsInterval 10
Context: server config
Module: mod_ctrls
Compatibility: 1.2.10rc1 and later

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

### ControlsLog

Syntax: ControlsLog file
Default: None
Context: server config
Module: mod_ctrls
Compatibility: 1.2.10rc1 and later

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

### ControlsMaxClients

Syntax: ControlsMaxClients number
Default: ControlsMaxClients 5
Context: server config
Module: mod_ctrls
Compatibility: 1.2.10rc1 and later

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

### ControlsSocket

Syntax: ControlsSocket file
Default: ControlsSocket var/run/proftpd.sock
Context: server config
Module: mod_ctrls
Compatibility: 1.2.10rc1 and later

The `ControlsSocket` 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, `ftpdctl`'s `-s` option will also need to be used.

### ControlsSocketACL

Syntax: ControlsSocketACL allow|deny user|group list
Default: None
Context: server config
Module: mod_ctrls
Compatibility: 1.2.10rc1 and later

The `ControlsSocketACL` 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 "allow" is used, then list, a comma-delimited list of users or groups, can use the control socket; all others are denied. If "deny" is used, then the list of users or groups cannot use the control socket; all others are allowed. A `ControlsSocketACL` directive with "user" and one using "group" may be used simultaneously.

### ControlsSocketOwner

Syntax: ControlsSocketOwner user group
Default: ControlsSocketOwner root root
Context: server config
Module: mod_ctrls
Compatibility: 1.2.10rc1 and later

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

# Control Actions

### `help`

Syntax: ftpdctl help
Purpose: Display a sorted list of active controls and their descriptions

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

### `insctrl`

Syntax: ftpdctl insctrl action|all [module]
Purpose: Enable control actions

The `insctrl` control action can be used to enable any disabled control action by name. The special "`insctrl all`" enables all disabled control actions. Once a specific action has been enabled (most control actions are enabled by default) , the "rmctrl" control action can be used to disable it.

Example:

      ftpdctl insctrl debug

### `lsctrl`

Syntax: ftpdctl lsctrl
Purpose: Display a sorted list of all active control actions

The `lsctrl` 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.

### `rmctrl`

Syntax: ftpdctl rmctrl action|all [module]
Purpose: Disable control actions

The `rmctrl` control action can be used to disable any registered control action by name, except for the actions registered by `mod_ctrls`: "insctrl", "lsctrl", and "rmctrl". The exception to this is the special "`rmctrl all`", which disables all actions and effectively turns `mod_ctrls` off. A daemon restart is then necessary to re-enable actions. Once a specific action has been disabled, the "insctrl" control action can be used to re-enable it.

Example:

      ftpdctl rmctrl memory

This disables all actions registered under the name "memory". If there was such an action registered by a specific module, `mod_ctrls_common` for example, that the administrator wished to disable, but to leave the "memory" actions of other modules enabled:

      ftpdctl rmctrl memory mod_ctrls_common.c

## Usage

The determination of "freshness" is part of determining client credentials. The method used by `mod_ctrls` 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.

Logging
The `mod_ctrls` module supports trace logging, via the module-specific log channels:

- ctrls

Thus for trace logging, to aid in debugging, you would use the following in your `proftpd.conf`:

      TraceLog /path/to/ftpd/trace.log
      Trace ctrls:20

This trace logging can generate large files; it is intended for debugging use only, and should be removed from any production configuration.

## Installation

The `mod_ctrls` module is distributed with ProFTPD. To enable use of Controls, use the `--enable-ctrls` configure option:

      $ ./configure --enable-ctrls
      $ make
      $ make install

This option causes `mod_ctrls` to be compiled into `proftpd`.

© Copyright 2000-2016 TJ Saunders
All Rights Reserved