Apache::Quota - Flexible transfer limiting/throttling under mod_perl
PerlSetVar QuotaFile /tmp/Apache-Quota.db
PerlSetVar QuotaLocker BerkeleyDB
PerlSetVar QuotaLocationKey foo
PerlSetVar QuotaType client-ip
PerlSetVar QuotaPeriod 1d
PerlSetVar QuotaLimit 3M
PerlSetVar QuotaOnExceed notes
PerlSetVar QuotaLocationKey bar
PerlSetVar QuotaType sub
PerlSetVar QuotaSub "MyApp::get_user_id"
PerlSetVar QuotaPeriod 60s
PerlSetVar QuotaLimit 500k
PerlSetVar QuotaOnExceed deny
This module provides flexible transfer quotas for all or part of a site. Additionally, quotas may be enforced for the site as a whole, on a per-client IP basis, or based on some other criterion you define.
Most of this module's functionality is used by setting variables via the mod_perl PerlSetVar directive. The module should be installed as a PerlFixupHandler in a Location or similar Apache configuration block.
The following directives are available:
The DB file where quota usage will be recorded. A single file can be shared across multiple locations.
This sets the quota limit. This can be a plain number, which will be interpreted as bytes, or a number followed by a letter. The valid letters are "k/K" (kilobytes), "m/M" (megabytes), or "g/G" (gigabytes). This module defines a kilobyte as 1024 bytes, a megabyte as 1024 ** 2 bytes, and a gigabyte as 1024 ** 3 bytes.
This sets the time period for which a quota is enforced. This can be a number, which will be interpreted as seconds, or a number followed by a letter. The valid letters are "s/S" (seconds), "m/M" (minutes), "h/H" (hours), or "d/D" (days).
This can be one of "global", "client-ip", or "sub". If it is set to "global", then the bandwidth limit is shared across all clients accessing the particular location.
If it is set to "client-ip", then quota usage is tracked on a per client IP address basis. Of course, given the presence of proxies, this may not actually correspond to a single client.
If it is set to "sub", then the module will call a user-specified subroutine to generate the unique identifier for the client. One way to use this would be to have it call a subroutine that gets a unique id from a cookie or uses $r->user().
This parameter defaults to "global".
This is the subroutine that should be called if QuotaType is set to "sub". This should simply be a string like "MyApp::quota_key". This parameter is required if you set QuotaType to "sub".
If this is specified, then this key is used to uniquely indentify the current location. This allows you to use one quota file for multiple locations, and track quota usage for each location separately. This key can be anything, but it must not contain a colon (:).
If not given, this default to "Apache-Quota global key" for all locations.
This parameter defines what the module does when it detects that a client has exceed the quota. The two valid options are "deny" or "notes". If this is set to "deny", then the module simply returns the FORBIDDEN constant for the request. If it is set to "notes", then it sets $r->notes('Apache::Quota::exceeded') to a true value. This can be checked from your application code.
This defaults to "deny".
The locking class to use. This should be one of "BerkeleyDB" or "DB_File::Lock". Using BerkeleyDB is preferred, as it better supported and uses a much more robust locking implementation. If no locker is specified, the module will try to load BerkeleyDB and DB_File::Lock, in that order. If it cannot load either, it will die.
Setting this to a true value turns on debugging messages which are sent to the Apache log via warn().
This module also offers some functions for directly looking at and manipulating quotas. None of these functions are exportable.
All of these functions accept the following parameters:
This is the db file you want to access.
The locker class to use, "BerkeleyDB" or "DB_File::Lock".
This function returns the current usage values in the form of a hash.
It takes an additional optional parameter, "period". If given, this will be used to determine which entries to ignore. This can be any value which is valid for the "QuotaPeriod" parameter.
The has returned is keyed on the "full key" used by Apache::Quota internally. This should be treated as an opaque value, and is returned only so that you can pass it back to the set_key() or reset_key() functions later.
The hash values are hash references. Each reference always contains the key "bytes", which is the total number of bytes used by the user/client identified by the "full key".
The other keys in the hash reference varies depending on whether the QuotaType parameter was set to "global", "client", or "sub". If it was set to "global", then there are no other keys. If the type was set to "client-ip", then the other key is "ip", and contains the client's IP address. If the type was set to "sub", then the other key is "sub", and contains the value returned by the subroutine you provided.
This function requires two additional parameters, "key" and "value". The key should be a "full key", as returned by the usage() function. The value should be a number, which will be the new number of bytes for the key. All historical values will be wiped out, and the number value will be set, along with the current time.
If the key is not in the db file, then this method returns a false value.
This function requires a "key" parameter. This completely resets usage information for the given key.
Please submit bugs to the CPAN RT system at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Apache%3A%3AQuota or via email at firstname.lastname@example.org.
Dave Rolsky <email@example.com>
Copyright (c) 2003 David Rolsky. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
The Apache modules mod_bandwidth and mod_throttle.
To install Apache::Quota, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.