mod_shaper
The mod_shaper module is designed to split overall rates, both
download and upload, for the proftpd daemon among all connected
FTP clients, shaping each session to use only a portion of the overall rate.
mod_shaper shapes both transmitted traffic,
e.g. bits being downloaded via the RETR command, and
received traffic, e.g. bits being uploaded via the
APPE, STOR, and STOU commands.
This module is contained in the mod_shaper.c file for
ProFTPD 1.2.x/1.3.x, and is not compiled by default.
Installation instructions are discussed here.
Detailed documentation on mod_shaper usage can be found
here.
The most current version of mod_shaper is distributed with the
ProFTPD source code.
Please contact TJ Saunders <tj at castaglia.org> with any questions, concerns, or suggestions regarding this module.
The ShaperAll directive is used to configure the overall
mod_shaper settings: the rate for the entire daemon, the
default shares for shaped sessions, and the default priority for shaped
sessions. If specified, the priority cannot be a negative number,
the rates are in KB/s and must be greater than zero, and the
shares must be greater than one. For configuring the priority and
shares for individual sessions, use the ShaperSession directive.
The rate parameter sets both the downrate (i.e. download rate from the server) and the uprate (i.e. the upload rate to the server) at the same time. Use downrate and uprate if you wish to configure different rates for downloads and uploads. Similarly, the shares parameter sets both downshares and upshares.
The default rate is -1.0, which means that in order for
mod_shaper to function properly, a rate, either rate,
downrate or uprate, must be specified.
The default shares setting is 5, the default priority is 10.
Examples:
# Change the overall daemon rate to 100 KB/s ShaperAll rate 100 # Give 20 shares to each session by default, and have an overall rate of 1000 ShaperAll rate 1000 shares 20 # Have a larger number of downshares than upshares ShaperAll rate 1000 downshares 2000 upshares 20 # Configure separate download and upload rates ShaperAll downrate 1000 uprate 500
See also: ShaperSession
The ShaperControlsACLs directive configures access lists of
users or groups who are allowed (or denied) the ability to
use the actions implemented by mod_shaper. 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 ShaperControlsACLs directives may be used to
configure ACLs for different control actions, and for both users and groups.
The actions provided by mod_shaper are "all",
"info", and "sess".
Examples:
# Allow only user root to alter the overall settings ShaperControlsACLs all allow user root # Allow the ftpadm group to shape current sessions ShaperControlsACLs sess allow group ftpadm # Allow everyone but user bob to see the current shaper stats ShaperControlsACLs info deny user bob
<VirtualHost>, <Global>
The ShaperEngine directive enables or disables the
"shaping" of sessions by mod_shaper. If it is set to
off this module does no shaping of transmitted traffic. Use this
directive to disable the module instead of commenting out all
mod_shaper directives.
The ShaperLog directive is used to specify a log file for
mod_shaper reporting and debugging. 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.
<VirtualHost>, <Global>, <Anonymous>
The ShaperSession directive is used to set shaping data on a
per-session basis. It is intended to be used within mod_ifsession
conditional configuration blocks. If used, the priority must not
be a negative number. The shares parameters must start with '+' or
'-'; these values adjust the default numbers of shares allotted to a
session, increasing or reducing the sessions's shares. The
ShaperAll directive is used for configuring overall shaping
data.
The shares parameter sets both the downshares (i.e. shares of the download rate) and the upshares (i.e. shares of the upload rate) at the same time. Use downshares and upshares if you wish to configure different shares for downloads and uploads for the session.
Example:
# Reward my friends ShaperSession shares +2 # Punish my enemies ShaperSession shares -4 # Allow for finer control over downloads by allocating more download # shares than upload shares for this session ShaperSession downshares +3 upshares -1 # Let <Directory>-level TransferRate directives take priority ShaperSession priority 3
See also: ShaperAll
The ShaperTable directive configures a path to a file
that mod_shaper uses for storing its shaping data. The given
path must be an absolute path. Note: this directive is
required for mod_shaper to function.
shaper all
The shaper all action is used to change the overall
mod_shaper settings on-the-fly. If specified, the
priority cannot be a negative number, the rates are in KB/s
and must be greater than zero, and the shares must be greater than
one. For changing the priority and shares for individual sessions, use the
shaper sess control action.
The rate parameter sets both the downrate (i.e. download rate from the server) and the uprate (i.e. the upload rate to the server) at the same time. Use downrate and uprate if you wish to configure different rates for downloads and uploads. Similarly, the shares parameter sets both downshares and upshares.
For example, to set the overall rate for the entire daemon to be 2000 KB/s:
ftpdctl shaper all rate 2000To give every session 10 shares, both downshares and upshares, by default:
ftpdctl shaper all shares 10To set the default priority for sessions:
ftpdctl shaper all priority 3Note that multiple parameters can also be used simultaneously:
ftpdctl shaper all rate 2000 shares 10 priority 3
See also: shaper sess
shaper info
The shaper info control action can be used to view information
on currently shaped sessions. This includes the current overall rate, the
default number of shares per session, and the total number of currently
shaped sessions. It also lists the following for each shaped session:
process ID (PID), priority, downshare ("D") and upshare
("U") adjustments, and session downrate and uprate.
Example listing:
# ftpdctl shaper info ftpdctl: Overall Rates: 1000.00 KB/s down, 500.00 KB/s up ftpdctl: Default Shares Per Session: 10 down, 10 up ftpdctl: Default Priority: 2 ftpdctl: Number of Shaped Sessions: 2 ftpdctl: PID Priority DShares DRate (KB/s) UShares URate (KB/s) ftpdctl: ----- -------- -------------- ------------ -------------- ------------ ftpdctl: 21750 2 12/24 (+2) 500.00 7/14 (-3) 250.00 ftpdctl: 21753 2 12/24 (+2) 500.00 7/14 (-3) 250.00