You are here: Foswiki>Support Web>ApacheConfigGenerator (19 Jul 2019, PacoHope)Edit Attach

Apache Config Generator

This page creates an Apache configuration file foswiki.conf for your installation. (See Help with this page if you don't understand some of the terminology used here.)
  1. Select your Foswiki and 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.

  • 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.
  • Using a web hosting service and can't configure Apache? Do not bother using this page - edit the various .htaccess template files. See details in the installation guide.

Foswiki version

Generate configuration for Foswiki version
  • Selecting 2.x will drop Apache protection for bin/configure.

Apache server information

Choose Apache Version:

Apache "Name based" virtual hosts (optional)

Complete this section to define an Apache virtual host eg: (<VirtualHost *:80>). Enter the qualified hostname, 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 an Apache "Virtual Host", leave hostname and port blank.

Host Name: (optional) Port: (optional)

Apache timers

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)

File system paths

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?
(optional)

URL information

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/Web/Topic instead of the normal domain.tld/foswiki/bin/view/Web/Topic
Enabled
Disabled

Runtime engine

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

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.) This should be larger than the largest ATTACHFILESIZELIMIT preference setting, Multiply ATTACHFILESIZELIMIT by 1024. Default of 10000k is 10240000 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.

SSL Configuration information

Only enable SSL if your server is not already configured for SSL, or this is a new virtual host that needs SSL

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:
(required)

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:
(optional)

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:
(optional)

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 "/Users/shortusername/Sites/foswiki/core/data" omit trailing slash.)

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

Attachments

PHP execution

Prevent execution of attached files as PHP scripts if PHP is installed:

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)

Apply Foswiki access controls to attachments by redirecting access to the viewfile script?
Check to control attachment access: Caution: Slows performance significantly when enabled!

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!

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)

foswiki.conf created from your data

The text field below now contains a complete foswiki.conf file to be included from httpd.conf. In many distributions the foswiki.conf file is automatically included by placing it in the directory that contains the other included Apache config files. Typically in /etc/httpd/conf.d or /etc/apache2/conf.d

You can also place it anywhere else add the following line to the end of your main httpd.conf file: include "/path/to/foswiki.conf"

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)

Comments

History

  • 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
  • Change "Foswiki 1.2" to "Foswiki 2.0" -- JanKrueger - 07 Jul 2015
  • Change PHP to a checkbox, and use IfModule statements to avoid server issues. Also added a help link - -- Main.GeorgeClark - 07 Aug 2015 - 22:51
  • Check for Foswiki version < 2.0 before generating Alias for configure -- Main.GeorgeClark - 28 Sep 2015 - 13:43
  • Don't display FastCGI / Mod_Perl warnings for Foswiki 2.0 -- Main.GeorgeClark - 06 Jan 2016 - 04:31
  • Remove Perl -wT switch for Foswiki 2.0, also make Apache 2.4 the default -- Main.GeorgeClark - 02 Feb 2016 - 15:32
  • Change foswiki.org link to https: add notes on aliases for google validation keys, Remove path from robots.txt URL. It's always at the root level. -- Main.GeorgeClark - 05 Sep 2016 - 03:46
  • Added a fallback to CGI if mod_perl is not enabled.
  • Clarify that SSL is not needed if apache already is configured for ssl.
  • The /bin/ prefix was missing from the FastCGI / FCGI LocationMatch clause. Also, added configure, as you would always want a logged in user to access it, also changed to match login or logon -- Main.GeorgeClark - 22 Oct 2016 - 03:56
  • Eliminate the "www" alias from the virtual host statement. Remove some older references about Foswiki 1.x. -- Main.GeorgeClark - 27 Oct 2016 - 01:47
  • Use "Define foswikiroot" on Apache 2.4 configs to simplify future changes. Change to Foswiki 2.x to clarify version selector. Increase length of SSL config fields. -- Main.GeorgeClark
  • Added Alias for /error/ documents for shortest URLs, Add FcgidMaxRequestsPerProcess 400 to control fcgid memory growth. -- Main.GeorgeClark - 06 May 2017
  • Correct some other minor errors related to Apache 1.x, 2.2 and 2.4 -- Main.GeorgeClark - 06 May 2017
  • Added SemrushBot to the bad bots list. Multiple foswiki sites have been knocked offline due to this aggressive bot. -- Main.GeorgeClark - 06 May 2017
  • Documented relationship between FcgidMaxRequestLen and ATTACHMENTFILESIZELIMIT -- Main.GeorgeClark - 03 Dec 2017 - 02:26
  • Correct arithmetic in ATTACHFILESIZELIMIT conversion - 10000k is 10240000, not 1024000 -- Main.ChadDougherty - 25 Apr 2017 - 16:02

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.

BasicForm edit

TopicClassification AdminTopic
Topic Summary Custom Apache config file generator
Extension
Interested Parties
Related Topics
Edit  | Attach | Print version | History: r101 < r100 < r99 < r98 | Backlinks | View wiki text | Edit wiki text | More topic actions
Topic revision: r101 - 19 Jul 2019, PacoHope
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy