Tags:
installation1Add my vote for this tag windows1Add my vote for this tag create new tag
, view all tags
ALERT! NOTE: This is a SupplementalDocument topic which is not included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

Installing TWiki on Windows, using IIS and Cygwin

Purpose & Scope

This is a summary of my experience in installing TWiki 4 using the IIS HTTP server and Cygwin. Familiarity with unix command shell (bash), Perl, Cygwin and the Microsoft Management Console for IIS (IIS Manager) are assumed.

Motivation

“Why use IIS and Windows when TWiki installs and runs well on Linux?”

My use of TWiki is for an Intranet where the end users are all using Windows machines and are already authenticated against a single Windows DOMAIN. I like the structured wiki approach, simple editing and easy document attachment of TWiki, but I also like (for this user base) the IIS user authentication model). With the installation described below, I can devolve responsibility for user authentication to IIS and, within TWiki, rely on each user's permissions granted by Windows.

Pre-requisites

  • IIS (version 6.0 was used here, version 5 was similar to use) - part of the Microsoft distribution with Windows Server.
  • Cygwin (version 1.5.22-1 was used here)
  • Further Perl libraries (not in the cygwin distribution) - see below
  • The TWiki distribution - the experince below was on version 4򈆩 of TWiki.

Summary of Steps

  • Install IIS
  • Unpack the TWiki tgz file (I used WinZip) to some directory (hereinafter called c:\TWiki )
  • Install Cygwin - install the default packages with the addition of perl and rcs. The text below assumes that Cygwin was installed in c:\cygwin
  • In IIS manager, select the default web site and create a new virtual directory. Select as the content, the directory to which you unpacked the TWiki distribution ( c:\TWiki ). Give read an execute permission to that virtual directory. Finish the ‘new virtual directory’ wizard.
  • In version 6 of IIS you need to go to the Web Service Extensions, in IIS manager, for the server and allow Unknown CGI Extensions (or explicitly define and allow CGI extensions for Cygwin Perl - I haven't tried that, I'm just working on an Intranet).
  • In IIS manager, under the properties of the website, set the site to allow integrated (and possibly basic) authentication and not to enable anonymous access.
  • Using the cygwin shell, rename the each file in the bin directory to have .pl at the end of the name. cd to the bin directory and do:
shopt -s extglob
for file in +([!.])
do
mv $file $file.pl ;
done

  • In IIS manager, select the properties of the bin directory. Under application settings, press Create and then Configuration. Add a extension .pl with the Executable:
c:\cygwin\bin\sh.exe CGI_Script "%s"

select "All verbs" and "Script engine".

  • Use an editor (such as TextPad) that will create files with Unix-style (no spurious ^M characters) end of lines and create, in c:\TWiki, a file called CGI_Script comprising:
#!/bin/sh
cd bin
/bin/perl -wT $1

Note invoking the Cygwin perl from a Cygwin shell feels like a bit of an overhead, but:

    • it sorts out a current directory issue

  • In IIS Manager make the data directory writeable
  • In IIS Manager make the pub and lib directories readable.
  • Next ensure that by the perl scripts are executable by all users, in a Unix command shell, cd to the bin directory and do:
chmod a+rx ../CGI_script *.pl
  • (This step requires some understanding of Perl libraries.) Obtain the Perl libraries for CGI and URI from CPAN and install them in an appropriate place. (I created a CPAN directory in c:\TWiki.)
  • In directory c:\TWiki\bin copy file LocalLib.cfg.txt to LocalLib.cfg. and edit that file thus:
$twikiLibPath = "/cygdrive/c/TWiki/lib";
@localPerlLibPath = ( '/cygdrive/c/TWiki/CPAN' );

I used TextPad for such edits.

  • (I didn't use the configure.pl script. It didn;t work for me easily and having edited the LocalSite.cfg file successfully for version 3 of TWiki, I followed the same approach.) In the lib directory, copy LocalSite.cfg.txt to LocalSite.cfg and edit the following lines:
$TWiki::cfg{DefaultUrlHost} = 
$TWiki::cfg{ScriptUrlPath} = 
$TWiki::cfg{PubUrlPath} = 
$TWiki::cfg{PubDir} = 
$TWiki::cfg{TemplateDir} = 
$TWiki::cfg{DataDir} = 

Host is the hostname; UrlPaths start /TWiki and directories start /cygdrive/c/TWiki

  • Before the
1;

line at the end of the LocalSite.cfg file, add these lines:

$cfg{ScriptSuffix} = '.pl';
$cfg{Register}{AllowLoginName} = $TRUE;
$cfg{MailProgram} = '';
$cfg{SMTP}{MAILHOST} = '';
$cfg{Register}{NeedVerification} = $FALSE;

Note that NeedVerification is false because all users are verified by IIS.

  • Because user names are passed, by IIS< to the Perl scripts with a '\' character (and, possibly, a '.' character) change both of those to '_' characters. In directory lib edit the file TWiki.pm and, after the line:
  • Note: as of Twiki-5.01 (and possibly earlier versions), this line does not exist, and $remoteUser is deprecated. Forcing new users to the registration page will fix some associated issues, such as Twiki trying to create a subweb based on your authentication domain name when the user tries to create their home page.
$remoteUser ||= $query->remote_user() || $TWiki::cfg{DefaultUserLogin};

add the lines:

#Change and '\' or '.' in the name into a '_'
 $remoteUser =~ tr'.\\'_';

  • Because each user should have permission to create, read and write any file in the data directory do the following:
    • Using the Windows Explorer, set the permissions on the data directory appropriately and (as a “belt and braces”) also
    • In a cygwin command shell cd to the data directory and do:
find . -type f -exec chmod a+rw {} \;
find . -type d -exec chmod a+rwx {} \;

Testing It

Try using your web browser to look at the virtual directory you defined in IIS and see what happens. Try looking at the URL for VirtualDirectory/bin/view.pl

If you need to do any debugging, once inside a Perl script, try and think in Unix terms. If you get no output from a URL, try altering the content of CGI_Script to:

#!/bin/sh
cd bin
/bin/perl -wT $1  | tee -a /tmp/CGI_out 2> /tmp/CGI_err

Point your web browser at the URL again and then see what is written to those two files (in c:\cygwin\tmp).

Further Configuration

If your TWiki installation works and you can view pages, edit the registration page, because passwords are handled by your Windows DOMAIN, not by the TWiki installation.

Note that you can use the Cygwin cygrunsrc command to install a Windows service to execute cron scripts. See the files:

C:\cygwin\usr\share\doc\Cygwin\cron.README 
C:\cygwin\usr\share\doc\Cygwin\cygrunsrv.README 

in your cygwin installation.

With a little bit of site specific hacking, I also got the mailnotify script in the tools directory to work.

In IIS manager, on the properties of the Web Site, set the home directory to be "A redirection to a URL" to /TWiki/bin/view.pl and check "A directory below URL entered".

Try adding a new web and editing some pages. If you have permissions problems, on the server use both Windows Explorer and the cygwin shell commands to ensure that files/directories have the correct permissions and that they are correctly inherited.

Other Choices

  • The reasons for using IIS and Cygwin are given above. I used the Perl within Cygwin because:
    1. It worked.
    2. I tried ActiveState Perl, but it seemed no better and I had problems with spurious re-draws on the desktop of the TWiki server.
    3. It seemed natural to me to work within a purely Unix-like environment for the CGI scripts.

Related Pages

-- Contributor: PhilipSweetenham - 06 Mar 2008



Comments & Questions about this Supplemental Document Topic

Thank you Philip for sharing this how-to with the TWikiCommunity!

-- PeterThoeny - 07 Mar 2008

I just want to combat an often seen misconception in TWiki discussions:

You seem to say that you have chosen Windows as the platform for your server because you are under the impression that by doing so user authentication with the Windows world becomes possible or perhaps just simpler than if your server was Linux/Solaris/etc. (well, I admit it does become marginally simpler with your server being IIS, but not more)

Not true. There really isn't any benefit gained from running under Windows unless you are an all-Windows shop, imho. User authentication against Windows world is dead simple with NTLM module in Apache and lots of other options exist as well. On top of that the TWiki install itself is a lot more simple on a platform with native Perl support, i.e. Linux/Solaris/etc.

So the reason for running TWiki on Windows IIS should be along the lines "because that is the only web server we use in my company" or similar, but not user authentication against Windows domains.

Just my two pennies worth. (I'm possibly biased smile )

-- LarsBruunxHansen - 09 Mar 2008

Lars, you are entirely correct. I over-simplified. In my organization, the support staff were very unwilling to consider either maintaining any OS other than a version of windows or any webserver other than IIS.

As an end user, my main concern was to move away from separate passwords - hence the emphasis above.

-- PhilipSweetenham - 14 Mar 2008

Lars, I think about installing TWiki with IIS, because we need NTLMv2 not only NTLM. An alternative could be kerberos, but I cannot find a Win32-binary for mod_auth_kerb. I would be very appreciated, if there is a simple way to do so with Apache2 under Win32.

-- LarsWith - 11 Apr 2008

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.
Edit | Attach | Watch | Print version | History: r7 < r6 < r5 < r4 < r3 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r7 - 2011-04-01 - PeterHoff
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.