]>
Commit | Line | Data |
---|---|---|
9938b57f TB |
1 | .if !'po4a'hide' .TH ext_time_quota_acl 8 "22 March 2011" |
2 | . | |
3 | .SH NAME | |
d632afde | 4 | ext_time_quota_acl \- Squid time quota external acl helper. |
9938b57f TB |
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 | |
ca02e0ec | 219 | .PP |
4ac4a490 | 220 | * Copyright (C) 1996-2017 The Squid Software Foundation and contributors |
ca02e0ec AJ |
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 | |
9938b57f TB |
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@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@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@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/ |