debian4Add my vote for this tag deployment1Add my vote for this tag easy_install25Remove my vote on this tag installation4Add my vote for this tag windows2Add my vote for this tag create new tag
, view all tags

TWiki VMware Virtual Machine (using Debian stable)

NOTE: This VMware software appliance is outdated and is no longer maintained. We recommend to download the latest TWiki-VM (Virtual machine)

Easy installation on Windows!

TIP First time visiting? Start learning about TWiki by browsing the TWiki front page at http://TWiki.org/! You can also try TWiki now by editing Sandbox pages.

Summary: This page enables you to quickly and easily install a pre-configured TWiki 4.0 'software appliance' on Windows, by using the free VMware Player or VMware Server - like another computer running within your computer. This generally performs better than a normal WindowsInstallCookbook approach and is easier to install than IndigoPerlCookbook (takes just 5 minutes, a bit like installing a hard disk that has TWiki and Linux pre-installed). Although running TWiki on Linux on top of Windows may seem complicated, it's actually much simpler than installing TWikiOnWindows - no TWiki or Linux knowledge is needed to get a working TWiki installation!

IDEA! This uses TWiki VM 4.0.4 released on 8 July 2006, an older TWiki release. See below for changes in 4.0.4 release. (For security reasons, you must apply the latest security hotfix for 4.0.4 before you use this TWiki VM in a production environment, and see the security checklist below.)

NEW: If you have set up a TWiki using this installation procedure and found it easy to follow, please tag it as easy_install (just click the link). If it wasn't easy, tell us why in TWikiVMComments!

NEW: Instructions to upgrade this VM to ver 4.3.1 have been added. Scroll down to the end of this page.

Download the TWiki VM

Includes TWiki Release 4.0.4, 358MB (does not include VMware, which is best installed first):


VMware has recently released free versions of two of their products, called VMware Player and VMware Server. This means it's become possible to create a complete pre-installed TWiki system for Windows, so that you can "download and go" with a very simple installation process.

You can download a VMware Virtual Machine (VM), with TWiki pre-installed in it, from this page. This gives you a TWikiOnLinux (really TWikiOnDebian) environment with very little installation work, and without requiring any Linux, Apache, Perl or TWiki skills to get started. If you can download and install Windows software, you can install TWiki.

VMs are quite large because they include a complete Debian GNU/Linux installation as well as TWiki. However, the increased download time means a much quicker install time. The TWiki VM approach will get you up and running faster than WindowsInstallCookbook or even IndigoPerlCookbook, and with full international character support.

VMware background

VMware has been around for quite a few years as a way of running a 'computer within a computer' - the relevant VMware products are:

  • VMware Player - freeware that enables ordinary PC users to easily run any virtual machine on a Windows or Linux PC.
  • VMware Server (now out of Beta) - freeware for server usage only (based on VMware GSX Server) and allows for more advanced setups, including creating VMs and running multiple virtual machines as services on the same PC or server. This page mainly applies to VMware Player, but VMware Server should also work.

Using TWiki VM on Linux and Mac

Note: Even though you can easily run this pre-built TWiki VM on top of Linux (using VMware for Linux), the benefits are not as obvious as running it on Windows, as TWiki is not too hard to install natively on Linux (see TWikiOn). However, it could be useful to evaluate TWiki on Windows and then transfer the VM unchanged onto a Linux server, and some people just find it easier to install TWiki VM on Linux than to do a native TWiki install.

UPDATED: VMware is now available on the Mac as VMWare Fusion - now, Mac users can get a working TWiki in 5 minutes! It's not clear if VMware Fusion (VMWare for Intel Macs) will remain free after its release, but it is for now. As with TWiki on Linux, it's not too hard to install TWiki natively on Mac (see TWikiOnMacOSX) but some people may prefer the VM route.

There is an entry in the VMware appliances directory that contains the link to this TWiki VMware download.

Note: There are compatibility issues with the X-Windows video driver, causing the console and firefox to not be directly accessible. TWiki will still work from your OSX Host.

Hardware requirements

TWiki VM will run on a PC with 256 MB RAM, but using it in 128 MB is not a good idea, particularly under Windows XP which really prefers 256 MB. If you run a lot of applications on the TWiki VM host PC, 512 MB RAM is recommended - a basic TWiki VM for desktop usage can take up between 90 and 160 MB or more of real memory. If using Windows Vista, you should increase these requirements significantly, but TWiki VM should be a small part of the overall 1 to 2 GB recommended with Vista.

VMware takes only a few per cent of your CPU, so the main thing to focus on is RAM. Any PC that is 1 GHz or higher should be fine. Of course, if you are using this TWiki VM for production deployment you may need a faster CPU, more RAM, and some tweaking with CGI accelerators such as ModPerl or SpeedyCGI (included in latest VM).

VMware lists minimum hardware requirements for VMware Player as "400MHz or faster processor (500MHz recommended) and 128MB RAM minimum (256MB RAM recommended)" ( VMware Player FAQ), but these are bare minimums that are not really enough for TWiki VM.

TWiki version

The current version of TWikiVMDebianStable is 4.0.4, based on TWiki 4.0.4 (TWikiRelease04x00x04).

Change log

Changes in TWiki VM release 4.0.4

SteffenPoulsen uploaded a new version of the VM on 8 Jul 2006, based on TWikiRelease04x00x04. Other changes are:

  • Upgraded to new Debian version (3.1)
  • Using 2.4 kernel instead of 2.6 kernel (2.6 has issues in some configurations)
  • Debian development environment on board (for compiling Apache modules, etc)
  • VMware Tools pre-installed (resolves TWikiVMWrongDate issue, adds more effective network driver)
  • Initial redirect from http://twiki-vm/ to the Main.WebHome page will work without configuration, including for hostnames other than twiki-vm
  • All mail activity suspended by default

As a consequence, this VM has grown a bit in size: now 360 MB zipped.

How to get started!

These simple steps will quickly provide you with your very own TWiki installation - and you will avoid having to go through a full installation process just to see TWiki in action in your own environment. No TWiki or Linux knowledge is needed to get a working TWiki installation for evaluation purposes!

  1. Download and install the VMware Player (from http://www.vmware.com/products/player/)
  2. Download the TWiki VM package and unzip it to somewhere like c:\twiki. Download locations:
  3. Start VMware Player and point it to the TWiki VM package ( .vmx file from the unzipped package)
  4. Set the VMWare Ethernet device to 'NAT' so that your TWiki VM is not visible on the network (just three clicks, important for security - see screenshot below)
Your NAT setup should look like this:

Screenshot showing NAT setup for security

If you're using a desktop or laptop PC, and you definitely enabled NAT in step 4, you can skip this security step:

  • For servers, including PC-based TWikis that are accessible to other users, you need to go through the Security Setup section.

That's it! There's absolutely nothing stopping you from just TWiki'ing away in your browser after that, blissfully ignoring the technical Linux details smile If this sounds like you, just read the next section, #Firing_up_your_browser, and you're done! However, if you want other users in a LAN to access this system, you will have more luck by setting the VMware player's network interface up as bridged, rather than NAT, that way the system gets an IP address that is within your normal network range (with DHCP enabled) - then read the Going Public sections below.

Firing up your browser

If you are in a Windows environment, all you need to do after the virtual machine is running is to point your browser at your new TWiki installation:

  • http://twiki-vm/

You should be presented with the Main topic of the installation.

If you're in another OS (Linux/FreeBSD/etc) you probably know what to do smile (Hint: Insert twiki-vm hostname and IP address in local DNS or in /etc/hosts).

As long as you are only using this for demos, and have set your VM to use NAT as per the installation steps above, you don't need to read the Security Setup section below (which helps in securing a real production TWiki server).

If using http://twiki-vm/ doesn't work for some reason, the IP address granted to your Debian installation can be used directly instead, e.g. http://192.168.94.xx/). You can find out the IP address of the TWiki VM by entering the command ifconfig eth0 as root in the VMware console. Using ipconfig and ping in the Windows console may also help.

Environment and OS settings in virtual machine

Some Debian or Linux/Unix expertise will help you in navigating the TWiki VM, but it is not really necessary, as you already have a working TWiki server. The following sections will help you in customizing your TWiki VM for your purposes.

The Operating System Configuration

The OS running inside the VM is Linux Debian stable, v3.1 (released December 20th, 2005). You can get further information on this Linux distribution at http://debian.org/. For more discussion of TWiki on Debian and on Linux generally, see TWikiOnDebian and TWikiOnLinux.

  • IP: DHCP-enabled installation.
    • With VMware set to NAT, VMware's DHCP server provides an IP address. Or you can use Bridged mode and get an IP from your broadband router or corporate DHCP server.
  • Hostname: twiki-vm
  • Domain: .lan
  • Services: ssh, samba, http
  • Perl: Perl 5.8.4
  • Users:
    • Root: login: root, password: root ( Be sure to change these passwords!)
    • User: login: user, password: user
  • Locales:
    • All locales installed, default set to en_US
    • Change default locale used in shell by running dpkg-reconfigure locales as root

TWiki Configuration

The TWiki installation in the virtual machine is a standard TWiki installation: as many default settings as possible are used. Your TWiki Configuration can be inspected by pointing your browser at: http://twiki-vm/twiki/bin/configure

Default configuration values are as follows:

{DefaultUrlHost} http://twiki-vm/
{ScriptUrlPath} /twiki/bin
{PubUrlPath} /twiki/pub
{PubDir} /home/httpd/twiki/pub
{TemplateDir} /home/httpd/twiki/templates
{DataDir} /home/httpd/twiki/data
{LocalesDir} /home/httpd/twiki/locale

It runs an authenticated setup (using TemplateLogin).

  • TWiki installation path
    • /home/httpd/twiki/
  • TWiki Users
    • Member ofTWikiAdminGroup: login: TWikiAdmin, password: TWikiAdmin
    • Standard user: login: TWikiUser, password: TWikiUser
  • Authentication is enabled / authenticated setup
  • view is running SpeedyCGI
  • WysiwygPlugin is enabled

http://twiki-vm/ redirects to http://twiki-vm/twiki/bin/view/Main/WebHome by default.

Password for saving (updating) the configuration is set to TWikiAdmin.

{Register}{NeedVerification} has been turned off, to avoid confusion on how the e-mail subsystem works (if the setting is turned on, activation codes are sent by e-mail - but these are not easily retrieved as e-mail subsystem is set to local delivery only).

Accessing TWiki-VM

As you play around more with TWiki-VM, and you realize how great it is ;-), you may want to access and modify various settings for your wiki. Many settings can be modified directly within TWiki itself (for example, AdminToolsCategory). But, for other things you may need to access the OS itself. TWiki-VM comes with SSH and Samba (Windows file sharing) enabled.

via Network Neighborhood file sharing

On your Windows PC, you should be able to browse and edit the files in the TWiki installation just by using this link from InternetExplorer or Windows Explorer:

  • file://twiki-vm/ (log in as user / user by default)
  • \\twiki-vm should also work

The TWiki installation is located in the twiki share. Note that FirefoxBrowser disables file:// links by default - see this Mozillazine on "Links to local pages don't work" to enable such links.

You can add, remove or update the files as you wish, but you need to use an editor that supports the UNIX file format to avoid unexpected results. Do not use Notepad if you want to alter the files in the installation. Notepad will change the files to Windows-style encoding which will break in Unix. The Crimson editor (http://www.crimsoneditor.com/) or UltraEdit (http://www.ultraedit.com/) are examples of editors that work well with the UNIX file format.

Finally, if you begin using TWiki-VM in a production-like environment, you'll want to turn off or restrict access ( /etc/samba/smb.conf) to the shares. In the default TWiki-VM install, the root directory is shared; meaning that some user on the network could stumble upon the share and accidently or maliciously do some serious damage to your TWiki-VM installation.

via SSH

An ssh service ( sshd) is already configured in the VM, so you can log on as user with the user password. Make sure you do something like ssh -l user twiki-vm to login in as "user", instead of using your local account name (default).

Even if you are on the same machine as your TWiki VM, this is easier than using the VMware console, which requires keypresses to get in and out of the VMware window, and will support normal copy/paste (in local keyboard locale as well). If you are on Windows, PuTTY is a good SSH client (Google:putty+ssh).

Restarting and Shutting down the VM

Rebooting the VM

You should only need to reboot if you are doing Linux tinkering, change the VM hostname, or if you change the VMware Ethernet setup. To reboot, login as root and type shutdown -r now. To shut down completely, type shutdown -h now. After typing shutdown, you should log off if using SSH.

Note: it's also possible to reboot by clicking within the VMware main window and typing Ctrl-Alt-Del. This only works with VMware or similar console-based Linux setups, whereas shutdown works on any Linux system.

Closing down VMware

To save memory if you are not using TWiki continuously, just close the VMware window, which by default makes VMware suspend its state to disk (like hibernate on a laptop). When you run VMware again with the TWiki image, it will resume operation from where it left off, saving on the time needed to boot Linux. Some users of the 4.0.1 version of this VM reported problems with date/time slippage, however this behaviour should hopefully be better now as the 4.0.4 version has VMwareTools installed. Note that some tweaks may be needed even with TWiki VM 4.0.4 (e.g. configuring an NTP time server or changing boot parameters for the VM) - see TWikiVMWrongDate.


The Main.WebHome -topic in your new installation shows you, by default:

  • Information on your currently installed version and a link to currently available versions

The intention is to use this as a vehicle to provide important security and vm release information to you - but you are free to update this topic as you please.

Advanced Configurations

These advanced configurations are only really needed for real TWiki servers, and are mostly optional for installation on laptops/desktops.

Time Configuration

This is useful for the next step "Email Configuration" so that emails don't get lost in your inbox 12 hours behind.

  1. Log in as user 'root', default password mentioned earlier.
  2. Run tzconfig (then go through and choose your timezone)
  3. Run date

You might notice some discrepancies between the time reported by tzconfig and date, and the real time. The discrepancies may also change over time as described in this VMWare support article, particularly if you suspend your TWiki VM rather than shutting it down.

NTP (Network Time Protocol) software also seems to have difficulty setting the time. You may need to experiment with tzconfig to manually fake a timezone to get the time in the ballpark. (See also TWikiVMWrongDate). However, the TWiki VM 4.0.4 version added support for VMware Tools, which includes NTP client support and should improve this.

Email configuration

To be able to experience change notifications, you need to configure a SMTP target. There are two ways to do this: configure the OS Mail Transport Agent, or (i believe) configure TWiki variable SMTPMAILHOST. The first option is described here as I'm not sure about the second.


  1. Log in as user root, default password mentioned earlier.
  2. At the prompt, dpkg-reconfigure --priority high exim4-config
  3. Choose "=Mail sent by smarthost; no local mail="
  4. Visible domain for local users: twikidemo (not sure if this is significant for testing)
  5. Machine handling ougoing mail for this host (smarthost): yoursmtpserver.somedomain.com (use your either your ISP or corporate SMTP server)

Now test by typing

# mail  testuser@yourdomain.com Subject: test1 does this work . Cc: 


In order to get mail notifications, you need to install and configure the MailerContrib plugin.

  1. Download the package from here
  2. Extract the package into your TWiki installation directory (/home/httpd/twiki/) or file://twiki-vm/twiki/
  3. Log in to your VM as root
  4. Run the MailerContrib installer
    1. cd /home/httpd/twiki
    2. perl MailerContrib _installer.pl
  5. Follow the on-screen instructions. The install script will automatically connect to CPAN to download packages such as CPAN:URI. If you haven't configured CPAN previously, it will ask if you want to manually configure it - automatic configuration seems to work ok. Note:This process can take some time, be patient!
  6. After some time, the MailerContrib installer should finish, test it out using the following:
    1. Edit your WebNotify topic to add yourself to the subscription list
    2. Make some changes in your Main web
    3. In your VM, as root: perl -I /home/httpd/twiki/bin /home/httpd/twiki/tools/mailnotify
  7. Only thing left for you to do is set the above command up as a Cron job, which is out of the scope of this set of instructions.

Note: Updated apparent typos in instructions above, this needs testing. --RD

IP Address Problems: Returning From Hibernate in Windows

On some machines with DHCP enabled, if you hibernate the machine while running VMWare server (i.e. without stopping the server), returning from Windows hibernation will result in some quirky behavior:

  1. TWiki will work fine for some time, presumably until the lease expires for the IP address assigned to twiki-vm
  2. The renewal process for the IP address then takes place but a new IP address is assigned (anyone who has info or insight as to why this happens?)
  3. The new IP address is usually the old IP address plus one, so if the old address was the new one will be
  4. With a new IP address, the twiki-vm hostname will no longer be accessible, ie, ping twiki-vm doesn't work and neither does http://twiki-vm in a webbrowser
  5. It is apparent from the ping command however that twiki-vm is still being resolved to the old IP address (in our example,
  6. Pinging the new IP address shows that the VM is working though (or the new IP address can also be confirmed via the ifconfig eth0 command after logging in to the VM)
  7. During this time accessing the samba share at \\twiki-vm should still work--Windows can apparently resolve the shared folder but not the hostname used when pinging or browsing
  8. After a fairly long delay, the Windows hostname will automatically update and resolve to the correct IP address, at which point everything will start working again

The net effect of this behavior is usually the maximum possible annoyance when returning from hibernate and going to edit a page. The edit will work, but during the edit the old IP address will expire. Trying to save the edited page after that point results in the webserver not being accessible to save the edit. When this happens you can:

  1. Wait the long delay out until the ping command works again and then perform the save
  2. Determine the new IP address using one of the two methods stated above, and substitute the IP address for twiki-vm in the URL (ie, instead of http://twiki-vm/

You may also try and set up the installation with a static IP address - see the Going public sections below - however, you can keep your VMware setup as NAT, and you don't need to open port 80 in firewalls, because the static IP address is only used by your Windows PC and the TWiki VM (not outside your PC)

Going public: changing the hostname and Samba workgroup

This is only needed for TWiki servers that are accessible to others on your network (not just within your PC), and is entirely optional for a personal installation on laptops/desktops.

To change the VM's hostname from twiki-vm to (say) fred, and the Samba workgroup for Windows filesharing to ourgroup, here's what to do:

  1. This setup may expose your TWiki VM to the wider network, depending on firewall settings, so be sure to go through the security checklist - home users who aren't exposing their TWiki to the Internet can probably skip this (but do make sure you have configured WPA security on any WiFi network, otherwise it's very easy to hack into your home network)
  2. TWiki: From your web browser, go to http://twiki-vm/twiki/bin/configure configure, under the General Path Settings section, change the DefaultUrlHost to http://fred.yourdomain.com
  3. Linux: Login as root via SSH (you can also use the root windows share for file editing - be sure to use a Unix-compatible editor) - (for vi see http://www-rohan.sdsu.edu/doc/debian/ch-editor.html) and #SshAccess and #FileSharing
  4. Linux: Change the twiki-vm hostname in /etc/hostname to fred - must include exactly one line
    • If you are in the Linux shell, type echo fred >/etc/hostname
  5. Linux: Edit /etc/hosts to change twiki-vm to fred on first line.
  6. Linux: Edit /home/httpd/twiki/.htaccess to change Redirect line with new hostname (Apache setup) (hint: make sure you fully qualify the machine name, like wiki.yourdomain.com, otherwise you'll have users outside your domain getting redirected to wikipedia or prompted for a MSN search!).
  7. Linux: Edit /etc/samba/smb.conf to change workgroup to ourgroup (Samba setup)
  8. Reboot the VM by typing shutdown -r now and logging off
    • Linux can change hostname without rebooting, but this helps Windows pick up the change.
  9. If you need to make your TWiki VM accessible from other machines on your network, see the next section.

Samba will pick up the new hostname on reboot. You now just need to fix any bookmarks, favourites or drive letters for filesharing, and you should be done. The TWiki pages shouldn't have any use of the hostname.

This can also be part of the 'hand over' of a TWiki VM, originally installed on your PC, to your IT department so they can install it on a server for wider use. There's probably a lot more to this, though - see #SecuritySetup.

Going public: from DHCP to Static IP address

This is mostly needed for TWiki servers that are accessible to others on your network (not just within your PC), and is entirely optional for a personal installation on laptops/desktops (although there is also a reason to do this if you want to hibernate your PC). In some networks, you can ask the IT administrator to set up DHCP to always hand out the same IP address for your TWiki VM. This section addresses the case where you need a static IP address for TWiki VM that is configured on your PC.

If you would like to give TWiki VM a static IP address, so that you can, for example, use it as your internal Wiki server and not have to worry about the IP address changing on you (mine, for example, changed a couple times when we were still experimenting), you will need to do this:

  1. This setup may expose your TWiki VM to the wider network, depending on firewall settings, so be sure to go through the security checklist - home users who aren't exposing their TWiki to the Internet can probably skip this (but do make sure you have configured WPA security on any WiFi network, otherwise it's very easy to hack into your home network)
  2. Get your corporate IT administrator to assign you an IP address and hostname, and configure the relevant DNS server. If you're a home user, just pick a static IP address from your network, and ensure your home DHCP server is configured not to hand out that address.
  3. If you want to be accessible from the Internet, you'll need to add the appropriate rules to your corporate firewall, or configure port forwarding and firewall rules on your home firewall box (most broadband routers include a firewall).
  4. In all cases, you'll need to configure your Windows PC's firewall, since it normally blocks HTTP (port 80) requests from outside your PC - most people on Windows XP SP2 or higher will have the built-in Windows firewall, while some will have installed a third party firewall such as Zone Alarm.
  5. In the TWiki VM itself, edit the file interfaces located in /etc/network/. On the iface line, change the dhcp word to static. Then add the static IP configuration, as in the example below, using your own address details - if you are a home user and don't have a home DNS server, the dns-search line can be left as is:
      # The primary network interface       auto eth0       iface eth0 inet static       address **       netmask **       gateway **       dns-search *yourdomain.com*       dns-nameservers ** 
  1. In VMware, change the Ethernet device from NAT to Bridged.
  2. Reboot TWiki VM by issuing the shutdown -r now command (and maybe reboot your Windows PC to be sure it picks up the new address.)
  3. Try to connect to TWiki from another machine using a web browser, using the IP address only, e.g., or via Telnet using telnet 80 (and hit Enter) - if you can't connect, check firewall logs on your Windows PC as well as any corporate or home firewall box. Note that ping will only work if your firewall setup enables ICMP.

Adding plugins

There are literally hundreds of plugins that can be added to the TWiki install, see Plugins.

There are two important aspects to remember when trying to install plugins in this virtual machine.

  • After installation of plugins, one has to also activate them with the configure option which will likely be found at something like http://twiki-vm/twiki/bin/configure . The confirmation password is the password of the TWikiAdmin (default password: TWikiAdmin)
  • view is running SpeedyCGI. This implies that plugins that you add do not seem to work (they only produce the correct output when previewing topics after edit). This is by design as explained by SteffenPoulsen in PluginsOnlyWorkInPreview.

To get the plugins working after installation, do one of these:

  • Reboot the virtual machine or
  • Issue a killall speedy_backend as root or
  • Issue a touch /home/httpd/twiki/bin/* as root

Doing one of these actions will make the TWiki reload its configuration, and the plugin will start to work (hopefully as expected :-)).

Localizing TWiki

TWiki has good support for internationalisation and comes with translations into several languages. TWiki VM is really the only way to get full TWiki I18N working on Windows, due to some issues with Perl I18N support on Windows.

The TWiki VM installation is set up for US usage by default, using the ISO-8859-1 character set for page contents (so you can use accented European characters in pages, but not in WikiWords). The TWikiVM comes pre-configured with quite a list of Debian locales and TWiki translations for languages such as French, German, Spanish, Portuguese, Danish and Chinese (and more are being developed).

See the main TWikiInstallationGuide and user documentation for details of how to set this up via the web-based configure tool, and in particular InstallationWithI18N which goes through additional I18N setup steps. Also, check UserInterfaceLocalisation for details of new translations.

Localizing VM Keyboard

The TWikiOnDebian VM will have a US keyboard by default - people in other countries may want to do something like (for UK keyboard):

   install-keymap /usr/share/keymaps/i386/qwerty/uk.kmap.gz 

You will want to change the uk and possibly the qwerty part ( azerty and qwertz are also available). Use ls to find what's available (hint: the TAB key auto-completes filenames).

This only needs to be done once - all Debian keymaps are available in the /usr/share/keymaps/i386 directory and subdirectories.

Security and use in production environments

This TWiki-VM, in its default configuration, is purely meant for demonstration purposes only. It's fine for individual use, as-is, as long as you set VMware's Ethernet to NAT (or 'host only'). But, as you move to a production or production-like (e.g. internal corporate use) environment, you'll likely want to perform some of the advanced configurations above, and run through the security checklist below:

Security Checklist

So, you're sold on TWiki, and are ready to move it to a production-like environment. You've completed the above steps for customizing the VM for your needs (changing the machine name and configured mail). Below is a checklist of items you should do before going live.

  1. Firewall - Everyone needs a good firewall. wink If you want to allow other users to access your TWiki-VM, your firewall(s) will have to be configured to allow http (port-80) traffic to the VM.
    • network-level - If you're within a corporate environment, you will likely already be behind the firewall and it will presumably block traffic to your computer and VM (check with your IT department to verify). If you're a home-user, a home-router (for example, a wireless Linksys WRT54G) is highly recommended (regardless of whether you're hosting a TWiki or not).
    • computer-level - Your Windows PC may already have a machine-level firewall installed and enabled (e.g. Windows XP SP2's built-in firewall). This should be enough to protect your machine and TWiki-VM from internal network users from maliciously or accidentally accessing the VM, and is a lot easier to configure and manage. Also note that many anti-virus packages (such as Norton and McAfee) also include firewalls of their own, which will typically replace the Windows built-in firewall.
    • VM-level - Since this VM includes Debian Linux, you also have the option of configuring the firewall included with it. This is mostly recommended for people who already know Linux firewall setup - there are also some good tutorials online.
  2. Change root and user passwords on Linux - Log in as root using the temp password above, and type the passwd root and passwd user command and follow the prompts.
  3. Change user password for samba service - Use this command as root in the shell: smbpasswd -a user and give a new password for the user user.
  4. Change TWikiAdmin and TWikiUser passwords on TWiki - If you're using the built-in, pre-configured TWiki authentication, you'll want to change the password for TWikiAdmin and TWikiUser. Simply login with each account and change the password on the ChangePassword page.
  5. Shut down unnecessary ports. Technically, the only thing needed to run TWiki-VM is http (port 80).
  6. Security-update the Debian Linux OS - Debian itself (the installed Linux OS) can be updated with the latest security patches by issuing the aptitude update and aptitude upgrade commands as the root user. Hit Enter if it suggests downloading additional packages, since this is a security upgrade.
  7. Restrict or Turn Off Samba - For the purposes of demonstrating TWiki, TWikiVM is configured to share its' root directory and twiki directory so that you can conveniently edit any config files. As you go "live", you will definitely want at least restrict who can login, or turn them shares off altogether (it's probably advisable to turn off the root share regardless). There is lots of information and how-to's available on the net for configuring Samba, including this section on Samba's site, as well as many other examples found from Google.
    • To turn off an individual share (such as root), edit the /etc/samba/smb.conf file and add a # at the beginning of each line within the share block.
    • If you want to remove the samba file sharing service altogether, simply remove it using Debians package management: aptitude remove samba (as root).
  8. Security-update TWiki release - TWiki VM doesn't necessarily use the latest release of TWiki so it is critical that you check TWikiSecurityAlerts and update TWiki to the latest release (shown in DownloadTWiki) - this can be done quite easily via hotfixes for the TWiki version in this VM. Just apply one hotfix and you are done - you don't need to do a full version upgrade of TWiki to remain secure.
  9. Security announcements - Keep up with the latest security announcements that may affect TWiki itself or the underlying Debian Linux OS included in the TWiki-VM:
  10. Edit robots.txt - If you don't want Google to eventually finding and indexing internal-use documents, you'll want to edit your twiki/robots.txt file. More help can be found here. To block all indexing, simply replace the text with:
               User-agent: *                Disallow: /=  


TWiki content produced inside the TWiki VM can be backed up, copied or moved out of the VM at any time, using tools such as ssh (scp) or Samba. See #FileSharing if you're on Windows.

For Windows users that can install and run the .NET framework and .NET applications, the free Microsoft SyncToy is an excellent backup application that can be automated to backup the data in the VM while it is running (via a network-shared folder such as \\twiki-vm\twiki). This application can perform backups extremely fast after an initial backup by analyzing date/time/size attributes and copying only updated files so the backup data remains current.

Caution: DO NOT set your backup software (such as Backup Exec) to automatically process the VMWare file itself while the VM is running--use only a network-shared folder or stop the VM. Otherwise it will crash the virtual machine; this is a known issue and is frequently brought up on the VMWare site. You should set it up to backup when the VMWare server isn't running; otherwise it will break.

Where to go for help

If you need help, many questions can be answered in the TWiki support forum. IF you're having issues specific to this VM, you might check TWikiVMComments and see if the answer is posted there. Or you can visit TWiki:Codev.TWikiConsultants for a list of people willing to assist you in setting up your own TWiki server - or any other problem you might be having with TWiki.

About this package

NOTE: Currently this package is provided solely by initiative of SteffenPoulsen. If you want to join in and support the effort you are most welcome. As this package is not part of the ordinary development effort in TWiki, updates are to be expected only on a best effort basis of SteffenPoulsen - which may likely not be an effort in line with what you would want, or when for that matter. Feel free to comment in TWikiVMComments about this.

This package was created with a focus on making it as easy as possible for new users to get an impression of a TWiki installation.

If you are interested in details on how this package was created, see TWikiVMDebianStableCreationLog.

Questions and Comments

Call for help with mod_auth_sspi - authenticating TWiki users against a Windows server

Has ANYONE had success integrating Windows authentication with TWikiVM??? I know I'm not alone with this need. I've tried following the instructions here ModAuthSSPICookbook and here GettingWindowsLoginPassedToTwiki? and here TransparentAuthentication and here WindowsInstallModNTLM all with no luck. I always get an Invalid ELF Header error. Is this because the mod_auth_sspi.so file is compiled for Windows or something? Is there anyone who can compile it for linux (sorry, my experience in Linux is a bit rusty)? If anyone can help me get this working I promise I'll write up detailed instructions!

-- RickVanderveer - 22 Jul 2006

Hi Rick, a few hints on doing this on Debian were just posted to NtlmForSolaris10 - they might be enough to get you started?

-- SteffenPoulsen - 04 Sep 2006


In security checklist, I've changed recommendation to be aptitude upgrade - it did say dist-upgrade which is a bit aggressive (could upgrade you to a new release of Debian when all you need is security updates).

-- RichardDonkin - 15 Mar 2008

A Quick way to upgrade to TWiki 4.2 (for Windows XP)

  1. Open "\\twiki-vm\root\home\httpd\twiki" in Explorer and delete everything except the apache-logfiles folder
  2. Unpack the new TWiki files in the same directory (\\twiki-vm\root\home\httpd\twiki).
  3. Rename LocalLib.cfg.txt to LocalLib.cfg (located at \\twiki-vm\root\home\httpd\twiki\bin) and change the Lib-Path (/home/httpd/twiki/lib)
  4. Generate the twiki_httpd.conf-file and place it in this directory: \\twiki-vm\root\home\httpd\twiki)
  5. Enter the following command in the shell
    chown -R www-data:www-data /home/httpd/twiki
  6. Restart Apache using the following command:
    /etc/init.d/apache2 restart
  7. Fix the access rights (SettingFileAccessRightsLinuxUnix)
  8. Open http://twiki-vm/bin/configure in your browser.

-- SebastianSchwarz - 13 Jun 2008

How to upgrade your VM to TWiki 4.2.2 (Linux)

I'm hardly a linux expert so for some of the following steps another linux command might be more appropriate. However, it worked quiet good for me - I've got a working 4.2.2 on my VM now smile

So here it is, a step by step guide with absolutely no other warranty than that it worked for me wink

  1. mkdir home/httpd/twiki_backup - create a backup directory.
  2. cp -r home/httpd/twiki/* home/httpd/twiki_backup - move your twiki into the backup directory
  3. rm -rf home/httpd/twiki - well, this good have been done smarter, but I didn't know the command to just remove the files inside the twiki directory wink
  4. mkdir /home/httpd/twiki - create the directory again wink
  5. upload TWiki-4.2.2.tgz to /home/httpd/
  6. tar zxvf home/httpd/TWiki-4.2.2.tgz - unpack your 4.2.2
  7. cp home/httpd/twiki_backup/bin/LocalLib.cfg home/httpd/twiki/bin/LocalLib.cfg - copy the old LocalLib
  8. chown -R www-data:www-data home/httpd/twiki - correct acces rights
  9. run configure (the url should be the same as for old your 4.0.5 twiki)
  10. resolve the errors (aka click next)
  11. go to http://yourdomain.com/twiki/bin/view - your TWiki should now run on 4.2.2 smile
  12. compare your old home/httpd/twiki_backup/lib/TWiki.cfg with your new home/httpd/twiki/lib/TWiki.cfg and check if you need to transfer any of your old settings
  13. Install all Plugins again frown
  14. cp all your non-standard webs ( data and pub) from your old twiki installation ( home/httpd/twiki_backup ) to your new 4.2.2 TWiki ( home/httpd/twiki/)
    • cp -rf home/httpd/twiki_backup/data/myweb home/httpd/twiki/data/myweb repeat for each web or use a smarter command to copy all webs but Main and TWiki, Sandbox, Trash, _default and _empty in case you are a real linux nerd wink
    • cp -rf home/httpd/twiki_backup/pub/myweb home/httpd/twiki/pub/myweb repeat for each web or use a smarter command to copy all webs but Main and TWiki, Sandbox, Trash, _default and _empty in case you are a real linux nerd wink
  15. cp all user topics from old Main to new Main
  16. cp home/httpd/twiki_backup/data/.htpasswd home/httpd/twiki/data/.htpasswd
  17. cp all your customizations (templates, css, topics in Main and TWiki, and plugins you modified, etc.)
  18. DONE :-]

-- CarloSchulz - 27 Aug 2008

How to upgrade your VM to version 4.3.1

I took CarloSchulz's guide (above) and corrected and improved upon it. Since I am not a linux guru, I made some modifications to the procedure. I have double-checked this procedure. It works 100% for me. Here it is

1. Download and run the vmware appliance. The link is at the top right of this page.

o It is an old release. We will upgrade it to the latest version later.
o It does not work on VMware ESX. We had both ESX and windows based VMware server. This worked only on the windows based VMWare server. I hear it will also run on desktop versions of vmware.

2. First of all let's install webmin on the Linux OS. This will make your life easier, especially if you have very little linux experience (like me!). Here is how:

o Use Putty to SSH to your vm
o Logon as root/root and run these commands:

cd /root

wget http://prdownloads.sourceforge.net/webadmin/webmin-1.480.tar.gz

gunzip webmin-1.480.tar.gz

tar xf webmin-1.480.tar

cd webmin-1.480

./setup.sh /usr/local/webmin

o A setup program runs now. Basically I accepted all options as default (just keep pressing enter!)
o At one point it will ask for a username and password. I left the username as admin and entered a password (twice)
o I also allowed it to start webmin at system startup.
o Press y and enter
o That's it!

Note: I use the tar file (NOT the deb file for webmin for Debian Linux). I wasted a few hrs trying to fix the dependencies. Then I broke down and used the tar. Works fine! No issues

3. Now go to webmin at http://twiki-vm:10000 and logon with the name and password you entered previously.
4. Open file manager. It is on the left menu >>> others >>> file manager

5. rename /home/httpd/twiki to /home/httpd/twiki_backup

6. create the directory /home/httpd/twiki

7. Download this file to your own desktop: http://sourceforge.net/project/downloading.php?group_id=3657&filename=TWiki-4.3.1.tgz

8. Unzip this file (I did it using 7zip). You will get a .tar file

9. In webmin's file Manger, go inside twiki folder you just created

10. Use the file manager's upload button to upload and expand this tar file (NOT the gzip file!!) to /home/httpd/twiki
Note: Make sure you select "Yes" for "Uncompress ZIP or TAR file?"

11. Now, you have to copy these files from your twiki-backup folder to the new twiki folder:

  1. /home/httpd/twiki_backup/bin/LocalLib.cfg to /home/httpd/twiki/bin/LocalLib.cfg
  2. /home/httpd/twiki_backup/lib/LocalSite.cfg to /home/httpd/twiki/lib/LocalSite.cfg

12. Solve Apache related issues:
o Create a folder for apache's files:
Otherwise apache won't start

o Copy /home/httpd/twiki_backup/twiki_httpd.conf to /home/httpd/twiki/twiki_httpd.conf

o Restart Apache server using webmin:
a. In webmin's Left menu click on servers
b. Click on apache's webserver
c. (upper right corner) click stop and then start apache.
d. Make sure there are no errors reported. If you really followed my steps listed above religiously, you should not have any errors!

13. Edit this file to prevent some CPAN related errors (you can do this using webmin's file manager. Look for the edit button):

Remove this line:
use Unicode::String qw(utf8 latin1 utf16be);

Replace the following two lines:
my $utf8AnchorName = Unicode::String->new($anchorName);
$anchorName = $utf8AnchorName->substr(0, 32);
with this line:
$anchorName =~ s/^(.{32})(.*)$/$1/; # limit to 32 chars

14. To change your Twiki Password edit this file: lib/LocalSite.cfg

Delete the $TWiki::cfg{Password} = '...'; line (whole line) from lib/LocalSite.cfg
This will make your password null (nothing / blank)

15. SSH into the twiki-vm OR use vmware console to logon as root/root. (you still have that SSH window, don't you wink

16. Run this command to correct access rights:
chown -R www-data:www-data /home/httpd/twiki

17. go to this website http://twiki-vm/twiki/bin/configure
and let configure run

18. resolve any errors (just click next)
Note: I also entered my company's mail server info. This will let TWiki send mails.

19. Set a new password on the next screen (bottom option). Put password twice and click the button.

20. It should come to a screen which says:
Password changed
Updating configuration

21. If you see this then you are done!

22. go to http://twiki-vm

23. your TWiki should now run on 4.3.1 . Nice?
Notice the message:
This site is running TWiki version TWiki-4.3.1, Wed, 29 Apr 2009, build 18054, Plugin API version 1.2

-- RajivMehra - 2009-06-23

General comments

See TWikiVMComments for a general discussion - helps to keep this page from growing too big. Please, feel free to say anything you like on TWikiVMComments.

Also, if you see any useful tips or corrections in the comments, please feel free to add them to this page!

Edit | Attach | Watch | Print version | History: r224 < r223 < r222 < r221 < r220 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r224 - 2011-08-31 - PeterThoeny
  • 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-2015 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.