1.if !'po4a'hide' .TH ext_time_quota_acl 8 "22 March 2011" 2. 3.SH NAME 4ext_time_quota_acl \- Squid time quota external acl helper. 5.PP 6Version 1.0 7. 8.SH SYNOPSIS 9.if !'po4a'hide' .B ext_time_quota_acl 10.if !'po4a'hide' .B "[\-b database] [\-l logfile] [\-d] [\-p pauselen] [\-h] configfile 11. 12.SH DESCRIPTION 13.B ext_time_quota_acl 14allows an administrator to define time budgets for the users of squid 15to limit the time using squid. 16.PP 17This is useful for corporate lunch time allocations, wifi portal 18pay-per-minute installations or for parental control of children. The 19administrator can define a time budget (e.g. 1 hour per day) which is enforced 20through this helper. 21. 22.SH OPTIONS 23. 24.if !'po4a'hide' .TP 25.if !'po4a'hide' .B "\-b database" 26.B Filename 27of persistent database. This defaults to ext_time_quota.db in Squids state 28directory. 29. 30.if !'po4a'hide' .TP 31.if !'po4a'hide' .B "\-p pauselen" 32.B Pauselen 33is given in seconds and defines the period between two requests to be treated as part of the same session. 34Pauses shorter than this value will be counted against the quota, longer ones ignored. 35Default is 300 seconds (5 minutes). 36. 37.if !'po4a'hide' .TP 38.if !'po4a'hide' .B "\-l logfile" 39.B Filename 40where all logging and debugging information will be written. If none is given, 41then stderr will be used and the logging will go to Squids main cache.log. 42. 43.if !'po4a'hide' .TP 44.if !'po4a'hide' .B "\-d" 45Enables debug logging in the logfile. 46. 47.if !'po4a'hide' .TP 48.if !'po4a'hide' .B "\-h" 49show a short command line help. 50. 51.if !'po4a'hide' .TP 52.if !'po4a'hide' .B configfile 53This file contains the definition of the time budgets for the users. 54.PP 55. 56.SH CONFIGURATION 57.PP 58The time quotas of the users are defined in a text file typically 59residing in /etc/squid/time_quota. Any line starting with "#" contains 60a comment and is ignored. Every line must start with a user 61followed by a time budget and a corresponding time period separated by 62"/". Here is an example file: 63.PP 64.if !'po4a'hide' .RS 65# user budget / period 66.if !'po4a'hide' .br 67.if !'po4a'hide' .B john 8h / 1d 68.if !'po4a'hide' .br 69.if !'po4a'hide' .B littlejoe 1h / 1d 70.if !'po4a'hide' .br 71.if !'po4a'hide' .B babymary 30m / 1w 72.if !'po4a'hide' .br 73.if !'po4a'hide' .RE 74.PP 75John has a time budget of 8 hours every day, littlejoe is only allowed 761 hour and the poor babymary only 30 minutes a week. 77.PP 78You can use "s" for seconds, "m" for minutes, "h" for hours, "d" for 79days and "w" for weeks. Numerical values can be given as integer 80values or with a fraction. E.g. "0.5h" means 30 minutes. 81.PP 82This helper is configured in 83.B squid.conf 84using the 85.B external_acl_type 86directive then access controls which use it to allow or deny. 87. 88.PP 89Here is an example. 90.PP 91.if !'po4a'hide' .RS 92# Ensure that users have a valid login. We need their username. 93.if !'po4a'hide' .br 94.if !'po4a'hide' .br 95.if !'po4a'hide' .B acl users proxy_auth REQUIRED 96.if !'po4a'hide' .br 97.if !'po4a'hide' .B http_access deny !users 98.if !'po4a'hide' .br 99# Define program and quota file 100.if !'po4a'hide' .br 101.if !'po4a'hide' .B external_acl_type time_quota ttl=60 children-max=1 %LOGIN /usr/libexec/ext_time_quota_acl /etc/squid/time_quota 102.if !'po4a'hide' .br 103.if !'po4a'hide' .br 104.if !'po4a'hide' .B acl noquota src all 105.if !'po4a'hide' .br 106.if !'po4a'hide' .B acl time_quota external time_quota 107.if !'po4a'hide' .br 108.if !'po4a'hide' .B deny_info ERR_ACL_TIME_QUOTA_EXCEEDED noquota 109.if !'po4a'hide' .br 110.if !'po4a'hide' .B http_access deny !time_quota noquota 111.if !'po4a'hide' .RE 112. 113.PP 114In this example, after restarting Squid it should allow access only for users as long as they have time budget left. 115If the budget is exceeded the user will be presented with an error page informing them. 116.PP 117In this example we use separate 118.B users 119access control and 120.B noquota 121ACL in order to keep the username and password prompt and the quota-exceeded messages separated. 122. 123.PP 124User is just a unique key value. The above example uses %LOGIN and the username but any of the 125.B external_acl_type 126format tags can be substituted in its place. 127.B %EXT_TAG 128, 129.B %LOGIN 130, 131.B %IDENT 132, 133.B %EXT_USER 134, 135.B %SRC 136, 137.B %SRCEUI48 138, and 139.B %SRCEUI64 140are all likely candidates for client identification. 141The Squid wiki has more examples at http://wiki.squid-cache.org/ConfigExamples. 142. 143.SH LIMITATIONS 144.PP 145This helper only controls access to the Internet through HTTP. It does 146not control other protocols, like VOIP, ICQ, IRC, FTP, IMAP, SMTP or 147SSH. 148. 149.PP 150Desktop browsers are typically able to deal with authentication to HTTP proxies like 151.B squid . 152But more and more different programs and devices (smartphones, 153games on mobile devices, ...) are using the Internet over HTTP. These 154devices are often not able to work through an authenticating proxy. 155Means other than %LOGIN authentication are required to authorize these devices and software. 156. 157.PP 158A more general control to Internet access could be a captive portal approach 159(such as pfSense or ChilliSpot) using %SRC, %SRCEUI48 and %SRCEUI64 as keys 160or maybe a 802.11X solution. But the latter is often not supported by mobile devices. 161. 162.SH IMPLEMENTATION 163.PP 164When the helper is called it will be asked if the current user is allowed to 165access squid. The helper will reduce the remaining time budget of this user 166and return 167.B OK 168if there is budget left. Otherwise it will return 169.B ERR . 170. 171.PP 172The 173.B ttl=N 174parameter in 175.B squid.conf 176determines how often the helper will be called, the example config uses a 1 minute TTL. 177The interaction is that Squid will only call the helper on new requests 178.B if 179there has been more than TTL seconds passed since last check. 180This handling creates an amount of slippage outside the quota by whatever amount is configured. 181TTL can be set as short as desired, down to and including zero. 182Though values of 1 or more are recommended due to a quota resolution of one second. 183. 184.PP 185If the configured time period (e.g. "1w" for babymary) is over, the 186time budget will be restored to the configured value thus allowing the 187user to access squid with a fresh budget. 188. 189.PP 190If the time between the current request and the previous request is greater than 191.B pauselen 192(default 5 minutes and adjustable with command line parameter 193.B "-p" 194), the current request will be considered as a new request and the time budget will 195not be decreased. If the time is less than 196.B pauselen 197, then both requests will be considered as part of the same active time period and the time budget will 198be decreased by the time difference. This allows the user to take arbitrary 199breaks during Internet access without losing their time budget. 200. 201.SH FURTHER IDEAS 202The following ideas could further improve this helper. Maybe someone 203wants to help? Any support or feedback is welcome! 204.if !'po4a'hide' .TP 205There should be a way for a user to see their configured and remaining 206time budget. This could be realized by implementing a web page 207accessing the database of the helper showing the corresponding 208data. One of the problems to be solved is user authentication. 209.if !'po4a'hide' .TP 210We could always return "OK" and use the module simply as an Internet 211usage tracker showing who has stayed how long in the WWW. 212.PP 213. 214.SH AUTHOR 215This program and documentation was written by 216.if !'po4a'hide' .I Dr. Tilmann Bubeck <t.bubeck@reinform.de> 217. 218.SH COPYRIGHT 219.PP 220 * Copyright (C) 1996-2021 The Squid Software Foundation and contributors 221 * 222 * Squid software is distributed under GPLv2+ license and includes 223 * contributions from numerous individuals and organizations. 224 * Please see the COPYING and CONTRIBUTORS files for details. 225.PP 226This program and documentation is copyright to the authors named above. 227.PP 228Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+). 229. 230.SH QUESTIONS 231Questions on the usage of this program can be sent to the 232.I Squid Users mailing list 233.if !'po4a'hide' <squid-users@lists.squid-cache.org> 234. 235.SH REPORTING BUGS 236Bug reports need to be made in English. 237See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report. 238.PP 239Report bugs or bug fixes using http://bugs.squid-cache.org/ 240.PP 241Report serious security bugs to 242.I Squid Bugs <squid-bugs@lists.squid-cache.org> 243.PP 244Report ideas for new improvements to the 245.I Squid Developers mailing list 246.if !'po4a'hide' <squid-dev@lists.squid-cache.org> 247. 248.SH SEE ALSO 249.if !'po4a'hide' .BR squid "(8), " 250.if !'po4a'hide' .BR GPL "(7), " 251.br 252The Squid FAQ wiki 253.if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq 254.br 255The Squid Configuration Manual 256.if !'po4a'hide' http://www.squid-cache.org/Doc/config/ 257