TIP This version has been saved as ApacheConfigGenerator. Please use that version.

Apache Config Generator

This tool needs further testing and validation. Latest version supports SSL configuration.

This page creates an Apache configuration file foswiki.conf for your installation.
  1. Select your Apache version, and fill out the form.
  2. Press the "Update Config File" button
  3. Copy and paste the generated configuration into a new file in the same directory as httpd.conf
  4. Add a line to httpd.conf so Apache loads the new configuration file (e.g. Include conf/foswiki.conf)
    • Note that the exact method of including a configuration file can vary by os and distribution. Consult your local apache documentation.

For setting up Foswiki on Linux or Unix, see also SettingFileAccessRightsLinuxUnix.

If you used the Debian packages to install Foswiki, do not use the ApacheConfigGenerator. Use the configuration files included in the .deb packages.
Windows Users: enter all file paths using linux forward-slash style, like C:/www/foswiki. Don't use Windows style back-slash in the paths.
Some people, including many using web hosts, can't edit http.conf. If this applies to you, do not bother using this page - edit the various .htaccess template files included in the download. (They have instructions in them. Their filenames are all different, but include "htaccess.txt" in them.)

Foswiki version

Generate configuration for Foswiki version

  • A configuration created for 1.0 will still work with 1.1, but some new features may be missing from the configuration.
  • A 1.1 configuration will work with 1.0, but 1.0 doesn't support all the features.
  • Selecting 1.2 (not yet released) will drop apache protection for bin/configure.

Base server information

Apache 2.4 uses a different configuration syntax for some settings. If your server is running Apache 2.4.x, select that here.

Apache Version:

Some people use Name Based virtual hosting. If you want to define a virtual host, enter the qualified hostname here, otherwise leave blank. You can also enter an optional port number. (Port not needed on most systems) Example: foswiki.myhost.com If you are not defining a "vhost", leave hostname and port blank.

Host Name: (optional) Port: (optional)

Enter the timeout in seconds for the maximum runtime of a foswiki transaction. (Any request exceeding this time will result in a 500 error to the user. Leave empty to take apache system default.)
TimeOut: (optional)

Enter the full file path to your foswiki root directory: Foswiki does not work with directory names containing spaces (especially important to notice for Windows users). So choose an installation directory without spaces.
Path: (mandatory, no spaces)

Will you require Symbolic Links in the pub/ or bin/ directories?

Enter the url path which foswiki is accessed :
(For shortest URL's, you can enter only the slash).
URL Path: (mandatory)

Short URLs

When you enable this, you can omit the bin/view/ from the URLs. Use domain.tld/foswiki/System/WebHome instead of the normal domain.tld/foswiki/bin/view/System/WebHome

Runtime engine

Choose the way foswiki is supposed to run (see FoswikiStandAlone). Select CGI if in doubt.

FastCGI module: mod_fcgid mod_fastcgi

Enter the maximum size of any data transmitted from the client to the Foswiki process. (Any request exceeding this size will result in error 500 to the user. Leave empty to take fcgid system default of 131072 bytes.)
FcgidMaxRequestLen: (optional)

Apache version: 1.x 2.x

Before you enable mod_perl in your webserver, you have to configure Foswiki. Otherwise, you'll face a chicken-and-egg problem, and would get something like this in your Apache error logs:
[error] Content-type: text/plain\n\nPerl error when reading LocalSite.cfg: \nPlease inform the site admin.\nBEGIN failed--
You will also have to generate a suitable mod_perl_startup.pl script for use with this configuration. See ModPerlStartup for guidance.
Before you enable fastcgi in your webserver, you should install the FastCGIEngineContrib using the Extensions: Install and update Extensions tool. The server will run, but all of the Foswiki scripts will fail with foswiki.fcgi not found until the Extension is installed.

Protect the bin/configure command

It is strongly recommended that the configure script be protected. (Not necessary on Foswiki 1.2). It can be protected by IP address(es), User name(s) or both (cf. ProtectingYourConfiguration).

Enter the hostnames that will have access to configure
Separate with spaces. Can be partial networks :
(optional) example: host1 localhost )
Enter the IP address ranges that will have access to configure
Separate with spaces. Can be partial networks :
(optional) (example: 192.168.2 )

Enter the list of user names that are allowed to access configure
Separate multiple names with spaces, can't be a name you use to edit Foswiki. Names must exist in .htpasswd file:

Choose if you want to require both Hostname/IP AND Username for configure access, or Hostname/IP OR Username validation.


SSL Configuration information

Enable SSL (https): (optional)

The certificate file should have it's password removed or Apache will prompt for a password when started.

Location of the SSL Certificate file:

Some Certificate Authorities will provide a CA Chain file. Provide the fully qualified filename here if required, otherwise blank out this field.

Location of the SSL Certificate CA Chain file:

Provide the Certificate private key file location if the key is separated from the certificate. If private key is embedded in the certificate file, blank out this field.

Location of the SSL Certificate Private key file:

Foswiki login support

Choose your Login Manager:
None - No login
TemplateLogin - Redirect to the login template, which asks for a username and password in a form
ApacheLogin - Apache is configured to ask for authorization information

Location of directory containing the .htpasswd file:
(optional - if blank, defaults to "/var/www/foswiki/data" omit trailing slash.)

Page to return when authentication fails:
None. Use Apache default 401 message
Custom: (enter Web/TopicName )


Prevent execution of attached files as PHP scripts if PHP is installed:
PHP4/5 Installed
PHP3 Installed
No PHP Installed
Caution: Choose None if if your server does not have PHP installed, or Apache will not start!

Attachment access protection

Block direct access to viewing attachments that ends with .htm or .html:
Check to block access: (recommended against spam abuse)

Block direct access to viewing attachments in Trash web
Check to block access: (recommended against spam abuse)

In some installations it is important to protect attached files with the same access controls that are applied to the owning topic. If this option is selected, the configuration will include some rewrite rules that redirect web access to attachments to the bin/viewfile script.

  • Note that this option can have a significant impact on performance.
  • Also, this option is incompatible with ImageGalleryPlugin as it writes to /pub/images which is not a valid web name.
  • Viewfile sets the mime type based upon file name suffix. Unknown types are served as text/plain which can result in corrupt files.
  • This option will also add some rewrite rules that bypass viewfile for certain graphics files - review the comments in the configuration carefully!

Do you want apply Foswiki access controls to attachments by redirecting access to the viewfile script?
Check to control attachment access: (optional)

Spiders and Robots

Do you want to include rules to block access from well known robot agents? Note, the default list includes well known robots including Google.
Check to deny access: (Recommended for public sites)

default foswiki.conf

Press the "Update config file" button to generate your custom config

By pressing the button below you select all the text in the textarea. Then you just need to copy the text to the clipboard and paste it into the foswiki.conf file.

Depending on the configuration you might get an error in Apache leading to a non-working configuration:
Options FollowSymLinks or SymLinksIfOwnerMatch is off which implies that RewriteRule directive is forbidden: /var/www/foswiki/bin/configure
In this case you should think about your redirection policy. One fix is to add the line
Options +FollowSymLinks
to the configuration which applies to the base directory of the path mentioned in the error message (either as htaccess or conditional in apache .conf)



  • Originally crafted and regularly maintained by KennethLavrsen
  • removed the handy W3C tools from the blocked list. -- WillNorris - 18 Feb 2009
  • ending % was missing for a %PATHURL in a ScriptAlias declaration -- ColasNahaboo - 23 Feb 2009
  • Noted can't use a configure user as an editing wiki user -- MartinCleaver - 23 Mar 2009
  • Remove /bin/view from the ErrorDocument strings if shorturls enabled - otherwise Apache fails to prompt for password - 5 Apr 2009
  • Disabled TinyMCE plugin as it messes up with the layout -- OlivierRaginel - 06 Apr 2009
  • Reorganized, added support for protecting attachments, FollowSymLinks -- GeorgeClark - 11 Apr 2009
  • Simplified viewfile regex - should fix compile failure on Apache startup.
  • Allow any wiki topic to be specified as the not-authorized page
  • Allow location of .htpasswd to be overridden
  • Add an optional port # for the Virtual host. So you can specify :80, :443, or whatever on the statement.
  • Fixed htpasswd to default to data directory if left blank, otherwise overrides path - 3 Sept 2009
  • Added (commented out) rules for serving pre-compressed .js and .css -- MichaelTempest - 22 Sep 2009
  • Moved LocationMatch for fcgi outside of the directory.
  • Add an Alias statement for robots.txt when short URLs are enabled
  • Add or/and configuration of access control to bin/configure command -- TobiasVonDerKrone - 11 Dec 2009
  • Fixed the urlpath element so that it roundtrips without adding a bogus leading space -- MartinCleaver - 11 Feb 2010
  • Added ErrorDocument 401 default for bin/configure, so it doesn't rewrite to the bin/view and cause other errors - 9 July 2010
  • Added NO_FOSWIKI_SESSION for protection against hungry spiders - AndrewJones - 14 July 2010
  • Improve regex for Expires header - match jpeg as well as jpg. ( WillNorris ) And match the gz compressed versions of css and js -- GeorgeClark - 30 Sep 2010
  • default Foswiki version to 1.1 -- WillNorris - 09 Nov 2010
  • changed default config mode to AND. Foswiki:Tasks/Item10018
  • Added more quotes on file system paths to deal with spaces. -- GeorgeClark - 26 Oct 2011
  • Added Timeout, FcgidIOTimeout, FcgidBusyTimeout and FcgidMaxRequestLength, changed default from mod_fastcgi to mod_fcgid. -- GeorgeClark - 29 Dec 2012 Tasks.Item12318
  • Added ModPerlStartup script -- CrawfordCurrie - 06 Jan 2014
  • Template Login should be enable by default on "Choose your Login Manager".
  • Add support for Foswiki 1.2 and Apache 2.4
  • On the line that starts with "Generated at..." I changed the topic reference from ApacheConfigGenerator to %TOPIC% so as to true to the version of of the config generator used. -- LynnwoodBrown - 30 Jan 2015
  • Added SSL support, also hide Configure protection if Foswiki 1.2 selected -- GeorgeClark - 22 Apr 2015 - 23:11

Wanted improvements.

  • For ShortURLs, I had to (at least for what I'm doing at SSLForNonViewScriptsOnly), add Alias /error/ "/usr/share/apache2/error/" above Alias / "/srv/www/vhosts/wiki.trin.org.au/foswiki/bin/view/"
  • Handle modules needed for LDAP library inclusions -- MartinCleaver - 11 Feb 2010
  • There should be a really basic configuration file ready to download and explained for newbies - there is the httpd.conf.txt at the root of the release
  • Shouldn't we change the FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|rest|.*auth......" to simply be something like FilesMatch "(?<!view)$" ?
    • No. In 1.2, the rest script does not require authentication. And jsonrpc does its own checking and can be unprotected.
  • Clarify why enabling Short URLs creates RewriteRules as well as Aliases, when ShorterUrlCookbook claims that only one or the other is necessary. -- HeathRaftery - 9 Feb 2012
    • The Rewrite rules redirect users who entered the full URL to the short URL. The Alias associates the view script with the short URL.
Topic revision: r6 - 05 May 2015, GeorgeClark - This page was cached on 25 May 2016 - 09:19.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License