InstallationGuide

# Installation Guide

This guide describes the steps for installing Foswiki using Apache as the web server, on Linux.
This guide describes the specific steps for installations on Linux with the Apache web server.
If you would prefer to use a different web server, please refer to supplemental documentation when you reach the Apache-specific steps:

- Nginx: FastCGIEngineContrib#Nginx andFoswiki on Nginx
- Lighttpd: Foswiki on Lighttpd

Contents

- Before you start
- 5-Minute Install
- Detailed Instructions
  - Step 1: Download and unpack Foswiki
  - Step 2: Confirm file and directory ownership and permissions
  - Step 3: Configure location of the Perl executable
  - Step 4: Configure the web server
  - Step 5: Bootstrap your configuration
  - Step 6: Configure email
  - Step 7: Check Authentication and Register Yourself
  - Step 8: Establish an Administrator user
  - Step 9. Save your configuration!
  - Congratulations! Your Foswiki Installation is Ready to Use!
- Troubleshooting
- Supplemental Information For Installation
  - System Requirements
- Server Requirements
- Specific distribution details
- Client Requirements
  - Uploading the Foswiki distribution to your web server host
  - About Administrators
    - Options to Protect the Configure Script
    - Establishing an internal admin login (optional)
  - User Authentication Options
    - Template Login authentication
    - Enabling Template Login
    - Apache Login authentication
    - Testing your authentication configuration:
  - Configuring Foswiki manually (without using the configure page)
  - TWiki Compatibility

Rather not install manually? Visit Foswiki:Download.OtherFoswikiInstallers for automated installers, and virtual machine images. These automate much of the installation process and may help some users get started more easily. For instructions using those packages, refer to the documentation provided there. Note that the installers are optimized for the target system, and do not necessarily follow the normal Foswiki directory structure documented below.

Upgrading? Please see the upgrade guide.

Need further information? Visit Foswiki:Support.SupplementalDocuments for additional notes on installing on different operating systems or shared web-hosting environments, performance tuning, security hardening and more.

Need help? Visit Foswiki:Support web or Foswiki:Community.InternetRelayChat (irc.freenode.net, channel #foswiki).

## Before you start

- This guide assumes the a basic knowledge of server administration on the system being used. For more information, see Foswiki:System.AdminSkillsAssumptions.
- Review the System Requirements (below) to make sure you have server prerequisites installed.
- Review the release notes.
- If you need to install any Perl libraries from CPAN, see Foswiki:Support.HowToInstallCpanModules for more information.

## 5-Minute Install

Here's the quick version of the instructions, for those that are already comfortable with performing such installations. More detailed instructions follow.

1. Download and unpack the latest version of Foswiki.
2. Configure Apache using the Foswiki:Support.ApacheConfigGenerator tool to generate a safe, working config file for your Foswiki installation.
   - Install the generated file and restart Apache.
   - In shared hosting environment where you don't have access to Apache config files, see the instructions in step 4 below for configuring using `.htaccess` files.
3. Bootstrap your the install by browsing to the default view URL for your site in your web browser. Depending upon your Apache configuration, your view URL might look something like:
   - `http://yoursite.com`
   - `http://yoursite.com/bin/view`
   - `http://yoursite.com/foswiki/bin/view`
4. Follow the link in the Bootstrap banner of the returned page to the bin/configure tool, address any warnings and save your configuration.
5. Return from configure (button at top of page), and register your first user.

Note: If you are using SSL (`https://`), and access Foswiki via a proxy server, you may need to give bootstrap a "hint" that SSL is in use. Add `SSL=1` to the URL, eg: `https://yoursite.com?SSL=1`. From there, bootstrap should function correctly. You only need to do this if the initial view screen displays without any styling and the links on the page point to non-SSL `http` locations.

That's it! You Foswiki should now be installed. Browse to `/bin/view` and start editing!

At some point, you will want to re-visit Configuring Foswiki to enable out-going emails, create administrators and properly secure your installation.

## Detailed Instructions

### Step 1: Download and unpack Foswiki

1. Go to your site's root directory as set by Apache (typically within the `/var/www` or `/srv/www` directory) or as set by your hosting company.
2. Download the Foswiki distribution from https://foswiki.org/Download
   - If you have shell access, you can download the distribution directly using using this command:

         wget  https://sourceforge.net/projects/foswiki/files/latest/download

   - If you do not have shell access to your web server host, see the section Uploading the Foswiki distribution to your web server host below.
3. Unpack the distribution file:
   - go to your web directory (usually /var/www) or in any directory you what to install Foswiki (designed after by /path/to/foswiki/)
   - Untar and gunzip the distribution using this command: (modify to match version number) tar -xzvf foswiki-VERSION.tgz A new subdirectory called Foswiki-VERSION will be created.
   - You can rename this subdirectory to a shorter name. For the rest of this document, this subdirectory is assumed to be at `/path/to/foswiki`.
   - Note: Foswiki does not support directory paths that contain spaces, so ensure that all of its directory paths do not contain any spaces (particularly on Windows).

### Step 2: Confirm file and directory ownership and permissions

Note: Installers on shared hosting sites and Windows can skip to next step.

The general command in Linux distributions to set file ownership to the Apache system user is:

    sudo chown -R {user}:{group} /path/to/foswiki

The appropriate user/group ownership varies, depending upon the operating system and distribution:

RedHat, Fedora, CentOS, Gentoo, Mandriva | `apache:apache`
debian, Ubuntu, Kubuntu | `www-data:www-data`
Suse | `wwwrun:www`
FreeBSD | `www:www`

The default file and directory access permissions as set by the distribution define a reasonable security level that will work for many types of installations, including shared hosting. Nonetheless, you should verify that the web server user has read access to all files and directories beneath the `foswiki` directory, and execute access for all directories. Also verify that the `data` and `pub` directories and all the subdirectories and files beneath them allow write access for the web server user.

If for some reason the file permissions have been modified, the shell script `tools/fix_file_permissions.sh` can be used to repair the installation.

    cd /path/to/foswiki
    sh tools/fix_file_permissions.sh

For more information on the appropriate permissions to ensure security for your Foswiki data, see Foswiki:Support.SecuringYourSite.

### Step 3: Configure location of the Perl executable

If you are running a Linux system with Perl found on the default path or are on a shared hosting site, then you can jump to this step. This step is required on Windows installations.

The easiest way to fix up the bin scripts is to run the `tools/rewriteshebang.pl` script:

    cd /path/to/foswiki/tools
    perl rewriteshebang.pl

or for Windows users:

    cd C:\path\to\foswiki\tools
    perl rewriteshebang.pl

The script will determine the location of the Perl interpreter and will prompt to update both the bin and tools scripts in a single step. The changed files will be reported, and it is safe to rerun the script.

If you get an error about perl command not found, the you need to find where your perl command is installed and include that in your command. For example:

    C:\path\to\perl rewriteshebang.pl

### Step 4: Configure the web server

Foswiki provides several methods to configure Apache depending of your access to root and sudo and your preference to set all in one file or several files.

Method 1 and 2 provide better performance and requires editing only one file. However, they require root or sudo access. Method 3 is for cases where you do not have root access (such as on hosted sites).

In details:

Method 1: Use Foswiki's configuration generator (Needs root access)

- See Foswiki:Support.ApacheConfigGenerator.
- This is the easiest and best way to generate a smooth-running and secure configuration file.
- After installing the config file as per your distribution's guidelines, remember to restart or reload Apache each time you edit the file to apply your changes.

Method 2: Customize the Apache config template file included in distribution (Needs root access)

- A sample config file called `foswiki_httpd_conf.txt` can be found in the root of the foswiki installation.
- This is provided in case you can not access the online configuration generator.
- Instructions are provided in the file for tailoring the configuration to you server.
- Be carefull! The configuration shipped with Foswiki is for Apache 2.2 or earlier. Apache 2.4 has changed the syntax of the configuration file. Ensure that `mod_access_compat` is enabled for backwards compatibility when using Apache 2.4
- As with Method 1, remember to restart or reload Apache each time you edit the file to apply your changes.

Method 3: Customize the `.htaccess` template files included in distribution (Useful on shared hosting sites)

- Sample `.htaccess` files for the Foswiki root and each subdirectory are included in the root of your installation. Each file contains instructions on modifying it for your installation. For more information, see Foswiki:Support.SupplementalDocuments.

location and name of sample .htaccess file | copy sample file to the following location | tailoring required (Detailed instuctions in each file)
--- | --- | ---
`foswiki/root-htaccess.txt` | `foswiki/.htaccess` | Optional: redirect to a default page for empty URL.
`foswiki/bin-htaccess-basic.txt` | `foswiki/bin/.htaccess` | Optional: In most cases this file will "just work" without tailoring.
`foswiki/bin-htaccess-advanced.txt` | `foswiki/bin/.htaccess` | Yes. Use this file for configuring Apache login, LDAP authentication and other advanced configurations. Must find/replace all instances of `{DataDir}`, `{DefaultUrlHost}` and `{ScriptUrlPath}` with valid information. The setting `SetHandler cgi-script` is critical to make sure that scripts in the `bin` directory will be executed by Apache.
`foswiki/pub-htaccess.txt` | `foswiki/pub/.htaccess` | Optional: - Uncomment and set correct URL path on the `ErrorDocument` statement for friendly handling of file-not-found errors.
`foswiki/subdir-htaccess.txt` | `foswiki/<subdir>/.htaccess` Copy to all other subdirectories below `foswiki`, including `data`, `lib`, `locale`, `templates`, `tools`, `working`. All directories except for `bin` and `pub` addressed above. | No

General points to keep in mind with any of the above Apache configuration approaches:

- For security purposes, it's important to check that web access is denied to all Foswiki subdirectories other than `bin` and `pub`. All three of the approaches described above (Foswiki:Support.ApacheConfigGenerator, the sample `foswiki_httpd_conf.txt` file included in the distribution, or `.htaccess` files) should provide for this but it should be confirmed by using web browser to confirm that direct access to the other directories is blocked.
- Also for security purposes, be sure to turn off any kind of PHP, Perl, Python, Server Side Includes, or other software execution mechanisms supported by your web server in the `pub` directory. Again, the three approaches described above all provide for this. However, different script execution mechanisms are disabled in different ways so refer see your web server configuration and documentation for more details.
- The configuration shipped with Foswiki is for Apache 2.2 or earlier. Apache 2.4 has changed the syntax of the configuration file. Ensure that `mod_access_compat` is enabled for backwards compatibility when using Apache 2.4, or use the Foswiki:Support.ApacheConfigGenerator config generator.
- New with Foswiki 2.0 The `configure` script no longer needs any special protection within the Apache configuration.

### Step 5: Bootstrap your configuration

1. Using your web browser, enter the default "view" url for your site. Depending upon your Apache configuration, this might look something like:
   - `http://yoursite.com/foswiki/bin/view`
   - `http://yoursite.com/bin/view`
   - `http://yoursite.com`
     This will Bootstrap your configuration and help Foswiki determine whether or not you are using Short URLs. It also logs you in as a the admin user. Don't close your browser until you've completed the configuration process and registered your first user.
2. Follow the link to configure rendered in the Bootstrap banner. (Do not manually enter the `bin/configure` URL or Foswiki will not correctly detect the URL configuration).
3. Make any required changes, and save the settings.
   - This will create the initial configuration and end the bootstrap process.
   - Configuration items which may require further attention will be highlighted.
   - Save as soon as possible, especially if your site is exposed. Anyone accessing Foswiki before the configuration has been saved will be granted admin rights.

- If the Foswiki installation can be accessed by more than one protocol://domain, ensure the additional alternative URLs are set in `{PermittedRedirectHostUrls}`. Example: if `{DefaultUrlHost}` is set to `https://wiki.company.com`, an example `{PermittedRedirectHostUrls}` might contain:

      https://company.com, http://111.222.123.234

- If your server requires a Proxy in order to access external resources like your mail server, this is configured on the "Security and Authentication" tab, "Proxies" sub-tab. Complete that before proceeding with the E-mail configuration.
- If you do not want to or are unable to configure from the web interface, there is an alternate command line configuration documented in System.InstallationGuide#ConfiguringFoswikiManually in your installation.

Now that your Foswiki installation is functional, you are encouraged to view this installation guide on your Foswiki site rather than the static `INSTALL.html` file included in the distribution. This will make it easier to implement the steps which follow because you will be able to use the embedded hyperlinks to jump directly to the referenced pages in your installation. To view this guide in your installation, follow the link provided in the bootstrap banner, or enter `System.InstallationGuide` in the jump-box.

### Step 6: Configure email

Outgoing e-mail is required for Foswiki to send registration confirmations, notifications of changes, password reset requests, etc.

1. Select the `Mail` tab in left bar of confgiure and fill out the following parameters:
   - The `{WebMasterEmail}` should be set to a valid e-mail address. This will be the From: ID used to send Foswiki Emails and will also appear on webmaster mailto: links.
     If you are running on a *nix server with a configured local mail transport agent, you can try pressing the "auto-configure email" button. If auto-configure succeeds, proceed to the next step, to send a test email. If your server is a Windows server, if auto-configure failed, or you know a local transport agent is not available, continue with the SMTP e-mail configuration:
   - The `{SMTP}{MAILHOST}` should be set to your e-mail server hostame: ex: `smtp.gmail.com`
   - On most systems, you will also have to configure `{SMTP}{Username}` and `{SMTP}{Password}`. These are used so that Foswiki can sign into the e-mail server for purposes of sending e-mail.
   - Click the "auto-configure email" button. (This can run a long time as Foswiki probes all possible e-mail configurations) This will probe the mail server to discover it's configuration, and will finish the configuration. If all goes well, the settings will have been fine tuned for your e-mail server and e-mail is automatically enabled.
2. Once auto-configure completes, Click the "Send test email" button. located on the `{WebMasterEmail}` field This will verify if the configuration is correct and able to send mail. If e-mail is enabled, but not functional, you will be unable to register users.
3. Click the Save button in the upper right corner of the configuration page.

If auto-configure fails to complete, you can use the "Advanced settings" tab to manually configure the e-mail server. You will also need to configure the basic information tab. Although outgoing email is necessary for user registration, it is not required for Foswiki to run otherwise, so if you are setting up a test installation or don't plan on enabling user registration, you can skip this step.

### Step 7: Check Authentication and Register Yourself

Authentication of users means their activity can be tracked, and access to your site can be controlled. This is particularly important for sites that are publicly accessible on the web. Foswiki is pre-configured with a flexible and user-friendly authentication set-up that fits most common use-cases. To learn more about this set-up and available alternatives, see User Authentication Options. You can also revisit this later and switch to an alternative authentication set-up.

Test if authentication is working by going to System.UserRegistration in your installation and registering yourself.

If there are problems, see authentication trouble-shooting tips.

After completing initial installation, you are strongly encouraged to read System.UserAuthentication in your installation and Foswiki:Support.UserAuthenticationSupplement for further information about managing users and access controls for your Foswiki site.

### Step 8: Establish an Administrator user

The last step in your configuration is to create and user with administration rights.

The steps outlined below are recommended for initial configuration. You should complete this before closing the browser after the bootstrap process. Once you close the browser you will lose your temporary admin status. Later on, you can review the further notes below regarding about administrators and options to protect configure and consider one of the more restrictive options.
Once the Foswiki bootstrap process is completed and you've logged out, configure will be restricted to Foswiki's "AdminGroup". Therefor you must add the user you just registered to the administrators group.

If you have not yet registered your first user, return to InstallationGuide#FirstUser and follow the steps to register a user. Once that is completed, return to

1. Go to Main.AdminGroup in your installation.
2. Scroll down to the "Administration" section and click on "Add Members" link.
   - If you do not see the Admistration section, then you don't have authorization to change this group. See #InternalAdmin for instructions on establishing an internal admin user.
3. Enter your "WikiName" as defined when you registered yourself in Step 7.
4. Click the Add Member button
5. Return to the AdminGroup by clicking the group name on the confirmation page and look under "Members" to confirm you have been added.

Foswiki provides multiple ways to protect configure. See #AboutAdminUsers for more details on how to protect your configuration.

### Step 9. Save your configuration!

Click the Save button in the upper right corner of the configuration page.

Refer back to any page in your installation (such as the "AdminGroup" page you were at in the previous step). The login section at the top of the left-hand menu should show that you are still be logged in as a temporary Admin user. Click on the "Log Out" link to exit that user.

### Congratulations! Your Foswiki Installation is Ready to Use!

You now have set up your Foswiki installation! At this point you can start creating and editing pages. See InstallationGuidePart2 to proceed with further tailoring your site.

In order to keep your user, group, and site configuration information separate from the actual content of your site, it is recommended that you create a new web in which your site's pages will reside. See System.ManagingWebs in your installation for more information on Wiki webs and how to create one.

## Troubleshooting

If you are having problems with your installation, try the following:

- Review the System.PerlDependencyReport in your installation and sure all dependencies are correctly resolved.
- Run the `configure` script and ensure you have resolved all errors and are satisfied that you understand any warnings.
  - You can also access the dependency report from the command line:

        cd /path/to/foswiki
        perl tools/dependencies

- Consult the topics at Foswiki:Support.SupplementalDocuments and Foswiki:Support.AskedQuestions.
- Ask for help on IRC (irc.freenode.net, channel #foswiki). There are often a number of people waiting to help.
- Ask a question in the Foswiki:Support web

## Supplemental Information For Installation

### System Requirements

## Server Requirements

Foswiki is written in Perl 5, which is supported on Microsoft Windows as well as Unix and Unix-like systems (including Linux and OSX). On Unix-like systems, it uses a number of shell commands. It should be able to run out-of-the-box on any server platform that meets the following requirements.

Resource | Required Server Environment
--- | ---
Perl | 5.8.8 or higher. A minimum of perl 5.12 is recommended.
External programs | GNU `diff` 2.7 or higher, `fgrep`, and `egrep` (not required on Windows)
Web server | Apache, Nginx and Lighttpd are all well supported; Apache sample configs are provided. For information on other servers, see Foswiki:Support.InstallingOnSpecificPlatforms.

Foswiki is designed to automatically detect the platform and generate a basic configuration the first time the `configure` script is run, but start from your expected default "view" URL, so that Foswiki can figure out your URL scheme.

Prior versions of Foswiki shipped with the important CPAN modules. Foswiki 2.0 does not, and you must ensure that the perl dependencies listed below are installed before attempting to use Foswiki. For a detailed report, System.PerlDependencyReport in your installation (admin access only!) or the shell script `tools/dependencies`.

If you are unable to install CPAN modules, see Foswiki:Extensions.CpanContrib. Install this extension into your Foswiki installation directory if you cannot install Perl modules otherwise.

You can check the dependencies before Foswiki is fully operational with the following command. It will list all potentially missing dependencies. Not all listed dependences are required on all installations, Refer to the usage message that accompanies each missing dependency in the report.

    cd /path/to/foswiki
    perl tools/dependencies

## Specific distribution details

Find the closest match to your installed system. and click on the "Show ..." link to reveal the details.

### Ubuntu and other Debian derived distributions

Show Debian / Ubuntu informationHide Debian details

#### Minimum requirements

Install apache and rcs: `apt-get install apache2 rcs`

Perl Module | Package to install | Notes
--- | --- | ---
Algorithm::Diff | `libalgorithm-diff-perl` |
Archive::Tar | `libarchive-tar-perl` |
Authen::SASL | `libauthen-sasl-perl` |
CGI | `libcgi-pm-perl` |
CGI::Session | `libcgi-session-perl` |
Crypt::PasswdMD5 | `libcrypt-passwdmd5-perl` |
Digest::SHA | `libdigest-sha-perl` | *First shipped in perl 5.9.3
Email::Address::XS | `libemail-address-xs-perl` |
Email::MIME | `libemail-mime-perl` |
Encode | `libencode-perl` |
Error | `liberror-perl` |
File::Copy::Recursive | `libfile-copy-recursive-perl` |
HTML::Parser | `libhtml-parser-perl` |
HTML::Tree | `libhtml-tree-perl` |
IO::Socket::IP | `libio-socket-ip-perl` | First shipped perl 5.19.8
IO::Socket::SSL | `libio-socket-ssl-perl` |
JSON | `libjson-perl` |
Locale::Codes | `liblocale-codes-perl` |
Locale::Maketext | `liblocale-maketext-perl` |
Locale::Maketext::Lexicon | `liblocale-maketext-lexicon-perl` | Optional, needed for internationalization
Locale::Msgfmt | `liblocale-msgfmt-perl` | Optional, needed for internationalization
LWP | `libwww-perl` |
LWP::Protocol::https | `liblwp-protocol-https-perl` |
URI | `liburi-perl` |
version | `libversion-perl` | Must be version 0.77 or newer, included with perl 5.10.1 and newer.

Note: to install all the above:

> `apt-get install` `libalgorithm-diff-perl` `libarchive-tar-perl` `libauthen-sasl-perl` `libcgi-pm-perl` `libcgi-session-perl` `libcrypt-passwdmd5-perl` `libdigest-sha-perl` `libemail-address-xs-perl` `libemail-mime-perl` `libencode-perl` `liberror-perl` `libfile-copy-recursive-perl` `libhtml-parser-perl` `libhtml-tree-perl` `libio-socket-ip-perl` `libio-socket-ssl-perl` `libjson-perl` `liblocale-codes-perl` `liblocale-maketext-perl` `liblocale-maketext-lexicon-perl` `liblocale-msgfmt-perl` `libwww-perl` `liblwp-protocol-https-perl` `liburi-perl` `libversion-perl`

#### Optional dependencies

Install as needed.

Perl Module | Package to install | Notes
--- | --- | ---
mod_perl2 | `libapache2-mod-perl2` | Required if using Apache 2 and mod_perl
Apache2::Request | `libapache2-request-perl` | Required if using Apache 2 and mod_perl
DBI | `libdbi-perl` | Used for the Foswiki Page cache
DBD::mysql | `libdbd-mysql-perl` | Used for MySQL based Page Cache
DBD::Pg | `libdbd-pg-perl` | Used for PostgreSQL based Page Cache
DBD::SQLite | `libdbd-sqlite3-perl` | Used for SQLite based Page Cache
FCGI | `libfcgi-perl` | Optional, needed for fastcgi / fcgi apache modules
FCGI::ProcManager | `libfcgi-procmanager-perl` | Optional, needed for fastcgi / fcgi process management on nginx
Crypt::SMIME | `libcrypt-smime-perl` | Optional, used for S/MIME email signing
Crypt::X509 | `libcrypt-x509-perl` | Optional, used for S/MIME email signing
Convert::PEM | `libconvert-pem-perl` | Optional, used for S/MIME email signing

After expanding the Foswiki archive, change the ownership of the files:

- Debian, Ubuntu, Kubunto: `chown -R www-data:www-data /path/to/foswiki`

Apache user should issue the following commands:

`a2enmod rewrite`
  Enables mod_rewrite
`a2enmod cgi` OR `a2enmod cgid`
  Enables CGI. May need cgid if using a threaded mpm.
`a2enmod access_compat`
  Apache 2.4: Enables compatibility with foswiki example apache configurations.

### RedHat, SuSE, CentOS and other RPM based distributions

Show RedHat, SuSE and other RPM detailsHide RPM details

#### Minimum requirements

Install apache2, rcs, and perl-CPAN

Perl Module | Package to install | Notes
--- | --- | ---
Algorithm::Diff | `perl-Algorithm-Diff` |
Archive::Tar | `perl-Archive-Tar` | *First shipped in perl 5.9.3
Authen::SASL | `perl-Authen-SASL` |
CGI | `perl-CGI` |
CGI::Session | `perl-CGI-Session` |
Crypt::PasswdMD5 | `perl-Crypt-PasswdMD5` |
Digest::SHA | `perl-Digest-SHA` | *First shipped in perl 5.9.3
Email::Address::XS | `perl-Email-Address-XS` |
Email::MIME | `perl-Email-MIME` |
Encode | `perl-Encode` |
Error | `perl-Error` |
File::Copy::Recursive | `perl-File-Copy-Recursive` |
HTML::Parser | `perl-HTML-Parser` |
HTML::Tree | `perl-HTML-Tree` |
IO::Socket::IP | `perl-IO-Socket-IP` | First shipped perl 5.19.8
IO::Socket::SSL | `perl-IO-Socket-SSL` |
JSON | `perl-JSON` |
Locale::Language | `perl-Locale-Codes` |
Locale::Maketext | `perl-Locale-Maketext` |
Locale::Maketext::Lexicon | `perl-Locale-Maketext-Lexicon` | Optional, needed for internationalization **
Locale::Msgfmt | `perl-Locale-Msgfmt` | Optional, needed for internationalization **
LWP | `perl-libwww-perl` |
LWP::Protocol::https | `perl-LWP-Protocol-https` |
URI | `perl-URI` |
version | `perl-version` | Must be version 0.77 or newer, included with perl 5.10.1 and newer.

##### To install the above packages on CentOS

Note, `Locale::Maketext::Lexicon` and `Locale::Msgfmt` are not available on Centos. Install using CPAN if Internationalization is required.

First add the appropriate perl module repository, and then install the packages.

> `yum install -y epel-release`
> `yum install` `perl-Algorithm-Diff` `perl-Archive-Tar` `perl-Authen-SASL` `perl-CGI` `perl-CGI-Session` `perl-Crypt-PasswdMD5` `perl-Digest-SHA` `perl-Email-Address-XS` `perl-Email-MIME` `perl-Encode` `perl-Error` `perl-File-Copy-Recursive` `perl-HTML-Parser` `perl-HTML-Tree` `perl-IO-Socket-IP` `perl-IO-Socket-SSL` `perl-JSON` `perl-Locale-Codes` `perl-Locale-Maketext` `perl-Locale-Maketext-Lexicon` `perl-Locale-Msgfmt` `perl-libwww-perl` `perl-LWP-Protocol-https` `perl-URI` `perl-version`

##### To install the above packages on SuSE

First add the appropriate SuSE perl-modules repository, and then install the packages. Note: Not all listed packages will install on SuSE, but all dependences are resolved.

> `zypper ar -f -n perl-modules http://download.opensuse.org/repositories/devel:/languages:/perl/openSUSE_13.1 perl-modules`
> `zypper install` `perl-Algorithm-Diff` `perl-Archive-Tar` `perl-Authen-SASL` `perl-CGI` `perl-CGI-Session` `perl-Crypt-PasswdMD5` `perl-Digest-SHA` `perl-Email-Address-XS` `perl-Email-MIME` `perl-Encode` `perl-Error` `perl-File-Copy-Recursive` `perl-HTML-Parser` `perl-HTML-Tree` `perl-IO-Socket-IP` `perl-IO-Socket-SSL` `perl-JSON` `perl-Locale-Codes` `perl-Locale-Maketext` `perl-Locale-Maketext-Lexicon` `perl-Locale-Msgfmt` `perl-libwww-perl` `perl-LWP-Protocol-https` `perl-URI` `perl-version`

#### Optional dependencies

Install as needed.

Perl Module | Package to install | Notes
--- | --- | ---
mod_perl2 | `mod_perl` | Required if using Apache2 and mod_perl
Apache2::Request | `perl-libapreq2` | Required if using Apache 2 and mod_perl
DBI | `perl-DBI` | Used for the Foswiki Page cache
DBD::mysql | `perl-DBD-mysql` | Used for MySQL based Page Cache
DBD::Pg | `perl-DBD-Pg` | Used for PostgreSQL based Page Cache
DBD::SQLite | `perl-DBD-SQLite` | Used for SQLite based Page Cache
FCGI | `perl-FCGI` | Optional, needed for fastcgi / fcgi apache modules
FCGI::ProcManager | `perl-FCGI-ProcManager` | Optional, needed for fastcgi / fcgi process management on nginx
Crypt::SMIME | `perl-Crypt-SMIME` | Optional, used for S/MIME email signing (Not available in default repositories)
Crypt::X509 | `perl-Crypt-X509` | Optional, used for S/MIME email signing
Convert::PEM | `perl-Convert-PEM` | Optional, used for S/MIME email signing

After expanding the Foswiki archive, change the ownership of the files:

- RedHat, Fedora, CentOS Mandriva: chown -R apache:apache /path/to/foswiki=
- Suse: `chown -R wwwrun:www /path/to/foswiki`

### Gentoo (ebuild) based distributions

Show Gentoo detailsHide Gentoo details

#### Minimum requirements

Install `www-servers/apache`, `dev-vcs/rcs`, and `dev-lang/perl`

Perl Module | Package to install | Notes
--- | --- | ---
Algorithm::Diff | `dev-perl/Algorithm-Diff` |
Archive::Tar | `perl-Archive-Tar` | *First shipped in perl 5.9.3
Authen::SASL | `dev-perl/Authen-SASL` | Optional, needed for authenticated SMTP
CGI | `dev-perl/CGI` |
CGI::Session | `dev-perl/CGI-Session` |
Crypt::PasswdMD5 | `dev-perl/Crypt-PasswdMD5` |
Digest::SHA |  | Included with perl
Email::Address::XS | `dev-perl/Email-Address-XS` |
Email::MIME | `dev-perl/Email-MIME` |
Error | `dev-perl/Error` |
Encode |  | Included with perl
File::Copy::Recursive | `dev-perl/File-Copy-Recursive` |
HTML::Parser | `dev-perl/HTML-Parser` |
HTML::Tree | `dev-perl/HTML-Tree` |
IO::Socket::IP |  | Ebuild not avaiable. Install with g-cpan if IPv6 is needed.
IO::Socket::SSL | `dev-perl/IO-Socket-SSL` | Optional, support encrypted email connection: STARTTLS or SSL
JSON | `dev-perl/JSON` |
Locale::Maketext |  | Included with perl
Locale::Maketext::Lexicon | `dev-perl/Locale-Maketext-Lexicon` | Optional, needed for internationalization
Locale::Msgfmt | `dev-perl/Locale-Msgfmt` | Optional, needed for internationalization
LWP | `dev-perl/libwww-perl` |
LWP::Protocol::https | `dev-perl/LWP-Protocol-https` |
URI | `dev-perl/URI` |
version |  | Must be version 0.77 or newer, included with perl 5.10.1 and newer.

##### To install the above packages on Gentoo

> `emerge` `dev-perl/Algorithm-Diff` `perl-Archive-Tar` `dev-perl/Authen-SASL` `dev-perl/CGI` `dev-perl/CGI-Session` `dev-perl/Crypt-PasswdMD5` `dev-perl/Email-Address-XS` `dev-perl/Email-MIME` `dev-perl/Error` `dev-perl/File-Copy-Recursive` `dev-perl/HTML-Parser` `dev-perl/HTML-Tree` `dev-perl/IO-Socket-SSL` `dev-perl/JSON` `dev-perl/Locale-Maketext-Lexicon` `dev-perl/Locale-Msgfmt` `dev-perl/libwww-perl` `dev-perl/LWP-Protocol-https` `dev-perl/URI`

#### Optional dependencies

Install as needed.

Perl Module | Package to install | Notes
--- | --- | ---
mod_perl2 | `www-apache/mod_perl` | Required if using Apache 2 and mod_perl
Apache2::Request | `libapache2-request-perl` | Required if using Apache 2 and mod_perl
DBI | `dev-perl/DBI` | Optional - Used for the Foswiki Page cache
DBD::mysql | `dev-perl/DBD-mysql` | Optional - Used for MySQL based Page Cache
DBD::Pg | `dev-perl/DBD-Pg` | Optional - Used for PostgreSQL based Page Cache
DBD::SQLite | `dev-perl/DBD-SQLite` | Optional - Used for SQLite based Page Cache
FCGI | `dev-perl/FCGI` | Optional, needed for fastcgi / fcgi apache modules
FCGI::ProcManager | `dev-perl/FCGI-ProcManager` | Optional, needed for fastcgi / fcgi process management on nginx
Crypt::SMIME | `dev-perl/Crypt-SMIME` | Optional, used for S/MIME email signing
Crypt::X509 | `dev-perl/Crypt-X509` | Optional, used for S/MIME email signing
Convert::PEM | `dev-perl/convert-pem` | Optional, used for S/MIME email signing

After expanding the Foswiki archive, change the ownership of the files:

- `chown -R apache:apache /var/www/path-to-foswiki`

### FreeBSD (pkg) based distributions

Show FreeBSD detailsHide FreeBSD details

#### Minimum requirements

Install `apache24`, `rcs`, and `perl5`

Perl Module | Package to install | Notes
--- | --- | ---
Algorithm::Diff | `p5-Algorithm-Diff` |
Archive::Tar | `p5-Archive-Tar` |
Authen::SASL | `p5-Authen-SASL` |
CGI | `p5-CGI` |
CGI::Session | `p5-CGI-Session` |
Crypt::PasswdMD5 | `p5-Crypt-PasswdMD5` |
Digest::SHA | `p5-Digest-SHA` | *First shipped in perl 5.9.3
Email::Address::XS | `p5-Email-Address-XS` |
Email::MIME | `p5-Email-MIME` |
Encode | `p5-Encode` |
Error | `p5-Error` |
File::Copy::Recursive | `p5-File-Copy-Recursive` |
HTML::Parser | `p5-HTML-Parser` |
HTML::Tree | `p5-HTML-Tree` |
IO::Socket::IP | `p5-IO-Socket-IP` | First shipped perl 5.19.8
IO::Socket::SSL | `p5-IO-Socket-SSL` |
JSON | `p5-JSON` |
Locale::Maketext | `p5-Locale-Maketext` |
Locale::Maketext::Lexicon | `p5-Locale-Maketext-Lexicon` | Optional, needed for internationalization
Locale::Msgfmt | `p5-Locale-Msgfmt` | Optional, needed for internationalization
LWP | `p5-libwww` |
LWP::Protocol::https | `p5-LWP-Protocol-https` |
URI | `p5-URI` |
version | `p5-version` | Must be version 0.77 or newer, included with perl 5.10.1 and newer.

##### To install the above packages on FreeBSD

> `pkg install` `p5-Algorithm-Diff` `p5-Archive-Tar` `p5-Authen-SASL` `p5-CGI` `p5-CGI-Session` `p5-Crypt-PasswdMD5` `p5-Digest-SHA` `p5-Email-Address-XS` `p5-Email-MIME` `p5-Encode` `p5-Error` `p5-File-Copy-Recursive` `p5-HTML-Parser` `p5-HTML-Tree` `p5-IO-Socket-IP` `p5-IO-Socket-SSL` `p5-JSON` `p5-Locale-Maketext` `p5-Locale-Maketext-Lexicon` `p5-Locale-Msgfmt` `p5-libwww` `p5-LWP-Protocol-https` `p5-URI` `p5-version`

After expanding the Foswiki archive, change the ownership of the files:

- `chown -R www:wwwadmin /var/www/path-to-foswiki`

#### Optional dependencies

Install as needed.

Perl Module | Package to install | Notes
--- | --- | ---
mod_perl2 | `ap24-mod_perl2` | Required if using Apache 2 and mod_perl
Apache2::Request | `libapreq2` | Required if using Apache 2 and mod_perl
BSD-Resource | `p5-BSD-Resource` | Optional - used for FCGI process handler resource limits
DBI | `p5-DBI` | Optional - Used for the Foswiki Page cache
DBD::mysql | `p5-DBD-mysql` | Optional - Used for MySQL based Page Cache
DBD::Pg | `p5-DBD-Pg` | Optional - Used for PostgreSQL based Page Cache
DBD::SQLite | `p5-DBD-SQLite` | Optional - Used for SQLite based Page Cache
FCGI | `p5-FCGI` | Optional, needed for fastcgi / fcgi apache modules
FCGI::ProcManager | `p5-FCGI-ProcManager` | Optional, needed for fastcgi / fcgi process management on nginx
Crypt::SMIME | `p5-Crypt-SMIME` | Optional, used for S/MIME email signing
Crypt::X509 | `p5-Crypt-X509` | Optional, used for S/MIME email signing
Convert::PEM | `p5-Convert-PEM` | Optional, used for S/MIME email signing

### Installation with CPAN

Show `CPAN` detailsHide `CPAN` details

Perl dependencies can also be installed on most systems using `cpanm`, aka `App::cpanminus`. On most unix* systems, `cpanminus` can bootstrap itself using curl or wget. If run as root, the modules will be installed in the System perl. Otherwise they are installed into the users local environment.

Perl Module | Notes
--- | ---
Algorithm::Diff |
Archive::Tar | *First shipped in perl 5.9.3
Authen::SASL | Optional, needed for authenticated SMTP
CGI |
CGI::Session |
Crypt::PasswdMD5 |
Digest::SHA | Included with perl
Error |
Email::Address::XS |
Email::MIME |
Encode |
File::Copy::Recursive |
HTML::Parser |
HTML::Tree |
IO::Socket::IP |
IO::Socket::SSL | Optional, support encrypted email connection: STARTTLS or SSL
JSON |
Locale::Maketext |
Locale::Maketext::Lexicon | Optional, needed for internationalization
Locale::Msgfmt | Optional, needed for internationalization
LWP |
LWP::Protocol::https |
URI |
version | Must be version 0.77 or newer, included with perl 5.10.1 and newer.

##### To install the above packages with `cpanm`

Note: We do not recommend installing CPAN modules with cpanminus as root. See below for information on using a private module library with cpanminus.

> curl -L http://cpanmin.us | perl - App::cpanminus (optional - install cpanminus if not available )
> cpanm Algorithm::Diff Archive::Tar Authen::SASL CGI CGI::Session Crypt::PasswdMD5 Digest::SHA Error Email::Address::XS Email::MIME Encode File::Copy::Recursive HTML::Parser HTML::Tree IO::Socket::IP IO::Socket::SSL JSON Locale::Maketext Locale::Maketext::Lexicon Locale::Msgfmt LWP LWP::Protocol::https URI version

#### Optional dependencies

Install as needed.

Perl Module | Package to install | Notes
--- | --- | ---
Apache2::Request | Required if using Apache 2 and mod_perl
DBI |  | Optional - Used for the Foswiki Page cache
DBD::mysql |  | Optional - Used for MySQL based Page Cache
DBD::Pg |  | Optional - Used for PostgreSQL based Page Cache
DBD::SQLite |  | Optional - Used for SQLite based Page Cache
FCGI |  | Optional, needed for fastcgi / fcgi apache modules
FCGI::ProcManager |  | Optional, needed for fastcgi / fcgi process management on nginx
Crypt::SMIME |  | Optional, used for S/MIME email signing
Crypt::X509 |  | Optional, used for S/MIME email signing
Convert::PEM |  | Optional, used for S/MIME email signing
Locale::Language | Optional, `Locale::Language` will be removed from the Perl core distribution in 5.28.

#### Installation using `cpanminus`

See Foswiki:Support.HowToInstallCpanModules for more information.

If you want to install the dependendencies into a specified location, add the `"-l"` option to cpanm, and add the lib path to `bin/LocalLib.cfg`. The dependencies will be installed under the specified location, in the `lib/perl5` subdirectory. Example: User "foswiki" logs in and installs the libraries locally under the foswikideps directory:

    cpanm -l foswikideps Algorithm::Diff Archive::Tar ...   (install libraries into =/home/foswiki/foswikideps=)

`/path/to/foswiki/bin/LocalLib.txt` is then edited, and the commented line is modified:

    # @localPerlLibPath = ( '/path/to/dir', '/path/to/another/dir', );
    @localPerlLibPath = ( '/home/foswiki/foswikideps/lib/perl5', );

Foswiki will now run using the libraries installed by cpanm.

## Client Requirements

The standard installation has relatively low browser requirements:

- XHTML 1.0 Transitional compliant
- Cookies, if persistent sessions are required
- Javascript, is required for configure, edit save and upload functionality. Foswiki is viewable without javascript.

CSS and Javascript are used in most skins. Some skins will require more recent releases of browsers. The default (Pattern) skin is tested on IE 6+, Safari, Chrome and Firefox.

You can easily select a balance of browser capability versus look and feel. Try the installed skins at System.SkinBrowser and more at Foswiki:Extensions.SkinPackage.

### Uploading the Foswiki distribution to your web server host

If you cannot unpack the Foswiki distribution directly in your installation directory, you can unpack the distribution on your local computer, 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 Foswiki files by FTP (transfer as text except for the image files in `pub` directory.)
- Note: Don't worry if you are not able to put the `lib` directory at the same level as the `bin` directory. You can create this directory elsewhere and configure the `bin/setlib.cfg` file.

  Foswiki dir: | What it is: | Where to copy: | Example:
  --- | --- | --- | ---
  `foswiki` | start-up pages | root Foswiki dir | `/home/smith/public_html/foswiki/`
  `foswiki/bin` | CGI bin | CGI-enabled dir | `/home/smith/public_html/foswiki/bin`
  `foswiki/lib` | library files | same level as `bin` | `/home/smith/public_html/foswiki/lib`
  `foswiki/locale` | language files | dir secure from public access | `/home/smith/public_html/foswiki/locale`
  `foswiki/pub` | public files | htdoc enabled dir | `/home/smith/public_html/foswiki/pub`
  `foswiki/data` | topic data | dir secure from public access | `/home/smith/public_html/foswiki/data`
  `foswiki/templates` | web templates | dir secure from public access | `/home/smith/public_html/foswiki/templates`
  `foswiki/tools` | Foswiki utlilities | dir secure from public access | `/home/smith/public_html/foswiki/tools`
  `foswiki/working` | Temporary and internal files | dir secure from public access | `/home/smith/public_html/foswiki/working`

### About Administrators

Administrators have read and write access to any topic, regardless of any access controls that have been applied to the topic or its web. Administrators also have access to configure unless further restricted.

The default setup in Foswiki is that members of Main.AdminGroup in your installation have administrator privileges. Any member of the Main.AdminGroup can add subsequent members to that group.

To more easily debug access control issues, you may want to have a regular Foswiki user account for daily use, and a special one that belongs to the `AdminGroup` that you use only for administering your Foswiki site. See System.AccessControls in your installation for more information on access controls and user groups.

Instead of adding users to the AdminGroup, grant those candidate administrators `ALLOWTOPICCHANGE` rights on the AdminGroup. They can then use a button on the AdminGroup page to join or leave the group at will.

#### Options to Protect the Configure Script

Foswiki 2.0 has changed how configure is protected. You no longer need to establish special protections within the web server configuration.

There are now several choices for how to protect configure:

- Option 1 Restrict configure to members of the AdminGroup:
  - This is the default configuration. You don't need to set anything special from within configure.
  - After you save your configuration, be sure to register a user and add them to the AdminGroup before you log out from the initial super admin login. Once you log out, you'll be blocked from any further configure access unless you can log in as a user in the AdminGroup. The default behaviour is that members of the AdminGroup have access to `bin/configure`

- Option 2 Restrict configure to a defined list of users:
  - Visit the "Security and Authentication" tab, "Access control" sub-tab.
  - Set `{FeatureAccess}{Configure}` to a list of WikiNames that will be allowed access to configure.
  - This setting overrides use of the AdminGroup, and these users do not have to be members of the AdminGroup.
  - If you want the admin super-user to also have access to configure, you need to include "BaseUserMapping_333" in that list.

- Option 3 Define a "super user" ID and allow it access to configure (This is not recommended)
  - Visit the "Security and Authentication" tab, "Passwords" tab. Enable "Expert" options. Set the `{Password}` field to a hashed `ApacheMD5` encoded password.
  - See #InternalAdmin for more information.

You must at least do one of the above before closing your browser or logging out from the temporary admin authority established during bootstrap. Once you close your browser, you have to have a usable id to run configure or you'll need to add a super-user admin login using the command line.

#### Establishing an internal admin login (optional)

Don't log in with the wikiname AdminUser, and never register or set a password for AdminUser.

There is an optional internal admin (Main.AdminUser in your installation) which is accessed by logging in with user `admin` and a password set in the configuration. Foswiki 2.0 no longer enables the internal admin by default.

- Setting password from `bin/configure` interface: The password can be set in configure, in the "Security and Authentication" -> "Passwords" tab. Enter the password in plain text. It will be automatically hashed when saved, and cannot be recovered.
- Setting the password from the command line: The password can also be set via command line configuration tool, using the following command:

      tools/configure -save -set {Password}='adminpass'

- Manually setting admin user in `LocalSite.cfg`: Follow these steps: ( Caution: This procedure only works for plain ascii passwords, it does not handle international characters.)
  1. Generate the hashed password using the Apache `htpasswd` tool: (replacing `{password}` with your password)

         htpasswd -bn  admin {password}

  2. Copy the password hash that's generated. (The part after `admin:` ex: `$apr1$Oc.PLq8V$wslABA3mWXfYT/wH0Hsom0`)
  3. Search `LocalSite.cfg` for `$Foswiki::cfg{Password}`, Replace the existing line, or if not found, insert a new line in the file, as shown:

         $Foswiki::cfg{Password} = '{password hash}';

### User Authentication Options

The most common authentication methods used for public Foswiki installations are Template Login and Apache Login. They have the following relative advantages:

- Template Login can be set up without any web server configuration, and users can log off without restarting the browser. As the login page is just a Wiki page, you can customize it to suit your needs.
- Apache Login allows you to use any Apache-module based authentication scheme, such as `mod_auth_ldap` or `mod_auth_mysql`. However, as your browser is caching your login, you must restart the browser to log out.

Note that the password databases for both of these authentication mechanisms are compatible, so you can switch between them at a later date.

#### Template Login authentication

Template Login asks for a username (or optionally e-mail address) and password in a web page, and processes them using whatever Password Manager you choose. Users can log in and log out. Client Sessions are used to remember users. Users can choose to have their session remembered so they will automatically be logged in the next time they start their browser.

#### Enabling Template Login

By default, your Foswiki installation is probably already using TemplateLogin, HtPasswdUser and TopicUserMappingContrib as the default `Login`, `Password` and `user mapping` options.

1. Using `configure`, `Security And Authentication` tab
   1. Navigate to the `Login` tab on the `Security and Authentication` panel. Select the `Foswiki::LoginManager::TemplateLogin` login manager.
   2. Navigate to the `Passwords` tab. Select the appropriate `PasswordManager` for your system - the default is `Foswiki::Users::HtPasswdUser`.
      There is an EXPERT configure setting `{TemplateLogin}{PreventBrowserRememberingPassword}` that you can set to prevent Browsers from remembering username and passwords if you are concerned about public terminal usage.
      There is an EXPERT configure setting `{TemplateLogin}{AllowLoginUsingEmailAddress}` that you can set to allow users to login using their password system registered e-mail addresses.

#### Apache Login authentication

With Apache Login enabled, when Foswiki needs to authenticate the user, the standard HTTP authentication mechanism is used: the browser itself will prompt for a user name and password.

The rest of this section describes Webserver Login using the Apache web server, but the same process is applicable to other webserver implementations as well (though you may require a customised version of the ApacheLogin module to do it).

The advantage of this scheme is that if you have an existing website authentication scheme using Apache modules such as `mod_auth_ldap` or `mod_auth_mysql` you can just plug in to them directly.

The disadvantage is that because the user identity is cached in the browser, you can log in, but you can't log out again unless you restart the browser.

Foswiki maps the `REMOTE_USER` that was used to log in to the webserver to a WikiName using the table in Main.WikiUsers. This table is updated whenever a user registers, so users can choose not to register (in which case their webserver username is used for their signature) or register (in which case that username is mapped to their WikiName).

The same private `.htpasswd` file used in Foswiki Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support.

Do not use the Apache `htpasswd` program to modify `.htpasswd` files generated by Foswiki! `htpasswd` wipes out e-mail addresses that Foswiki saves in the info fields of this file.

Apache Login is required for Apache-based login methods such as `mod_ldap`

You can use any Apache authentication module that sets the `REMOTE_USER` environment variable.

To set up Apache Login, perform the following steps:

1. Configure Apache Login. Under the `Security and Authentication` pane on the `Login` tab in `configure`:
   1. Select `Foswiki::LoginManager::ApacheLogin` for `{LoginManager}`.
   2. Select `Foswiki::Users::HtPasswdUser` for `{PasswordManager}`.
   3. Select `Foswiki::Users::TopicUserMapping` for `{UserMappingManager}`.
   4. Save your settings.
   5. Configure your Apache settings for HTTP authentication. Use the Foswiki:Support.ApacheConfigGenerator tool or the `foswiki/bin-htaccess-advanced.txt` file to set the following Apache directives on the `bin` scripts:(This example is for Apache 2.2, there are changes required if using Apache 2.4)

           AuthType Basic
           <FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|.*auth).*">
           require valid-user
           </FilesMatch>

      You can also refer to the sample `foswiki_httpd_conf.txt` and `bin-htaccess-advanced.txt` files to see how the appropriate Apache directives are specified.

#### Testing your authentication configuration:

1. Verify that registration works by registering yourself with the System.UserRegistration topic. If there are problems, try these troubleshooting tips:
   1. Note: If e-mail is enabled in configure, Foswiki will not allow any new registrations unless e-mail is functional. In order to avoid issues, return to the `Mail and Proxies`, `Email Test` tab in `configure` and verify that Foswiki can successfully send e-mail.
   2. If your PasswordManager is `HtPasswdUser` (the default), check the `.htpasswd` file is being updated correctly with a new entry. If not, check `{Htpasswd}{FileName}` is correct (under `Security and Authentication` on the `Password` tab in `configure`), and that the webserver user has write permission.
2. Create a new topic (in Sandbox.WebHome web for example) to confirm that authentication works.
3. Add users to the Main.AdminGroup. Edit the Main.AdminGroup topic in the Main web to include users that should have administrator status. Read defining adminstrator user(s) for more information.
   This is a very important step, as users in this group can access all topics, independent of Foswiki access controls.

### Configuring Foswiki manually (without using the `configure` page)

Foswiki 2.0 includes a shell based configuration tool that can be run from a server command-line login. It will bootstrap the configuration, and prompt for settings as required. Here is an example of using it for an interactive command line bootstrap:
Note: If any of your configuration settings use utf-8 characters, (eg. Ünicöde) be sure to run configure with the perl `-CAS` option so that all prompted input is properly encoded.

    $ perl -CAS tools/configure -save

    $ tools/configure -save

    LocalSite.cfg load failed
    AUTOCONFIG: Found Bin dir: /var/www/foswiki/distro/core/tools, Script name:
    configure using FindBin
    AUTOCONFIG: PubDir = /var/www/foswiki/distro/core/pub
    AUTOCONFIG: DataDir = /var/www/foswiki/distro/core/data
    AUTOCONFIG: WorkingDir = /var/www/foswiki/distro/core/working
    AUTOCONFIG: ToolsDir = /var/www/foswiki/distro/core/tools
    AUTOCONFIG: TemplateDir = /var/www/foswiki/distro/core/templates
    AUTOCONFIG: LocalesDir = /var/www/foswiki/distro/core/locale
    AUTOCONFIG: ScriptDir = /var/www/foswiki/distro/core/bin
    AUTOCONFIG: Unable to use PlainFileStore: ,v files were found in data or pub,
    which indicates this installation is already configured for RCS e.g.
    /var/www/foswiki/distro/core/data/WFWeb/WebChanges.txt,v
    AUTOCONFIG: Store configured for RcsLite
    AUTOCONFIG: {Store}{SearchAlgorithm} set to Forking
    AUTOCONFIG: Detected OS UNIX:  DetailedOS: linux
    ** Enter values for critical configuration items.
    ** type a new value or hit return to accept the value in brackets.

    This is the root of all Foswiki URLs.
    For example, =http://myhost.com:123=
    (do not include the trailing slash.)

    {DefaultUrlHost} (http://localhost): http://myhost.com

    This is the 'cgi-bin' part of URLs used to access the Foswiki bin
    directory. For example =/foswiki/bin=.
    See [[https://foswiki.org/Support/ShorterUrlCookbook][ShorterUrlCookbook]]
    for more information on setting up Foswiki to use shorter script URLs.

    {ScriptUrlPath} (/foswiki/bin):

    ...

It can also be run in a non-interactive mode, for use in automated deployment systems.

    tools/configure -save -noprompt
    tools/configure -save -set {DefaultUrlHost}='http://mysite.com'
    tools/configure -save -set {ScriptUrlPath}='/bin'
    tools/configure -save -set {ScriptUrlPaths}{view}=''
    tools/configure -save -set {PubUrlPath}='/pub'
    perl -CA tools/configure -save -set {Password}='ÄdmînPäss'

Any configuration keys may be set using this tool.

To run a wizard, for example autoconfiguration of email:

    tools/configure -save -set {WebMasterEmail}='user@email.com'
    tools/configure -save -set {SMTP}{MAILHOST}='smtpserver.email.com'
    tools/configure -save -set {SMTP}{Username}='userid'
    tools/configure -save -set {SMTP}{Password}='password'
    tools/configure -save -wizard AutoConfigureEmail -method autoconfigure

And the configuration can then be checked, with optional verbose output: (Without -verbose, only errors and warnings are reported.)

    tools/configure -check -verbose

File system permissions can also be checked for any of `{DataDir}`, `{LocalesDir}`, `{PubDir}`, `{ScriptDir}`, `{TemplateDir}`, `{ToolsDir}` and `{WorkingDir}`, for ex:

    tools/configure -check {DataDir} -method validate_permissions

Configuration settings can be searched and queried as well:

    tools/configure -search Umask
    tools/configure -getcfg {Store}

### TWiki Compatibility

Foswiki is 100% backwards compatible with TWiki™ markup up to and including TWiki 4.2.4. Existing TWiki webs, topics and attachments can be used with Foswiki without requiring any changes.

To support a seamless upgrade from TWiki, Foswiki ships with a plugin called `TWikiCompatibilityPlugin`. This plugin enables most TWiki extensions to work with Foswiki, without modifications. It also maps requests for legacy TWiki web topics to their Foswiki equivalents, as defined in Foswiki:Development.TopicNameMappingTable. The `TWIKIWEB` and `MAINWEB` TWiki variables are also mapped to the new Foswiki macros `SYSTEMWEB` and `USERSWEB`.

If you are not upgrading an existing TWiki installation and do not plan to install plugins from the TWiki web site, it is recommended that you disable the TWikiCompatibilityPlugin in the Plugins Section on the `configure` page.

If a plugin exists both in a TWiki version and a Foswiki version, it is strongly recommended that you use the Foswiki version, as this is coded to work optimally with Foswiki. As part of the Foswiki project, the Foswiki community is evaluating all of the extensions that are available for TWiki, and porting them over to the Foswiki name space. Many of them are being enhanced through the removal of bugs and security vulnerabilities, resulting in better, more functional extensions for Foswiki.

TWiki is a registered trademark of Peter Thoeny.

Related Topics: System.InstallationGuidePart2 in your installation, System.AdminDocumentationCategory in your installation, Foswiki:Support.SupplementalDocuments