Windows + IIS + CygwinPerl Installation Cookbook

WARNING:	THIS DOCUMENT DOES NOT APPLY TO TWIKI-4 though you may be able to extrapolate some steps from here

This document should be used with Caution. Unless you consider yourself expert with Cygwin, IIS and Perl you should use the Apache/Cygwin-based WindowsInstallCookbook instructions.

I say this because:

• Main.DougRansom sent me an email to say that he'd given up on TWiki and was now working with SushiWiki instead.
• Main.TorbenGB told me on TWikiIRC that he'd given up on IIS and was working with the Apache-based TWikiOnWindows instructions

Going forward, I'd like to suggest that:

• this page should be renamed TWikiOnWindowsUsingIISAndCygwinPerl &
• TWikiOnWindowsUsingIIS be renamed TWikiOnWindowsUsingIISAndActiveStatePerl
• We ask around our users for a known-good TWikiOnWindowsUsingIISAndActiveStatePerl configuration and capture this as part of the TWikiUnixInstaller
  • I will email all the users listed on this page - MartinCleaver
  • MartinsInstallOnIIS could be a place to start - this is the instructions we put together at my last workplace
  • DougsInstallOnIIS shows the process he went through

Buyer beware... beyond this point lie dragons.

-- MartinCleaver - 10 Jul 2003

---

This topic provides a short list of outcomes and main traps MarkusKling encountered while installing TWiki for the first time on Windows, CygwinPerl and IIS. Please start reading at the WindowsInstallCookbook since here you will only find very brief descriptions of the minimum required steps.

Software Requirements

• CygWin with RCS
• ActiveState Perl
• IIS

Installation

• Download/Install cygwin from http://www.cygwin.com. You have to select the rcs files manually
• Download ActiveState Perl from http://www.activestate.com and select the IIS integration while installing
• Extract TWiki contribution from http://Twiki.org/download.html to the folder of your choice.

CYGWIN

• Run cygwin.bat
• Mount the drive where your TWiki installation resides as binary type (for instance e:\)
  • mkdir /e
  • mount -b e:/ /e

RCS

• My-Computer -> System Properties -> Environment -> System Variables
  • add cygwin/bin, perl/bin to the PATH variable
  • add LOGNAME = anonymous
  • add RCSINIT = -x,v

• Goto the data directory. For each subdirectory type
  • rcs -u *.txt (answer break-lock questions with "yes")
  • rcs -l *.txt

IIS

• Start IIS
• Open MMC
• Create Virtual Directory pointing to your twiki directory
• Change Authentication to Basic & Integrated Windows Authentication
• Point MMC to the bin directory and select Properties
  • Create an Application
  • Select "Scripts and Executables"
  • Configure ".pl", ".plx" within "Application Mappings" that they don't check that the file exists

• Now you must REBOOT your server in order that the environment variables you set before take effect for the "SYSTEM" user
• Some versions of IIS (eg. the one in Windows Vista) block access to any directory named "bin". You can either rename the bin directory to something else (the configure script will notice and set the path correctly, though you should review the PubUrlPath as some versions of Foswiki set it incorrectly if you rename the bin directory) or remove the blocking. It's located in the c:\inetpub\temp\appPools\AppPoolName.config in <security><requestFiltering><hiddenSegments>. It's safer to rename the directory because IIS tends to reset the restriction if you make changes to the file extension mapping.

Configure TWiki

• Goto bin
  • type rename * *.pl
• Open lib\Twiki.cfg
  • Point wikiHomeUrl, defaultUrlHost, scriptUrlPath, pubUrlPath, pubDir, templateDir, dataDir to the appropriate pathes. Use fully qualified names in "/" notation for your paths!
  • set scriptSuffix to .pl
  • add "cygwin\\bin" and "winnt\\system32" to the safeEnvPath. Use the "d:\\" Notation for your pathes!
  • set rcsArg to -x,v
  • Edit rcsDir, revInitBinaryCmd, revCiCmd, revCiDateCmd, revCoCmd, revHistCmd, revInfoCmd, revDiffCmd, revDelRevCmd, revUnlockCmd, revLockCmd, revBreakLockCmd. Use "d:\\" notation and add ".exe" to the commands.
  • Edit lsCmd, egrepCmd, fgrepCmd. Use full qualified names in "d:\\" notation and add ".exe" to the commands. Keep in mind that there don't exist an fgrep command; fgrep must also point to grep.exe.
    • Specify the -E option on the $egrepCmd setting, e.g. "c:\\cygwin\\bin\\grep -E". (Necessary with more recent Cygwin versions.)
    • Specify the -F option on the $fgrepCmd setting, e.g. "c:\\cygwin\\bin\\grep -F".

• Test your configuration, pointing the browser to "url/twiki/bin/view.pl"

Code Changes

• Store.pm
  • remove the 2>&1 1>$TWiki::nullDev from all commands.
• Search.pm
  • Search for if( $theRegex ) and add . " -E" to the egrep command in order to support regular expressions. - not needed, done by editing TWiki.cfg above.

Authentication

The TWiki can interact with the built in IIS authentication. So you can map users from your NT domain to TWiki users while providing their case sensitive intranet-login name via registration. Use the ASP below to query your actual username.

   example.asp
   <%=Request.ServerVariables("AUTH_USER")%>

In order to receive a TWikiGuest when the user is not remembered edit TWiki::userToWikiName and change

   my $wUser = $userToWikiList{ $loginUser } || $loginUser;
   to
   my $wUser = $userToWikiList{ $loginUser } || $defaultUserName;

Then edit TWiki.cfg and set the defaultUserName to TWikiGuest.

-- MarkusKling - 15 Jul 2002

In the Application for the bin directory, I had to add -T to the perl command associated with the .pl extension in order to get around a Too late for for "-T" option error when testing view.pl (IIS 5.1 on WinXP). Also, for pubDir, templateDir, and dataDir I had to use Windows notation to get view.pl to work (i.e. /c/TWiki/pub didn't work, but c:\\TWiki\\pub did work). TWiki20011201.zip.

-- DavidMurray - 10 Oct 2002

The /c/TWiki/pub notation doesn't work because you are using ActivePerl not CygWin Perl. I've also made an update above so people don't need to edit Search.pm. The WindowsInstallCookbook settings for fgrep and egrep options (-F and -E, I think) can be used if you have problems.

-- RichardDonkin - 06 Dec 2002

"Point wikiHomeUrl, defaultUrlHost, scriptUrlPath, pubUrlPath, pubDir, templateDir, dataDir to the appropriate pathes. Use fully qualified names in "/" notation for your paths! " "Edit rcsDir, revInitBinaryCmd, revCiCmd, revCiDateCmd, revCoCmd, revHistCmd, revInfoCmd, revDiffCmd, revDelRevCmd, revUnlockCmd, revLockCmd, revBreakLockCmd. Use "d:\\" notation and add ".exe" to the commands. "

"Create Virtual Directory pointing to your twiki directory". Which is the twiki directory

installdir/twiki?
installdir/twiki/data?
installdir/twiki/data/twiki?
installdir/twiki/data/main?

I wish I understood what these meant and what I should change them to. A little more handholding in the instructions would be nice.

I think it would be insightful to have a complete example. List the virtual dirs set up in IIS, the absolute directories twiki is installed to, and a concrete example of every variable listed above.

-- DougRansom 24 Dec 2002 --

For W2K Server with IIS & ActiveState had to add the -T to the perl command. It looks like this: D:\apps\Perl\bin\perl.exe -T "%s" %s

I don't understand the motivation to remove the 2>&1 1>$TWiki::nullDev from all commands and have not yet done this.

It worries me that I see a shell flash on the server when I edit a wiki page using a browser running on the server itself.

-- DougRansom - 24 Dec 2002

I followed the mount instructions (to the best of my ability anyway ☻) The value for data dir /d/apps/twiki/data/ doesn't work, but d:/apps/twiki/data/ does work. "mount" displays:

d: on /d type system (binmode)

I think this is causing me problems and the one area I could really use some help on.

-- DougRansom - 24 Dec 2002

A performance improvement may be possible using ISAPI instead of CGI to run the perl scripts. http://aspn.activestate.com//ASPN/Reference/Products/ActivePerl/faq/Windows/ActivePerl-Winfaq6.html#How_do_I_configure_Microsoft_IIS ISAPI for perl

-- DougRansom - 25 Dec 2002

Hi Doug, don't worry

• The TWiki directory is the main directory of your installation containing at least the "/bin" and the "/pub" directory.
• I had to remove the 2>&1 1>$TWiki::nullDev from some commands in order to have them executed correctly. Maybe this has been fixed since today.
• If you're using CYGWIN then the mount point is only for the cygwin.dll (and executables using it) to access the files correctly. You must still use Windows notations for TWiki pathes if you use the ActiveStatePerl executable/dll.
• I could not execute all scripts correctly using the Perl ISAPI plugin. Had some problems regarding POST/GET and HTTP refreshes. Would be nice if you state some of your experiences.

-- MarkusKling - 26 Dec 2002

I have not actually tried the Perl ISAPI filter yet instead of the CGI because I have yet to get twiki working. I am having problems similar to GettingRCSToWorkWithIIS. I can change a page, and view the change in wiki, but others cannot edit the same wiki page because its locked by me (even though I have a finished my edits), and my changes never show up in the diffs and the rcs version number does not increase. Obviously, my edits are not sucessfully checked in.

I thought this might bee due to the mount behavior I described on Dec 24.

I am at a loss of what to do next. I am using ActiveStatePerl. All help appreciated.

-- DougRansom - 26 Dec 2002

Finally after hours of digging around, I found I had to change LOGNAME to "nobody". The instructions above say "anonymous". During hacking about, I also changed some environment variables, tried cygwin perl (didn't get it going), went back to activeState perl, and gave everyone full access to the twiki directory. Not sure which of these are required.

-- DougRansom - 30 Dec 2002

Attachments don't work, but otherwise RCS seems to work. I am curious as to whether I have incorrectly set one of the variables in twiki.cfg -- I have attached that file to DougsInstallOnIIS.

-- DougRansom - 30 Dec 2002

Just found a useful page with http://www.whitecrow.demon.co.uk/steve/iis4.html Tips on IIS4 and Perl while looking for something else

-- RichardDonkin - 23 Feb 2003

Have these instructions been tested with the Beijing code base? Against IIS 5.1?

-- MarkLevison - 27 Feb 2003

MarkLevison, I'm currently trying to install Twiki 20030201 onto Windows XP Pro with IIS 5.1 ... so far I have found some discrepancies but a skilled person should be able to get it working anyway.

I am discovering that I am not skilled enough for this. But then again, some webserver and perl skills are stated in the requirements to use Twiki, so this is more a blame on me than on Twiki. So far, I have it partially running but I grapple with some configuration issues to make the Perl (v5.6.1) run without complaints.

I chose to not use ActivePerl v5.8 even though I have it, because I was afraid it would get even more complicated (more discrepancies). I've read here on Codev that there are issues with v5.8 as well, so I thought v5.6.1 was the safer road.

-- TorbenGB - 10 May 2003

Common Traps

Mount failing for RCS

Cygwin apparently changed the Mount command. "mount -b C:\ /c" doesn't seem to work try:

"ln -s /cygdrive/c/ c"

It will create a symbiolic link to the C drive, which was automounted by Cygwin under the cygdrive directory and thus mount barfs on it.

-- NormanKing - 03 Sep 2002

The problem here is that you are using the Cygwin shell (bash), which interprets '\' specially, and are specifying c:\ instead of c:/ with the CygWin mount command. Alternatively, you can type c:\\ (because '\' is a special character it must be doubled), but it's easier to use c:/, which works OK with ActivePerl, Apache and almost all Windows programs as well (the main exceptions are Microsoft Office and cmd.exe / command.com).

The following works with the latest version of Cygwin:

$ mkdir /c $ mount -b -s c:/ /c $ mount ... c: on /c type system (binmode) ... 

This is a bit cleaner than using symbolic links, since you can type mount to see the mappings, and works OK for filename completion as well.

I have fixed the cookbook's mount command (in cygwin section, above) to use e:/, since this will work in all cases, and the cookbook said to run the cygwin.bat command.

One Cygwin tip - create a shortcut to C:\cygwin\bin\bash.exe --login and use that instead of the cygwin.bat file - this avoids starting up a virtual DOS machine and is much faster.

-- RichardDonkin - 04 Sep 2002

Further modifications

Index Server

IndexServerSearchForMsIisAddOn provides a way to replace the SearchCgiScript with one that uses MS Index Server.

-- MartinCleaver

Commenting is disabled while not logged in