ProFTPD module mod_counter

## ProFTPD module `mod_counter`

The `mod_counter` module is designed to allow a sort of "locking" to be enforced when the same file is being uploaded or downloaded by multiple clients at the same time.

The `mod_counter` works by creating a SysV semaphore for a file being read/written, and placing a number of reader or writer "counters" in that semaphore. When the configured maximum number of counters is reached, the FTP command which seeks to add another reader/writer counter will be denied. This allows site to configure the maximum number of clients which can be reading/writing any file at one time.

This module is contained in the `mod_counter.c` file for ProFTPD 1.2.x/1.3.x, and is not compiled by default. Installation instructions are discussed here. Example configurations and further details are discussed in the usage section.

The most current version of `mod_counter` can be found at:

      http://www.castaglia.org/proftpd/

## Author

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

## Directives

- CounterEngine
- CounterFile
- CounterLog
- CounterMaxReaders
- CounterMaxWriters

## CounterEngine

Syntax: CounterEngine on|off
Default: off
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_counter
Compatibility: 1.2.10rc1 and later

The `CounterEngine` directive enables or disables the module's runtime counter engine. If it is set to off this module does no "locking". Use this directive to disable the module instead of commenting out all `mod_counter` directives.

## CounterFile

Syntax: CounterFile path
Default: None
Context: server config, `<VirtualHost>`, `<Global>`, `<Anonymous>`, `<Directory>`
Module: mod_counter
Compatibility: 1.3.2rc1 and later

The `CounterFile` directive configures a file that `mod_counter` uses for tracking the semaphores it creates. This directive is required for `mod_counter`, if enabled, to function.

## CounterLog

Syntax: CounterLog path|"none"
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_counter
Compatibility: 1.2.10rc1 and later

The `CounterLog` directive is used to a specify a log file for `mod_counter` reporting and debugging, and can be done a per-server basis. The path parameter must be the full path to the file to use for logging. Note that this path must not be to a world-writeable directory and, unless `AllowLogSymlinks` is explicitly set to on (generally a bad idea), the path must not be a symbolic link.

If path is "none", no logging will be done at all; this setting can be used to override a `CounterLog` setting inherited from a `<Global>` context.

## CounterMaxReaders

Syntax: CounterMaxReaders max
Default: 0
Context: server config, `<VirtualHost>`, `<Global>`, `<Anonymous>`, `<Directory>`
Module: mod_counter
Compatibility: 1.2.10rc1 and later

The `CounterMaxReaders` directive specifies the maximum number of clients allowed to be reading to the same file at the same time. By default, all clients are allowed to read the same file at one time by `mod_counter`.

## CounterMaxWriters

Syntax: CounterMaxWriters max
Default: 1
Context: server config, `<VirtualHost>`, `<Global>`, `<Anonymous>`, `<Directory>`
Module: mod_counter
Compatibility: 1.2.10rc1 and later

The `CounterMaxWriters` directive specifies the maximum number of clients allowed to be writing to the same file at the same time. By default, only one client is allowed to write to the same file at one time by `mod_counter`.

## Installation

To install `mod_counter`, copy the `mod_counter.c` file into

      proftpd-dir/contrib/

after unpacking the latest proftpd-1.3.x source code. Then follow the usual steps for using third-party modules in proftpd:

      ./configure --with-modules=mod_counter

To build `mod_counter` as a DSO module:

      ./configure --enable-dso --with-shared=mod_counter

Then follow the usual steps:

      make
      make install

For those with an existing ProFTPD installation, you can use the `prxs` tool to add `mod_counter`, as a DSO module, to your existing server:

      # prxs -c -i -d mod_counter.c

## Usage

The `mod_counter` module pays attention to the following FTP commands:

- `APPE`
- `DELE`
- `RETR`
- `RNFR`
- `RNTO`
- `STOR`

This means, for example, that you can use `mod_counter` to prevent an uploaded file from being deleted or renamed before the uploading client has finished the upload by using:

      <IfModule mod_counter.c>
        CounterEngine on
        CounterFile /var/proftpd/counter.txt

        # Allow only one client at a time to be writing (including deletes and renames) to a given file.
        CounterMaxWriters 1
      </IfModule>

Likewise, if for some reason you need to limit the number of clients which can be downloading a given file at the same time, you would use the `CounterMaxReaders` directive:

      <IfModule mod_counter.c>
        CounterEngine on
        CounterFile /var/proftpd/counter.txt

        # Allow only three clients at a time to be reading the same file
        CounterMaxReaders 3
      </IfModule>

© Copyright 2004-2017 TJ Saunders
All Rights Reserved