TWiki 4 Installation on RedHat, Fedora and Centos
This topic is a draft topic for a contribution on TWiki:Codev.TWikiOnRedHat. I use this to practice before I publish updates. If you have questions or improvement please visit TWiki:Codev.TWikiOnRedHat and use the if you need help. Do not email me directly.
This guide explains how to install a Linux with TWiki4 on RedHat type distributions such as RedHat Enterprice Linux 4 (RHEL4), Fedora Core 4 and 5 (FC4 and FC5) and Centos 4. For those unfamiliar with Centos, Centos is a clone of RedHat. It is built from the original RedHat source RPMs and anything that runs on RHEL will run on Centos. The only difference is that Centos does not charge any fees for updates, it has no support other than community support and all RedHat logos and branding has been replaced by Centos' own. Any RPMs made for RHEL4 can be used on Centos 4.
Installation of RHEL, Fedora or Centos.
- When you install the Linux you will be asked which type of installation you want. Personally I always choose "Everything", but you will get the required software installed by choosing both "Software Development" and "WebServer". (Note: FC5 does not have the "Everything" option).
- You are installing a web server so your Linux box must be setup with fixed IP address.
- The Linux box will need to send emails so it must have access DNS to be able to look up email addresses.
- The Firewall should be activated but with port 80 open to the world. This is suggested during initial installation.
- SELinux can be enabled but it is not easy to setup so TWiki is working. For now it is probably best to deactivate it during initial installation.
- It is always recommended to have a router between the public Internet and the Webserver and then forward only port 80 to the webserver. The webserver is then setup with a local fixed IP address. If your webserver is on an Intranet serving only internal clients you are for sure already on a router protected from the wild public Internet. Then all you need is a fixed IP address and a local domain name.
In the following we will be assuming that you are the administrator of the RH/Fedora/Centos Linux box and have root access. Most of the steps requires that you run the commands as root.
Activate the Apache server
Many of these procedure can be done via a GUI, but it is so much easier to do from a terminal when you follow a guide like this
As root you do these steps
- Activate the Apache server:
service httpd start
- Enable the Apache server also after reboots:
chkconfig --levels 345 httpd on
- Check that the server is running by opening a browser and look up
What you should see is a default test page.
- Check that the server can be accessed from another machine by looking up the IP address (or domain name if available) from another client machine. Again what you should see is a default test page.
Install the CPAN modules required by TWiki
You should install the following CPAN modules which are required by TWiki and the most popular plugins. This list is a little longer than actually required by the basic TWiki installation but sooner or later you will want to install some of the more popular plugins and then it is nice to already have the necessary CPAN modules installed.
CPAN modules are Perl libraries that are well tested and made standard. Your RHEL/Fedora/Centos already have many installed but the onces in the list below are not installed per default.
There are at least 3 ways to install CPAN modules
- Download the source package from CPAN and build it manually.
- Easy but not always possible: Install the using the CPAN modules which builds and installs it all for you. First time you run it you will be asked a lot of questions that set it up. It can be a little tricky to get to work if you are behind a firewall that requires authentication.
- Download and install RPM modules. Since you are running a RedHat type Linux it make most sense to download and install RPMs. That also makes it easy to later upgrade the modules to newer versions. So this is the method the author of this document recommends.
These are the CPAN modules that are recommended to install
- CGI::Session - Needed for TWiki's session feature which is really a must have
- Error - Needed if you later want to develop plugins. It is also distributed with TWiki but the author has experienced lots of trouble with the build script that builds plugins which sometimes cannot find this library. By adding it to the site Perl library you avoid this kind of trouble.
- FreezeThaw - an indirectly needed module used by other modules.
- GD - Used by the pluging that can produce graphics such as . It requires that lib gd is installed. If your choice of installation does not include you simply need to install the rpms gd and gd-devel. They are both on the CDs or DVD.
- HTML::Tree - Needed by some popular plugins
- Time-modules (Time::CTime, Time::DaysInMonth, Time::JulianDay, Time::ParseDate, Time::Timezone) also needed by some popular plugins.
If your already installed RHEL/Fedora/Centos was not installed as "Software Development" and "WebServer" you may need to install additional modules. lists the modules requires for a basic installation and shows how to test which ones you have. A few examples of this.
- To check for perl module Filehandle:
perl -e 'use FileHandle; print $FileHandle::VERSION."\n"'
- To check perl module Time::Local:
perl -e 'use Time::Local; print $Time::Local::VERSION."\n"'
Install CPAN modules manually
(difficuly - only if you have to).
First we download them
- CGI::Session -
- Error -
- FreezeThaw -
- GD -
- HTML::Tree -
- Time-modules -
Then we install them. This is done more or less the same way with all of them. At least one module depends on FreezeThaw so install that first.
- Untar the package in some temporary directory with
tar -zxvf filename.tar.gz
- Run these commands (look in the readme file - maybe there are extra steps
perl Makefile.PL
make
make test
make install
- You can delete the entire directory with the sources afterwards if you desire.
Install CPAN modules with CPAN.pm module
(easy but not always possible)
First time you run the CPAN module it will ask for a lot of things of which you probably have no idea. The good thing is that all you need to do is answer all the default values by hitting enter except when it asks you for the part of the world, and the country. Finally it lists a number of CPAN mirrors in your country with a number in front. Just add 3-5 of them. If one is with your own ISP add that as the first on the list.
Make sure you install the FreezeThaw module first as other modules may depend on it.
The generic command to install a module called Chocolate::Belgian is
perl -MCPAN -e 'install Chocolate::Belgian'
So to install the recommended modules you run
perl -MCPAN -e 'install FreezeThaw'
perl -MCPAN -e 'install CGI::Session'
perl -MCPAN -e 'install Error'
perl -MCPAN -e 'install GD'
perl -MCPAN -e 'install HTML::Tree'
perl -MCPAN -e 'install Time-modules'
Install CPAN modules from RPM
(easy and recommended by the author of this topic)
The missing CPAN modules are not on the CDs or DVD and I have not found them on RedHat's, Fedora's or Centos' sites either. But Dag Wieers has them all in his collection and they are kept pretty up to date. Simply download the RPMs and put them all in the same directory.
The URLs contains a couple of versions and packages for both RedHat and Fedora. For RHEL and Centos simply use the newest 'el4' package. For Fedora use the latest Fedora package. For Fedora 5 the 'el4' is probably the best if there is no fc4, or fc5 version. Since these are Perl modules it is not as critical as with binary packages.
- CGI::Session -
- Error -
- FreezeThaw -
- GD -
- HTML::Tree -
- Time-modules -
From the directory in which you have the 6 rpm files simply run
rpm -ivh *
This installs all of them at once.
If you later want to update one of them to a newer version you use rpm -Uvh filename.rpm
Create the TWiki directory
You will see many examples on TWiki.org where TWiki is installed in the Apache DocumentRoot (which in RedHat/Fedora/Centos is /var/www/html). This is not a good idea because this means that all the directories are per default accessible from the web and we will have to disable the access. You will also see examples where the TWiki installation is placed below some users name. This means that the unpriviledged Apache user can read any file from this users home directory and that is not a good idea either. The best is to place the TWiki installation in a place where Apache has access but not in the DocumentRoot directory. A good choice for RedHat/Fedora/Centos is
/var/www/twiki.
mkdir /var/www/twiki
Download TWiki and any additional hotfixes and unpack them
VERSION is the current version number like e.g. 4.0.4 for TWiki and 4.0.4-2 for hotfix 2
- Download TWiki from TWiki:Codev.DownloadTWiki. Choose the tgz file.
- Download the latest hotfix package (linked from TWiki:Codev.DownloadTWiki)
- Maked sure both
TWiki-VERSION.tgz and hotfix-VERSION.tgz to /var/www/twiki
- Unpack first TWiki.
tar -zxvf TWiki-VERSION.tgz
- Now unpack on top of the already unpacked TWiki tree so files get replaced
tar -zxvf hotfix-VERSION.tgz
- You can now delete the two tgz files or move them somewhere else.
Create an Apache config file
The key element in any type of security is to start with having an overview. Spreading small .htaccess files all over the place is not the ideal way to have an overview. The best thing is to keep everything related to TWiki in one easy to overview Apache config file which is included from the main Apache config file.
RedHat/Fedora/Centos keeps the Apache config file in /etc/httpd/conf/httpd.conf. Inside httpd.conf you will find a statement Include conf.d/*.conf. This means that all files that ends with .conf in the /etc/httpd/conf.d directory are included. We take advantage of this and create a file /etc/httpd/conf.d/twiki.conf which contains all the settings for TWiki.
If you have multiple virtual hosts defined in httpd.conf then you should know that certain Apache features such as rewrite will not work unless they are defined within the scope of the virtual host. This is easy to overcome.
Instead of the filename twiki.conf we give it a different suffix so it does not get included in the global apache config context. We can call the file twiki.config instead. And then include this file from within the virtual host definition in httpd.conf
Example
ServerName mydomain.dk
ServerAlias *.mydomain.dk
DocumentRoot /var/www/mydomain/html
Include conf.d/twiki.config
Now let us make that twiki.conf file. We assume you know how to create a new file from a text editor. To make the content of twiki.conf we use the .
- The default twiki root directory /var/www/twiki is fine
- Enter the IP address range or hostnames that will have access to configure. It is essential that the configure script is protected either by IP address or by username/password. To get started without too much problems protecting by IP address is a good idea. If you work locally on the machine simply put 127.0.0.1 in this field. If you setup the machine from a remote client use the IP address of this remote client instead.
- Enter the list of user names that are allowed to view configure. For this to work you need a .htpasswd file with a username and a password. Later when TWiki is fully installed TWiki and provided that you have chosen to authenticate with Apache .htpasswd type authentication this .htpasswd file will be created by TWiki. But at this point we have a "chicken and the egg" situation where we need. If you provided an IP address in the previous step then you overcome this problem. Simply add the usenname that you will use later when you register yourself on your TWiki. You can always change this later. Put a name so you have the right syntax.
- Enable mod_perl? You are adviced to startup without mod_perl. Mod_perl means that Apache preloads the TWiki code and keep it compiled in RAM. This can make TWiki twice as fast as without. But it also requires that the perl code is written without any uninitialized global variables. Not all plugins fulfills this requirement. Start without. Then you can try enabling it later by revisiting the .
- Choose your Login Manager. Here you have to make an important choice. Do not choose None!
- TemplateLogin - Redirect to the login template, which asks for a username and password in a form. This is easy to get to work. But if you later want to authenticate using an LDAP server or similar you cannot use this method. The author of this document does not like the current implementation of TemplateLogin because especially Internet Explorer think that each URL within TWiki is new and cannot remember username and password. The result is that you are prompted all the time without username and password autofilled. TemplateLogin is by far the most pretty way to login.
- ApacheLogin - Apache is configured to ask for authorization information. This is a very plain authentication where Apache asks the browser to authenticate. The browser presents the user with the standard small pop-up window with username and password fields. With this methpd even Internet Explorer has no problem with remembering username and password.
- Choose which PHP version you have installed. Unless you have a very old RedHat the answer is always "PHP4/5 Installed". Even though TWiki has nothing to do with PHP - we need to make sure that all execution of PHP scripts are disabled in the directory in which TWiki keeps file attachments. Otherwise you have a major security issue.
- Finally you choose two counter measures against spam. If your TWiki will be on the public Internet turn these on. If it is only on an Intranet you do not want to activate this protection as it put some limits to the use of TWiki with respect to which types of attachments you can upload.
- Click the "Update config" button. You can now copy paste an entire twiki.conf from the text area and into your twiki.conf file. Save the file.
- Change the access right and ownership of the twiki config file.
chmod 644 twiki.conf
chown root:root twiki.conf
Setting the Library path in bin/LocalLib.cfg
The next step it to tell the TWiki CGI scripts where to find the rest of TWiki.
- Go to the /var/www/twiki/bin directory
- Copy the file LocalLib.cfg.txt to LocalLib.cfg.
cp LocalLib.cfg.txt LocalLib.cfg
- Open the file with a text editor.
- Change the line
$twikiLibPath = "/absolute/path/to/your/lib"; to $twikiLibPath = "/var/www/twiki/lib";
- Save the file.
Change the ownership of twiki to Apache
Now we change the ownership of the entire twiki directory tree to Apache. We change both owner and group. On RHEL/Fedora/Centos Apache runs with username apache and group name apache.
chown -R apache:apache /var/www/twiki
Set the file and directory access rights
If you followed the advice so far and installed the .tgz file the access rights should be correct. However if you are in doubt or you accidently have altered the access rights then go to . Here you will find a script you can run which sets all the access rights back to the default recommended.
Note that there is a difference between access rights for files and for directories. For Apache to be able to access files in a subdirectory all the parent directories must be "redable and executable" to the world assuming the owner is normally root. Ie. the access rights of /var and /var/www must be 755. When people chose to place the twiki directory a different place - typically under a user - failing to have world executable but enabled on the parent directories is the main reason why nothing works.
Restart the Apache server
It is now time to restart the Apache server so we read in the TWiki config file.
Run configure first time
From a browser look up the following URL.
If you are using another client machine replace localhost with the IP address or domain name of the webserver.
You should not see the TWiki configure script. It will tell you that there are a massive amount of errors. Ignore them all for now. Click on the "General Path Setting" bar.
- Check that the default URL host is correct with the correct domain name that people will use when they access the server.
- Ignore all other settings and errors for now and go to the bottom and hit "Next".
- Enter a configure password. This password has nothing to do with the admin user password you later use in TWiki and it has nothing to do with any username/password you may have setup to protect the access to configure. This password is just an extra protection against saving settings in configure. But it is not secure enough to leave configure accessible to the public which is why we protected it earlier by IP address or username.
- You now get back to configure. All the errors should now be gone and we are ready to setup the rest of TWiki.
Configure - Setting up security
Hit the Security Setup bar. We now walk through the steps in this important section and give recommendations. The ones in bold are the ones where you may have to change something.
- {UseClientSessions} - YES! Life is so much easier for the users when Client Sessions are enabled.
- {Sessions}{Dir} - Leave the defaut /tmp
- {Sessions}{ExpireAfter} - Set this to a negative number. A good value is -21600. TWiki becomes a crawling snail if this number is positive because it means that it cleans our sessions each time someone views a page. Instead we will purge the session files with a cron job. We get back to that later
- {Sessions}{IDsInURLs} - Leave this off
- {Sessions}{UseIPMatching} - Leave this on
- {Sessions}{MapIP2SID} - Leave this off
- {LoginManager} - We discussed this earlier when we created twiki.conf. Choose the LoginManager that matches your preference.
- {DefaultUserLogin} - Leave this as "guest"
- {DefaultUserWikiName} - Leave this as "TWikiGuest"
- {AdminUserWikiName} - Leave this as "TWikiAdminGroup"
- {SuperAdminGroup} - Leave this as "TWikiAdminGroup"
- {UsersTopicName} - Leave this as "TWikiUsers"
- {MapUserToWikiName} - Leave this on! Ignore the help text. Keep this on even if you do not enable users to have login names different from their WikiName. If you turn this off a bug in TWiki prevents users from resetting their password. And some plugins do not work well either.
- {AuthScripts} - Leave these as default "attach,edit,manage,rename,save,upload,viewauth,rdiffauth".
- {AuthRealm} - You can leave this as is or change the words to suit your needs. The text is displayed in the username/password window when using ApacheLogin
- {PasswordManager} - Leave it at TWiki::Users::HtPasswdUser is you have the users passwords stored in a .htpasswd file. If you use LDAP authentication or similar external password manager set this to "None".
- {MinPasswordLength} - Change this to your preferred policy
- {Htpasswd}{FileName} - Leave this as default /var/www/twiki/data/.htpasswd. Then you know where you have it and it fits the twiki.conf file we created earlier and we know it is protected from access.
- {Htpasswd}{Encoding} - The default 'crypt' is probably fine.
- {UserMappingManager} - There is currently nothing to choose from. Leave it.
- {Register}{AllowLoginName} - Leave this off if you keep the passwords in the .htpasswd file. If you use an external authentication such as LDAP then your usernames are most likely different from the WikiNames. Then you need to set this ON.
- {Register}{HidePasswd} - Leave this on.
- {Register}{NeedVerification} - It may be a good idea to leave this off until you have registered yourself - in case you run into problems with TWiki sending emails. If you run a public TWiki you should go back and enable this once your TWiki is setup and running. For Intranet TWikis leave this off. It is not annoying then.
- {SafeEnvPath} - Leave as default.
- {DenyDotDotInclude} - Leave this on.
- {INCLUDE}{AllowURLs} - For Internets only enable this if you need it. For Intranets turn this ON. It is a nice feature.
- {AllowInlineScript} - Leave this on.
- {UploadFilter} - Leave this as default.
- {NameFilter} - Leave this as default.
- {ForceUnsafeRegexes} - Leave this off
- {GetScriptUrlFromCgi} - Leave this off
- {RemovePortNumber} - Leave this off
Configure - setting up Antispam Measures
- {AntiSpam}{EmailPadding} - For Internets add some UPPERCASE spam padding word to make it a little more difficult to harvest email addresses. For Intranets turn this feature off.
- {AntiSpam}{HideUserDetails} - For Internet sites turn this on. For Intranet sites turn it off.
- {AntiSpam}{RobotsAreWelcome} - Leave this on
Configure - setting up Localisation
Localisation is an expensive feature with respect to performance. Do not enable it unless it is important that your TWiki has some strings in your local language. And if you enable it - turn only the languages on that you really need.
Mails and proxies
- {MailProgram} is not important. You have Net::SMTP installed by default on your RHEL/Fedoa/Centos
- {SMTP}{MAILHOST} - Set this to localhost. You can also set it to a local SMTP server
- {SMTP}{SENDERHOST} - Set this to the registered domain name you have - if you have one.
- {SMTP}{Username} and {SMTP}{Password} are used when you specify an external {SMTP}{MAILHOST} and this requires authentication
Plugins
- Enable the ones you think you need. We recommend that you enable them all - except WysiwygPlugin which you should only enable if you accept that it is not a finished perfect tool.
Register yourself as a user.
You now register yourself as a user.
- Open this URL in your browser:
twiki/bin/view/TWiki/TWikiRegistration
- Fill out the form and submit.
- Note that a WikiName is automatically composed from your First and Last names. This is the username that TWiki knows you as when you are logged in.
- If you had turned off the {Register}{NeedVerification} in configure you are now registered. Otherwise TWiki will send you a verification code by email and will be presenting you with a page on which you must enter the verification code. If for some reason email does not work, you can find the verification code in the file
/var/www/twiki/data/RegistrationApprovals directory. The file there is named as FirstLast .Approval_code. Complete the registration by entering the verification code.
Change your user account to being an administrator.
To become the administrator you simply add yourself to the TWikiAdminGroup.
- Go to
twiki/bin/view/Main/TWikiAdminGroup
- Hit the edit button.
- In the line saying
* Set GROUP = ATWikiUser replace ATWikiUser by the WikiName you registred
- In the line saying
* #Set ALLOWTOPICCHANGE = TWikiAdminGroup remove the #. This locks the topic so that only you can edit it and add more names to the TWikiAdminGroup.
- Hit the Save button
- You are now an administrator on your TWiki.
Cron setup
We need to add a couple of lines to the cron daemon. The cron daemon runs programs according to a schedule. We run a program
/var/www/twiki/tools/tick_twiki.pl which cleans out expired session files and remove expired lease files.
In /etc/crontab add this line to run the tick_twiki.pl every night at 5 o'clock.
0 5 * * * root cd /var/www/twiki/tools && perl -I /var/www/twiki/bin tick_twiki.pl
If you want TWiki to send emails notifying people about topic changes you need a similar line to run mailnotify. Here is an example where we run this script at midnight.
0 0 * * * root cd /var/www/twiki/tools && perl -I /var/www/twiki/bin mailnotify -q
Note that crond refuses to run anything in /etc/crontab if the file is writable by anyone else than root. So watch out not to change access rights. Access right for /etc/crontab should be 600 or 644.
Change WIKIWEBMASTER
We need to change the setting that defines the email address of the webmaster. The setting for this is found in TWiki.TWikiPreferences. However you should never edit anything in this topic because you risk it all gets overwritten when you upgrade. Instead copy the setting to Main.TWikiPreferences
- Go to
twiki/bin/view/Main/TWikiPreferences
- Edit the page
- Copy paste this into the topic making sure that you have either 3 or 6 spaces before the "*" and replacing the example by your real admin email account.
---+++ E-mail Settings
* TWiki administrator e-mail address:
* Set WIKIWEBMASTER = emailaddress@domain.com
Other tailoring
Now the fun begins setting up your TWiki with your own logos, adding new webs etc. This is where this topic ends.
Enjoy your new TWiki
