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