From: Amos Jeffries Date: Tue, 9 Sep 2008 13:33:34 +0000 (+1200) Subject: Import windows support notes from 2.6 X-Git-Tag: SQUID_3_0_STABLE9~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6cee15438e4ce76458924d952bee32618c69fb18;p=thirdparty%2Fsquid.git Import windows support notes from 2.6 --- diff --git a/doc/release-notes/release-3.0.html b/doc/release-notes/release-3.0.html index 717a5ed68f..94cdcdf775 100644 --- a/doc/release-notes/release-3.0.html +++ b/doc/release-notes/release-3.0.html @@ -123,11 +123,229 @@ Some have been dropped as they are not needed. Some have not yet been forward-po

See http://www.squid-cache.org/Doc/FAQ/FAQ-6.html#ss6.7 for a definition of all log types.

+

5. Windows support

+

This Squid version can run on Windows as a system service using the Cygwin emulation environment, +or can be compiled in Windows native mode using the MinGW + MSYS development environment. Windows NT 4 SP4 and later are supported.
+On Windows 2000 and later the service is configured to use the Windows Service Recovery option +restarting automatically after 60 seconds. +

+ +
Usage
+

Some new command line options were added for the Windows service support:

+

The service installation is made with -i command line switch, it's possible to use -f switch at +the same time for specify a different config-file settings for the Squid Service that will be +stored on the Windows Registry.

+

A new -n switch specify the Windows Service Name, so multiple Squid instance are allowed. +"Squid" is the default when the switch is not used.

+

So, to install the service, the syntax is:

+

+

+squid -i [-f file] [-n name]
+
+

+

Service uninstallation is made with -r command line switch with the appropriate -n switch.

+

The -k switch family must be used with the appropriate -f and -n switches, so the syntax is:

+

+

+squid -k command [-f file] -n service-name
+
+ +where service-name is the name specified with -n options at service install time.

+

To use the Squid original command line, the new -O switch must be used ONCE, the syntax is:

+

+

+squid -O cmdline [-n service-name]
+
+ +If multiple service command line options must be specified, use quote. The -n switch is +needed only when a non default service name is in use.

+

Don't use the "Start parameters" in the Windows 2000/XP/2003 Service applet: they are +specific to Windows services functionality and Squid is not designed for understand they.

+

In the following example the command line of the "squidsvc" Squid service is set to "-D -u 3130":

+

+

+squid -O "-D -u 3130" -n squidsvc
+
+

+
+

+

+

+
PSAPI.DLL (Process Status Helper) Considerations
+

The process status helper functions make it easier for you to obtain information about +processes and device drivers running on Microsoft® Windows NT®/Windows® 2000. These +functions are available in PSAPI.DLL, which is distributed in the Microsoft® Platform +Software Development Kit (SDK). The same information is generally available through the +performance data in the registry, but it is more difficult to get to it. PSAPI.DLL is +freely redistributable.

+

PSAPI.DLL is available only on Windows NT, 2000, XP and 2003. The implementation in Squid is +aware of this, and try to use it only on the right platform.

+

On Windows NT PSAPI.DLL can be found as component of many applications, if you need it, +you can find it on Windows NT Resource KIT. If you have problem, it can be +downloaded from here: +http://download.microsoft.com/download/platformsdk/Redist/4.0.1371.1/NT4/EN-US/psinst.EXE

+

On Windows 2000 and later it is available installing the Windows Support Tools, located on the +Support\Tools folder of the installation Windows CD-ROM.

+
+

+

+

+
Registry DNS lookup
+

On Windows platforms, if no value is specified in the dns_nameservers option on +squid.conf or in the /etc/resolv.conf file, the list of DNS name servers are +taken from the Windows registry, both static and dynamic DHCP configurations +are supported.

+
+

+

+

+
Compatibility Notes
+

+

    +
  • It's recommended to use '/' char in Squid paths instead of '\'
    • +
  • Paths with spaces (like 'C:\Programs Files\Squid) are NOT supported by Squid
    • +
  • When using ACL like 'acl aclname acltype "file"' the file must be in DOS text +format (CR+LF) and the full Windows path must be specified, for example: + +
    +acl blocklist url_regex -i "c:/squid/etc/blocked1.txt"
+
    + +
    • +
  • The Windows equivalent of '/dev/null' is 'NUL'
    • +
  • Squid doesn't know how to run external helpers based on scripts, like .bat, .cmd, +.vbs, .pl, etc. So in squid.conf the interpreter path must be always specified, for example: + +
    +redirect_program c:/perl/bin/perl.exe c:/squid/libexec/redir.pl
+redirect_program c:/winnt/system32/cmd.exe /C c:/squid/libexec/redir.cmd
+
    +
    • +
  • When Squid runs in command line mode, the launching user account must have administrative privilege on the system
    • +
  • "Start parameters" in the Windows 2000/XP/2003 Service applet cannot be used
    • +
  • Building with MinGW, when the configure option --enable-truncate is used, Squid cannot run on Windows NT, only Windows 2000 and later are supported
    • +
+

+
+

+

+

+
Known Limitations
+

+

    +
  • Squid features not operational:
    +
      +
    • DISKD: still needs to be ported
      • +
    • WCCP: cannot work because user space GRE support on Windows is missing
      • +
    • Transparent Proxy: missing Windows non commercial interception driver
      • +
    +
    • +
  • Some code sections can make blocking calls.
    • +
  • Some external helpers may not work.
    • +
  • File Descriptors number hard-limited to 2048 when building with MinGW.
    • +
+

+
+

+

+

+
Building Squid on Windows
+

A reasonably recent release of +Cygwin or +MinGW is needed.
+The usage of the Cygwin environment is very similar to other Unix/Linux environments, and -devel version of libraries must be installed.
+For the MinGW environment, the packages MSYS, MinGW and msysDTK must be installed. Some additional libraries and tools must be downloaded separately:

+OpenSSL: +Shining Light Productions Win32 OpenSSL
+libcrypt: +MinGW packages repository
+db-1.85: +TinyCOBOL download area
+uudecode: +Native Win32 ports of some GNU utilities

+When running configure, --disable-wccp and --disable-wccpv2 options should always specified to avoid compile errors.
+

    +
  • New configure options:
    +
      +
    • --enable-win32-service
      • +
    +
    • +
  • Updated configure options:
    +
      +
    • --enable-arp-acl
      • +
    • --enable-default-hostsfile
      • +
    +
    • +
  • Unsupported configure options:
    +
      +
    • --enable-coss-aio-ops: On Windows Posix AIO is not available
      • +
    • --with-large-files: No suitable build environment is available on both Cygwin and MinGW, but --enable-large-cache-files works fine
      • +
    +
    • +
  • Recommended configure minimal options for Windows:
    +
      +
    • --prefix=c:/squid --disable-wccp --disable-wccpv2 --enable-win32-service --enable-default-hostsfile=none
      • +
    +
    • +
+
+Before build Squid with SSL support, some operations are needed (in the following example OpenSSL is installed in C:\OpenSSL and MinGW in C:\MinGW): +
    +
  • Copy C:\OpenSSL\lib\MinGW content to C:\MinGW\lib
    • +
  • Copy C:\OpenSSL\include\openssl content to C:\MinGW\include\openssl
    • +
  • Rename C:\MinGW\lib\ssleay32.a to C:\MinGW\lib\libssleay32.a
    • +
+

+ +
+

+

+

+
Using cache manager on Windows:
+

On Windows, cache manager (cachemgr.cgi) can be used with Microsoft IIS or Apache.
+Some specific configuration could be needed:
+

    +
  • IIS 6 (Windows 2003):
    +
      +
    • On IIS 6.0 all CGI extensions are denied by default for security reason, so the following configuration is needed:
      +
        +
      • Create a cgi-bin Directory
        • +
      • Define the cgi-bin IIS Virtual Directory with read and CGI execute IIS +permissions, ASP scripts are not needed. This automatically defines a +cgi-bin IIS web application
        • +
      • Copy cachemgr.cgi into cgi-bin directory and look to file permissions: +the IIS system account and SYSTEM must be able to read and execute the file
        • +
      • In IIS manager go to Web Service extensions and add a new Web Service +Extension called "Squid Cachemgr", add the cachemgr.cgi file and set the +extension status to Allowed
        • +
      +
      • +
    +
    • +
  • Apache:
    +
      +
    • On Windows, cachemgr.cgi needs to create a temporary file, so Apache must be instructed +to pass the TMP and TEMP Windows environment variables to CGI applications:
      +
      +ScriptAlias /squid/cgi-bin/ "c:/squid/libexec/"
+<Location /squid/cgi-bin/cachemgr.cgi>
+    PassEnv TMP TEMP
+    Order allow,deny
+    Allow from workstation.example.com
+</Location>
+
      +
      • +
    +
    • +
+

+
+

-

4.4 Changes to squid.conf +

5.1 Changes to squid.conf

There have been many changes to Squid's configuration file since Squid-2.6.

@@ -333,7 +551,7 @@ If set to 1 and the ICAP server cannot be reached, the request will go through without being processed by an ICAP server service_url = icap://servername:port/service -Note: reqmod_precache and respmod_postcache is not yet implemented +Note: reqmod_postcache and respmod_postcache is not yet implemented Example: icap_service service_1 reqmod_precache 0 icap://icap1.mydomain.net:1344/reqmod @@ -732,7 +950,7 @@ This is useful for class 4 Delay Pools in Squid 3.x

-

4.5 Changes to ./configure Options +

5.2 Changes to ./configure Options

There have been some changes to Squid's build configuration since Squid-2.6.

diff --git a/doc/release-notes/release-3.0.sgml b/doc/release-notes/release-3.0.sgml index 762707c62c..3b5f694c9b 100644 --- a/doc/release-notes/release-3.0.sgml +++ b/doc/release-notes/release-3.0.sgml @@ -110,7 +110,191 @@ Some have been dropped as they are not needed. Some have not yet been forward-po

The requested object was cached but STALE. The IMS query returned the new content.

See for a definition of all log types. +Windows support +

This Squid version can run on Windows as a system service using the Cygwin emulation environment, +or can be compiled in Windows native mode using the MinGW + MSYS development environment. Windows NT 4 SP4 and later are supported. +On Windows 2000 and later the service is configured to use the Windows Service Recovery option +restarting automatically after 60 seconds. + + +Usage + +Some new command line options were added for the Windows service support: + +The service installation is made with -i command line switch, it's possible to use -f switch at +the same time for specify a different config-file settings for the Squid Service that will be +stored on the Windows Registry. + +A new -n switch specify the Windows Service Name, so multiple Squid instance are allowed. +squid -i [-f file] [-n name] + +Service uninstallation is made with -r command line switch with the appropriate -n switch. + +The -k switch family must be used with the appropriate -f and -n switches, so the syntax is: + +squid -k command [-f file] -n service-name +where squid -O cmdline [-n service-name] +If multiple service command line options must be specified, use quote. The -n switch is +needed only when a non default service name is in use. + +Don't use the "Start parameters" in the Windows 2000/XP/2003 Service applet: they are +specific to Windows services functionality and Squid is not designed for understand they. + +In the following example the command line of the "squidsvc" Squid service is set to "-D -u 3130": + +squid -O "-D -u 3130" -n squidsvc + + + +PSAPI.DLL (Process Status Helper) Considerations + +The process status helper functions make it easier for you to obtain information about +processes and device drivers running on Microsoft® Windows NT®/Windows® 2000. These +functions are available in PSAPI.DLL, which is distributed in the Microsoft® Platform +Software Development Kit (SDK). The same information is generally available through the +performance data in the registry, but it is more difficult to get to it. PSAPI.DLL is +freely redistributable. + +PSAPI.DLL is available only on Windows NT, 2000, XP and 2003. The implementation in Squid is +aware of this, and try to use it only on the right platform. + +On Windows NT PSAPI.DLL can be found as component of many applications, if you need it, +you can find it on Windows NT Resource KIT. If you have problem, it can be +downloaded from here: + + +On Windows 2000 and later it is available installing the Windows Support Tools, located on the +Support\Tools folder of the installation Windows CD-ROM. + + + +Registry DNS lookup +On Windows platforms, if no value is specified in the + + +Compatibility Notes + +It's recommended to use '/' char in Squid paths instead of '\' +Paths with spaces (like 'C:\Programs Files\Squid) are NOT supported by Squid +When using ACL like 'acl aclname acltype "file"' the file must be in DOS text +format (CR+LF) and the full Windows path must be specified, for example: + +acl blocklist url_regex -i "c:/squid/etc/blocked1.txt" + +The Windows equivalent of '/dev/null' is 'NUL' +Squid doesn't know how to run external helpers based on scripts, like .bat, .cmd, +.vbs, .pl, etc. So in squid.conf the interpreter path must be always specified, for example: + +redirect_program c:/perl/bin/perl.exe c:/squid/libexec/redir.pl +redirect_program c:/winnt/system32/cmd.exe /C c:/squid/libexec/redir.cmd +When Squid runs in command line mode, the launching user account must have administrative privilege on the system +"Start parameters" in the Windows 2000/XP/2003 Service applet cannot be used +Building with MinGW, when the configure option --enable-truncate is used, Squid cannot run on Windows NT, only Windows 2000 and later are supported + + + + +Known Limitations + +Squid features not operational: + +DISKD: still needs to be ported +WCCP: cannot work because user space GRE support on Windows is missing +Transparent Proxy: missing Windows non commercial interception driver + +Some code sections can make blocking calls. +Some external helpers may not work. +File Descriptors number hard-limited to 2048 when building with MinGW. + + + +Building Squid on Windows +A reasonably recent release of or is needed. +The usage of the Cygwin environment is very similar to other Unix/Linux environments, and -devel version of libraries must be installed. +For the MinGW environment, the packages MSYS, MinGW and msysDTK must be installed. Some additional libraries and tools must be downloaded separately: +OpenSSL: +libcrypt: +db-1.85: +uudecode: +When running configure, --disable-wccp and --disable-wccpv2 options should always specified to avoid compile errors. + +New configure options: + +--enable-win32-service + +Updated configure options: + +--enable-arp-acl +--enable-default-hostsfile + +Unsupported configure options: + +--enable-coss-aio-ops: On Windows Posix AIO is not available +--with-large-files: No suitable build environment is available on both Cygwin and MinGW, but --enable-large-cache-files works fine + +Recommended configure minimal options for Windows: + +--prefix=c:/squid --disable-wccp --disable-wccpv2 --enable-win32-service --enable-default-hostsfile=none + + + +Before build Squid with SSL support, some operations are needed (in the following example OpenSSL is installed in C:\OpenSSL and MinGW in C:\MinGW): + +Copy C:\OpenSSL\lib\MinGW content to C:\MinGW\lib +Copy C:\OpenSSL\include\openssl content to C:\MinGW\include\openssl +Rename C:\MinGW\lib\ssleay32.a to C:\MinGW\lib\libssleay32.a + + + + + +Using cache manager on Windows: +On Windows, cache manager (cachemgr.cgi) can be used with Microsoft IIS or Apache. +Some specific configuration could be needed: + +IIS 6 (Windows 2003): + +On IIS 6.0 all CGI extensions are denied by default for security reason, so the following configuration is needed: + +Create a cgi-bin Directory +Define the cgi-bin IIS Virtual Directory with read and CGI execute IIS +permissions, ASP scripts are not needed. This automatically defines a +cgi-bin IIS web application +Copy cachemgr.cgi into cgi-bin directory and look to file permissions: +the IIS system account and SYSTEM must be able to read and execute the file +In IIS manager go to Web Service extensions and add a new Web Service +Extension called + +Apache: + +On Windows, cachemgr.cgi needs to create a temporary file, so Apache must be instructed + to pass the TMP and TEMP Windows environment variables to CGI applications: + +ScriptAlias /squid/cgi-bin/ "c:/squid/libexec/" +<Location /squid/cgi-bin/cachemgr.cgi> + PassEnv TMP TEMP + Order allow,deny + Allow from workstation.example.com +</Location> + + + +