Permalink
Browse files

Item14346: Fix some issues with systemd service file

and clarify documentation.
  • Loading branch information...
gac410 committed Mar 21, 2017
1 parent a4ddd17 commit e002399716fb58f51662323b7716782841e54361
@@ -1,4 +1,4 @@
-%META:TOPICINFO{author="ProjectContributor" comment="" date="1475978414" format="1.1" version="1"}%
+%META:TOPICINFO{author="ProjectContributor" comment="" date="1490124221" format="1.1" version="1"}%
---+!! <nop>FastCGI Engine Contrib
%$SHORTDESCRIPTION%
@@ -17,8 +17,6 @@ Some !FastCGI features:
* 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.
-<!-- NOT IMPLEMENTED YET
- * Besides the [[http://www.fastcgi.com/drupal/node/6?q=node/22#S6.2][responder]] [[http://www.fastcgi.com/drupal/node/6?q=node/22#S6][role]], equivalent of classic CGI scripts, there is the [[http://www.fastcgi.com/drupal/node/6?q=node/22#S6.3][authorizer]], that can be used to add access checks to attachments with less overhead and resource usage than [[System/CommandAndCGIScripts#viewfile][viewfile]] script. -->
---++ Installation Instructions
@@ -80,22 +78,17 @@ There are two options that basicly do the same thing
* 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.
-
-It is difficult to recommend one or the other. In some cases one will work and the other will not. Most positive reports have been with mod_fcgid but
-both have been tested and work with standard out-of-the-box Apache and Foswiki setups. mod_fcgid is easier to find as package because of its GPL license
-so it may be the best place to start. Fedora has mod_fcgid on the installation DVD now.
+
+=mod_fcgid= is provided by default with apache2, and is recommended for simplicity of installation and configuration.
Below are some resources for the most common Linux distributions. The actual versions of the latest packages may have changed since this documentation was written.
mod_fcgid resources
* Sources - http://httpd.apache.org/mod_fcgid/
- * !RedHat/Centos EL5 64 bit - http://centos.karan.org/el5/extras/testing/x86_64/RPMS/mod_fcgid-2.2-4.el5.kb.x86_64.rpm
- * !RedHat/Centos EL5 32 bit - http://centos.karan.org/el5/extras/testing/i386/RPMS/mod_fcgid-2.2-4.el5.kb.i386.rpm
* Debian - http://packages.debian.org/search?searchon=names&keywords=libapache2-mod-fcgid
mod_fastcgi resources
* !RedHat/Centos - http://rugmonster.org/2009/03/building-mod_fastcgi-on-rhel5/ and http://www.nagare.org/trac/blog/apache_mod_fastcgi
- * Debian - http://packages.debian.org/unstable/httpd/libapache2-mod-fastcgi
---++++ Apache Configuration
@@ -288,64 +281,79 @@ $HTTP["url"] =~ "^%URL%/" {
---+++ Nginx
-In contrast to Apache or Lighttpd Nginx does not control the life time of the =foswiki.fcgi= backend process. Instead you will
+In contrast to Apache or Lighttpd, Nginx does not control the life time of the =foswiki.fcgi= backend process. Instead you will
have to start it yourself using the system's init process. The FCGI::ProcManager class will then take care of (re-)spawning
enough child processes as required.
First, let's configure nginx to contact a =foswiki.fcgi= process on some socket on the localhost:
<pre class="bash">
server {
-...
- root %ROOT%;
-
- location = / {
- try_files $uri @foswiki;
- }
-
- location ~ ^/(?:%URL%/)?([A-Z_].*)$ {
- rewrite ^/(.*)$ %URL%/view/$1;
- }
-
- location ~ ^/pub/(System|Applications|images|cache)/ {
- expires 8h;
- gzip_static on;
- }
-
- location /pub {
- rewrite ^/pub/(.*)$ %URL%/viewfile/$1;
- }
-
- location %URL% {
- try_files $uri @foswiki;
- }
-
- location @foswiki {
- gzip off;
-
- fastcgi_pass 127.0.0.1:9000;
-
- fastcgi_split_path_info ^%URL%/(.+?)(/.*)$;
- fastcgi_param SCRIPT_FILENAME %ROOT%/bin/foswiki.fcgi;
- fastcgi_param PATH_INFO $fastcgi_path_info;
-
- include fastcgi_params;
- }
-
- location ~ (^/lib|^/data|^/locale|^/templates|^/tools|^/work) {
- deny all;
- }
-
-...
+ listen 80;
+ server_name nginx.domain.com;
+
+ set $foswiki_root "/home/www-data/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;
+
+ 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 ($ffastcgi_script_name) and ($fastcgi_path_info)
+ fastcgi_param SCRIPT_FILENAME $foswiki_root/$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;
+ }
}
</pre>
Next, to integrate the =foswiki.fgi= process into the system's init process use the two helper scripts in the =tools= directory:
- * =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.
- * =foswiki.defaults=: copy this to =/etc/default/foswiki= and make appropriate adjustmenst; make sure the process uses the same socket as configured in nginx (see above, defaults to =127.0.0.1:9000=)
+ * 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 adjustmenst; make sure the process uses the same socket as configured in nginx (see above, defaults to =127.0.0.1:9000=)
+
+ * 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=.
+<div class="foswikiHelp">%X% *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=.
+</div>
-If your system uses =systemd=, then you will need to trigger a re-read of the init scripts by running (as root): =systemctl daemon-reload=
+If your system uses =systemd=, then you will need to trigger a re-read of the init scripts and service files by running (as root): =systemctl daemon-reload=.
+*This must be done any time the init scripts or service files are modified.*
You should now be able to control the backend processes using either:
* =service foswiki start/stop/reload/restart/status=. _or_
@@ -355,24 +363,27 @@ Finally, add the service to the runlevels using =update-rc.d foswiki defaults= t
---++ Tuning
-Except from Apache using only =.htaccess= file, it's possible to adjust the number of !FastCGI processes. There is no _magic number_: it depends on some variables, like the hardware resources and access load. If you set this number too low, users may experience high latencies and you'll not use all hardware potential, on the other hand if this setting is adjusted too high then the server can be forced to use swap, what degrades performance a lot.
+Except from Apache configured using only =.htaccess= file, it's possible to adjust the number of !FastCGI processes. There is no _magic number_: it depends on some variables, like the hardware resources and access load. If you set this number too low, users may experience high latencies and you'll not use all hardware potential, on the other hand if this setting is adjusted too high then the server can be forced to use swap, what degrades performance a lot.
+Due to possible memory growth, it's recommended to automatically restart the FCGI handlers afer they serve some number of requests. On Apache, this is
+done using the =FcgidMaxRequestsPerProcess 500= setting. On other web servers, use the Foswiki configuration setting: ={FastCGIContrib}{MaxRequests} = 100=
+
Dynamic servers are more useful when Foswiki access load on the server is low and/or it's used for something in addition to Foswiki. Under high loads, static servers can deliver better performance.
---++ Known Issues
-[[http://www.fastcgi.com/drupal/node/6?q=node/22][FastCGI specification]] defines an [[http://www.fastcgi.com/drupal/node/6?q=node/22#S6.3][authorizer role]] besides the common used [[http://www.fastcgi.com/drupal/node/6?q=node/22#S6.2][responder]]. Foswiki, by default, doesn't check access to attachments, unless you use [[System.CommandAndCGIScripts#viewfile][viewfile]] script. The problem with that script is that it's slow and resource-hungry. In future releases, this contrib will provide a way to add access checks to attachments with very little overhead, using the authorizer role.
-
<div class="foswikiHelp">
-%X% This is a persistent engine, so you need to restart the web server after some configuration update is performed. However, there is an auto-reload mechanism that apply changes without a web server restart. Unfortunately, there is a delay: 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.
-
+%X% 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.
%X% !FastCGI support on IIS 6.0 (and maybe other versions) is *broken* with respect to the =STDERR= stream. This may cause problems.
</div>
---++ Info
| Change History: | |
+| 21 Mar 2017 | (1.04) Foswikitask:Item14346 - Fix issues in the systemd service file. Improve documentation. |
| 04 Oct 2016 | (1.03) Foswikitask:Item13883 - Documentation updates, Foswikitask:Item14086 - Add a systemd example service file. |
| 14 Jun 2015 | (1.02) Foswikitask:Item10751 - Prepare for Unicode core. |
| 29 Mar 2015 | (1.01) Foswikitask:Item13342 - Add missing dependency, don't re-init back end after every transaction while bootstrapping. |
@@ -6,6 +6,6 @@ lib/Foswiki/Contrib/FastCGIEngineContrib/Config.spec 0644
lib/Foswiki/Contrib/FastCGIEngineContrib.pm 0644
lib/Foswiki/Engine/FastCGI.pm 0644
lib/Foswiki/Engine/FastCGI/ProcManager.pm 0644
-tools/systemd/foswiki-fastcgi.service 0755
+tools/systemd/foswiki.service 0755
tools/foswiki.defaults 0755
tools/foswiki.init-script 0755
@@ -5,4 +5,6 @@ FOSWIKI_CHILDREN=3
FOSWIKI_MAX_REQUESTS=-1
FOSWIKI_MAX_SIZE=200000
FOSWIKI_CHECK_SIZE=10
+# The followng variables are NOT used by the systemd/foswiki.service file.
FOSWIKI_QUIET=true
+FOSWIKI_PIDFILE=/var/run/$NAME.pid
@@ -8,34 +8,42 @@
Description=Foswiki
[Service]
+#Environment=SYSTEMD_LOG_LEVEL=debug
+
Environment=FOSWIKI_ROOT=/var/www/foswiki
Environment=FOSWIKI_FCGI=foswiki.fcgi
Environment=FOSWIKI_BIND=127.0.0.1:9000
Environment=FOSWIKI_CHILDREN=3
Environment=FOSWIKI_MAX_REQUESTS=-1
Environment=FOSWIKI_MAX_SIZE=250000
Environment=FOSWIKI_CHECK_SIZE=10
-Environment=FOSWIKI_QUIET=true
-Environment=FOSWIKI_PIDFILE=/var/run/foswiki.pid
# Optional, overrides settings above
EnvironmentFile=-/etc/default/foswiki
-# Doesn't seem to support variable substitution. Should be ${FOSWIKI_ROOT}/bin/
+# The User, Group, PIDFile and WorkingDirectory cannot be specified by Environment variables. Update as needed.
+User=www-data
+Group=www-data
+
+# If changing pidfile, be sure to also update the -p argument on the ExecStart command
+# The PIDFile directory must exist and be writable by the User:Group specified above
+PIDFile=/var/www/foswiki/working/foswiki.pid
+#PIDFile=/var/run/foswiki/foswiki.pid # conventional location
+
+# Path to the foswiki bin directory, including a trailing slash
WorkingDirectory=/var/www/foswiki/bin/
# Starts foswiki fcgi service
ExecStart=/usr/bin/perl ${FOSWIKI_ROOT}/bin/${FOSWIKI_FCGI} \
-n $FOSWIKI_CHILDREN \
-l $FOSWIKI_BIND \
- -p $FOSWIKI_PIDFILE \
-c $FOSWIKI_CHECK_SIZE \
-x $FOSWIKI_MAX_REQUESTS \
-s $FOSWIKI_MAX_SIZE \
+ -p ${FOSWIKI_ROOT}/working/foswiki.pid \
-d
Type=forking
-PIDFile=$FOSWIKI_PIDFILE
Restart=always
SyslogIdentifier=foswiki
@@ -1,11 +1,11 @@
-%META:TOPICINFO{author="ProjectContributor" date="1484611418" format="1.1" version="1"}%
+%META:TOPICINFO{author="ProjectContributor" date="1490124221" format="1.1" version="1"}%
%META:TOPICPARENT{name="AdminDocumentationCategory"}%
<noautolink>
---+!! Installation Guide
<div class='foswikiHelp' style='border:2px orange solid' >
This guide describes the steps for installing Foswiki, with __specific steps for installations on Linux with the Apache web server__.%BR%
If you would prefer to use a different web server, please refer to supplemental documentation when you reach the Apache-specific steps:
- * *Nginx:* [[https://foswiki.org/Support/FoswikiOnNginx][Foswiki on Nginx]]
+ * *Nginx:* [[https://foswiki.org/System/FastCGIEngineContrib#Nginx][FastCGIEngineContrib#Nginx]] and[[https://foswiki.org/Support/FoswikiOnNginx][Foswiki on Nginx]]
* *Lighttpd:* [[https://foswiki.org/Support/LighttpdBestPractice][Foswiki on Lighttpd]]
</div>
@@ -1,4 +1,4 @@
-%META:TOPICINFO{author="ProjectContributor" date="1458933734" format="1.1" version="1"}%
+%META:TOPICINFO{author="ProjectContributor" date="1490124221" format="1.1" version="1"}%
%META:TOPICPARENT{name="InstallationGuide"}%
---+!! Installation Guide Part 2
---++!! Post-Installation Configuration and Tuning
@@ -104,7 +104,7 @@ Foswiki is installed by default supporting standard CGI scripts as well as CLI a
%X% *Caution*
* Foswiki 2.0 can be "bootstrapped" with either of these accelerators active, however it is often simpler to initially configure Foswiki using CGI.
* The [[https://foswiki.org/Support/ApacheConfigGenerator][ApacheConfigGenerator]] will help creating a valid configuration for these accelerators.
- * Enabling the apache configuration without installing the pre-req modules and extensions will break your site!
+ * Enabling the apache configuration without installing the pre-req modules will break your site!
* The core default extensions are well tested with web acceleration, other extensions can exhibit inconsistent behaviour when accelerated.
---++++ Page Caching

0 comments on commit e002399

Please sign in to comment.