Foswiki Windows Installation Guide

with IIS and ActiveState Perl or Strawberry Perl

Prerequisites

Thx to the author(s) of the FoswikiOnWindowsApacheAndActivePerl document for the ideas and the form of this document.

This Guide will show you how to run Foswiki (1.0.6 to 1.0.9) on a Windows machine with IIS (already installed). I used Windows SB Server 2003 (x86) with IIS 6.0, but it should also work on Windows XP / Vista.

Downloads

• Download ActivePerl.The normal free version is fine
  • PLEASE NOTE: There seems to be an issue with perl 5.12 (last checked perl5.12.1 Build 1201), it caused errors of the form "Use of uninitialized value in lc at [masked_path]\configure.pl line 127". Recommendation: use Perl 5.10 (last checked perl5.10.1 Build 1007), this works fine.
    • 5.16.3 (build 1603) is fine (x64)
  • Or you can use Strawberry Perl, cause it's Open Source, but then your perl.exe will be under c:\strawberry\perl\bin
• Download the latest Foswiki release from http://foswiki.org/Download
• here was a link to FastCGI - but this is not working with Perl, only with PHP

Installations

• Install Perl. Using the default installation settings should work just fine.
  • If you do want a "minimal" installation, make sure you uncheck the following features during setup:
    • "plx" support
    • "plex" support
    • "aspl" support
    • IIS Perl samples
• Unzip your Foswiki release and put its content on a path without space characters. C:\inetpub\wwwroot\foswikiwould be a default location for IIS.
  • If you choose to install it in your root directory or create a virtual directory which points directly to /foswiki, you will have no access to the "bin" directory by default. So don't do it.

Foswiki configuration

• Go to C:\inetpub\wwwroot\foswiki\bin and copy/rename LocalLib.cfg.txt to LocalLib.cfg
• Edit LocalLib.cfg and replace the line $foswikiLibPath = "/absolute/path/to/your/lib"; by $foswikiLibPath = "C:/inetpub/wwwroot/foswiki/lib";
• Go to C:\inetpub\wwwroot\foswiki\bin and rename all the extension-less files to ".pl" extensions ( PL rename script)
• Go to C:\inetpub\wwwroot\foswiki\bin and make all the files writable (you will need to search-replace content, most utilities will not allow this on read-only files):
  • Open a command prompt cmd.exe .
  • Go to C:\inetpub\wwwroot\foswiki\bin.
  • Run attrib -r * to make the files writeable

The next point seems to be obsolete, no need to change the #! line under IIS:

• • Run perl ..\tools\rewriteshebang.pl.
  • Specify the location of your Perl executable (e.g. C:\Perl\bin\perl.exe) at the prompt and confirm.
  • If you get a "permission denied at Line 71" you probably didn't make the files writeable!

If you plan to use the "TemplateLogin" login manager and you are using Foswiki 1.0.9, you wil also need to make a one-character change to a foswiki library file whose current behaviour causes major issues in IIS6:

• In "Foswiki\lib\Foswiki\LoginManager\TemplateLogin.pm"; change "$session->{response}->status(400);" to "$session->{response}->status(200);" (around line 189).
• If you do not make this change, you may find that clicking "Login" (or attempting an action that triggers a login screen to display, such as attemtping to edit a page) will cause your browser to wait for about 5 minutes, and eventually display a "Bad Request" error.
• This issue is tracked (indirectly) in Tasks.Item1029, and reported as an IIS-specific issue in Support.Question551. It is corrected in the code of Foswiki versions subsequent to 1.0.9.

IIS configuration

Link below is dead, I used following instead: http://www.howtogeek.com/50479/how-to-install-perl-on-iis-7-for-windows-server-2008/

• Go to Webservice Extensions -> Perl CGI Extension (for IIS7 see http://vanvu.net/configure-activeperl-to-work-with-iis-7/)
  • remove the <yourperlpath>\bin\perl.exe "%s" %s entry
  • set a new entry with <yourperlpath>\bin\perl.exe -T "%s" %s (adding -T enables tainting checks, essential for security)
    • IIS7 - Click "Request Restrictions..." and ensure Access is "Execute" (default is "Script").
  • ensure you set the extension to "Allowed" again, as it will have been automatically disallowed during this process.

• Ensure that the main website or Foswiki folder is reasonably safe
  • Go to Default Website -> (right-click) Properties -> Home Directory
  • Ensure that the "Execute Permissions" drop-down is set to "Scripts only" or "none"
  • Ensure that the "Script source access", "Write" and "Directory Listing" checkboxes are unchecked, and that the "Read" checkbox is checked.

• Create and configure a new perl "Application" for the "bin" folder of your Foswiki site:
  • Go to Default Website -> foswiki "bin" folder -> (right-click) Properties -> Directory -> "Create" button
    • IIS7 - right-click "bin" folder -> "convert to application"
  • Ensure that the "Execute Permissions" drop-down is set to "Scripts and Executables" (it defaults to "Scripts only")
  • Ensure that the "Script source access", "Write" and "Directory Listing" checkboxes are unchecked, and that the "Read" checkbox is checked.
  • Click "Configuration" and set the ".pl" mapping to <yourperlpath>\bin\perl.exe -T "%s" %s

• • Ensure the "Verify that file exists" setting is unchecked for this ".pl" mapping
  • IIS7 (and maybe 6) with ASP.NET installed will by default block access to any url containing "/bin/" for security reasons - this can be overridden by a web.config created in the /foswiki/bin directory, see http://blogs.iis.net/bills/archive/2008/03/23/how-to-un-block-directories-with-iis7-web-config.aspx for details.

• The following folders have to be writeable for IUSR_DOMAIN:
  • foswiki\data
  • foswiki\pub
  • foswiki\working
  • foswiki\lib (For create and maintain of LocalSite.cfg)
• The remaining folders should have read access only;

More Foswiki configuration

• Now you need some tool to search and replace a line of code in all .pl files in foswiki/bin (I used Notepad++ for this) because Foswiki is looking for the setlib.cfg in the local directory and IIS doesn't execute scripts with the pwd as to where the script lives. You can either fix this with a combination of chdir and FindBinor update the bin scripts with the find and replace below:
  • in Foswiki 1.0.5look for:
    • unshift @INC, '.';
  • in Foswiki 1.0.6look for:
    • unshift @INC ('.', grep { $_ ne '.' } @INC);
  • in Foswiki 1.0.7 (at least up to 1.0.9) look for:
    • @INC = ('.', grep { $_ ne '.' } @INC);
  • and replace it with:
    • unshift @INC, "c:/inetpub/wwwroot/foswiki/bin/";
• Go to http://localhost/foswiki/bin/configure.pl.
• You should get a list of warnings in the General path settings section.
• Open the General path settings section.
• Fix all the paths containing backslashes ( \) by replacing them with a forward slash ( /).
• In the ScriptSuffix setting, enter ".pl" (without the quotes)
• Click the Next button.
• Enter a new password, confirm and click Change Password and Save button.
• Follow the Return to configuration link.
• Now you should get 52 errors in the Store Settings section, one warning in the Security Setup section, and one warning in the Mail and Proxies section.
• Click the Yes, I've read all the documentation button at the top of the page.
• Go to the Security Setup section and select for {LoginManager}
  • ApacheLogin if you're using the More IIS configuration (AD) below
  • TemplateLogin to use the built in htpasswd files
  • none is not a good idea (every User is guest)
• Goto the Store Settings section and select the option RcsLite for {StoreImpl}.
• Goto the Mail and Proxies section and provide your email address in the {WebMasterEmail} field.
• Go to the Mail and Proxies section and set appropriate SMTP settings, including SENDERHOST. For a typical simple internal setup this will just be "localhost" in the "MAILHOST" and "SENDERHOST" settings, as IIS has a built-in SMTP server. If you do not set these correctly then the Registration process will hang for a long time and eventually fail.
• Search for the {RCS}{SearchAlgorithm} option in the Store settings section and select Foswiki::Store::SearchAlgorithms::PurePerl.
• Click the Next button, provide your password and save.
• Follow the Go to the Foswiki front page link.

More IIS configuration (AD)

• You have to enable ApacheLogin as Login method
• Go to your default website in the IIS Manager, right click on it, select Properties
• Or if you only want to use your AD for Foswiki, look for the foswiki directory, right click on it, select Properties
• Go to Directory Security -> Authentication and Access Control -> Edit
• Unselect "Enable anonymous access"
• Select "Integrated Windows Authentication" and "Digest authentication for Windows Domain Name Servers"
• That's it, now you can use your AD Users as login for foswiki
• Disadvantage:
  • You cannot logout anymore unless you close the browser

• If you get some errors about a "Permission denied" on "foswiki/working/tmp" or "foswiki/data" you have to set permissions for these directories
• In Windows Explorer go to these directories and right click on them and select "Properties"
• Select "Security" and click on "User (DOMAIN\User)"
• Give it read/write access to
  • foswiki\data
  • foswiki\pub
  • foswiki\working

Congratulations

You are done!

Happy Foswiki