Apache Config Generator

Apache 2.4 users: See ApacheConfigGenerator24 for a version of this tool that supports Apache 2.4 configuration. Or enable mod_access_compat for backwards compatibility with Apache 2.2 configurations.

This page creates an Apache configuration file foswiki.conf for your installation.
  1. 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.

Base server information

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

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.

Security related settings

Protect the bin/configure command

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

Enter the IP address range or hostnames that will have access to configure
Separate with spaces. Can be partial networks (example: localhost 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:

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

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
  • Template Login should be enable by default on "Choose your Login Manager".
  • 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)$" ?
  • 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

BasicForm edit

TopicClassification AdminTopic
Topic Summary Custom Apache config file generator
Interested Parties
Related Topics
Topic revision: r83 - 05 Dec 2014, GeorgeClark

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