TWiki On Ubuntu/Kubuntu - Manual Install

See TWikiOnUbuntu for a much simpler installation guide using Ubuntu's TWiki package - this works for Kubuntu, Ubuntu, Xubuntu and Edubuntu.

Originally installed on version 6.10 - Edgy Eft.

This guide was started by a total Linux newbie who ended up with a Kubuntu box and wanted to share specific installation steps, using a manual installation before there was a TWiki packaged for Ubuntu/Kubuntu.

I surfed across many of the installation related pages here, but seemingly without an explicit Ubuntu/Kubuntu guide, some steps were a litte different. Likely these steps will be very similar across all Ubuntu flavors such as Xubuntu, Ubuntu, etc - see TWikiOnUbuntu for the differences when using Ubuntu (GNOME based) rather than Kubuntu.

This is not (at first) an attempt to provide steps towards a perfect TWiki install, only the minimal needed to get a running instance, with several security and permission issues just hacked through. I wanted to get myself a running TWiki and then over time get more used to it and Kubuntu, tuning it towards a secure published server later. There are other guides that can be useful for topics like authentication.

If anybody wants to contribute to improve this guide in the areas where I've bypassed important areas, feel free to add in colored comments or links to related documents. I put some useful commands at the bottom of the page, I used them all while tinkering.

Preparing Kubuntu

Open Konsole Session New Root Shell, enter password (same as the default user).

(Or just type sudo bash from an existing root shell.)

The rest of this guide assumes you are root.

Installing Apache2

It is super easy to install a lot of items on Kubuntu. To install apache I simply entered in my terminal window:

apt-get install apache2

And observed lots and lots of text scrolling by as everything was set up locally. I don't remember if I had to answer any questions, but at any time that came up I'd just pick sensible answers.

After Apache was installed, I was already able to open localhost in Konqueror and get my local webserver's index directory, so far only listing apache2-default/, the Apache placeholder directory.

So far so good!

Downloading TWiki

I found my apache2-default directory in:

/var/www/apache2-default

I decided to put TWiki in its own directory on the same level, i.e. /var/www/twiki - from an open root console, including the download, it went:

cd /var/www
mkdir twiki
cd twiki
wget http://twiki.org/p/pub/Codev/Release/TWiki-4.1.2.tgz (of course, this will only get you the 4.1.2 version)

This left me with the compressed file /var/www/twiki/TWiki-4.1.2.tgz

To decompress, I did:

tar -zxvf TWiki-*.tgz (I figured the * just made it easier and version agnostic)

At this point I now had the base files in the right place. Huzzah!

Installing dependencies

CGI::Session

From the guru at work, who I got to install our corporate TWiki earlier, I knew I had to install something called CGI:Session, so I did:

cpan

This opened a special CPAN shell for installing various Perl modules. I typed:

install CGI::Session

Stay in this CPAN shell for the next step.

Net::SMTP

While tinkering with email, I figured out that Net::SMTP was installed, but some setting wasn't right - something about {SMTP}{MAILHOST}, which is set through the TWiki configure CGI script (accessed via a web browser).

I reinstalled Net::SMTP anyway, which allowed me to set the SMTP and POP3 variables to my personal domain's email address. First I triggered the install:

cpan (unless you're already there from installing CGI::Session)
install Net::SMTP

During the reinstall it asked for several settings - I just entered my mail server for SMTP. Afterwards I corrected the configure script changes - more on that later. (NOTE: If you just use your ISP's mail server, specify that. You only need to specify your SMTP settings for TWiki to work.)

To get back out of cpan, simply type exit

RCS

Later in the configuration I found issues related to lacking "RCS" - so I blindly landed at the correct answer:

apt-get install rcs

Everything seemed to install correctly and the configure script stopped complaining.

Setting up TWiki

At this point, all the dependencies were ready on my system. Of course, I found half the dependencies while setting up TWiki itself, but for ease I put them all together before starting on the setup.

The first thing to make sure is that everything can access enough for TWiki to work - there's a right way to do this, and there's the easy "I don't think this is really secure" way to do it. First time around, easy way it is!

TWiki & Apache ownership / permissions

To make sure apache and TWiki could get along, I did:

cd /var/www
chown -R www-data twiki (www-data appears to be the apache user on my box)
chmod -R u+w twiki

To actually figure out what the apache username was, I used a command listing all active processes on the system, then guessed the user. There's obviously a better way, but I was working fairly blind.

ps axu | more (the | more part helps avoid scolling, but you may not need it)

Temp directory

One of the eventual config errors I got was related to TWiki being unable to write to its temp directory - more guessing, based on TWiki stating it was trying to use /tmp/twiki:

cd /tmp
mkdir twiki
chmod -R u+w twiki

I think this was sufficient - didn't have to assign ownership using chown

Prepare LocalLib.cfg

Standard part of the install. Make a copy of a provided file with a correct filename and adjust it a bit.

cd /var/www/twiki/bin
cp LocalLib.cfg.txt LocalLib.cfg
pico LocalLib.cfg

With pico open (or any other text editor you can work) find the $twikiLibPath and adjust it to the absolute path of your TWiki's lib dir, just like the instructions said. Mine became:

$twikiLibPath = "/var/www/twiki/lib";

To exit pico, press CTRL-x

Prepare TWiki's apache conf file

I copied the provided Apache config file to Apache's location on my system and edited with Pico:

cp /var/www/twiki/twiki_httpd_conf.txt /etc/apache2/conf.d/twiki.conf
pico /etc/apache2/conf.d/twiki.conf

As the file instructs, edit each occurrance of the provided path to match your system.

You don't need PHP for TWiki, and in fact it can contribute to a security hole, SecurityAlertSecureFileUploads. So comment out the lines mentioning PHP in this file, as directed by the comments.

Now, this is where my main security flaw comes up - I adjusted the section related to the configure script as per the instructions, changing JohnDoe with my login name - but couldn't get past the login prompt you get when trying to hit the configure page, like many others in various other install / bug docs around here. I probably did something wrong, but I found a simple fix - I commented out the whole section (with #'s)

Of course, when I did this, I had hacked my way through this process many times. But if you edit everything as suggested the first time, hopefully you won't have to edit again, until you actually want security.

Restart Apache

To restart Apache, just type this as root:

/etc/init.d/apache2 restart

Hit configure!

Finally you can try hitting the configure script. Open Konqueror and go to localhost. If all is well, there should be twiki/ directory next to the apache2-default/. Click twiki/ and you'll be presented with the TWiki setup page. Click on the Configure TWiki link - from here you can continue to your webhome if all appears well, and review the status of everything if not.

Set {SMTP}{MAILHOST}

It was at this point I had some trouble with email - in the end, I just had to find this setting under Mail and Proxies in the TWiki.TWikiPreferences page.

Set the WebMasterEmail along with the SMTP to your mail server, or maybe just localhost - I used my mail server. Since I did that, I also had to provide the username and password I use for my normal mail program.

TWiki away!

With the configure reviewed, you're basically set - you will probably want to secure your system and TWiki better, enable user authentication, and so on, but that's covered well elsewhere. Have fun with TWiki!

Useful commands

During my journeys with the root command prompt, I used the following useful commands, some familiar to me from the DOS days, others new and nifty

• cd - change directory, note that a newly opened console starts one cd .. away from the top of the file system
• dir or ls - directory listings, the ls version using color codes to distinguish directories, compressed files, etc
• cp source destination simple file copy from one spot to another. I put TWiki in the wrong place at first, yay me.
• chown -R user * - assign ownership of files to the stated user. -R makes it recursive through subdirs, * means all the files & dirs in the active directory
• chmod -R u+w * - assign access permissions (I guess the u+w does something good!)
• pico filename - easy text editor
• ps axu | more - list all processes active on the system and the users that own them

-- Contributors: RasmusPraestholm - 10 Mar 2007

Discussion

Great writeup, thanks for doing this! I use Kubuntu myself.

A few comments:

• PHP is not required for TWiki, curious what made this necessary - was it perhaps an error in Apache startup about a directive mentioning PHP?
• You can install CPAN:CGI::Session directly using apt-get install libcgi-session-perl - but your technique works fine with all CPAN packages, not all of which have been repackaged by Debian or Ubuntu.

Since Kubuntu is very similar to the GNOME-based Ubuntu, your writeup will work fine for Ubuntu users once they have launched a root shell.

-- RichardDonkin - 11 Mar 2007

Thanks! - And yes, for the PHP part I seemed unable to start Apache due to something in the PHP section of the twiki.conf. Instead of commenting it out (I think that was a suggestion in the .conf) I just installed PHP and it went away. I wasn't sure if it would hurt TWiki any to not have PHP, so I included it just in case. I put a note for that above.

-- RasmusPraestholm - 11 Mar 2007

It is important to understand what the php_admin_flag engine off is doing and why it is there.

The directive disables PHP for all files in the pub directory. This is an extremely important security detail. Without anyone can attach a PHP program to a topic and execute it simply by looking up the URL for it. And once you have this, you can do anything. You can even upload a PHP program that gives you a command prompt. Apache will serve a PHP program even if the file is called something.with.php.haha.harmless.

So when you installed PHP to remove the error message it was not very smart. You should have removed the directive instead. The only defense for it is that if you later wanted to use the same webserver to serve PHP and then install PHP in 6 months you will have forgotten all about the TWiki config. At least you are secured now

With respect to configure. The problem with configure is that before you have installed TWiki you do not have a .htpasswd file with a user. And without a user in .htpasswd you cannot run configure if you have protected it by requiring a valid user. This is why I made the default example file as well as the ApacheConfigGenerator so that you can protect both with a username/password or with allowing specific IP addresses. If localhost is one of them, you can access configure from the machine that runs TWiki without being asked for a password to view configure.

When you unpack the TWiki-4.1.2.tgz the access rights should per default be correct. It should only be necessary to change the ownership.

Just running a chmod -R is not recommended. The INSTALL.html recommends using the script shown on SettingFileAccessRightsLinuxUnix to restore the right access rights. This can also be run after manually installing plugins etc.

-- KennethLavrsen - 12 Mar 2007

Are you saying that one needs to explicitly disable PHP for the pub directory? I thought one had to explicitly activate it using some SetHandler directive or something like that!?

-- StephaneLenclud - 12 Mar 2007

See also https://slion.net/view/Dev/LinuxUbuntu.

-- StephaneLenclud - 12 Mar 2007

You should just disable PHP completely, which is best done by uninstalling it - e.g. apt-get remove php. Then just comment out the PHP-related directives in the .htaccess file for pub and any /etc/apache2/conf/* files (I put twiki.conf under that directory and it gets included when Apache starts up). The security hole Kenneth is talking about is SecurityAlertSecureFileUploads - properly configured TWiki sites (as recommended here) are not vulnerable to this.

TWiki is written in Perl - PHP is another web scripting language not used in TWiki, so it's not needed. In fact the only PHP-related config in TWiki is intended to avoid malicious uploads of PHP scripts as attachments, as mentioned.

I've removed the PHP section above and put a comment in the Apache config section.

-- RichardDonkin - 12 Mar 2007

Aha, that makes sense. I'm aware of what PHP is, but simply figured it might be needed either for part of TWiki or some plugins, or simply be useful elsewhere. And I just wanted to rush through to a working TWiki for now. Thanks for the explanation!

And of course, edit away above if you'd like to state this more clearly in the guide / link to more relevant topics.

-- RasmusPraestholm - 13 Mar 2007

I'm still unsure of what needs to be done in my server configuration. I do need to use PHP as I'm also running websvn in the same virtual host. Yet I understand PHP is enabled only in the websvn directories. I this case do I need to add extra directive to prevent PHP attachments being run?

-- StephaneLenclud - 13 Mar 2007

If PHP is not enabled in the websvn directories you can comment out the php-disabling lines in the TWiki config for Apache. Good idea to test this by uploading a PHP file, see the security alert above for details.

-- RichardDonkin - 14 Mar 2007

I've added a link to TWikiOnUbuntu, which summarises the only differences I could think of when using Ubuntu rather than Kubuntu (but there may be more).

See also this Ubuntu forums thread.

-- RichardDonkin - 28 May 2007

To install all dependencies, I think you just need to run this command:

sudo apt-get install rcs libnet-perl libcgi-session-perl

The libnet-perl package maps onto Net::* i.e. it should include Net::SMTP.

-- ArenodBrenner - 20 Jun 2007

have to wonder - has anyone used the debian packages that are in debian etch?? they take care of all the dependancies etc.

-- SvenDowideit - 30 Jun 2007

I haven't, but this Ubuntu forums thread mentions this. I think it's partly that people aren't sure whether the Debian package would work on Ubuntu.

Is the Debian package always updated when there's a new TWiki release? If so it would probably be the best solution.

-- RichardDonkin - 01 Jul 2007

Yes, I update for each release. Though due to Debian stability rules, 4.1.2 did not make it into etch, so its in unstable. I also have a testing repository mentioned at distributedINFORMATION which has the beginnings of packages for all plugins too - no dependencies, and thusfar, not enough testing / feedback to know how well it works.

You do have to wonder about Ubuntu users - they often don't bother to report errors to the package maintainers - especially when they are just using the Debian package, unmodified. (can you tell I'm a Debian user?? )

-- SvenDowideit - 01 Jul 2007

I think most Ubuntu users would report bugs in Ubuntu's Launchpad bug database - reporting to the upstream distro maintainer is a somewhat advanced behaviour. Even though Ubuntu is similar to Debian, you presumably wouldn't expect a MEPIS user (derivative of Ubuntu) to report bugs to Ubuntu, and/or to Debian, I guess?

It needs to be easier to filter bugs upstream from the various distros, with suitable vetting...

-- RichardDonkin - 03 Jul 2007

yes, it is hard personally, I'd much rather get pushed all bugs from all distro's that use a derivitive of my package, especially if its a straight copy. That would make it possible for me to make the most genericly applicable package, and help the customisors (i don't think there are any atm) too. The upstream downstream seperation I see as the biggest flaw in the debian distribution - both for derived distro's, and between the developing project and debian - but its also damned hard

So - keep the bugs coming - email me if you see something - I even collect rumors of bugs, cos one day they add up to that mini-aha

-- SvenDowideit - 03 Jul 2007

Some refactoring and edits above to simplify this. It turns out that Sven's Debian package of TWiki is already in Ubuntu, from Dapper onwards.

Sven - seems you can get Ubuntu bug reports filtered directly to you as package maintainer - see UbuntuForDebianDevelopers on the Ubuntu wiki.

There's also an interesting article on forking with particular reference to Ubuntu and Debian. The Ubuntu project is trying quite hard to be a cooperative downstream branch of Debian, rather than forking, e.g. it resyncs all packages from Debian to Ubuntu every 6 months. Of course, the average Ubuntu user is far less techie than the average Debian user (although there's a big range) so there are more likely to be newbies getting confused, in addition to experts.

Since Ubuntu is now one of the most popular desktop distros, shipped by Dell and so on, it could be a great opportunity to get TWiki far more widely deployed.

UPDATE: The twiki package for Ubuntu, derived from Sven's, works really well on Ubuntu Feisty - see TWikiOnUbuntu for the writeup.

-- RichardDonkin - 28 Sep 2007

Renamed this page to better reflect what it is. The installation steps will actually work for any Ubuntu flavour, like TWikiOnUbuntu, but this page is a more complex manual install than TWikiOnUbuntu.

-- RichardDonkin - 30 Jul 2008