Squid proxy is a very popular open-source Internet proxy, which is available for both Unix, Mac and Windows operating systems. It has a large configuation file that can be difficult to edit for people who are not familiar with it. This appendix outlines required to configure Squid for use with PaperCut NG. However it is not a complete guide to configuring Squid, and should be read in conjunction with the Squid Proxy documentation.
When Squid is running on Linux/Mac it is common to authenticate users with an LDAP directory or Microsoft Active Directory (which is also an LDAP v3 compliant directory).
The Squid LDAP authentication helpers are used to integrate Squid with an LDAP server. This guide assumes the proxy is Squid 2.5 or greater (with LDAP helpers). Information on the LDAP helpers can be found here: http://www.die.net/doc/linux/man/man8/squid_ldap_auth.8.html
If the LDAP helpers are included in your Squid installation, the ldap_auth
(or sometimes names squid_ldap_auth) will be found in /var/lib/squid
(or equivalent location where Squid is installed).
The first step is to configure Squid to authenticate usernames/passwords with the LDAP / Active Directory. You will need to open your Squid configuration file (squid.conf) and make the following changes:
Find the auth_param section of the config file (TAG: auth_param), and change the
auth param basic program line to look like this. (Indented text indicates one line)
auth_param basic program /usr/lib/squid/ldap_auth -R
-b "dc=vm-domain,dc=mydomain,dc=com"
-D "cn=Administrator,cn=Users,dc=your,dc=domain,dc=com"
-w "password" -f sAMAccountName=%s -h 192.168.1.75
auth_param basic children 5
auth_param basic realm Your Organisation Name
auth_param basic credentialsttl 5 minutes
These settings tell Squid authenticate names/passwords in the LDAP / Active Directory.
The -b option indicates the base LDAP distinguished name of our domain. e.g.
your.domain.com would be dc=your,dc=domain,dc=com.
The -D option indicates the user that is used to perform the LDAP query (e.g. an Administrator).
This example uses the built-in Administrator user, however you can use another user of your choice.
The -w option is the password for the user in the -D option.
For improved security you can store the password in a file and use the -W /path/to/password_file syntax instead.
The -h option is used to indicate the LDAP server to connect to.
The -R option is required for Squid to connect to Windows Active Directory.
The -f option is the LDAP query used to lookup the user. In the above example, sAMAccountName=%s,
will match if the user's Windows logon name matches the username entered when prompted by Squid. Any LDAP query can be used.
An LDAP search query tool can be helpful to help get the syntax correct and to ensure the query works correctly.
The %s is replaced with what the user enters as their username.
Remember to restart Squid to make these changes to come into effect. Then test accessing the Internet and ensure that the Squid prompts for a username and password, and the authentication works as expected. Ensure that the username now appears in the Squid log file.
PaperCut NG includes a Squid ACL helper that can be used to define access rules so that only users with credit available can access the Internet. The ACL helper is located:
Linux - [app-path]/providers/net/bin/linux-i686/squid-acl-helper
Apple Mac - [app-path]/providers/net/bin/mac/squid-acl-helper
To configure the ACL helper open the Squid config file (e.g. /etc/squid.conf) in a text editor, and make
the changes as described below.
The first step is to define the ACL helper configuration. This is done by adding the following line to the config file in the external ACL type section (TAG: external_acl_type). (NOTE: This is a single line, and is only split over multiple lines for formatting).
external_acl_type papercut_credit ttl=60 %LOGIN
[app-path]/providers/net/bin/[platform]/squid-acl-helper -s [server]
Where [app-path] is the location where PaperCut NG is installed.
The -s [server] option sets is the machine or IP address of the application server. If the
-s option is not specified localhost is assumed.
The ttl is the number of seconds Squid caches the credit check. Setting this too low
will slow down both the proxy and PaperCut NG. Setting this value too high means this it will take
longer for users to be denied accees once they run out of credit. It is recommended to set the
ttl value to between 60 and 300 seconds.
The next step is to define an ACL for the new external ACL type defined above. To do this add the following line in the ACL section (TAG: acl).
acl papercut_allow external papercut_credit
The final step is to configure Squid so that only users with credit have Internet. To do this add an ACL by adding
the following line to the HTTP access (TAG: http_access). The rule should be added above the
http_access deny all line.
http_access allow papercut_allow
It is important to add the ACL so that it works as expected with other defined ACLs. The above ACL will work correctly if only the default Squid ACLs are defined. If other custom Squid ACL rules are used then using the above line might not work as expected.
Squid works by finding the first matching ACL rule that it encounters (from top to bottom) and a uses the specified action (allow/deny) and then no other ACLs are tested. If the above rule is used, it will match all users with credit in PaperCut NG and allow Internet access and will not process other rules. For examples, see the section called “Squid ACL examples”.
Remember to restart Squid for the changes to take effect. After restarting test the access controls are working as expected:
Access the Internet using the Squid proxy. When prompted, login as a user who has credit available in PaperCut NG. Ensure that access is allowed.
In PaperCut NG edit the balance of the user logged into Squid so they have no available credit and
set the user as "restricted". The user should no longer have access to the Internet. NOTE: That depending
on the the ttl value set on the external ACL helper it may take some time for Squid to
recheck if the user has available credit.
Configuring Squid ACL rules can get complicated when you need to define multiple rules. It is important to understand how Squid processes ACL rules, otherwise it is difficult to achieve the correct result. Squid processes the ACL rules from top to bottom, and applies the allow/deny action to the first matching rule. The Squid documentation and some complex ACL examples can be found here: http://www.visolve.com/squid/squid24s1/access_controls.php#http_access
If using the default squid configuration and no custom ACL rules have been defined then the PaperCut NG ACL
should be added below most of the default ACLs but above the http_access deny all line.
For example:
http_access allow manager localhost
http_access deny manager
http_access deny !Safe_ports
http_access deny CONNECT !SSL_ports
http_access allow papercut_allow
http_access deny all
This configuration means that Squid will allow manager access to requests from localhost, deny all other manager access, deny access to unsafe ports, and only allow access if the user has credit in PaperCut NG.
To allow access to a local intranet, even if the user does not have credit in PaperCut NG, then the following
rules could be used. The intranet ACL is assumed to be defined to include all internal web hosts
using either the dst or dstdomain ACL types.
http_access allow manager localhost
http_access deny manager
http_access deny !Safe_ports
http_access deny CONNECT !SSL_ports
http_access allow intranet
http_access allow papercut_allow
http_access deny all
This configuration means that Squid will allow access to the Intranet no matter whether they have credit available in
PaperCut NG. It does this because the http_access allow intranet rule will match, and access
will be allowed and no further rules are processed.
Some schools have users that are denied Internet access for disciplinary or other reasons. These users are
added to the "Denied Internet Users" group on the domain. These students should not have Internet access
even if they have available credit in PaperCut NG. This can be achieved using the following rules. This
assumes that the denied_group ACL is defined test for membership of the "Denied Internet Users"
group.
http_access allow manager localhost
http_access deny manager
http_access deny !Safe_ports
http_access deny CONNECT !SSL_ports
http_access deny denied_group
http_access allow papercut_allow
http_access deny all
This configuration means that Squid will deny access to users in the "Denied Internet Users" group no matter what credit they have in PaperCut NG.
© Copyright 1999-2009. PaperCut Software International Pty Ltd. All rights reserved.