ext_time_quota_acl(8)					      System Manager's Manual					     ext_time_quota_acl(8)

NAME

       ext_time_quota_acl - Squid time quota external acl helper.

       Version 1.0

SYNOPSIS

       ext_time_quota_acl [-b database] [-l logfile] [-d] [-p pauselen] [-h] configfile

DESCRIPTION

       ext_time_quota_acl allows an administrator to define time budgets for the users of squid to limit the time using squid.

       This  is  useful  for  corporate  lunch time allocations, wifi portal pay-per-minute installations or for parental control of children. The
       administrator can define a time budget (e.g. 1 hour per day) which is enforced through this helper.

OPTIONS

       -b database
	      Filename of persistent database. This defaults to ext_time_quota.db in Squids state directory.

       -p pauselen
	      Pauselen is given in seconds and defines the period between two requests to be treated as part of the same session.  Pauses  shorter
	      than this value will be counted against the quota, longer ones ignored.  Default is 300 seconds (5 minutes).

       -l logfile
	      Filename	where  all  logging  and debugging information will be written. If none is given, then stderr will be used and the logging
	      will go to Squids main cache.log.

       -d     Enables debug logging in the logfile.

       -h     show a short command line help.

       configfile
	      This file contains the definition of the time budgets for the users.

CONFIGURATION

       The time quotas of the users are defined in a text file typically residing in /etc/squid/time_quota. Any line starting with "#" contains  a
       comment	and is ignored. Every line must start with a user followed by a time budget and a corresponding time period separated by "/". Here
       is an example file:

	      # user budget / period
	      john 8h / 1d
	      littlejoe 1h / 1d
	      babymary 30m / 1w

       John has a time budget of 8 hours every day, littlejoe is only allowed 1 hour and the poor babymary only 30 minutes a week.

       You can use "s" for seconds, "m" for minutes, "h" for hours, "d" for days and "w" for weeks. Numerical values can be given as integer  val-
       ues or with a fraction. E.g. "0.5h" means 30 minutes.

       This helper is configured in squid.conf using the external_acl_type directive then access controls which use it to allow or deny.

       Here is an example.

	      # Ensure that users have a valid login. We need their username.
	      acl users proxy_auth REQUIRED
	      http_access deny !users
	      # Define program and quota file
	      external_acl_type time_quota ttl=60 children-max=1 %LOGIN /usr/libexec/ext_time_quota_acl /etc/squid/time_quota
	      acl noquota src all
	      acl time_quota external time_quota
	      deny_info ERR_ACL_TIME_QUOTA_EXCEEDED noquota
	      http_access deny !time_quota noquota

       In  this  example,  after  restarting  Squid it should allow access only for users as long as they have time budget left.  If the budget is
       exceeded the user will be presented with an error page informing them.

       In this example we use separate users access control and noquota ACL in order to keep the username  and	password  prompt  and  the  quota-
       exceeded messages separated.

       User is just a unique key value. The above example uses %LOGIN and the username but any of the external_acl_type format tags can be substi-
       tuted in its place.  %EXT_TAG , %LOGIN , %IDENT , %EXT_USER , %SRC , %SRCEUI48 , and %SRCEUI64 are all likely candidates for client identi-
       fication.  The Squid wiki has more examples at http://wiki.squid-cache.org/ConfigExamples.

LIMITATIONS

       This helper only controls access to the Internet through HTTP. It does not control other protocols, like VOIP, ICQ, IRC, FTP, IMAP, SMTP or
       SSH.

       Desktop browsers are typically able to deal with authentication to HTTP proxies like squid .  But more  and  more  different  programs  and
       devices	(smartphones,  games on mobile devices, ...) are using the Internet over HTTP. These devices are often not able to work through an
       authenticating proxy.  Means other than %LOGIN authentication are required to authorize these devices and software.

       A more general control to Internet access could be a captive portal approach (such as pfSense or  ChilliSpot)  using  %SRC,  %SRCEUI48  and
       %SRCEUI64 as keys or maybe a 802.11X solution. But the latter is often not supported by mobile devices.

IMPLEMENTATION

       When the helper is called it will be asked if the current user is allowed to access squid. The helper will reduce the remaining time budget
       of this user and return OK if there is budget left. Otherwise it will return ERR .

       The ttl=N parameter in squid.conf determines how often the helper will be called, the example config uses a 1 minute TTL.  The  interaction
       is  that  Squid	will  only call the helper on new requests if there has been more than TTL seconds passed since last check.  This handling
       creates an amount of slippage outside the quota by whatever amount is configured.  TTL can be set as short as desired, down to and  includ-
       ing zero.  Though values of 1 or more are recommended due to a quota resolution of one second.

       If  the configured time period (e.g. "1w" for babymary) is over, the time budget will be restored to the configured value thus allowing the
       user to access squid with a fresh budget.

       If the time between the current request and the previous request is greater than pauselen (default 5 minutes and  adjustable  with  command
       line parameter -p ), the current request will be considered as a new request and the time budget will not be decreased. If the time is less
       than pauselen , then both requests will be considered as part of the same active time period and the time budget will be decreased  by  the
       time difference. This allows the user to take arbitrary breaks during Internet access without losing their time budget.

FURTHER IDEAS

       The following ideas could further improve this helper. Maybe someone wants to help? Any support or feedback is welcome!

       There should be a way for a user to see their configured and remaining
	      time  budget. This could be realized by implementing a web page accessing the database of the helper showing the corresponding data.
	      One of the problems to be solved is user authentication.

       We could always return "OK" and use the module simply as an Internet
	      usage tracker showing who has stayed how long in the WWW.

AUTHOR

       This program and documentation was written by Dr. Tilmann Bubeck <t.bubeck@reinform.de>

COPYRIGHT

       This program and documentation is copyright to the authors named above.

       Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

QUESTIONS

       Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@squid-cache.org>

REPORTING BUGS

       Bug reports need to be made in English.	See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with
       your bug report.

       Report bugs or bug fixes using http://bugs.squid-cache.org/

       Report serious security bugs to Squid Bugs <squid-bugs@squid-cache.org>

       Report ideas for new improvements to the Squid Developers mailing list <squid-dev@squid-cache.org>

SEE ALSO

       squid(8), GPL(7),
       The Squid FAQ wiki http://wiki.squid-cache.org/SquidFaq
       The Squid Configuration Manual http://www.squid-cache.org/Doc/config/

								   22 March 2011					     ext_time_quota_acl(8)