Ubuntu Manpage: ext_time_quota_acl - Squid time quota external acl helper.

Provided by: squid-openssl_5.9-0ubuntu0.22.04.2_amd64

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 values 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 substituted in its place. %EXT_TAG , %LOGIN ,
%IDENT , %EXT_USER , %SRC , %SRCEUI48 , and %SRCEUI64 are all likely candidates for client
identification. 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 including 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

        * Copyright (C) 1996-2023 The Squid Software Foundation and contributors
        *
        * Squid software is distributed under GPLv2+ license and includes
        * contributions from numerous individuals and organizations.
        * Please see the COPYING and CONTRIBUTORS files for details.

       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@lists.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@lists.squid-cache.org>

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