src/acl/external/time_quota/ext_time_quota_acl.8

   1 .if !'po4a'hide' .TH ext_time_quota_acl 8 "22 March 2011"
   2 .
   3 .SH NAME
   4 ext_time_quota_acl \- Squid time quota external acl helper.
   5 .PP
   6 Version 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
  14 allows an administrator to define time budgets for the users of squid
  15 to limit the time using squid.
  16 .PP
  17 This is useful for corporate lunch time allocations, wifi portal
  18 pay-per-minute installations or for parental control of children. The
  19 administrator can define a time budget (e.g. 1 hour per day) which is enforced
  20 through this helper.
  21 .
  22 .SH OPTIONS
  23 .
  24 .if !'po4a'hide' .TP
  25 .if !'po4a'hide' .B "\-b database"
  26 .B Filename
  27 of persistent database. This defaults to ext_time_quota.db in Squids state
  28 directory.
  29 .
  30 .if !'po4a'hide' .TP
  31 .if !'po4a'hide' .B "\-p pauselen"
  32 .B Pauselen
  33 is given in seconds and defines the period between two requests to be treated as part of the same session.
  34 Pauses shorter than this value will be counted against the quota, longer ones ignored.
  35 Default is 300 seconds (5 minutes).
  36 .
  37 .if !'po4a'hide' .TP
  38 .if !'po4a'hide' .B "\-l logfile"
  39 .B Filename
  40 where all logging and debugging information will be written. If none is given,
  41 then 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"
  45 Enables debug logging in the logfile.
  46 .
  47 .if !'po4a'hide' .TP
  48 .if !'po4a'hide' .B "\-h"
  49 show a short command line help.
  50 .
  51 .if !'po4a'hide' .TP
  52 .if !'po4a'hide' .B configfile
  53 This file contains the definition of the time budgets for the users.
  54 .PP
  55 .
  56 .SH CONFIGURATION
  57 .PP
  58 The time quotas of the users are defined in a text file typically
  59 residing in /etc/squid/time_quota. Any line starting with "#" contains
  60 a comment and is ignored. Every line must start with a user
  61 followed 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
  75 John has a time budget of 8 hours every day, littlejoe is only allowed
  76 1 hour and the poor babymary only 30 minutes a week.
  77 .PP
  78 You can use "s" for seconds, "m" for minutes, "h" for hours, "d" for
  79 days and "w" for weeks. Numerical values can be given as integer
  80 values or with a fraction. E.g. "0.5h" means 30 minutes.
  81 .PP
  82 This helper is configured in
  83 .B squid.conf
  84 using the
  85 .B external_acl_type
  86 directive then access controls which use it to allow or deny.
  87 .
  88 .PP
  89 Here 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
 114 In this example, after restarting Squid it should allow access only for users as long as they have time budget left.
 115 If the budget is exceeded the user will be presented with an error page informing them.
 116 .PP
 117 In this example we use separate
 118 .B users
 119 access control and
 120 .B noquota
 121 ACL in order to keep the username and password prompt and the quota-exceeded messages separated.
 122 .
 123 .PP
 124 User is just a unique key value. The above example uses %LOGIN and the username but any of the
 125 .B external_acl_type
 126 format 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
 140 are all likely candidates for client identification.
 141 The Squid wiki has more examples at http://wiki.squid-cache.org/ConfigExamples.
 142 .
 143 .SH LIMITATIONS
 144 .PP
 145 This helper only controls access to the Internet through HTTP. It does
 146 not control other protocols, like VOIP, ICQ, IRC, FTP, IMAP, SMTP or
 147 SSH.
 148 .
 149 .PP
 150 Desktop browsers are typically able to deal with authentication to HTTP proxies like
 151 .B squid .
 152 But more and more different programs and devices (smartphones,
 153 games on mobile devices, ...) are using the Internet over HTTP. These
 154 devices are often not able to work through an authenticating proxy.
 155 Means other than %LOGIN authentication are required to authorize these devices and software.
 156 .
 157 .PP
 158 A 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
 160 or maybe a 802.11X solution. But the latter is often not supported by mobile devices.
 161 .
 162 .SH IMPLEMENTATION
 163 .PP
 164 When the helper is called it will be asked if the current user is allowed to
 165 access squid. The helper will reduce the remaining time budget of this user
 166 and return
 167 .B OK
 168 if there is budget left. Otherwise it will return
 169 .B ERR .
 170 .
 171 .PP
 172 The
 173 .B ttl=N
 174 parameter in
 175 .B squid.conf
 176 determines how often the helper will be called, the example config uses a 1 minute TTL.
 177 The interaction is that Squid will only call the helper on new requests
 178 .B if
 179 there has been more than TTL seconds passed since last check.
 180 This handling creates an amount of slippage outside the quota by whatever amount is configured.
 181 TTL can be set as short as desired, down to and including zero.
 182 Though values of 1 or more are recommended due to a quota resolution of one second.
 183 .
 184 .PP
 185 If the configured time period (e.g. "1w" for babymary) is over, the
 186 time budget will be restored to the configured value thus allowing the
 187 user to access squid with a fresh budget.
 188 .
 189 .PP
 190 If 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
 195 not 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
 198 be decreased by the time difference. This allows the user to take arbitrary
 199 breaks during Internet access without losing their time budget.
 200 .
 201 .SH FURTHER IDEAS
 202 The following ideas could further improve this helper. Maybe someone
 203 wants to help? Any support or feedback is welcome!
 204 .if !'po4a'hide' .TP
 205 There should be a way for a user to see their configured and remaining
 206 time budget. This could be realized by implementing a web page
 207 accessing the database of the helper showing the corresponding
 208 data. One of the problems to be solved is user authentication.
 209 .if !'po4a'hide' .TP
 210 We could always return "OK" and use the module simply as an Internet
 211 usage tracker showing who has stayed how long in the WWW.
 212 .PP
 213 .
 214 .SH AUTHOR
 215 This 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-2023 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
 226 This program and documentation is copyright to the authors named above.
 227 .PP
 228 Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
 229 .
 230 .SH QUESTIONS
 231 Questions 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
 236 Bug reports need to be made in English.
 237 See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
 238 .PP
 239 Report bugs or bug fixes using http://bugs.squid-cache.org/
 240 .PP
 241 Report serious security bugs to
 242 .I Squid Bugs <squid-bugs@lists.squid-cache.org>
 243 .PP
 244 Report 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
 252 The Squid FAQ wiki
 253 .if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
 254 .br
 255 The Squid Configuration Manual
 256 .if !'po4a'hide' http://www.squid-cache.org/Doc/config/