1ext_time_quota_acl(8)       System Manager's Manual      ext_time_quota_acl(8)
2
3
4

NAME

6       ext_time_quota_acl - Squid time quota external acl helper.
7
8       Version 1.0
9

SYNOPSIS

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

DESCRIPTION

15       ext_time_quota_acl allows an administrator to define time  budgets  for
16       the users of squid to limit the time using squid.
17
18       This  is  useful for corporate lunch time allocations, wifi portal pay-
19       per-minute installations or for parental control of children.  The  ad‐
20       ministrator can define a time budget (e.g. 1 hour per day) which is en‐
21       forced through this helper.
22

OPTIONS

24       -b database
25              Filename   of   persistent   database.    This    defaults    to
26              ext_time_quota.db in Squids state directory.
27
28       -p pauselen
29              Pauselen  is given in seconds and defines the period between two
30              requests to be treated as part  of  the  same  session.   Pauses
31              shorter  than  this  value  will  be  counted against the quota,
32              longer ones ignored.  Default is 300 seconds (5 minutes).
33
34       -l logfile
35              Filename where all logging and  debugging  information  will  be
36              written. If none is given, then stderr will be used and the log‐
37              ging will go to Squids main cache.log.
38
39       -d     Enables debug logging in the logfile.
40
41       -h     show a short command line help.
42
43       configfile
44              This file contains the definition of the time  budgets  for  the
45              users.
46

CONFIGURATION

48       The  time  quotas of the users are defined in a text file typically re‐
49       siding in /etc/squid/time_quota. Any line starting with "#" contains  a
50       comment and is ignored. Every line must start with a user followed by a
51       time budget and a corresponding time period separated by "/".  Here  is
52       an example file:
53
54              # user budget / period
55              john 8h / 1d
56              littlejoe 1h / 1d
57              babymary 30m / 1w
58
59       John  has a time budget of 8 hours every day, littlejoe is only allowed
60       1 hour and the poor babymary only 30 minutes a week.
61
62       You can use "s" for seconds, "m" for minutes, "h" for  hours,  "d"  for
63       days and "w" for weeks. Numerical values can be given as integer values
64       or with a fraction. E.g. "0.5h" means 30 minutes.
65
66       This helper is configured in squid.conf using the external_acl_type di‐
67       rective then access controls which use it to allow or deny.
68
69       Here is an example.
70
71              # Ensure that users have a valid login. We need their username.
72              acl users proxy_auth REQUIRED
73              http_access deny !users
74              # Define program and quota file
75              external_acl_type   time_quota   ttl=60   children-max=1  %LOGIN
76              /usr/libexec/ext_time_quota_acl /etc/squid/time_quota
77              acl noquota src all
78              acl time_quota external time_quota
79              deny_info ERR_ACL_TIME_QUOTA_EXCEEDED noquota
80              http_access deny !time_quota noquota
81
82       In this example, after restarting Squid it should allow access only for
83       users as long as they have time budget left.  If the budget is exceeded
84       the user will be presented with an error page informing them.
85
86       In this example we use separate users access control and noquota ACL in
87       order  to  keep the username and password prompt and the quota-exceeded
88       messages separated.
89
90       User is just a unique key value. The above example uses %LOGIN and  the
91       username  but  any  of the external_acl_type format tags can be substi‐
92       tuted in its place.  %EXT_TAG , %LOGIN , %IDENT , %EXT_USER  ,  %SRC  ,
93       %SRCEUI48  , and %SRCEUI64 are all likely candidates for client identi‐
94       fication.  The Squid wiki  has  more  examples  at  https://wiki.squid-
95       cache.org/ConfigExamples.
96

LIMITATIONS

98       This  helper only controls access to the Internet through HTTP. It does
99       not control other protocols, like VOIP, ICQ, IRC, FTP,  IMAP,  SMTP  or
100       SSH.
101
102       Desktop browsers are typically able to deal with authentication to HTTP
103       proxies like squid .  But more and more different programs and  devices
104       (smartphones, games on mobile devices, ...) are using the Internet over
105       HTTP. These devices are often not able to work through an  authenticat‐
106       ing  proxy.  Means other than %LOGIN authentication are required to au‐
107       thorize these devices and software.
108
109       A more general control to Internet access could be a captive portal ap‐
110       proach  (such  as  pfSense  or  ChilliSpot)  using  %SRC, %SRCEUI48 and
111       %SRCEUI64 as keys or maybe a 802.11X solution. But the latter is  often
112       not supported by mobile devices.
113

IMPLEMENTATION

115       When  the  helper is called it will be asked if the current user is al‐
116       lowed to access squid. The helper will reduce the remaining time budget
117       of  this  user and return OK if there is budget left. Otherwise it will
118       return ERR .
119
120       The ttl=N parameter in squid.conf determines how often the helper  will
121       be  called, the example config uses a 1 minute TTL.  The interaction is
122       that Squid will only call the helper on new requests if there has  been
123       more  than  TTL seconds passed since last check.  This handling creates
124       an amount of slippage outside the quota by whatever amount  is  config‐
125       ured.   TTL can be set as short as desired, down to and including zero.
126       Though values of 1 or more are recommended due to a quota resolution of
127       one second.
128
129       If  the  configured  time  period (e.g. "1w" for babymary) is over, the
130       time budget will be restored to the configured value thus allowing  the
131       user to access squid with a fresh budget.
132
133       If  the  time  between  the current request and the previous request is
134       greater than pauselen (default 5 minutes and  adjustable  with  command
135       line  parameter  -p  ), the current request will be considered as a new
136       request and the time budget will not be decreased. If the time is  less
137       than  pauselen  ,  then both requests will be considered as part of the
138       same active time period and the time budget will be  decreased  by  the
139       time  difference.  This allows the user to take arbitrary breaks during
140       Internet access without losing their time budget.
141

FURTHER IDEAS

143       The following ideas could further improve this  helper.  Maybe  someone
144       wants to help? Any support or feedback is welcome!
145
146       There should be a way for a user to see their configured and remaining
147              time  budget.  This could be realized by implementing a web page
148              accessing the database of the helper showing  the  corresponding
149              data. One of the problems to be solved is user authentication.
150
151       We could always return "OK" and use the module simply as an Internet
152              usage tracker showing who has stayed how long in the WWW.
153

AUTHOR

155       This  program  and  documentation  was  written  by  Dr. Tilmann Bubeck
156       <t.bubeck@reinform.de>
157
159        * Copyright (C) 1996-2023 The Squid Software Foundation and  contribu‐
160       tors
161        *
162        * Squid software is distributed under GPLv2+ license and includes
163        * contributions from numerous individuals and organizations.
164        * Please see the COPYING and CONTRIBUTORS files for details.
165
166       This program and documentation is copyright to the authors named above.
167
168       Distributed under the GNU General Public License (GNU GPL) version 2 or
169       later (GPLv2+).
170

QUESTIONS

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

REPORTING BUGS

176       Bug  reports  need  to  be  made  in  English.  See https://wiki.squid-
177       cache.org/SquidFaq/BugReporting for details of what you need to include
178       with your bug report.
179
180       Report bugs or bug fixes using https://bugs.squid-cache.org/
181
182       Report  serious  security  bugs  to Squid Bugs <squid-bugs@lists.squid-
183       cache.org>
184
185       Report ideas for new improvements to the Squid Developers mailing  list
186       <squid-dev@lists.squid-cache.org>
187

SEE ALSO

189       squid(8), GPL(7),
190       The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq
191       The Squid Configuration Manual http://www.squid-cache.org/Doc/config/
192
193
194
195                                 22 March 2011           ext_time_quota_acl(8)
Impressum