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
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:
- It worked.
- I tried ActiveState Perl, but it seemed no better and I had problems with spurious re-draws on the desktop of the TWiki server.
- 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
)
--
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