Patch for external_acl "time quota" to limit squid access (parental control)

From: Dr. Tilmann Bubeck <>
Date: Mon, 04 Apr 2011 22:44:11 +0200


please find attached a patch for a new external_acl helper to limit
access time to squid.

The main purpose is for parental control to limit access to the internet
for children. You can configure something like "littlejoe 1h/1d" which
means, that littlejoe has a time quota of 1 hour every day.

The helper must be used together with proxy_auth or ident
authentication, so that the identity of the user is proved. It comes
with a detailled manual page which I converted to text and included
below to get an idea of the stuff.

Please integrate this helper into the squid distribution. The license is

The patch is against Squid3 (

I appreciate any feedback and I am willing to support the helper in the

Kind regards,
  Tilmann Bubeck


ext_time_quota_acl(8) ext_time_quota_acl(8)

        ext_time_quota_acl - Squid time quota external acl helper.

        Version 1.0

        ext_time_quota_acl [-b database] [-l logfile] configfile

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

        The primary use is for parental control for children. The
        parents can define a time budget (e.g. 1 hour per day) which
        is enforced through this helper.

        -b database
               Filename of persistent database. If not specified the
               available and used time budgets will be kept in memory
               only and will reset each time Squid restarts it's
               helpers (Squid restart or rotation of logs).

        -l logfile
               Filename to a log file where all logging and debugging
               information will be written.

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

        This helper needs to know the identity of the user to asso‐
        ciate a time budget with this user. Currently only proxy_auth
        is able to deliver this information. The following paragraph
        gives a short overview of a very basic setup using
        "basic_ncsa_auth". More different options and a complete and
        detailed explanation can be found in the Squid user manual.

        Start by setting up a file containing usernames and the cor‐
        responding passwords. Use the htpasswd program coming with
        Apache to enter the data and repeat this step for all users.

               root# htpasswd /etc/squid/passwd john
               New password: johnssecret
               Re-type new password: johnssecret
               Adding password for user john

        Edit squid.conf to define a basic authentication program
        called "basic_ncsa_auth", which authenticates users with the
        above password file. Define a ACL using that program and deny
        access to web pages for unautenticated users.

               # Define program and password file for auth.
               auth_param basic program /usr/libexec/basic_ncsa_auth
               # Define ACL
               acl authenticated_users proxy_auth REQUIRED
               # Deny access for unauthenticated users
               http_access deny !authenticated_users

        After restarting Squid it should allow access only for
        authenticated users with the configured names and passwords.
        All other users will be rejected.

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

               # username 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

        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

        This helper is also configured in squid.conf where you first
        declare the helper, then define a ACL which then decides when
        to allow or deny. Enter the following text after the user

               # Define program and quota file
               external_acl_type time_quota ttl=60 children-max=1
               %LOGIN /usr/libexec/ext_time_quota_acl -b
               /var/run/squid/time_quota.db /etc/squid/time_quota
               # Define ACL for time_quota helper
               acl time_quota external time_quota
               # Deny access if quota exceeded
               http_access deny !time_quota
               # If quota exceeds, tell user
               deny_info TIME_QUOTA_EXCEEDED time_quota

        After restarting Squid it should allow access only for
        authenticated users as long as they have time budget left. If
        the buget is exceeded or an invalid username or password is
        given, the user will be prompted for a correct username and
        password having time quota left.

        For Unix machines it should be possible for the parents to
        authenticate using ident so that they always have access to
        the internet even without supplying user names and passwords.
        If this "falls through", then the above helper would be
        called. This could be done by something like "http_access
        allow ident" with a correct ident configuration. This is out
        of scope of this manual page.

        Whenever you hit a problem, then start the helper with -l
        logfile (e.g. "-l /tmp/time_quota.log") and look into that
        log file to find any problem.

        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 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. Sometimes one can sucess‐
        fully use the internet browser on those devices but often
        online games and other stuff fails.

        A more general control to internet access could be a captive
        portal (like pfSense or ChilliSpot) or maybe a 802.11X solu‐
        tion. But the latter is often not supported by mobile

        The helper is called once a minute and 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".

        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

        If the time between the current request and the previous
        request is greater than 5 minutes, the current request will
        be considered as a new request and the time budget will not
        be decreased. If the time is less than 5 minutes, than both
        request will be considered as part of the same active time
        period and the time budget will be decreased by the time dif‐
        ference. This allows the user to make arbitrary breaks during
        internet access without decreasing the time budget.

        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 its configured and
               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
               usage tracker showing who has staid how long in the

        This program and documentation was written by Dr. Tilmann
        Bubeck <>

        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 on the usage of this program can be sent to the
        Squid Users mailing list <>

        Bug reports need to be made in English. See for details
        of what you need to include with your bug report.

        Report bugs or bug fixes using

        Report serious security bugs to Squid Bugs <squid-bugs_at_squid->

        Report ideas for new improvements to the Squid Developers
        mailing list <>

        squid(8), basic_ncsa_auth(8), GPL(7),
        The Squid FAQ wiki
        The Squid Configuration Manual http://www.squid-

                             22 March 2011 ext_time_quota_acl(8)

|       | dr. tilmann bubeck               reinform medien- und       |
|       |                                  informationstechnologie AG |
| rein  | fon  : +49 (711) 7 82 76-52      loeffelstr. 40             |
| form  | fax  : +49 (711) 7 82 76-46      70597 stuttgart / germany  |
|    AG | cell.: +49 (172) 8 84 29 72      fon: +49 (711) 75 86 56-10 |
|       | email:     |
|       +-------------------------------------------------------------+
|       | pflichtangaben nach paragraph 80, AktG:                     |
|       | reinform medien- und informationstechnologie AG, stuttgart  |
|       | handelsregister stuttgart, HRB 23001                        |
|       | vorstand:     dr. tilmann bubeck (vorsitz)                  |
|       | aufsichtsrat: frank stege (vorsitz)                         |

Received on Mon Apr 04 2011 - 21:02:29 MDT

This archive was generated by hypermail 2.2.0 : Tue Apr 05 2011 - 12:00:04 MDT