1ext_time_quota_acl(8) System Manager's Manual ext_time_quota_acl(8)
2
6 ext_time_quota_acl - Squid time quota external acl helper.
7 Version 1.0
9
11 ext_time_quota_acl [-b database] [-l logfile] [-d] [-p pauselen] [-h]
12 configfile
13
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 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
24 -b database
25 Filename of persistent database. This defaults to
26 ext_time_quota.db in Squids state directory.
27 -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 -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 -d Enables debug logging in the logfile.
40 -h show a short command line help.
42 configfile
44 This file contains the definition of the time budgets for the
45 users.
46
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 # user budget / period
55 john 8h / 1d
56 littlejoe 1h / 1d
57 babymary 30m / 1w
58 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 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 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 Here is an example.
70 # 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 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 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 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
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 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 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
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 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 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 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
143 The following ideas could further improve this helper. Maybe someone
144 wants to help? Any support or feedback is welcome!
145 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 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
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 This program and documentation is copyright to the authors named above.
167 Distributed under the GNU General Public License (GNU GPL) version 2 or
169 later (GPLv2+).
170
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
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 Report bugs or bug fixes using https://bugs.squid-cache.org/
181 Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-
183 cache.org>
184 Report ideas for new improvements to the Squid Developers mailing list
186 <squid-dev@lists.squid-cache.org>
187
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 22 March 2011 ext_time_quota_acl(8)