Username:
Password:
Remember me on this computer
Submit

You are here: Sandbox » NginxConfiguration

Nginx Config Generator

17 June 2021 - 18:51 | Version 1 | LynnwoodBrown

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.)

Select your Foswiki and Apache version, and fill out the form.
Press the "Update Config File" button
Copy and paste the generated configuration into a new file in the same directory as httpd.conf
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 Middle Fork Home Wiki 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 "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.

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.

Copy text below to tools/foswiki.defaults to /etc/default/foswiki, and tailor it for your installation. If your distribution does not use etc/default files, then these settings need to be manually inserted into the init script.

FOSWIKI_ROOT=/var/www/foswiki             <=== Location of the expanded foswiki distribution
FOSWIKI_FCGI=foswiki.fcgi
FOSWIKI_BIND=127.0.0.1:9000               <=== Must match settings in nginx host configuration

# Autogenerated httpd.conf file for Foswiki.
# Generated at https://middleforkhome.us/Sandbox/NginxConfiguration?vhost=;port=;dir=/var/www/foswiki;symlink=;pathurl=/foswiki;shorterurls=enabled;engine=CGI;fastcgimodule=fcgid;fcgidreqlen=;apver=2;confighost=;configip=;configuser=;loginmanager=Template;htpath=;errordocument=UserRegistration;errorcustom=;disablephp=on;blockpubhtml=;blocktrashpub=;controlattach=;blockspiders=;foswikiversion=2.x;apacheversion=2.4;timeout=;ssl=;sslcert=/etc/ssl/apache2/yourservercert.pem;sslchain=/etc/ssl/apache2/sub.class1.server.ca.pem;sslkey=/etc/ssl/apache2/yourservercertkey.pem

# Configuration generated for Foswiki 2.x,  Apache 2.4


# set to maximum upload size ... or to zero to disable the check in nginx so that foswiki's ATTACHFILESIZELIMIT takes precedence
client_max_body_size 0;

# enable this to redirect any http to https, see "listen" in next server block below
# server {
#   server_name ~^(www\.)?(?.+)$;
#   listen 80;
#
#   return 301 https://$host$request_uri;
#}

server {
  server_name  ;           # <=== Replace with your hostname

  set $foswiki_root /var/www/foswiki;      # <=== Path to expanded foswiki distribution

  root /var/www/html;
  index index.html;

  # enable for bad clients detection, see below
#  if ($bad_client) {
#    return 403;
#  }  
#  if ($bad_referer) {
#     return 444;
#  }

  # listen to http in case you don't want to redirect all http to https, see above
  listen 80;

  # listen for both, http and https
  # listen 443 ssl http2;
  # ssl_certificate     /etc/ssl/certs/server.crt; 
  # ssl_certificate_key /etc/ssl/private/server.key; 

  # enable when listening to 443 only 
  # ssl on;

  # Uncomment for htpasswd
  #auth_basic "FOSWiki";
  #auth_basic_user_file $foswiki_root/data/.htpasswd;

  # browsers tend to search for a favicons and robots.txt in the root directory: if it is there fine, if not don't bother
  location /favicon.ico {
    log_not_found off;
    access_log off;
  }
  location /robots.txt {
    allow all;
    log_not_found off;
    access_log off;
  }

  # first test for static files in the document root, then redirect to foswiki backend
  location / {
    try_files $uri @foswiki;
  }

  # redirect short urls to view
  location ~ ^/(?:bin/)?([A-Z_].*)$ {
    rewrite ^/(.*)$ /bin/view/$1 last;
  }

  # any /bin goes to foswiki
  location /bin {
    try_files $uri @foswiki;
  }

  # static files that we don't need to authenticate, i.e. css and js
  location ~ ^/pub/(System|Applications|cache)/ {
    root $foswiki_root;
    expires 8h;
    gzip_static on;
  }

  # any other static files need to be sanctioned by the foswiki backened
  location /pub {
    root $foswiki_root;

    # either by the standard viewfile approach ...
    rewrite ^/pub/(.*)$ /bin/viewfile/$1;

    # or by XSendFileContrib using
    #
    # {XSendFileContrib}{Header} = 'X-Accel-Redirect';
    # {XSendFileContrib}{Location} = '/files';
    #rewrite ^/pub/(.*)$ /bin/xsendfile/$1;
  }

  # internal location that sendfile serves sanctioned static files from
  location /files {
    internal;
    alias $foswiki_root/pub/;
    expires 8h;
    access_log off;
  }

  # deny any direct access to these directores
  # note that this only is required in case the document root equals the $foswiki_root
  location ~ (^/lib|^/data|^/locale|^/templates|^/tools|^/work) {
     deny all;
  }

  # optional location for WebDAVContrib. 
  location /dav {
     gzip off;
 
     fastcgi_pass   127.0.0.1:9001;                  # <=== Must match FOSWIKI_BIND parameters in /etc/default/foswiki-dav

     # connection settings to mitigate some buggy webdav clients
     keepalive_timeout 0;
     fastcgi_keep_conn off;

     fastcgi_split_path_info ^/dav/(.+?)(/.*)$;
     fastcgi_param  SCRIPT_FILENAME  $foswiki_root/tools/wedav.fcgi;
     fastcgi_param  PATH_INFO $fastcgi_path_info;

     # set a HTTP2 env variable to indicate the kind of connection to foswiki 
     fastcgi_param  HTTP2 $http2;
 
     include fastcgi_params;
  }

  # internal location for anything foswiki
  location @foswiki {
     gzip off;

     fastcgi_pass   127.0.0.1:9000;                   # <=== Must match FOSWIKI_BIND parameters in /etc/default/foswiki-da

     # a request taking more than 2 minutes is considered an error
     fastcgi_read_timeout 120s; 

     fastcgi_split_path_info ^/bin/(.+?)(/.*)$;
     fastcgi_param  SCRIPT_FILENAME  $foswiki_root/bin/foswiki.fcgi;
     fastcgi_param  PATH_INFO $fastcgi_path_info;
     # Uncomment the next 2 if using htpasswd
     #fastcgi_param  AUTH_USER  $remote_user;
     #fastcgi_param  REMOTE_USER  $remote_user;
     # set a HTTP2 env variable to indicate the kind of connection to foswiki 
     fastcgi_param  HTTP2 $http2;

     include fastcgi_params;
  }
}
# Autogenerated httpd.conf file for Foswiki.
# Generated at https://middleforkhome.us/Sandbox/NginxConfiguration?vhost=;port=;dir=/var/www/foswiki;symlink=;pathurl=/foswiki;shorterurls=enabled;engine=CGI;fastcgimodule=fcgid;fcgidreqlen=;apver=2;confighost=;configip=;configuser=;loginmanager=Template;htpath=;errordocument=UserRegistration;errorcustom=;disablephp=on;blockpubhtml=;blocktrashpub=;controlattach=;blockspiders=;foswikiversion=2.x;apacheversion=2.4;timeout=;ssl=;sslcert=/etc/ssl/apache2/yourservercert.pem;sslchain=/etc/ssl/apache2/sub.class1.server.ca.pem;sslkey=/etc/ssl/apache2/yourservercertkey.pem

# Configuration generated for Foswiki 2.x,  Apache 2.4


Define foswikiroot "/var/www/foswiki"







# The Alias defines a url that points to the root of the Foswiki installation.
# The first parameter will be part of the URL to your installation e.g.
# http://my.co.uk/foswiki/bin/view/...
# The second parameter must point to the physical path on your disc.

ScriptAlias /foswiki/bin "${foswikiroot}/bin"

# The following Alias is used to access files in the pub directory (attachments etc)
# It must come _after_ the ScriptAlias.
# If short URLs are enabled, and any other local directories or files need to be accessed directly, they
# must also be specified in an Alias statement, and must not conflict with a web name.

Alias /foswiki/pub "${foswikiroot}/pub"
Alias /robots.txt "${foswikiroot}/robots.txt"
# Add aliases for any other files that must be read at the root level. eg.
# Alias /google[somehashkey].html "${foswikiroot}/google[somehashkey].html"




#  Rewriting is required for Short URLs, and Attachment redirecting to viewfile
RewriteEngine    on
#LogLevel alert rewrite:trace3




# short urls
Alias /foswiki "${foswikiroot}/bin/view"
RewriteRule ^/+foswiki/+bin/+view/+(.*) /foswiki/$1 [L,NE,R]
RewriteRule ^/+foswiki/+bin/+view$ /foswiki/ [L,NE,R]





# This enables access to the documents in the Foswiki root directory

<Directory "${foswikiroot}">
    <RequireAll>
        Require all granted
        Require not env blockAccess
    </RequireAll>
</Directory>



# This specifies the options on the Foswiki scripts directory. The ExecCGI
# and SetHandler tell apache that it contains scripts. "Allow from all"
# lets any IP address access this URL.
# Note:  If you use SELinux, you also have to "Allow httpd cgi support" in your SELinux policies

<Directory "${foswikiroot}/bin">
    AllowOverride None

    <RequireAll>
        Require all granted
        Require not env blockAccess
    </RequireAll>


    Options +ExecCGI  -FollowSymLinks
    SetHandler cgi-script

    # Password file for Foswiki users
    AuthUserFile "${foswikiroot}/data/.htpasswd"
    AuthName 'Enter your WikiName: (First name and last name, no space, no dots, capitalized, e.g. JohnSmith). Cancel to register if you do not have one.'
    AuthType Basic

    # File to return on access control error (e.g. wrong password)
    ErrorDocument 401 /foswiki/System/UserRegistration





</Directory>

# This sets the options on the pub directory, which contains attachments and
# other files like CSS stylesheets and icons. AllowOverride None stops a
# user installing a .htaccess file that overrides these options.
# Note that files in pub are *not* protected by Foswiki Access Controls,
# so if you want to control access to files attached to topics you need to
# block access to the specific directories same way as the ApacheConfigGenerator
# blocks access to the pub directory of the Trash web
<Directory "${foswikiroot}/pub">
    Options None
    Options -FollowSymLinks
    AllowOverride None

    <RequireAll>
        Require all granted
        Require not env blockAccess
    </RequireAll>
    ErrorDocument 404 /foswiki/bin/viewfile

   # If you have PHP installed as Apache module, one of the below directives will ensure
   # that it is disabled.   The "ifmodule" statements should prevent this from causing
   # errors if php is not installed.

    <ifmodule mod_php3.c>
        php3_engine off
    </ifmodule>
    <ifmodule mod_php4.c>
        php_admin_flag engine off
    </ifmodule>
    <ifmodule mod_php5.c>
        php_admin_flag engine off
    </ifmodule>

   # This line will redefine the mime type for the most common types of scripts
    AddType text/plain .shtml .php .php3 .phtml .phtm .pl .py .cgi

   # add an Expires header that is sufficiently in the future that the browser does not even ask if its uptodate
   # reducing the load on the server significantly
   # IF you can, you should enable this - it _will_ improve your Foswiki experience, even if you set it to under one day.
   # you may need to enable expires_module in your main apache config

   #<ifmodule mod_expires.c>
   #  <filesmatch "\.(jpe?g|gif|png|css(\.gz)?|js(\.gz)?|ico)$">
   #       ExpiresActive on
   #       ExpiresDefault "access plus 11 days"
   #   </filesmatch>
   #</ifmodule>
   #
   # Serve pre-compressed versions of .js and .css files, if they exist
   # Some browsers do not handle this correctly, which is why it is disabled by default
   # <FilesMatch "\.(js|css)$">
   #         RewriteCond %{HTTP:Accept-encoding} gzip
   #         RewriteCond %{REQUEST_FILENAME}.gz -f
   #         RewriteRule ^(.*)$ %{REQUEST_URI}.gz [L,QSA]
   # </FilesMatch>
   # <FilesMatch "\.(js|css)\?.*$">
   #         RewriteCond %{HTTP:Accept-encoding} gzip
   #         RewriteCond %{REQUEST_FILENAME}.gz -f
   #         RewriteRule ^([^?]*)\?(.*)$ $1.gz?$2 [L]
   # </FilesMatch>
   # <FilesMatch "\.js\.gz(\?.*)?$">
   #         AddEncoding x-gzip .gz
   #         AddType application/x-javascript .gz
   # </FilesMatch>
   # <FilesMatch "\.css\.gz(\?.*)?$">
   #         AddEncoding x-gzip .gz
   #         AddType text/css .gz
   # </FilesMatch>

</Directory>

# Security note: All other directories should be set so
# that they are *not* visible as URLs, so we set them as =deny from all=.
<Directory "${foswikiroot}/data">
    Require all denied
</Directory>

<Directory "${foswikiroot}/templates">
    Require all denied
</Directory>

<Directory "${foswikiroot}/lib">
    Require all denied
</Directory>

<Directory "${foswikiroot}/locale">
    Require all denied
</Directory>

<Directory "${foswikiroot}/tools">
    Require all denied
</Directory>

<Directory "${foswikiroot}/working">
    Require all denied
</Directory>

# We set an environment variable called blockAccess.
#
# Setting a BrowserMatchNoCase to ^$ is important. It prevents Foswiki from
# including its own topics as URLs and also prevents other Foswikis from
# doing the same. This is important to prevent the most obvious
# Denial of Service attacks.
#
# You can expand this by adding more BrowserMatchNoCase statements to
# block evil browser agents trying to crawl your Foswiki
#
# Example:
# BrowserMatchNoCase ^SiteSucker blockAccess
# BrowserMatchNoCase ^$ blockAccess



BrowserMatchNoCase ^$ blockAccess

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)

Welcome

Log in

Sandbox

Nginx Config Generator

Foswiki version

Apache "Name based" virtual hosts (optional)

Apache timers

File system paths

URL information

Short URLs

Runtime engine

Security related settings

Protect the `bin/configure` command

SSL Configuration information

Foswiki login support

Attachments

PHP execution

Attachment access protection

Spiders and Robots

default foswiki.conf

Comments

Attachments ($count)

Welcome

Log in

Sandbox

Nginx Config Generator

Foswiki version

Apache "Name based" virtual hosts (optional)

Apache timers

File system paths

URL information

Short URLs

Runtime engine

Security related settings

Protect the bin/configure command

SSL Configuration information

Foswiki login support

Attachments

PHP execution

Attachment access protection

Spiders and Robots

default foswiki.conf

Comments

Attachments ($count)

Protect the `bin/configure` command