Installing TWiki 4.x on Solaris 10

Introduction

Solaris is a fine platform for TWiki. With the latest version of Solaris, v10, there is very little you need to do to get TWiki running. It will run equally well on SPARC-based or X86-based hardware.

This article demonstrates getting TWiki running on a Solaris 10 host. It focuses on the things that are specific to Solaris and is not intended as yet another guide on how to install TWiki. Before you read this you should read the official installation documentation, i.e. the TWiki Reference Manual.

The target web server is the Apache 2.0 that comes pre-installed with Solaris 10.

Two optional extras are referenced in this article:

• mod_perl. Comes with the Apache. Speeds up TWiki tremendously.
• mod_ntlm. For seamless authentication against Windows domain, saving your users of having to login to TWiki. This is described in a separate topic.

You should follow the guide in the order it is described. It won't take more than 30 minutes and in the end you will have a fully functional TWiki installation.

You will need to have root access and know how to install packages on Solaris using the pkgadd command.

Solaris preparations

Which zone?

TWiki can live in the global zone or in a non-global zone, it really does not matter. How to use zones in Solaris 10 is open for debate. Most recommandations seems to suggest that only things that really, really have to live in the global zone should live there. TWiki is certainly not one of them so a non-global zone is most appropriate. The advantage is that if security somehow is compromised in TWiki then it will only compromise that zone and not the whole box. More importantly non-global zones are simply more secure by default because they lack some important privileges. Without these privileges it is difficult for an attacker to install trojans or hide his presence.

OS user for TWiki

You need to decide which user should run TWiki. This corresponds to the User directive in Apache. The default in Solaris is a user named webservd. The best is to leave it like that since the webservd user is already restricted to only have the necessary priviliges.

Directory structure

This guide uses the following directory structure for TWiki:

• /apps/twiki-root
  • bin Binaries for TWiki only.
  • perlmodules Perl modules for TWiki.
  • tools
  • apachemodules Apache modules specific to TWiki, e.g mod_ntlm, mod_dav, etc.
  • twiki Symbolic link to one of the TWiki versions below. In this is example it would likely point to twiki-4.2.0.
  • twiki-4.0.1 Install directory for TWiki v4.0.1.
  • twiki-4.0.2 Install directory for TWiki v4.0.2.
  • twiki-4.0.3 Install directory for TWiki v4.0.3.
  • twiki-4.0.4 Install directory for TWiki v4.0.4.
  • twiki-4.1.0 Install directory for TWiki v4.1.0.
  • twiki-4.2.0 Install directory for TWiki v4.2.0.

In short the path to TWiki's pub directory would be /apps/twiki-root/twiki/pub.

The idea behind this structure is:

• Keep TWiki related stuff (special binaries, special perl modules, etc) with TWiki itself. This makes it easier to re-establish TWiki on another host should this be needed.
• Use a symbolic link to point to the TWiki version which is actually used in production. This makes it easier to do fall-back to a previous version.

There are many ways to do this and this layout has advantages as well as probably some disadvantages. The rest of the document will assume this directory layout. Substitute your own if required.

Create your directory structure now.

Unpacking TWiki package and setting file/dir priviliges.

1. Download latest version of TWiki from twiki.org.
2. Unpack into appropriate directory depending on version, e.g. /apps/twiki-root/twiki-4.0.4.
3. Move the symbolic link, e.g.
   cd /apps/twiki-root
rm twiki
ln -s twiki-4.0.4 twiki
4. Create default LocalLib.cfg file:
   cd /apps/twiki-root/twiki/bin; cp LocalLib.cfg.txt LocalLib.cfg
   We will customize this file later. Make sure you follow the order in this guide to the letter. For example if you try to start TWiki's configure script before having customized this file you will run into problems.
5. Most important is to make sure the Apache user, typically webservd, has read/write access to the directory tree:
   chown -R webservd:webservd /apps/twiki-root

Perl preparations

Solaris 10 comes with Perl 5.8.4 installed. (v5.8.8 if your are using CoolStack).

If you are not using CoolStack you will need at least two extra modules:

• CGI::Session module (mandatory)
• Digest::SHA1 module (mandatory)
• HTML::Tagset module (optional but required for the WYSIWIG editor)
• HTML::Parser module (optional but required for the WYSIWIG editor)

If you are using CoolStack then it is already included.

Install the above modules from CPAN. Instructions for building CPAN Perl modules on Solaris 10 are here. It is crucial that these instructions are followed as the method differs slightly from that of Linux.

Suggestion is to install the required Perl modules into /apps/twiki-root/perlmodules. However then you need to let TWiki know where to find the extra Perl modules. We will do this later.

Utilities preparations

GNU grep

Solaris 10 has both Sun's versions of grep (living in /usr/bin) and the GNU greps (living in /usr/sfw/bin) installed. TWiki needs the GNU version, not the Sun version. The GNU grep utilities that TWiki needs are in /usr/sfw/bin/gegrep and /usr/sfw/bin/gfgrep, respectively. The path will be set later in the "Customising TWiki configuration files" section. Note that no installation of software is required if you are on Solaris 10. You already have what you need. Installing GNU grep on your own (e.g. from SunFreeware or compiling on your own) is discouraged.

GNU diff

While Solaris of course has diff it is not the GNU version which TWiki needs. GNU diff is found on the Solaris 10 Companion Disk. Don't use that version as it will not be compatible with the RCS that we will use (see below).

Get diff from SunFreeware. The package is called 'diffutils'. GNU diff will then live in /usr/local/bin.

or, using Blastwave (after you have installed blastwave, installation is as easy as pkg-get install diffutils will be installed as /opt/csw/bin/gdiff )

RCS

rcs has the path to the diff binary hardcoded into it. It is important that the diff used by rcs is the GNU diff. Therefore get rcs from SunFreeware. It will point to the GNU diff you just installed above. rcs will then live in /usr/local/bin.
Note: Has been lots of problems with this historically. Can only recommend to verify by running
strings /usr/local/bin/ci | grep diff
from which you should be able to tell which diff executable rcs is using. It is very important that it points to /usr/local/bin/diff and not /usr/bin/diff. If you browse the SunFreeware ftp directory (ftp://ftp.sunfreeware.com/pub/freeware/intel/10/) you will notice that there are two versions of RCS, one named 'intel' in the name and another named 'x86' in the name. This is a mistake, I believe. The one you want is the one named 'x86' in the name.

or, using Blastwave pkg-get install rcs - the rcs executables will be in /opt/csw/bin (if you install this, the diffutils will be installed automatically, as Blastwave, follows package dependencies)

GNU patch

Solaris 10 has two versions of 'patch': the Sun one (/usr/bin/patch) and the GNU one (/usr/bin/gpatch). Unfortunately TWiki will not recognise that the patch binary is called 'gpatch'. We will fix this by creating a symbolic link but in such a way so that only TWiki will see this (you don't want to break something outside of TWiki that happen to depend on the Sun version of patch). Here is what you do:

ln -s /usr/bin/gpatch /apps/twiki-root/bin/patch

As you will see later we will add the /apps/twiki-root/bin directory to the path that TWiki uses.

Apache Web Server

Solaris comes pre-installed with both Apache 1.3 and Apache 2.0. The advantage of using this rather than the one you compile yourself or get from SunFreeware or Blastwave is that it is part of the core Solaris distribution, i.e. Sun promises to keep it updated, to support it, etc. (if you have a Service Plan of course). Another advantage of the pre-installed version is that mod_perl is included without requiring any other action than configuration.

In this guide Apache 2.0 is chosen rather than Apache 1.3.

To make Apache active do the following as root:

1. Copy the example httpd.conf to use as baseline for a new httpd.conf :
$ cp /etc/apache2/httpd.conf-example /etc/apache2/httpd.conf
There is a really annoying bug in this file: The User directive appears twice. Change the second occurence of "User webservd" to what it should be, i.e. "UserDir public_html". (You will encounter this bug if you ever want to have Apache run as another user than the standard on Solaris, the webservd user.). Note that in recent versions of Solaris 10 this is no longer an issue because the httpd.conf-example file has changed as part of the Solaris Secure by Default initiative which has completely changed the httpd.conf-example file that comes with Solaris.

2. Start Apache Web Server via the SMF (Service Management Facility).
$ svcadm enable apache2

3. Point your web browser to your host and you should see the Apache welcome screen.

You now have a working Apache server running.

Note: If you are running an early version of Solaris 10 such as version 3/05 you will experience that mod_perl.so is missing. This is a bug which has been corrected in later releases of Solaris 10.

Some useful things to know about the pre-installed Apache 2 that comes with Solaris:

• It is managed via the SMF but in the end it still uses the apachectl script to stop, start and restart the server. When you use svcadm enable or svcadm disable you do not however see on the console the messages you will normally see when you use apachectl. SMF writes logs on the outcome of such commands to /var/svc/log/network- http:apache2.log
• You will find web server configuration files in /etc/apache2.
• You will find web server log files in /var/apache2/logs.

Configuring TWiki

Customising Apache configuration for TWiki

TWiki has recommendations for Apache config setup in twiki_httpd_conf.txt which you can find in your TWiki directory. Better yet is to use the ApacheConfigGenerator which will generate TWiki related httpd.conf for you based on inputs. This generator is always kept up-to-date with latest security recommendations. Append this configuration to your httpd.conf file.

Then restart the Apache Web Server (as root):

1. svcadm disable apache2
2. svcadm enable apache2
3. Check /var/svc/log/network- http:apache2.log

Customising TWiki configuration files

Somewhere above you created a file called LocalLib.cfg. Now it is time to customize this file:

1. Set the twikiLibPath:
   $twikiLibPath = "/apps/twiki-root/twiki/lib";
2. Set the path for TWiki related Perl modules:
   @localPerlLibPath = ( '/apps/twiki-root/perlmodules','/apps/twiki-root/perlmodules/???-solaris-64int' );
   (be sure to remove the preceeding # from that line, ??? should be substituted by 'i86pc' if you are on a X86 system and by 'sun4' if you are on a SPARC system)

The rest of the configuration is all done from within TWiki's web interface. Point your browser to

http://yourhost/twiki/bin/configure

Note: It is really important that you have customized your LocalLib.cfg file before you try the above from your browser.

If you have done everything correctly up until now you will see the TWiki Configuration page. In here there a few things to do:

1. Click on the section called "Security setup". Find the SafeEnv parameter. Change its value to
   /usr/local/bin:/apps/twiki-root/bin:/usr/bin
   The first directory is where TWiki will find GNU diff and rcs.
   The second directory is where TWiki will find GNU patch.
   The third directory is where TWiki will find shells.
   
2. Press "Next", choose a configuration password and save your changes.
3. Go back to configuration and correct the following in the 'Store settings' section:
   • The GNU grep command have a preceeding 'g' on Solaris and are found in /usr/sfw/bin, e.g. egrep is /usr/sfw/bin/gegrep.
     • Note: In case you install the original GNU grep, make sure to not use the egrep and fgrep wrappers. Use the binary grep with -E / -F switch instead, such as /path/to/gnu/grep -E %CS{|-i}% %DET{|-l}% -H -- %TOKEN|U% %FILES|F% and /path/to/gnu/grep -F %CS{|-i}% %DET{|-l}% -H -- %TOKEN|U% %FILES|F%, respectively.
   • All of the rcs commands (rlog, rcs, rcsdiff, co, ci) are found in /usr/local/bin.
4. Save your changes.

Happy end

You are now ready to fire up TWiki. Point your browser to http://myhost/twiki/bin/view and take it from there. Now is a good time to go back to the TWiki Reference Manual.

You should consider these two optional extras:

• mod_perl on Solaris. TWiki is not the fastest in itself. mod_perl speeds up your response time tremendously. It should be mandatory with TWiki to use mod_perl.
• NTLM authentication on Solaris. Adding seamless login if your users are on Windows.

References

• Solaris 10 and Apache security. Excellent guide on how to use the Zones features and SMF to harden your Web Server.

• TWiki on CoolThreads architecture. A Sun employee blogging about TWiki on CoolThreads architecture. Sun have released special optimised versions of Apache and Perl that are compiled with specific options that take advantage of the CoolThreads architecture. CoolThreads is a CMT (chip multithreaded) architecture that theoretically is an optimal fit for TWiki.

• Building Perl CPAN modules on Solaris 10. A cookbook on how to build CPAN modules on Solaris 10. (the method is slightly different from that of Linux and therefore needs some comments).

-- Contributors: Lars Haarber - 21 Sep 2006

Discussion

The bug mentioned in the "Apache Web Server" seems to occur only in the OpenSolaris or Nevada/Solaris Express builds. On normal Solaris 10 (01/06 and 06/06) there is only one User directive.

-- JoernKrueger - 28 Sep 2006

Can't see that to be the case. Just checked my Solaris 10 6/06 DVD, i.e. not Nevada or Solaris Express.

-- LarsHaarber - 28 Sep 2006

The proposed apache config file above is not up to date with the latest security advices. You have "Options +Includes" for the pub directory which means that people potentially can upload a file and execute it as a server side include. See more on SecurityAlertSecureFileUploads. You have not protected configure either. See SecurityAlertCmdExecWithConfigure. I am not familiar with Solaris but f it has PHP installed then you also need to deactivate that. You should walk through the apache config again up against the ApacheConfigGenerator which I keep up to date with the latest security advices including Apache configuration.

-- KennethLavrsen - 29 Sep 2006

I just doublechecked my Jumpstart repository (01/06 release), I only have one "User=nobody" directive in each of the files highperformance-std.conf, highperformance.conf and httpd-std.conf. But the comment doesn't harm, it just confused me as I wondered if I changed the file already Thanks Kenneth for the hints regarding security.

-- JoernKrueger - 29 Sep 2006

Joern: Unfortunately it is the file httpd.conf-example (and not any of the files you mention) which is the file recommended by Sun to use to start an Apache2 on Solaris 10. It is this file that has the bug. So if you follow Sun's recommendations on how to get going with the Apache2 on Solaris 10 then you will encounter the bug.

-- LarsHaarber - 30 Sep 2006

Kenneth: Thanks for pointing this out. As I write in the Cookbook the Apache config presented in the Cookbook is based entirely on the config recommendation that comes with TWiki itself (the file twiki_httpd_conf.txt). Mine is from v4.0.4. I see that hotfixes has come out for this file very recently and I will change the above config asap. PS: php is not enabled in a default Apache2 config on Solaris 10. PPS: Really like the ApacheConfigGenerator. Maybe I should just have a link to that one as the Apache config in the Cookbook is not really specific to Solaris anyway.

-- LarsHaarber - 30 Sep 2006

As indicated in previous posting: The proposed httpd.conf is now completely removed and instead replaced with a recommendation to use the ApacheConfigGenerator.

-- LarsHaarber - 01 Oct 2006

Mea culpa, the http.conf-example does indeed contain the bug. I just checked the files in the SUNWapch2r/reloc/etc/apache2 directory.

-- JoernKrueger - 04 Oct 2006

I added the GNU grep info from SearchFailsAfterDakarUpgrade.

-- PeterThoeny - 04 Dec 2006

Peter, to make things clear I've added some comments on the GNU grep section above to discourage people from installing their own GNU grep if on Solaris 10, as there is really no need to ... and if they do anyway they must use the comments that you have added. I think that on previous versions of Solaris Sun did not bundle GNU grep and you would have to install from an alternative source. But this is a Solaris 10 guide.

-- LarsHaarber - 06 Dec 2006

hi, i am new to the twiki. i dont know much about this i just installed that the steps in above. i have done steps upto customising apache configuration file. when i try to load http://localhost/twiki/bin/configure it shows the requested url /twiki/bin/NOT SETNOT SET/oops/TWiki/TWiki Registration does not found on this server.

i dont know why it shows like that what i have to do now please tell me

i am working in solaris 10 when i start apache it starts without error in log file. tell me suggestion and send to my id baskarkpm@yahooPLEASENOSPAM.co.in

-- BaskarNamazhwar - 21 Dec 2006

Please ask support questions in the Support web.

-- PeterThoeny - 24 Dec 2006

I am having issues with Solaris 10 and RCS [RcsErrorWithTWikiOnSolaris]

=/usr/local/bin/rcs -i -t-none -ko %FILENAME% of .../Main/AbcGroup.txt,v failed to create history file =

I somehow cannot get around this. Can someone on this group help me??

-- ShivajiDutta - 18 Jan 2007

I have a problem with the installation of rcs.

In the manual is mentioned:

Note: Has been lots of problems with this historically. Can only recommend to verify by running strings /usr/local/bin/ci | grep diff from which you should be able to tell which diff executable rcs is using. It is very important that it points to /usr/local/bin/diff and not /usr/bin/diff.

But if I run this command, the rcs points to /usr/bin and not to /usr/local/bin. How can i change the Path in the ci-File. Or do i use the wrong version of ftp://ftp.sunfreeware.com/pub/freeware/intel/10/rcs-5.7-sol10-intel-local.gz

-- NilsMielke - 01 Feb 2007

Nils: Steve (maintainer of SunFreeware) has two versions of RCS for X86 on his site. If you browse the ftp directory (ftp://ftp.sunfreeware.com/pub/freeware/intel/10/) you will notice that there are two versions of RCS, one named 'intel' in the name and another named 'x86' in the name. This is a mistake, I believe. The one you want is the one named 'x86' in the name. I've of course alerted the maintainer to this quite some time ago and honestly I would have thought it to be solved by now and therefore I had not mentioned in the Cookbook. Now added to the text above. Download the new version, install and verify with the strings command.

-- LarsHaarber - 03 Feb 2007

Lars:Thanks, this works. Now I have a question about a File named "testenv". This File should show me some Infos about my twiki and it should start when i point the Browser on http://127.0.0.1/twiki/bin/testenv . The problem is, it does not work and i discovered that there is no testenv file in /twiki/bin. But the twiki/bin/configure works. Any ideas...... http://web1.quadrics.com/twiki/bin/testenv

-- NilsMielke - 07 Feb 2007

Please ignore my last Comment because i dont need the testenv to run twiki. But at the Configure page i cant open the Security Setup. The link points to http://localhost/twiki/bin/configure# Any ideas

-- NilsMielke - 07 Feb 2007

My Bad, no Pathvariable set

-- NilsMielke - 07 Feb 2007

Excellent cookbook, successful installation in a couple of hours. I think that perhaps it should be mentioned that the paths in twiki.conf should reflect the suggested directory strucutre suggested, which differs from the twiki.conf defaults (mainly, replacing /home/httpd/twiki with /apps/twiki-root/twiki).

-- EyalTeutsch - 10 Sep 2007

Eyal, feel free to make corrections above as well as commenting.

-- RichardDonkin - 10 Sep 2007

I found that using a symlink pointing twiki -> twiki-4.1.2 caused a bizarre problem where my plugins would only work occasionally. Making it a normal directory solved the problem.

-- IanDonaldson - 18 Oct 2007

Re your symlink problem, you might want to look at Google:Apache+FollowSymLinks

-- RichardDonkin - 24 Mar 2008

This guide could be a little confusing if you are using Solaris Coolstack. The path of the log and conf files differ (/opt/coolstack/apache2/conf). Also, use svcadm enable/disable csk-http instead of svcadm enable/disable apache2, if using SMF. I wonder if the httpd.conf will require a lot of modifications for coolstack!

-- PrateekParekh - 30 Apr 2008

I am still trying to get the utilities setup before I install Twiki. The instructions for installing GNU diff are only one line long: "Get diff from SunFreeware. The package is called 'diffutils'. GNU diff will then live in /usr/local/bin." I tried the "live in" command and it didn't work =/ But seriously, I unzipped it in that directory and then what? Am I done? I can't execute it. Should I leave the default name "diffut~1"? Some more details on what it means to make GNU diff "live somewhere" would be nice because the phrase is nondescript. All the same stuff can be said regarding the GNU RCS instructions.

-- StevePJohnson - 07 Jul 2008

Steve, software packages from SunFreeware site comes in Solaris' default software package format. This means they must be installed using the pkgadd command. The SunFreeware site has a page describing how to install their packages, follow the link on the left of their main page entitled "Downloading/Installation".

-- LarsHaarber - 01 Aug 2008