FastCGI Engine Contrib

Overview

• The number of persistent processes is configurable, independent of the web server. This leads to easier capacity planning/management.
• Processes can be run with a different user: more security.
• Processes can be run on another machines: easier load balancing.

Installation Instructions

We recommend that you use the thoroughly tested Foswiki:Support.ApacheConfigGenerator for creating your apache configuration. It can generate a comprehensive Apache configuration for your installation.

• Apache web server
  • Using only .htaccess (typically on host services)
  • With access to apache configuration files
    • Remote FastCGI processes
  • Using mod_fcgid or mod_fastcgi
• Lighttpd web server
  • Remote FastCGI processes
• nginx web server
  • remote FastCGI processes

Installation of the FCGI CPAN library

Apache

Apache Module

• mod_fastcgi which is the oldest implementation. It is released under a custom non-free license but it is free of charge.
• mod_fcgid which is the newer implementation released under the GPL license and now part of the Apache Foundation.

• Sources - http://httpd.apache.org/mod_fcgid/
• Debian - http://packages.debian.org/search?searchon=names&keywords=libapache2-mod-fcgid

Apache Configuration

It is strongly recommended that users work from Foswiki:Support.ApacheConfigGenerator to create initial Apache configurations. This config generator is comprehensive and well tested.

Lighttpd

# Example with FastCGI processes launched by the webserver

$HTTP["url"] =~ "^/foswiki/bin/" {
    alias.url += ( "/foswiki/bin" => "/var/www/foswiki/bin/foswiki.fcgi" )
    fastcgi.server = ( ".fcgi" => (
            (
                "socket"    => "/var/www/foswiki/working/tmp/foswiki.sock",
                "bin-path"  => "/var/www/foswiki/bin/foswiki.fcgi",
                "max-procs" => 3
            ),
        )
    )
}

# Example with external FastCGI processes (running on the same host, with another user or at a remote machine)

$HTTP["url"] =~ "^/foswiki/bin/" {
    alias.url += ( "/foswiki/bin" => "/var/www/foswiki/bin/foswiki.fcgi" )
    fastcgi.server = ( ".fcgi" => (
            (
                "host"    => "example.com",
                "port"    => "8080",
            ),
        )
    )
}

Nginx

Configure nginx to contact a foswiki.fcgi process on some socket on the localhost:

server {
    listen       80;
    server_name  nginx.domain.com;

    set $foswiki_root "/var/www/foswiki";
    root $foswiki_root;

    access_log  /var/log/nginx/foswiki-access.log;
    error_log   /var/log/nginx/foswiki-error.log;
    #error_log   /var/log/nginx/foswiki-error.log debug;

    client_max_body_size 10M;   # Set to maximum attachment size, See also ATTACHFILESIZELIMIT

    location = / {
        root $foswiki_root;
    rewrite .* /Main/WebHome;
    }

    location ~ (^/pub) {
        allow all;
    }

    location ~ ^/bin/ {
           gzip off;
           #fastcgi_pass             unix:/var/run/nginx/foswiki.sock;
           fastcgi_pass             127.0.0.1:9000;
           fastcgi_split_path_info  ^(/bin/\w+)(.*);
           #  Captures two variables   ($fastcgi_script_name) and ($fastcgi_path_info)
           fastcgi_param            SCRIPT_FILENAME $foswiki_root/bin/$fastcgi_script_name;
           fastcgi_param            SCRIPT_NAME     $fastcgi_script_name;
           fastcgi_param            PATH_INFO       $fastcgi_path_info;
           include fastcgi_params;
       }

    location ~ (^/lib|^/data|^/locale|^/templates|^/tools|^/work) {
        deny all;
    }

    if ($http_user_agent ~
^SiteSucker|^iGetter|^larbin|^LeechGet|^RealDownload|^Teleport|^Webwhacker|^WebDevil|^Webzip|^Attache|^SiteSnagger|^WX_mail|^EmailCollector|^WhoWhere|^Roverbot|^ActiveAgent|^EmailSiphon|^CrownPeak-HttpAgent|^$) {
        rewrite .* /404.html break;
   }

    location ~ ^/(.*)$ {
        rewrite ^/(.*)$ /bin/view/$1;
    }
}

Add the foswiki.fcgi process into the system init.

• Conventional init scripts (Should also work with systemd)
  • tools/foswiki.init-script: copy this to /etc/init.d/foswiki; make the file executable using chmod +x /etc/init.d/foswiki, and ensure that it is assigned to user/group root.
  • tools/foswiki.defaults: copy this to /etc/default/foswiki and make appropriate adjustments;
    • make sure the process uses the same socket as configured in nginx (see above, defaults to 127.0.0.1:9000)
    • verify that the FOSWIKI_ROOT setting points to your foswiki installation.

• systemd specific service files (Used in place of the init scripts. Don't use both!)
  • tools/systemd/foswiki-fastcgi.service: copy this to /etc/systemd/system/foswiki.service.

• FreeBSD init scripts
  • tools/foswiki.freebsd.init-script:
  • tools/foswiki.freebsd.etc-defaults:

Note: The service file does not honor all of the variables in tools/foswiki.defaults. If you need to override any of:

• The user/group - defaults to www-data
• The PIDFile - defaults to /var/www/foswiki/working/foswiki.pid
• The scripts directory - defaults to /var/www/foswiki/bin/

Then the /etc/systemd/system/foswiki.service file must be edited directly, or overridden by a systemd "drop-in" file created in /etc/systemd/system/foswiki.d/foswiki.conf.

• service foswiki start/stop/reload/restart/status. or
• /etc/init.d/foswiki start/stop/reload/restart/status

Customizing the fcgi process

• Changing the name of the process / init script
  • Copy /etc/init.d/foswiki, /etc/defaults/foswiki and if used, /etc/systemd/system/foswiki.service, to a new name (ex. myfoswiki)
  • Edit the init script to use the new name internally. (The foswiki.service file would need similar changes not detailed here.)

    # Provides:          myfoswiki
    # Short-Description: Start the myfoswiki backend server.
    NAME=myfoswiki                <== Should match script name
    # The following defaults are overridden in etc/default/foswiki
    FOSWIKI_PNAME=myfoswiki       <== Process name displayed in =ps aux=
    

  • Make sure the new instance is using a unique fastcgi_pass and matching FOSWIKI_BIND

Tuning

Known Issues

This is a persistent engine, so you need to restart the web server after any configuration changes. The Foswiki FastCGI implementation on Apache has an auto-reload mechanism that can detect and restart the handlers when the LocalSite.cfg is changed. However there is a delay, and it is recommended to restart apache. After the update, each process will still serve one more request before reloading itself (e.g. if you're using 3 processes, the next 3 requests after the update will not be affected. The update will take effect on the requests made after the initial 3). This reloading mechanism works only on operating systems that have the exec(2) system call, like Linux and other POSIX compliant systems.

FastCGI support on IIS 6.0 (and maybe other versions) is broken with respect to the STDERR stream. This may cause problems.

Dependencies

Change History