Difference: TWikiInstallationGuide (80 vs. 81)

Revision 812014-10-05 - TWikiContributor

Line: 1 to 1
 

TWiki Installation Guide

Changed:
<
<
The following is installation instructions for the TWiki 5.1 production release on an Apache web server on Linux. Visit TWiki:TWiki.InstallingTWiki for the latest updates to this guide and supplemental information for installing or upgrading TWiki, including notes on installing TWiki on different platforms, environments and web hosting sites.
>
>
The following is installation instructions for the TWiki-6.0 production release on an Apache web server on Linux. Visit TWiki:TWiki.InstallingTWiki for the latest updates to this guide and supplemental information for installing or upgrading TWiki, including notes on installing TWiki on different platforms, environments and web hosting sites.
  If you are upgrading from a previous version of TWiki, you probably want to read TWikiUpgradeGuide instead.
Line: 27 to 27
 

Basic Installation

Changed:
<
<
  1. Download the TWiki distribution from http://TWiki.org/. (Example - download TWiki-5.1.2.tgz for Linux)
  2. Copy the downloaded package into the directory where you want to install TWiki (Example: /home/httpd ). Unpack the distribution in it (Example: tar xvfz TWiki-5.1.2.tgz). The unpack will create a directory called twiki which contains the TWiki package. In the rest of this document we assume this directory is called twiki.
>
>
  1. Download the TWiki distribution from http://TWiki.org/. (Example - download TWiki-6.0.1.tgz for Linux)
  2. Copy the downloaded package into the directory where you want to install TWiki (Example: /home/httpd ). Unpack the distribution in it (Example: tar xvfz TWiki-6.0.1.tgz). The unpack will create a directory called twiki which contains the TWiki package. In the rest of this document we assume this directory is called twiki.
 
    • Note: TWiki does not allow spaces in directory names. Especially on Windows make sure to use a directory path without spaces.
  1. Setup access file and directory rights to enable the webserver user (the user Apache runs the CGI scripts as) to read and write inside the twiki directory.
    • Warning: Do not just just run a chmod -R 770 twiki. The access rules have different meaning for files and directories. This is the most common mistake installers make.
Line: 52 to 52
 
  1. Configure the webserver
    • Unless you are an Apache expert setting up the webserver can be quite difficult. But TWiki has three resources that make setting up Apache easier.
      • The best and easiest way is to use webpage TWiki:TWiki.ApacheConfigGenerator which contains a tool that can generate a safe and working config file for TWiki on Apache.
Changed:
<
<
      • In the root of the twiki installation you find an example config file twiki_httpd_conf.txt (nevertheless, it is better to use the generator).
    • In case you do not have root priviledges on the server:
>
>
      • In the twiki installation you find an example config file misc/twiki_httpd_conf.txt (nevertheless, it is better to use the generator).
    • In case you do not have root privileges on the server:
 
      • In the root of the twiki installation and in the twiki/bin directory you find example .htaccess files you can copy and modify. The files contains help text explaining how to set them up. In twiki/bin you find .htaccess.txt which can be copied to .htaccess and defined access to the CGI scripts.
Changed:
<
<
      • In the root of TWiki you find pub-htaccess.txt which you can copy to pub/.htaccess, subdir-htaccess.txt which you can copy to all directories as .htaccess except bin and pub, and you find root-htaccess.txt which you can copy to .htaccess in the twiki root directory. But again only use .htaccess files if you do not have root priviledges.
>
>
      • In the TWiki misc directory you find pub-htaccess.txt which you can copy to pub/.htaccess, subdir-htaccess.txt which you can copy to all directories as .htaccess except bin and pub, and you find root-htaccess.txt which you can copy to .htaccess in the twiki root directory. But again only use .htaccess files if you do not have root privileges.
 
    • If you are unsure about how to do this on your system, see TWiki:TWiki.InstallingTWiki#OtherPlatforms for links to information about various server setups.
    • Note: When you use config files you need to restart Apache each time you change a setting to make the new setting active.
Changed:
<
<
  1. Run the configure script from your browser (enter http://yourdomain/twiki/bin/configure into your browser address bar)
>
>
  1. Run the configure script from your browser (enter http://yourdomain/do/configure into your browser address bar)
 
    • Specify and reenter a password. This is your configure password, as well as the admin user password once TWiki is running.
      • Note: In case you forgot the password, you can reset it by deleting $TWiki::cfg{Password} from LocalSite.cfg file from {TWIKI_ROOT}/lib directory.
    • When you run configure for the first time, you can only edit the General Path Settings section. Save these settings, and then return to configure to continue configuration.
Line: 67 to 67
 
    • When you return to configure you now need to setup Mail and Proxies. Especially the {WebMasterEmail}, and {SMTP}{MAILHOST} must be defined to enable TWiki to send administrative emails, such as for registration and notification of topic changes. Many ISPs have introduced authentication when sending emails to fight spam so you may also have to set {SMTP}{Username} and {SMTP}{Password}. If you do not want to enable mailing or want to enable it later you can uncheck {EnableEmail}.
    • If you want administrative e-mails to be signed, see S/MIME setup instructions below.
Changed:
<
<
You now have a basic, unauthenticated installation running. At this point you can just point your web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!
>
>
You now have a basic, unauthenticated installation running. At this point you can just point your web browser at http://yourdomain.com/do/view and start TWiki-ing away!
 

Important Server Security Settings

Before you continue any further there are some basic and very important security settings you have to make sure are set correctly.

Changed:
<
<
  1. As already described above, you should protect the configure script from general access. The configure script is designed for use by administrators only and should be restricted to invocation by them only, by using the basic Apache authentication. Because of this there has not been put much effort into hardening the script. The configure script cannot save any settings once the password has been saved the first time, but the script could still be vulnerable to specially crafted field values and the script reveals many details about the webserver that you should not display in public.
  2. You absolutely must turn off any kind of PHP, Perl, Python, Server Side Includes etc in the pub directory. TWiki has some built-in protection which renames files with dangerous filenames by appending .txt to the filename. But this is a secondary security measure. The essential action that you must take is to turn off any possible execution of any of the attached files.
    Most Linux distributions have a default Apache installation which has PHP and server side include (SSI) enabled.
  3. Make sure that you deny access to all other twiki directories than the bin and pub directories. When you have access to the Apache config files the twiki_httpd_conf.txt file mentioned above also contains protection of these directories.
    For those who do not have access to the Apache config files a sample subdir-htaccess.txt file can be copied as .htaccess to the data, lib, locale, templates, tools and working directories.
  4. Attachments are not secured by default to the access control setting of the topic. In other words, anyone can read them if they know the direct URL of the attachment, which includes name of the web, topic and attachment. You can configure TWiki to secure attachments.
>
>
  1. You absolutely must turn off any kind of PHP, Perl, Python, Server Side Includes etc in the pub directory. TWiki has some built-in protection which renames files with dangerous file names by appending .txt to the file name. But this is a secondary security measure. The essential action that you must take is to turn off any possible execution of any of the attached files.
    Most Linux distributions have a default Apache installation which has PHP and server side include (SSI) enabled.
  2. Don't put the whole twiki distribution into an HTML document enabled directory. Apache needs to be aware of only two directories: The bin directory should be script enabled, and the pub directory should be HTML document enabled.
    For those who do not have access to the Apache config files, a sample misc/subdir-htaccess.txt file can be copied as .htaccess to the data, lib, locale, templates, tools and working directories.
  3. Attachments are not secured by default to the access control setting of the topic. In other words, anyone can read them if they know the direct URL of the attachment, which includes name of the web, topic and attachment. You can configure TWiki to secure attachments.
 
Changed:
<
<
The TWiki:TWiki.ApacheConfigGenerator as well as the example twiki_httpd_conf.txt and example htaccess.txt files include the needed settings that protect against all 4 security elements.
>
>
The TWiki:TWiki.ApacheConfigGenerator as well as the example misc/twiki_httpd_conf.txt and example misc/htaccess.txt files include the needed settings that protect against all 3 security elements.
 

Next Steps

Changed:
<
<
Once you have TWiki installed and running, you might consider the following optional steps for setting up and customizing your TWiki site. Many of the references below refer to topics within your TWiki installation. For example, TWiki.TWikiSkins refers to the TWikiSkins topic in your TWiki web. Easy way to jump directly to view the pages is to open your own TWiki in your browser and write TWiki.TWikiSkins in the Jump test box to the right in the top bar and hit Enter. You can find these topics in the on-line reference copy at the official TWiki website: TWiki Release 5.1.
>
>
Once you have TWiki installed and running, you might consider the following optional steps for setting up and customizing your TWiki site. Many of the references below refer to topics within your TWiki installation. For example, TWiki.TWikiSkins refers to the TWikiSkins topic in your TWiki web. Easy way to jump directly to view the pages is to open your own TWiki in your browser and write TWiki.TWikiSkins in the Jump test box to the right in the top bar and hit Enter. You can find these topics in the on-line reference copy at the official TWiki website: TWiki-6.0 Release.
 

Enable Authentication of Users

Line: 111 to 110
 
Changed:
<
<
The TWiki:TWiki.ApacheConfigGenerator includes this section when you choose ApacheLogin. In the example twiki_httpd_conf.txt and bin/.htaccess.txt files this section is commented out with #. Uncomment the section when you use ApacheLogin. It is important that this section is commented out or removed when you use TemplateLogin.
>
>
The TWiki:TWiki.ApacheConfigGenerator includes this section when you choose ApacheLogin. In the example misc/twiki_httpd_conf.txt and bin/.htaccess.txt files this section is commented out with #. Uncomment the section when you use ApacheLogin. It is important that this section is commented out or removed when you use TemplateLogin.
 

Define the Administrator User(s)

Line: 174 to 173
  When a new users registers on your TWiki, a user profile topic is created for them based on the NewUserTemplate topic (and its UserForm). It contains additional resources you can use to:
  • Localize the user topic.
Deleted:
<
<
  • Add a default ALLOWTOPICCHANGE so only the user can edit their own home topic. We do not encourage this for Intranet sites as it sends a wrong signal to new users, but it can be necessary on a public TWiki to prevent spam.
 
  • Add and remove fields defined in the UserForm

If you choose to tailor anything you are strongly advised to copy NewUserTemplate and UserForm to the Main web and tailor the Main web copies. TWiki will look for the NewUserTemplate in the Main web first and if it does not exist TWiki uses the default from the TWiki web. By creating a Main.NewUserTemplate and its Main.UserForm you will not loose your customization next time you upgrade TWiki.

Changed:
<
<
If you added or removed fields from the user form you may also need to tailor TWikiRegistration.
>
>
If you added or removed fields from the user form you may also want to tailor TWikiRegistration.
 

Custom Start Web and Homepage

Line: 272 to 270
 
Changed:
<
<
It is also advisable to review TWiki:Codev/KnownIssuesOfTWiki05x00.
>
>
It is also advisable to review TWiki:Codev/KnownIssuesOfTWiki06x00.
  If you need help, ask a question in the TWiki:Support web or on TWiki:Codev/TWikiIRC (irc.freenode.net, channel #twiki)
Line: 295 to 293
 
  • Step 2: If you cannot unpack the TWiki distribution directly in your installation directory, you can unpack the distribution on your local PC and then manually create the directory structure on your host server and upload the files as follows:
    • Using the table below, create a directory structure on your host server
    • Upload the TWiki files by FTP (transfer as text except for the image files in pub directory.)
Changed:
<
<
    • Note: Don't worry if you are not able to put the twiki/lib directory at the same level as the twiki/bin directory (e.g. because CGI bin directories can't be under your home directory and you don't have root access). You can create this directory elsewhere and configure the twiki/bin/setlib.cfg file (done in Step 2).
>
>
    • Note: Don't worry if you are not able to put the twiki/lib directory at the same level as the twiki/bin directory (e.g. because CGI bin directories can't be under your home directory and you don't have root access). You can create this directory elsewhere and configure the twiki/bin/LocalLib.cfg file (done in Step 2).
 
TWiki dir: What it is: Where to copy: Example:
Changed:
<
<
twiki start-up pages root TWiki dir /home/smith/twiki/
twiki/bin CGI bin CGI-enabled dir /home/smith/twiki/bin
twiki/lib library files same level as twiki/bin /home/smith/twiki/lib
twiki/locale language files dir secure from public access /home/smith/twiki/locale
twiki/pub public files htdoc enabled dir /home/smith/twiki/pub
twiki/data topic data dir secure from public access /home/smith/twiki/data
twiki/templates web templates dir secure from public access /home/smith/twiki/templates
twiki/tools TWiki utlilities dir secure from public access /home/smith/twiki/tools
twiki/working Temporary and internal files dir secure from public access /home/smith/twiki/working
>
>
twiki/ TWiki package TWiki root directory, should be secure from public access /home/smith/twiki/
twiki/bin/ CGI bin move to script-enabled dirctory /home/smith/cgi/twiki/
twiki/lib/ library files leave in TWiki root /home/smith/twiki/lib/
twiki/locale/ language files leave in TWiki root /home/smith/twiki/locale/
twiki/pub/ public files move to HTML document enabled directory /home/smith/html/twiki-pub/
twiki/data/ topic data leave in TWiki root /home/smith/twiki/data/
twiki/templates/ web templates leave in TWiki root /home/smith/twiki/templates/
twiki/tools/ TWiki utlilities leave in TWiki root /home/smith/twiki/tools/
twiki/working/ Temporary and internal files leave in TWiki root /home/smith/twiki/working/
 
  • Step 3: Files in the pub directory must be readable as a url. This means that directory permissions should be set to 755 (or 775 ) and file permissions should be set to 644 (or 664). If you can run a chmod command, you can accomplish this in two quick steps by running these commands from the root direct:
    • chmod -R 755 pub
    • chmod 644 `find pub -type f -print`
Changed:
<
<
    • In addition, you should create a .htaccess file in the pub directory, using the template included in the root level of the distribution entitled pub-htaccess.txt.
>
>
    • In addition, you should create a .htaccess file in the pub directory, using the template included in the distribution entitled misc/pub-htaccess.txt.
 

  • Step 6: In order to run the configure script, create a file called .htaccess in the bin directory that includes the following single line: SetHandler cgi-script . This informs the server to treat all the perl scripts in the bin directory as scripts.
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiInstallationGuide.