[thirdparty/squid.git] / src / acl / external / time_quota / ext_time_quota_acl.8

.if !'po4a'hide' .TH ext_time_quota_acl 8 "22 March 2011"
.
.SH NAME
ext_time_quota_acl \- Squid time quota external acl helper.
.PP
Version 1.0
.
.SH SYNOPSIS
.if !'po4a'hide' .B ext_time_quota_acl
.if !'po4a'hide' .B "[\-b database] [\-l logfile] [\-d] [\-p pauselen] [\-h] configfile
.
.SH DESCRIPTION
.B ext_time_quota_acl
allows an administrator to define time budgets for the users of squid
to limit the time using squid.
.PP
This is useful for corporate lunch time allocations, wifi portal
pay-per-minute installations or for parental control of children. The
administrator can define a time budget (e.g. 1 hour per day) which is enforced
through this helper.
.
.SH OPTIONS
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-b database"
.B Filename
of persistent database. This defaults to ext_time_quota.db in Squids state
directory.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-p pauselen"
.B Pauselen
is given in seconds and defines the period between two requests to be treated as part of the same session.
Pauses shorter than this value will be counted against the quota, longer ones ignored.
Default is 300 seconds (5 minutes).
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-l logfile"
.B Filename
where all logging and debugging information will be written. If none is given,
then stderr will be used and the logging will go to Squids main cache.log.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-d"
Enables debug logging in the logfile.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-h"
show a short command line help.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B configfile
This file contains the definition of the time budgets for the users.
.PP
.
.SH CONFIGURATION
.PP
The time quotas of the users are defined in a text file typically
residing in /etc/squid/time_quota. Any line starting with "#" contains
a comment and is ignored. Every line must start with a user
followed by a time budget and a corresponding time period separated by
"/". Here is an example file:
.PP
.if !'po4a'hide' .RS
# user budget / period
.if !'po4a'hide' .br
.if !'po4a'hide' .B john 8h / 1d
.if !'po4a'hide' .br
.if !'po4a'hide' .B littlejoe 1h / 1d
.if !'po4a'hide' .br
.if !'po4a'hide' .B babymary 30m / 1w
.if !'po4a'hide' .br
.if !'po4a'hide' .RE
.PP
John has a time budget of 8 hours every day, littlejoe is only allowed
1 hour and the poor babymary only 30 minutes a week.
.PP
You can use "s" for seconds, "m" for minutes, "h" for hours, "d" for
days and "w" for weeks. Numerical values can be given as integer
values or with a fraction. E.g. "0.5h" means 30 minutes.
.PP
This helper is configured in 
.B squid.conf 
using the
.B external_acl_type 
directive then access controls which use it to allow or deny.
.
.PP
Here is an example.
.PP
.if !'po4a'hide' .RS
# Ensure that users have a valid login. We need their username.
.if !'po4a'hide' .br
.if !'po4a'hide' .br
.if !'po4a'hide' .B acl users proxy_auth REQUIRED
.if !'po4a'hide' .br
.if !'po4a'hide' .B http_access deny !users
.if !'po4a'hide' .br
# Define program and quota file
.if !'po4a'hide' .br
.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
.if !'po4a'hide' .br
.if !'po4a'hide' .br
.if !'po4a'hide' .B acl noquota src all
.if !'po4a'hide' .br
.if !'po4a'hide' .B acl time_quota external time_quota
.if !'po4a'hide' .br
.if !'po4a'hide' .B deny_info ERR_ACL_TIME_QUOTA_EXCEEDED noquota
.if !'po4a'hide' .br
.if !'po4a'hide' .B http_access deny !time_quota noquota
.if !'po4a'hide' .RE
.
.PP
In this example, after restarting Squid it should allow access only for users as long as they have time budget left.
If the budget is exceeded the user will be presented with an error page informing them.
.PP
In this example we use separate 
.B users 
access control and 
.B noquota 
ACL in order to keep the username and password prompt and the quota-exceeded messages separated.
.
.PP
User is just a unique key value. The above example uses %LOGIN and the username but any of the 
.B external_acl_type 
format tags can be substituted in its place. 
.B %EXT_TAG
,
.B %LOGIN
, 
.B %IDENT
, 
.B %EXT_USER
, 
.B %SRC 
,
.B %SRCEUI48
, and 
.B %SRCEUI64
are all likely candidates for client identification.
The Squid wiki has more examples at http://wiki.squid-cache.org/ConfigExamples.
.
.SH LIMITATIONS
.PP
This helper only controls access to the Internet through HTTP. It does
not control other protocols, like VOIP, ICQ, IRC, FTP, IMAP, SMTP or
SSH.
.
.PP
Desktop browsers are typically able to deal with authentication to HTTP proxies like
.B squid . 
But more and more different programs and devices (smartphones,
games on mobile devices, ...) are using the Internet over HTTP. These
devices are often not able to work through an authenticating proxy.
Means other than %LOGIN authentication are required to authorize these devices and software.
.
.PP
A more general control to Internet access could be a captive portal approach
(such as pfSense or ChilliSpot) using %SRC, %SRCEUI48 and %SRCEUI64 as keys 
or maybe a 802.11X solution. But the latter is often not supported by mobile devices.
.
.SH IMPLEMENTATION
.PP
When the helper is called it will be asked if the current user is allowed to
access squid. The helper will reduce the remaining time budget of this user
and return 
.B OK 
if there is budget left. Otherwise it will return 
.B ERR .
.
.PP
The 
.B ttl=N 
parameter in 
.B squid.conf 
determines how often the helper will be called, the example config uses a 1 minute TTL.
The interaction is that Squid will only call the helper on new requests
.B if
there has been more than TTL seconds passed since last check.
This handling creates an amount of slippage outside the quota by whatever amount is configured.
TTL can be set as short as desired, down to and including zero.
Though values of 1 or more are recommended due to a quota resolution of one second.
.
.PP
If the configured time period (e.g. "1w" for babymary) is over, the
time budget will be restored to the configured value thus allowing the
user to access squid with a fresh budget.
.
.PP
If the time between the current request and the previous request is greater than
.B pauselen
(default 5 minutes and adjustable with command line parameter 
.B "-p"
), the current request will be considered as a new request and the time budget will
not be decreased. If the time is less than 
.B pauselen 
, then both requests will be considered as part of the same active time period and the time budget will
be decreased by the time difference. This allows the user to take arbitrary
breaks during Internet access without losing their time budget.
.
.SH FURTHER IDEAS
The following ideas could further improve this helper. Maybe someone
wants to help? Any support or feedback is welcome!
.if !'po4a'hide' .TP
There should be a way for a user to see their configured and remaining
time budget. This could be realized by implementing a web page
accessing the database of the helper showing the corresponding
data. One of the problems to be solved is user authentication.
.if !'po4a'hide' .TP
We could always return "OK" and use the module simply as an Internet
usage tracker showing who has stayed how long in the WWW.
.PP
.
.SH AUTHOR
This program and documentation was written by
.if !'po4a'hide' .I Dr. Tilmann Bubeck <t.bubeck@reinform.de>
.
.SH COPYRIGHT
.PP
 * Copyright (C) 1996-2020 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
.PP
This program and documentation is copyright to the authors named above.
.PP
Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
.
.SH QUESTIONS
Questions on the usage of this program can be sent to the
.I Squid Users mailing list
.if !'po4a'hide' <squid-users@lists.squid-cache.org>
.
.SH REPORTING BUGS
Bug reports need to be made in English.
See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
.PP
Report bugs or bug fixes using http://bugs.squid-cache.org/
.PP
Report serious security bugs to
.I Squid Bugs <squid-bugs@lists.squid-cache.org>
.PP
Report ideas for new improvements to the
.I Squid Developers mailing list
.if !'po4a'hide' <squid-dev@lists.squid-cache.org>
.
.SH SEE ALSO
.if !'po4a'hide' .BR squid "(8), "
.if !'po4a'hide' .BR GPL "(7), "
.br
The Squid FAQ wiki
.if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
.br
The Squid Configuration Manual
.if !'po4a'hide' http://www.squid-cache.org/Doc/config/
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
77b1029d	220	* Copyright (C) 1996-2020 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
8311b837	233	.if !'po4a'hide' <squid-users@lists.squid-cache.org>
9938b57f TB	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
8311b837	242	.I Squid Bugs <squid-bugs@lists.squid-cache.org>
9938b57f TB	243	.PP
	244	Report ideas for new improvements to the
	245	.I Squid Developers mailing list
8311b837	246	.if !'po4a'hide' <squid-dev@lists.squid-cache.org>
9938b57f TB	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/