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

Discussion:

Dr. Tilmann Bubeck

2011-04-04 20:44:11 UTC

Hello!

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
GPL2+.

The patch is against Squid3 (http://bzr.squid-cache.org/bzr/squid3/trunk).

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

Kind regards,
Tilmann Bubeck

---------%-<------------------

ext_time_quota_acl(8) 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] configfile

DESCRIPTION
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.

OPTIONS
-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.

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

USER AUTHENTICATION
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
/etc/squid/passwd
#
# 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.

DEFINING TIME QUOTAS
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
file:

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

CONFIGURATION
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
authentication.

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

LOGGING
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.

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 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
devices.

IMPLEMENTATION
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
budget.

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.

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 its 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 staid how long in the
WWW.

AUTHOR
This program and documentation was written by Dr. Tilmann
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-***@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-***@squid-
cache.org>

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

SEE ALSO
squid(8), basic_ncsa_auth(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)
--
+-------+-------------------------------------------------------------+
| | 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: ***@reinform.de http://www.reinform.de |
| +-------------------------------------------------------------+
| | pflichtangaben nach paragraph 80, AktG: |
| | reinform medien- und informationstechnologie AG, stuttgart |
| | handelsregister stuttgart, HRB 23001 |
| | vorstand: dr. tilmann bubeck (vorsitz) |
| | aufsichtsrat: frank stege (vorsitz) |
+-------+-------------------------------------------------------------+

Amos Jeffries

2011-04-05 02:00:06 UTC

Permalink

Post by Dr. Tilmann Bubeck
Hello!
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 GPL2+.
The patch is against Squid3
(http://bzr.squid-cache.org/bzr/squid3/trunk).
I appreciate any feedback and I am willing to support the helper in
the future.

Thank you.

ext_time_quota_acl.8:
* I don't think we need to mention the parental controls use-case in
the manual. That is likely to be a minor use, the more common usages
will be likely corporate "lunch-time" allocations and wifi portal
pay-per-minute installations.

* Please mention for -l that the default is to use stderr for logging
to Squids main cache.log.

* the section on setting up authentication can also go. Along with the
SEE ALSO reference to the specific NCSA helper.

Username is just a unique key value. Any of the external_acl_type
format tags can be substituted in its place. %EXT_TAG, %LOGIN, %IDENT,
%EXT_USER, %SRC and the %SRCEUI* ones are all likely to be popular. The
wiki ConfigExamples or Feature auth section can be referenced instead of
re-writing.

* Your error message makes use of the name "key" as in "key too long".
This should be reflected in the manual page mentioning that the %LOGIN
etc is the relevant key.
NP: making mention of those above tags as options for the "key" also
removes the need for the paragraph on IDENT starting "For Unix
machines" (which is wrong, all modern OS have IDENT available in one way
or another).

* the section on defining the quotas config file should go under
"CONFIGURATION".

* under "IMPLEMENTATION" you state the helper is "called once every
minute". This is wrong. Please mention instead that the ttl=N parameter
determines this time period, the example config uses 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. So the
correct description is: "at most once per TTL period".
It would also be worth mentioning that TTL creates an amount of
slippage outside the quota by whatever amount. 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.

ext_time_quota_acl.cc:

* Please document that "-h" is available for command line help. In
both the manual and the usage() display.

* Accepting '-?' option as an alternative to -h is not necessary. If
used it will default.

* Please add the "-d" option setting a global "int debug_enabled" to
enable/disable debugging level information in the log.

* Please place the program_name before the FATAL/ERROR/WARNING label.
What it should look like in the log is:
<timestamp> ext_time_quota_acl| ERROR: blah...

* The '-b' option can be made optional by passing a default database
path from the Makefile.am like this:
DEFS += -DDEFAULT_QUOTA_DB=\"$(localstatedir)/ext_time_quota.db\"
Which makes the string macro DEFAULT_QUOTA_DB available in the .cc

Extra ideas:

* Since we last spoke I've been thinking about the pauseLength. I have
come to the conclusion that this should be made configurable from the
command line. 300 is reasonable as a default, but may not always suit.
Please add that.

* If you want to emit the remaining time like this:
SEND_OK("message=\"Remaining quota: 35 seconds\""); we can separately
update the cachemgr reports to display the ACL cache contents and get a
report of the quotas values.

Amos

Alex Rousskov

2011-04-05 15:08:44 UTC

Permalink

Post by Amos Jeffries

* I don't think we need to mention the parental controls use-case in
the manual. That is likely to be a minor use, the more common usages
will be likely corporate "lunch-time" allocations and wifi portal
pay-per-minute installations.

Still, mentioning parental controls may be a good idea because it
provides rationale for some of the design decisions and configuration
examples.

FWIW, I would mention _all_ of the above possible use cases so that
folks searching for what _they_ need have more chances of finding this
useful extension.

$0.02,

Alex.

Dr. Tilmann Bubeck

2011-04-06 06:01:42 UTC

Permalink

Hello!

thanks for the various hints and tips. Please find attached an updated
version of the patch. I hope that I did everything OK, and did not
forget anything.

In any case, your comment is very welcome!

Kind regards,
Till

Post by Alex Rousskov

Post by Amos Jeffries

Still, mentioning parental controls may be a good idea because it
provides rationale for some of the design decisions and configuration
examples.
FWIW, I would mention _all_ of the above possible use cases so that
folks searching for what _they_ need have more chances of finding this
useful extension.
$0.02,
Alex.

Amos Jeffries

2011-04-06 09:57:24 UTC

Permalink

Post by Dr. Tilmann Bubeck
Hello!
thanks for the various hints and tips. Please find attached an updated
version of the patch. I hope that I did everything OK, and did not
forget anything.
In any case, your comment is very welcome!
Kind regards,
Till

templates/ERR_TIME_QUOTA_EXCEEDED:

* Please model this quota exceeded message on ERR_TOO_BIG. That means ...

** "The system returned: %E" can be erased. There is no
operating system error to display.

** "This means:" can be erased. Without the system error there
is nothing technical to be explained.

** The explanation would be better saying this:

This proxy limits your time online with a quota. Your time budget is
now empty but will be refilled when the configured time period starts
again.
These limits have been established by the Internet Service Provider
who operates this cache. Please contact them directly if you feel this
is an error.
Your cache administrator is <a href="mailto:%w%W">%w</a>.

ext_time_quota_acl.8:

* Please check the attached version is okay with you.

Amos

--
Please be using
Current Stable Squid 2.7.STABLE9 or 3.1.12
Beta testers wanted for 3.2.0.6

Dr. Tilmann Bubeck

2011-04-06 10:07:39 UTC

Permalink

Amos,

thanks a lot for your valuable feedback and corrections. All changes are
more than OK to me. It would be great, if "time quota" could get a part
of Squid.

Feel free to apply or ask for any further changes.

Kind regards,
Till

Post by Amos Jeffries

* Please model this quota exceeded message on ERR_TOO_BIG. That means ...
** "The system returned: %E" can be erased. There is no
operating system error to display.
** "This means:" can be erased. Without the system error there is
nothing technical to be explained.
This proxy limits your time online with a quota. Your time budget is
now empty but will be refilled when the configured time period starts
again.
These limits have been established by the Internet Service Provider
who operates this cache. Please contact them directly if you feel this
is an error.
Your cache administrator is <a href="mailto:%w%W">%w</a>.
* Please check the attached version is okay with you.
Amos