<HTML> <HEAD> <TITLE>MSNTAUTH readme</TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> <!-- If you require this document in text form, download the HTML-text package from http://members.tripod.com/stellarx. --> <H1> MSNT Auth v2.0.3-squid.1<BR> Squid web proxy NT authentication module<BR> Modified by the Squid HTTP Proxy team<BR> Wed Jun 26 21:16:32 CEST 2002<BR> Original release by Antonino Iannella, Stellar-X Pty Ltd<BR> </H1> <H2>Contents</H2> <UL> <LI> <A HREF="#introduction">Introduction</A> <LI> <A HREF="#installation">Installation</A> <LI> <A HREF="#compiling">Issues when compiling</A> <LI> <A HREF="#configuration">Configuration file</A> <LI> <A HREF="#denying">Denying users</A> <LI> <A HREF="#allowing">Allowing users</A> <LI> <A HREF="#squid">Squid.conf changes</A> <LI> <A HREF="#testing">Testing</A> <LI> <A HREF="#contact">Contact details</A> <LI> <A HREF="#unknown">Unknown username issue</A> <LI> <A HREF="#changes">Revision history</A> </UL> <A NAME="introduction"><H2>Introduction</H2> <P> This is an authentication module for the Squid proxy server to use an NT domain server. <P> It originates from the Samba and SMB packages by Andrew Tridgell and Richard Sharpe. It is sourced from the Pike authentication module by William Welliver (hwellive@intersil.com), and the SMB 1.0.1 libraries. Releases up to version 2.0.3 were created by Antonino Iannella (antonino@rager.com.au, http://stellarx.tripod.com). The module is now distributed with Squid, and is maintained by the Squid proxy team as an Open Source effort. Msntauth is released under the GNU General Public License. <P> Usage is simple. It accepts a username and password on standard input. It will return OK if the username/password is valid for the domain, or ERR if there was some problem. Check syslog messages for reported problems. <P> Msntauth works in environments with NT domain controllers on Windows (TM) NT 4, 2000, and Samba. <A NAME="installation"><H2>Installation</H2> <P> Msntauth will be compiled when you compile Squid, using their autoconf system. Refer to Squid documentation for details. If the build is suitable, you can skip this section. <P> Alternatively, a supplementary makefile is also provided for manual compiling. Review Makefile.MSNT, and modify it based on the target platform or site requirements. <P> Make any necessary changes to the source code. <P> Copy Makefile.MSNT to Makefile. Type 'make', then 'make install', then 'make clean'. <P> To avoid using the makefile, it may compile with gcc -O2 -s -o msntauth *.c <P> 'Make install' will put 'msntauth' into /usr/local/squid/bin. <A NAME="compiling"><H2>Issues when compiling</H2> <P> The Makefile uses your C compiler (usually GCC), assuming it's in your PATH. Msntauth is known to compile properly on Linux, FreeBSD, and Solaris. <P> When compiling under Solaris, link to the NSL and socket libraries. In the Makefile, enable the alternative CFLAGS line for Solaris. Ensure /usr/ccs/bin is in your PATH. In Smbencrypt.c, '#include <sys/vfs.h>' only gets included when compiled with Solaris. <P> For Digital Unix/Tru64, review the INSTALL line in the makefile. The install-bsd command is used to place files in their target location. <A NAME="configuration"><H2>Configuration file</H2> <P> Msntauth uses a configuration file, usually /usr/local/squid/etc/msntauth.conf. To change this, edit the following line in confload.c - <PRE> #define CONFIGFILE "/usr/local/squid/etc/msntauth.conf" </PRE> <P> An example configuration file is provided - <PRE> # Sample MSNT authenticator configuration file # Antonino Iannella, Stellar-X Pty Ltd # Tue Aug 26 17:26:59 GMT+9 2003 # NT domain hosts. Best to put the hostnames in /etc/hosts. server myPDC myBDC myNTdomain server otherPDC otherBDC otherdomain # Denied and allowed users. Comment these if not needed. denyusers /usr/local/squid/etc/denyusers allowusers /usr/local/squid/etc/allowusers </PRE> <P> All comments start with '#'. <P> NT servers are used to query user accounts. The 'server' lines are used for this, with the PDC, BDC, and NT domain as parameters. Up to 5 servers/domains can be queried. If this is not enough, modify the MAXSERVERS define in confload.c. At least one server must be specified, or msntauth will not start. Server names must be resolvable by the system. If not, msntauth reports an error. If you can't ping it, you might have a host resolution problem. <P> The name you specify is used in the NetBIOS protocol when communicating with the target server. The name must be resolvable by the local system, and it must be a name that the target server uses. You cannot simply invent a hostname. You cannot use it IP address. <P> When a user provides a username/password, each of these servers will be queried to authenticate the username. It stops after a user has been successfully authenticated, so it makes sense to specify the most commonly queried server first. Make sure the servers can be reached and are active, or else msntauth will report failures. <P> The 'denyusers' and 'allowusers' lines give the absolute path to files of user accounts. They can be used to deny or allow access to the proxy. Remove these directives if you do not need these features. <A NAME="denying"><H2>Denying users</H2> <P> Users who are not allowed to access the web proxy can be added to the denied user list. This list is read around every minute, or when the msntauth process receives a SIGHUP signal. <P> The denied user file is set using the 'denyusers' directive in msntauth.conf. The denied user file contains a list of usernames, one per line. If the file does not exist, no users are denied. The file must be readable by the web proxy user. <P> Msntauth will send syslog messages if a user was denied, at LOG_USER facility. Check your syslog messages for clues. <A NAME="allowing"><H2>Allowing users</H2> <P> Similar to denying users, you can allow users to access the proxy by username. This is useful if only a number of people are allowed to use a proxy. <P> The allowed user file is set using the 'allowusers' directive in msntauth.conf. If the file does not exist or if empty, all users are allowed. <P> You could make use of the SHOWMBRS tool in Microsoft Technet. This gives you a list of users which are in a particular NT Domain Group. This list can be made into the allowed users file using sed or awk. <P> Some other rules - <OL> <LI> The operation of the denied user file is independent of the allowed user file. The former file is checked first. <LI> You can use none, one, or both files. <LI> If a username appears in the denied user file, they will be denied, even if they are in the allowed user file. <LI> If a username is not in either file, they will be denied, because they have not been allowed. <LI> If the allowed user file is in use and is empty, all users will be allowed. </OL> <A NAME="squid"><H2>Squid.conf changes</H2> <P> Refer to Squid documentation for the required changes to squid.conf. You will need to set the following lines to enable authentication for your access list - <PRE> acl <I>yourACL</I> proxy_auth REQUIRED http_access allow password http_access allow <I>yourACL</I> http_access deny all </PRE> <P> You will also need to review the following directives. The number of msntauth children spawned is set with authenticate_children. The number of children needed is site-dependent, so some experimentation may be required to find the best number. There should be no visible delay in performance with Squid once msntauth is in use. As an example, a firm with 1500 users and a T1 internet connection required a value of 30. <PRE> proxy_auth_realm enterprise web gateway authenticate_program /usr/local/squid/bin/msntauth authenticate_ttl 5 authenticate_children 20 </PRE> <A NAME="testing"><H2>Testing</H2> <P> I strongly urge that Msntauth is tested prior to being used in a production environment. It may behave differently on different platforms. To test it, run it from the command line. Enter username and password pairs separated by a space. <P> It should behave in the following way - <PRE> - Press ENTER to get an OK or ERR message. - Make sure pressing CTRL-D behaves the same as a carriage return. - Make sure pressing CTRL-C aborts the program. - Test that entering no details does not result in an OK or ERR message. - Test that entering an invalid username and password results in an ERR message. Note that if NT guest user access is allowed on the PDC, an OK message may be returned instead of ERR. - Test that entering an valid username and password results in an OK message. Try usernames which are and aren't in the denied/allowed user files, if they're in use. - Test that entering a guest username and password returns the correct response. </PRE> <P> If the above didn't work as expected, you may need to modify the main() function in msntauth.c. Inform the Squid maintainers of any problems. <P> Usernames cannot have whitespace in them, but passwords can. <P> As of version 2.0.3, the msntauth version can be found in the executable. Type this to retrieve it - <PRE> strings msntauth | grep -i msntauth </PRE> <A NAME="contact"><H2>Support details</H2> <P> Refer to the Squid website at http://www.squid-cache.org. Submit problems or fixes using their Bugzilla facility. <A NAME="unknown"><H2>Unknown username issue</H2> <P> For an unknown username, Msntauth returns OK. This is because the PDC returns guest access for unknown users, even if guest access is disabled. This problem was reported by Mr Vadim Popov (vap@iilsr.minsk.by). <P> The tested environment consisted of PDC on Windows NT 4, SP 6. Squid 2.3 and Msntauth was tested on SuSe, RedHat, and Debian Linux. A fix was provided in case you have this problem. Apply the provided patch before compiling, using <PRE> patch smblib.c < smblib.c.patch </PRE> <A NAME="changes"><H2>Revision history</H2> <P> The following sequence of changes have been made to improve msntauth. <UL> <LI>Added many patches from Duane Wessels to stop compilation errors <LI>Improved the main() function yet again <LI>Created a more informative Makefile <LI>Added an 'allowed users' feature to complement the 'denied users' feature <LI>Stopped the use of alarm() which was causing problems under Solaris <LI>Added more syslog messages for authentication problems <LI>Added the use of a configuration file, instead of hard-coding NT server details <LI>Allowed for querying multiple NT servers and domains (this was a hot issue) <LI>Changed README into an HTML document to improve readability <LI>Removed denied/allowed username substring search limitation <LI>Fixed a bug which occurred when reading denied/allowed usernames <LI>Allows whitespace in passwords <LI>To check user list changes, doesn't use an alarm every minute. <LI>Fixed a sigaction compilation error, causing problems on FreeBSD and HPUX <LI>Removed a problem of finding a valid username as a substring in the denied user list. <LI>Support email address change from antonino@usa.net to antonino@rager.com.au. <LI>Msntauth was successfully tested on Tru64. <LI>PDC and BDC hostnames are now checked if they are resolvable. <LI>Smbencrypt.c does not have to be checked for Solaris systems any more. <LI>Imbedded version information in the executable. <LI>Version 2.0.3 and later now supported by the Squid team. </UL> <P> A future improvement may be to cache accepted usernames and passwords, to reduce network authentication traffic, and improve the Squid response time. </BODY> </HTML>
