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

Provided by: squid-openssl_6.10-0ubuntu0.24.04.1_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 https://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 https://wiki.squid-cache.org/SquidFaq/BugReporting for
       details of what you need to include with your bug report.

       Report bugs or bug fixes using https://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>