Tags:
solaris1Add my vote for this tag create new tag
, view all tags

Installing TWiki 5.x on Solaris 11

Introduction

This guide is for Solaris 11 and derivatives (i.e. distros based off OpenSolaris).

This is basically a re-write of SolarisInstallCookbook which is for Solaris 10. Most of what you read below I owe to SolarisInstallCookbook. There are some significant changes between Solaris 10 and Solaris 11 so a separate install guide for Solaris 11 can be justified. Secondly the guide has been upgraded to apply to TWiki v5.1.1.

The author's experience is from an X86 platform but the guide should apply equally well to SPARC based systems. The descriptions below have been tested on

  • Solaris 11 11/11 from Oracle (Text Install version)
  • TWiki 5.1.1 (Community version)
This guide demonstrates getting TWiki running on a Solaris 11 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.2 that comes with the Solaris 11 eco-system. The emphasis in this guide is on doing things the Oracle Solaris way, i.e. using the build-in software components and not using software from outside the Oracle Solaris eco-system except where no other possibility exist.

You will need to have root access and have the following knowledge:

  • Know how to install packages on Solaris 11 using the IPS pkg command.
  • Know the Solaris SMF basics. In Solaris 11 everything is using SMF so you really need to know a little bit about SMF..

Solaris preparations

Zone for TWiki

In Solaris it is to dead-simple (and cost free) to create logical hosts, called zones. Zones provides a lot of benefits in terms security, delegation of responsibilty, migration to other hosts in case of failure etc. Unlike most other virtualization technologies they really have new-zero overhead. Zones have become so ingrained in the minds of every Solaris admin that nowadays nobody will problably even dream of running anything from the global zone.

Unless you are only just testing your TWiki installation should start by creating a zone dedicated for TWiki. It is outside the scope of this guide to explain how to do that.

TIP NOTE: Here's a caveat for Solaris 11: When you install new zones and no manifest is explicitly provided to the zoneadm install command the default manifest will use pkg:/group/system/solaris-small-server for the list of packages to install into the zone. This will give you a very stripped down Solaris 11 without a lot packages that will increase the attack surface of the server or blow your disk space. I personally like this approach as it makes zones very lightweight. Your literally get a container dedicated to TWiki that you can move around as you see fit. However what it means for TWiki install phase is that you will have to manually add some needed packages into the zone after the zone has been created even if you find that said packages are indeed installed on the global zone. These are packages like GNU grep and GNU diff. It is detailed below in the section called 'Utilities preparations' exactly how to install such packages. In reality what will happen when you execute those pkg install commands from within the non-global zone is that the package will be installed via an IPS proxy server that always runs in the global zone. Thus the package actually comes from global zone in case no Internet connection is available. Neat !

This guide assumes that you are installing into a non-global zone that was created with the "small server" manifest as this seems to be what Solaris admins generally tend to do. If this is not the case you may find that you do not have to install some of the packages mentioned belowed. Check if the package is there before you start installing it.

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 11 is a user named webservd which is a locked user account. The best is to leave it like that since the webservd user is already restricted to only have the necessary privileges. Alternatively consider running TWiki under a Solaris role account, e.g. create a "twiki" role.

Directory structure

This guide uses the following directory structure for TWiki:

  • /apps/twiki-root
    • bin Binaries for TWiki only. (Haven't really found a need for it on Solaris 11 as opposed to Solaris 10 ... but never mind)
    • perlmodules Perl modules for TWiki.
    • tools. We will use this for anything which doesn't really depend on any specific version of TWiki. For example this is a good place to store the mod_perl startup script (in case we use mod_perl).
    • apachemodules Apache modules specific to TWiki, e.g mod_ntlm, mod_dav, mod_auth_gss. etc. You may not need this.
    • twiki Symbolic link to one of the TWiki versions below. In this is example it would likely point to twiki-5.1.1.
    • twiki-5.1.0 Install directory for TWiki v5.1.0.
    • twiki-5.1.1 Install directory for TWiki v5.1.1.
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. In other words: have a self-contained install of TWiki.
  • 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-5.1.1. Note that if you happen to download the tarball (*.tgz) then remember - as always - to use GNU tar ( gtar) to untar as per the comments above in the "GNU tar" section.
  3. Move the symbolic link, e.g.
    cd /apps/twiki-root
    rm twiki
    ln -s twiki-5.1.1 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 11 comes with Perl 5.12 installed but because we are using the stripped down "small server" zone version of Solaris 11 there isn't that many Perl modules installed. The exact modules you need depends on your version of TWiki and on the plugins you wish to have installed. For a start you should take a look in the System Requirement document for TWiki (the link is for v5.1).

Install the above modules from CPAN. Instructions for building CPAN Perl modules on Solaris 10/11 are here. It is crucial that these instructions are followed as the method differs slightly from that of Linux. (read the section called "Solaris 11 experience").

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

Many - if not all - of the utilities that you will make available on your system in this section of the guide are pretty much mandatory (IMHO) on any system being it on a TWiki host or some other host. It will generally make your life a lot easier if you make it a habbit always to have tools such as GNU tar, GNU make and GNU grep on any of your Solaris servers,TWiki or no TWiki.

GNU grep

GNU grep does not get copied into a non-global zone when you install zones with the "small server" manifest. TWiki needs the GNU version of grep, not the Sun version.

This is not a problem. Simply do:

pkg install text/gnu-grep

The GNU grep tools will end up on /usr/bin path (in reality they live in /usr/gnu/bin) but be prefixed with a 'g' to distinguish them from the Sun equivalents. If you take them from /usr/gnu/bin they will not have the prefix.

Installing GNU grep on your own (e.g. from SunFreeware or compiling on your own) is discouraged.

GNU diff

GNU diff does not get copied into a non-global zone when you install zones with the "small server" manifest. TWiki needs GNU diff, not the Solaris equivalent. Fear not. Simply do:

pkg install text/gnu-diffutils

The GNU diff tools will end up on /usr/bin path (in reality they live in /usr/gnu/bin) but be prefixed with a 'g' to distinguish them from the Sun equivalents. If you take them from /usr/gnu/bin they will not have the prefix.

GNU patch

GNU patch does not get copied into a non-global zone when you install zones with the "small server" manifest. TWiki needs GNU patch, not the Solaris equivalent. Fear not. Simply do:

pkg install text/gnu-patch

The GNU patch tool will end up on /usr/bin path (in reality it lives in /usr/gnu/bin) but be prefixed with a 'g' to distinguish it from the Sun equivalent. If you take it from /usr/gnu/bin it will not have the prefix.

GNU tar

GNU tar does not get copied into a non-global zone when you install zones with the "small server" manifest. Only the Sun 'tar' exist by default. There are subtle differences between them and sometimes you can see strange stuff happening if you try to untar a file using Sun tar that has been tar'ed using GNU tar. For this reason I recommend always to have GNU tar on your system. Strictly speaking I do not think it makes a difference to TWiki but it is good to have for example when you unpack the TWiki software bundle. Fear not. Simply do:

pkg install archiver/gnu-tar

The GNU tar tool will end up on /usr/bin path (in reality it lives in /usr/gnu/bin) but be prefixed with a 'g' to distinguish it from the Sun equivalent. If you take it from /usr/gnu/bin it will not have the prefix.

GNU rcs

This turned out to require a little more work than the other requirements. As of April 2012 you cannot get GNU rcs from the official Oracle Solaris IPS repository. Admittedly GNU rcs is is somewhat arcane these days and this might explain why Oracle hasn't bothered to make it available in the official IPS repository. You can of course go hunt for it in other IPS repositories but remember that it is intrinsincly linked with GNU diff and if you don't get that link right you will never get TWiki working.

So I decided on building rcs myself. Fear not. This is really only a 10 min task.

First you have to make sure you have a C compiler:

pkg install developer/build/gnu-make
pkg install system/header
pkg install gcc-45

Now download GNU rcs sources from an appropriate GNU mirror. The file I downloaded was rcs-5.8.tar.gz. Unpack to a temporary location of your choice but remember to use GNU tar :

gzip -d rcs-5.8.tar.gz
gtar xf rcs-5.8.tar

Now change into the rcs-5.8 directory that was created by the unpack above. Then do:

./configure CC=gcc MAKE=gmake DIFF=/usr/gnu/bin/diff DIFF3=/usr/gnu/bin/diff 
gmake MAKE=gmake
gmake MAKE=gmake install

rcs has the path to the diff binary hardcoded into it. This is why it is important to tell rcs where to find GNU diff tools as we do above.

After you have done the above then rcs will live in /usr/local. We could have set the PREFIX variable on the configure command line if we wanted this in a different place.

Apache Web Server

Apache 2 Web Server does not get copied into a non-global zone when you install zones with the "small server" manifest. Fear not. Simply do:

pkg install web/server/apache-22
pkg install web/server/apache-22/module/apache-perl

There are several other Apache related modules on the official Oracle Solaris IPS repository. Get the ones you think you need. Only web/server/apache-22 is strictly required but I like to use mod_perl and I therefore also get the web/server/apache-22/module/apache-perl package.

To make Apache active do the following as root:

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

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

You now have a working Apache server running.

Some useful things to know about the Apache 2.2 from the official Oracle Solaris IPS repository:

  • 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\:apache22.log
  • You will find web server configuration files in /etc/apache2/2.2.
  • You will find web server log files in /var/apache2/2.2/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 apache22
  2. svcadm enable apache22
  3. Check /var/svc/log/network-http\:apache22.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','/apps/twiki-root/perlmodules/lib/perl5','/apps/twiki-root/perlmodules/lib/perl5/xxx-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

If following this guide you used /apps/twiki-root/twiki as the twiki root directory on the ApacheConfigGenerator (as suggested by the example) then the URL to the configuration script would be:

http://yourhost/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. The TWiki configure script tries to guess a lot of things for you but unfortunately there's a chicken-and-egg situation when it comes to Solaris: On the first run of the configure script it will only look for tools in "/bin" and hence it will not pick up the tools you want it to. This means that paths to tools must be configured manually in the configure tool.

In order to get access to actually change the values you want on the Configure screen you may have push this button:

Access to EXPERT level variables

Here are the variables on the Configure screen that you should change:

Variable section Variable name Value and comments
Security setup SafeEnv /usr/gnu/bin:/usr/local/bin:/usr/bin
The first directory is where TWiki will find the GNU tools you have installed above using pkg command.
The second directory is where TWiki will find GNU rcs.
The third directory is where TWiki will find shells.

Store settings {RCS}{initBinaryCmd}
{RCS}{initTextCmd}
{RCS}{tmpBinaryCmd}
{RCS}{ciCmd}
{RCS}{ciDateCmd}
{RCS}{coCmd}
{RCS}{histCmd}
{RCS}{infoCmd}
{RCS}{rlogDateCmd}
{RCS}{diffCmd}
{RCS}{lockCmd}
{RCS}{unlockCmd}
{RCS}{breaklockCmd}
{RCS}{delRevCmd}
Make sure the path for all of these are /usr/local/bin because that's where you have installed GNU rcs.
Store settings {RCS}{EgrepCmd}
{RCS}{FgrepCmd}
Make sure the path to these tools are /usr/gnu/bin.

You may have to change other stuff as well on the Configure screen but I've focused only on the things that are different for Solaris so the rest I consider outside of scope for this guide.

Save you Configure settings and off you go !

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. smile
  • NTLM authentication on Solaris. Adding seamless/promptless login if your users are on Windows. (based on NTLM v1 which is no longer supported in MS Windows as of Win7)
  • SPNEGO authentication on Solaris. Adding seamless/promptless login for browsers that support SPNEGO (most browsers do !). Ths is the "standard" way for a browser to authenticate its user against a given website.

References



-- Contributors: BrianMartinUK - 28 April 2012

Discussion

Thank you very much Brian for sharing this with the TWiki community!

-- PeterThoeny - 2012-04-30

I added links to this doc in relevant places.

-- PeterThoeny - 2012-05-01

I corrected one link to the Perl configuration and added a clarification to the URL you should use to access the configure script.

-- Ãlvar Garcia - 2013-04-25

Edit | Attach | Watch | Print version | History: r9 < r8 < r7 < r6 < r5 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r9 - 2013-04-25 - AlvarGarcia
 
  • 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.