Minimum version required

The features described on this page require EZproxy 3.4a GA (2005-08-02) or later.


UsageLimit is a position-dependent config.txt/ezproxy.cfg option that interacts with database definitions.

UsageLimit is used to detect when a user is downloading an excessive amount of content and automatically suspend the user's access. When a user's access is suspended and that user tries to access content through EZproxy, EZproxy sends the file suspend.htm from the docs directory under the directory where EZproxy is installed to the remote user. If you are going to enforce limits, you should create suspend.htm and provide information to tell users what to do if they have encountered this limit, particularly during early configuration when your limits may be too strict to meet the actual needs of your users.

A UsageLimit is evaluated based on the username used to log into EZproxy and apply across all user sessions. If you use CGI authentication, your CGI authentication must be configured to provide username information to EZproxy for UsageLimits to work properly.

UsageLimit -end -enforce -expires= 120 -interval= 60 -local -MB= 100 -transfers= 100 name

The options each have a hyphen (-) in front of their names. You can include or omit any option. The only required component of a UsageLimit is its name that appears at the very end of the directive.

The -end option specifies that this UsageLimit should not consider activity for any of the database that follow in config.txt/ezproxy.cfg. Use this if you only want a UsageLimit to apply to certain databases.

The -enforce option specifies that accounts that exceed the -MB or -transfers threshhold with -interval minutes should be suspended. If this option is not specified, usage is monitored but users who exceed the thresholds are not denied access. As a safety precaution, the access for EZproxy administrators is never suspended.

The -expires option specifies that if a user's account is suspended, the suspension should automatically clear after the number of minutes specified have elapsed. If -expires not specified, a suspended account remains suspended until the EZproxy administrator clears the suspension. See EZproxy Administration for information on how to access the EZproxy administration page.

The -interval option specifies the interval over which to consider the -MB or -transfers limits. For example, with -interval=60, the number of transfers or the megabytes transferred would have to exceed the limit within the past 60 minutes for suspension to occur. If no -interval is specified, the default is 1440 minutes (one day).

The -local option specifies that access to local EZproxy pages, including the menu page or pages served from the /public, /limited, or /loggedin directries, should be counted with this limit.

The -MB specifies the threshold of the number of megabytes of data transfer at which account access should be suspended.

The -transfers specifies the number of page requests at which account access should be suspended.


To start out, you can simply monitor EZproxy by adding:

UsageLimit Global

The choice of Global for the usage limit name is completely arbitrary. This limit will monitor usage information over the past 1440 minutes (day). Accounts will not be suspended. Requests for information that come directly from EZproxy are not included.

If you decide that a user should not transfer more than 100MB per day, you can start by using:

UsageLimit -MB=100 Global

This will only monitor use, not suspend access. If user rdoe exceeds this limit, a message like this will be recorded in messages.txt/ezproxy.msg:

2005-08-01 09:00:00 Global 0.001MB usage limit exceeded by rdoe

Once you are ready to enforce a limit, you need to add the -enforce option, such as:

UsageLimit -enforce -MB=100 Global

With this in place, if a user exceeds this limit, the user will be unable to access EZproxy until you clear his/her suspension through the EZproxy administration page. If you want the suspension to expire automatically after 360 minutes (six hours), you could use:

UsageLimit -enforce -expires=360 -MB=100 Global

When you specify an expiration period, you can still manually clear the suspension manually using the administration page.

In a more complicated example, we will impose two separate limits, one arbitrarily named Global and the other arbitrarily named Selective. Global will impose a 100MB limit on all databases. Selective will impose a limit allowing only a total of 500 transfers that occur to either Some Database or Another Database. Some Database and Another Database are not adjacent. The Global limit will require manual resetting, but the Selective limit will automatically reset after 180 minutes (three hours). For this, you could use:

UsageLimit -enforce -MB=100 Global
UsageLimit -enforce -expires=180 -transfers=500 Selective
Title Some Database
UsageLimit -end Selective
Title Other Database
# You do not need to repeat the options when applying an existing limit
# to more databases
UsageLimit Selective
Title Another Database
UsageLimit -end Selective

In this configuration, users who transfer more than 100MB of data from any combination of databases, or users who transfer more than 500 pages from any combination of Some Database and Another Database, will have their access suspended. The Selective limit will not apply to any access to Other Database, nor will it apply to access to additional databases that appear further down in config.txt/ezproxy.cfg.

Advanced Example

An example of how to combine all of the security features of EZproxy appears at Securing Your EZproxy Server .

See also