[thirdparty/squid.git] / helpers / external_acl / eDirectory_userip / ext_edirectory_userip_acl.8

.if !'po4a'hide' .TH ext_edirectory_userip_acl 8
.
.SH NAME
ext_edirectory_userip_acl \- Squid eDirectory IP Lookup Helper
.PP
Version 2.0
.
.SH SYNOPSIS
.if !'po4a'hide' .B ext_edirectory_userip_acl
.if !'po4a'hide' .B "[\-h | \-\-help | \-\-usage]"
.if !'po4a'hide' .br
.if !'po4a'hide' .B ext_edirectory_userip_acl
.if !'po4a'hide' .B  \-H "
host
.if !'po4a'hide' .B "\-p "
port
.if !'po4a'hide' .B "[\-Z] [\-P] [\-v "
LDAP version
.if !'po4a'hide' .B "] \-b "
basedn
.if !'po4a'hide' .B "\-s "
scope
.if !'po4a'hide' .B "\-D "
binddn
.if !'po4a'hide' .B "\-W "
bindpass
.if !'po4a'hide' .B "\-F "
filter
.if !'po4a'hide' .B "[\-G]"
.
.SH DESCRIPTION
.B ext_edirectory_userip_acl
is an installed binary.
.PP
This program has been written in order to solve the problems associated with running the Perl 
.B squid_ip_lookup.pl 
as a squid external helper.
.PP
The limitations of the Perl script involved memory/cpu utilization, speed, the lack
of eDirectory 8.8 support, and IPv6 support.
.
.SH OPTIONS
.if !'po4a'hide' .TP 12
.if !'po4a'hide' .B "\-4"
Force Addresses to be in IPv4 (0.0.0.0 format).
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-6"
Force Addresses to be in IPv6 (:: format).
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .BI \-b " base"
Specify 
.B base
DN. For example; 
.B o=ORG
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B \-d
Write debug info to stderr.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .BI \-D "binddn"
Specify binding DN. For example; 
.B "cn=squid,o=ORG"
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .BI \-F " filter"
Specify LDAP search filter. For example; 
.B "(objectClass=User)"
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-G"
Specify if LDAP search group is required. For example; 
.B groupMembership=
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-h | \-\-help | \-\-usage"
Display the binary help and command line syntax info using stderr.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .BI \-H " host"
Specify hostname or IP of server
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .BI \-p " port"
Port number.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-P"
Use persistent connections.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .BI \-t " seconds"
Timeout factor for persistent connections. Set to 
.B 0 
for never timeout. Default is 
.B 60 
seconds.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .BI -s " base|one|sub"
search scope. Defaults to
.B sub
.IP
.B base
object only,
.IP 
.B one
level below the base object or
.IP
.BR sub tree
below the base object
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .BI \-u " attribute"
Set userid 
.B attribute .
Default is
.B cn
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .BI \-v " 1|2|3"
Set LDAP 
.B version
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-V"
Display version information and exit.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .BI \-W " password"
Specify binding 
.B password
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-Z"
Enable TLS security.
.
.SH CONFIGURATION
.
.if !'po4a'hide' .RS
.if !'po4a'hide' .B external_acl_type IPUser %SRC /usr/sbin/ext_edirectory_userip_acl
.if !'po4a'hide' .br
.if !'po4a'hide' .B acl edirectory_users_allowed external IPUser cn=Internet_Allowed,ou=ORG,o=BASE
.if !'po4a'hide' .B acl edirectory_users_denied external IPUser cn=Internet_Denied,ou=ORG,o=BASE
.if !'po4a'hide' .br
.if !'po4a'hide' .B http_access deny edirectory_users_denied
.if !'po4a'hide' .B http_access allow edirectory_users_allowed
.if !'po4a'hide' .B http_access deny all
.if !'po4a'hide' .RE
.PP
In this example, the 
.B Internet_Allowed
and 
.B Internet_Denied 
are Groups that users may be used to control internet access, which can also be stacked against other ACL's.
Use of the groups is optional, unless the '-G' option has been passed.  Please note that you need to specify
the full LDAP object for this, as shown above.
.
.SH KNOWN ISSUES
.PP
IPv6 support has yet to be tested in a real IPv6 environment, but the code is in place to read IPv6
networkAddress fields, please attempt this in a TESTING environment first.  Please contact the author
regarding IPv6 support development.
.
.PP
There is a known issue regarding Novell's Client for Windows, that is mostly fixed by using
version 4.91 SP3+, with the 'Auto-Reconnect' feature not re-populating the networkAddress
field in eDirectory.
.
.PP
I have also experienced an issue related to using NetWare 6.5 (SP6 and lower?) and connection licensing.
It appears that whenever a server runs low on connection licenses, that it 
I sometimes 
does not populate the networkAddress fields correctly.
.
.PP
Majority of Proxy Authentication issues can be resolved by having the users' 
.B reboot 
if their networkAddress is not correct, or using 
.B basic_ldap_auth 
as a fallback.  Check ConsoleOne, etc to verify their networkAddress fields to troubleshoot.
.
.SH AUTHOR
This program was written by
.if !'po4a'hide' .I Chad E. Naugle <chad.naugle@travimp.com>
.PP
This manual was written by
.if !'po4a'hide' .I Chad E. Naugle <chad.naugle@travimp.com>
.if !'po4a'hide' .I Amos Jeffries <amosjeffries@squid-cache.org>
.
.SH COPYRIGHT
.PP
 * Copyright (C) 1996-2015 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@squid-cache.org>
.
.SH REPORTING BUGS
.PP
I 
.B "STRONGLY RECOMMEND" 
using the latest version of the Novell Client in all situations 
.B before
seeking support!  You may also need to make sure your servers have the latest service packs installed, and that
your servers are properly synchronizing partitions.
.
.PP
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@squid-cache.org>
.PP
Report ideas for new improvements to the
.I Squid Developers mailing list
.if !'po4a'hide' <squid-dev@squid-cache.org>
.
.SH SEE ALSO
.if !'po4a'hide' .BR squid "(8), "
.if !'po4a'hide' .BR basic_ldap_auth "(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
a2c8080d AJ	1	.if !'po4a'hide' .TH ext_edirectory_userip_acl 8
	2	.
	3	.SH NAME
d632afde	4	ext_edirectory_userip_acl \- Squid eDirectory IP Lookup Helper
a2c8080d AJ	5	.PP
	6	Version 2.0
	7	.
	8	.SH SYNOPSIS
	9	.if !'po4a'hide' .B ext_edirectory_userip_acl
	10	.if !'po4a'hide' .B "[\-h \| \-\-help \| \-\-usage]"
	11	.if !'po4a'hide' .br
	12	.if !'po4a'hide' .B ext_edirectory_userip_acl
	13	.if !'po4a'hide' .B \-H "
	14	host
	15	.if !'po4a'hide' .B "\-p "
	16	port
	17	.if !'po4a'hide' .B "[\-Z] [\-P] [\-v "
	18	LDAP version
	19	.if !'po4a'hide' .B "] \-b "
	20	basedn
	21	.if !'po4a'hide' .B "\-s "
	22	scope
	23	.if !'po4a'hide' .B "\-D "
	24	binddn
	25	.if !'po4a'hide' .B "\-W "
	26	bindpass
	27	.if !'po4a'hide' .B "\-F "
	28	filter
	29	.if !'po4a'hide' .B "[\-G]"
	30	.
	31	.SH DESCRIPTION
	32	.B ext_edirectory_userip_acl
	33	is an installed binary.
	34	.PP
	35	This program has been written in order to solve the problems associated with running the Perl
	36	.B squid_ip_lookup.pl
	37	as a squid external helper.
	38	.PP
	39	The limitations of the Perl script involved memory/cpu utilization, speed, the lack
	40	of eDirectory 8.8 support, and IPv6 support.
	41	.
	42	.SH OPTIONS
	43	.if !'po4a'hide' .TP 12
	44	.if !'po4a'hide' .B "\-4"
	45	Force Addresses to be in IPv4 (0.0.0.0 format).
	46	.
	47	.if !'po4a'hide' .TP
	48	.if !'po4a'hide' .B "\-6"
	49	Force Addresses to be in IPv6 (:: format).
	50	.
	51	.if !'po4a'hide' .TP
	52	.if !'po4a'hide' .BI \-b " base"
	53	Specify
	54	.B base
	55	DN. For example;
	56	.B o=ORG
	57	.
	58	.if !'po4a'hide' .TP
	59	.if !'po4a'hide' .B \-d
	60	Write debug info to stderr.
	61	.
	62	.if !'po4a'hide' .TP
	63	.if !'po4a'hide' .BI \-D "binddn"
	64	Specify binding DN. For example;
	65	.B "cn=squid,o=ORG"
	66	.
	67	.if !'po4a'hide' .TP
	68	.if !'po4a'hide' .BI \-F " filter"
69	Specify LDAP search filter. For example;
70	.B "(objectClass=User)"
71	.
72	.if !'po4a'hide' .TP
73	.if !'po4a'hide' .B "\-G"
74	Specify if LDAP search group is required. For example;
75	.B groupMembership=
76	.
77	.if !'po4a'hide' .TP
78	.if !'po4a'hide' .B "\-h \| \-\-help \| \-\-usage"
79	Display the binary help and command line syntax info using stderr.
80	.
81	.if !'po4a'hide' .TP
82	.if !'po4a'hide' .BI \-H " host"
83	Specify hostname or IP of server
84	.
85	.if !'po4a'hide' .TP
86	.if !'po4a'hide' .BI \-p " port"
87	Port number.
88	.
89	.if !'po4a'hide' .TP
90	.if !'po4a'hide' .B "\-P"
91	Use persistent connections.
92	.
93	.if !'po4a'hide' .TP
94	.if !'po4a'hide' .BI \-t " seconds"
95	Timeout factor for persistent connections. Set to
96	.B 0
97	for never timeout. Default is
98	.B 60
99	seconds.
100	.
101	.if !'po4a'hide' .TP
102	.if !'po4a'hide' .BI -s " base\|one\|sub"
103	search scope. Defaults to
104	.B sub
105	.IP
106	.B base
107	object only,
108	.IP
109	.B one
110	level below the base object or
111	.IP
112	.BR sub tree
113	below the base object
114	.
115	.if !'po4a'hide' .TP
116	.if !'po4a'hide' .BI \-u " attribute"
117	Set userid
118	.B attribute .
119	Default is
120	.B cn
121	.
122	.if !'po4a'hide' .TP
123	.if !'po4a'hide' .BI \-v " 1\|2\|3"
124	Set LDAP
125	.B version
126	.
127	.if !'po4a'hide' .TP
128	.if !'po4a'hide' .B "\-V"
129	Display version information and exit.
130	.
131	.if !'po4a'hide' .TP
132	.if !'po4a'hide' .BI \-W " password"
133	Specify binding
134	.B password
135	.
136	.if !'po4a'hide' .TP
137	.if !'po4a'hide' .B "\-Z"
138	Enable TLS security.
139	.
140	.SH CONFIGURATION
141	.
142	.if !'po4a'hide' .RS
6ca7324f	143	.if !'po4a'hide' .B external_acl_type IPUser %SRC /usr/sbin/ext_edirectory_userip_acl
a2c8080d	144	.if !'po4a'hide' .br
6ca7324f AJ	145	.if !'po4a'hide' .B acl edirectory_users_allowed external IPUser cn=Internet_Allowed,ou=ORG,o=BASE
6ca7324f AJ	146	.if !'po4a'hide' .B acl edirectory_users_denied external IPUser cn=Internet_Denied,ou=ORG,o=BASE
a2c8080d AJ	147	.if !'po4a'hide' .br
	148	.if !'po4a'hide' .B http_access deny edirectory_users_denied
	149	.if !'po4a'hide' .B http_access allow edirectory_users_allowed
	150	.if !'po4a'hide' .B http_access deny all
	151	.if !'po4a'hide' .RE
	152	.PP
	153	In this example, the
	154	.B Internet_Allowed
	155	and
	156	.B Internet_Denied
	157	are Groups that users may be used to control internet access, which can also be stacked against other ACL's.
6ca7324f AJ	158	Use of the groups is optional, unless the '-G' option has been passed. Please note that you need to specify
6ca7324f AJ	159	the full LDAP object for this, as shown above.
a2c8080d AJ	160	.
	161	.SH KNOWN ISSUES
	162	.PP
	163	IPv6 support has yet to be tested in a real IPv6 environment, but the code is in place to read IPv6
	164	networkAddress fields, please attempt this in a TESTING environment first. Please contact the author
	165	regarding IPv6 support development.
	166	.
	167	.PP
	168	There is a known issue regarding Novell's Client for Windows, that is mostly fixed by using
	169	version 4.91 SP3+, with the 'Auto-Reconnect' feature not re-populating the networkAddress
	170	field in eDirectory.
	171	.
	172	.PP
	173	I have also experienced an issue related to using NetWare 6.5 (SP6 and lower?) and connection licensing.
	174	It appears that whenever a server runs low on connection licenses, that it
	175	I sometimes
	176	does not populate the networkAddress fields correctly.
	177	.
	178	.PP
	179	Majority of Proxy Authentication issues can be resolved by having the users'
	180	.B reboot
	181	if their networkAddress is not correct, or using
	182	.B basic_ldap_auth
	183	as a fallback. Check ConsoleOne, etc to verify their networkAddress fields to troubleshoot.
	184	.
	185	.SH AUTHOR
	186	This program was written by
	187	.if !'po4a'hide' .I Chad E. Naugle <chad.naugle@travimp.com>
	188	.PP
	189	This manual was written by
	190	.if !'po4a'hide' .I Chad E. Naugle <chad.naugle@travimp.com>
	191	.if !'po4a'hide' .I Amos Jeffries <amosjeffries@squid-cache.org>
	192	.
	193	.SH COPYRIGHT
ca02e0ec	194	.PP
bde978a6	195	* Copyright (C) 1996-2015 The Squid Software Foundation and contributors
ca02e0ec AJ	196	*
	197	* Squid software is distributed under GPLv2+ license and includes
	198	* contributions from numerous individuals and organizations.
	199	* Please see the COPYING and CONTRIBUTORS files for details.
	200	.PP
a2c8080d AJ	201	This program and documentation is copyright to the authors named above.
	202	.PP
	203	Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
	204	.
	205	.SH QUESTIONS
	206	Questions on the usage of this program can be sent to the
	207	.I Squid Users mailing list
	208	.if !'po4a'hide' <squid-users@squid-cache.org>
	209	.
	210	.SH REPORTING BUGS
	211	.PP
10228f68 AJ	212	I
	213	.B "STRONGLY RECOMMEND"
	214	using the latest version of the Novell Client in all situations
a2c8080d	215	.B before
6ca7324f AJ	216	seeking support! You may also need to make sure your servers have the latest service packs installed, and that
6ca7324f AJ	217	your servers are properly synchronizing partitions.
a2c8080d AJ	218	.
	219	.PP
	220	Bug reports need to be made in English.
	221	See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
	222	.PP
	223	Report bugs or bug fixes using http://bugs.squid-cache.org/
	224	.PP
	225	Report serious security bugs to
	226	.I Squid Bugs <squid-bugs@squid-cache.org>
	227	.PP
	228	Report ideas for new improvements to the
	229	.I Squid Developers mailing list
	230	.if !'po4a'hide' <squid-dev@squid-cache.org>
	231	.
	232	.SH SEE ALSO
	233	.if !'po4a'hide' .BR squid "(8), "
	234	.if !'po4a'hide' .BR basic_ldap_auth "(8), "
	235	.if !'po4a'hide' .BR GPL "(7), "
	236	.br
	237	The Squid FAQ wiki
	238	.if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
	239	.br
	240	The Squid Configuration Manual
	241	.if !'po4a'hide' http://www.squid-cache.org/Doc/config/