FreeBSD Configure Apache 2.2 PHP with FastCGI mod_fcgi Module

last updated in Categories , , , , ,

I‘d like to switch from mod_php5 to mod_fastcgi. I’m using FreeBSD 7 release along with following software:


+ Apache 2.2
+ PHP as mod_php5
+ MySQL DB 5.1.23 server
How do I configure php as FastCGI server?

mod_fcgid has a new process management strategy, which concentrates on reducing the number of fastcgi server, and kick out the corrupt fastcgi server as soon as possible. It is a binary compatibility alternative to Apache module mod_fastcgi; so your existing fastcgi programs do not need to be recompiled. mod_fcgid supports suEXEC.

Why run PHP5 as mod_fcgi / mod_fastcgi?

FastCGI as has some serious advantages over mod_php5:

  • You can do user level separations. You can enable quotas per user. Limit users by processes and CPU consumption.
  • chroot security call per user possible
  • According to several reports fastcgi works much faster than mod_php and cgi mode.

Step # 1: Install mod_fcgid

Make sure your ports are upto date:
# portsnap fetch update
Install mod_fcgid:
# cd /usr/ports/www/mod_fcgid
# make install clean

Make sure php supports FastCGI

Make sure php-cgi binary exists and it is compiled with fastcgi support:
# cd /usr/ports/lang/php5
# make showconfig | grep -i FASTCGI


FASTCGI=on "Enable fastcgi support (CGI only)"

Another way to test fastcgi support, enter:
# /usr/local/bin/php-cgi -v

PHP 5.2.5 with Suhosin-Patch (cgi-fcgi) (built: Mar  6 2008 09:15:41)
Copyright (c) 1997-2007 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2007 Zend Technologies

If you don’t see word cgi-fcgi, recompile php with fastcgi support by visiting /usr/ports/lang/php5
# cd /usr/ports/lang/php5
# make config
# make install clean

Step # 3: Load mod_fcgi module

Open your httpd.conf file located at /usr/local/etc/apache22/ directory:
# vi /usr/local/etc/apache22/httpd.conf
Load mod_fcgi module:
LoadModule fcgid_module libexec/apache22/
Configure mod_fcgi

<IfModule mod_fcgid.c>
    AddHandler fcgid-script .fcgi
    FCGIWrapper /usr/local/bin/php-cgi .php

Find your DocumentRoot directory configuration option that read as follows:

<Directory "/usr/local/www/apache22/data">

Append following two lines:
SetHandler fcgid-script
FCGIWrapper /usr/local/bin/php-cgi .php
Options ExecCGI

At the end configuration should read as follows:

# This should be changed to whatever you set DocumentRoot to.
<Directory "/usr/local/www/apache22/data">
    Options Indexes FollowSymLinks
    AllowOverride None
    Order allow,deny
    SetHandler fcgid-script
    FCGIWrapper /usr/local/bin/php-cgi .php
    Options ExecCGI
  Allow from all

Step # 4: Disable mod_php5

Find line that read as follows:
LoadModule php5_module libexec/apache22/
Comment out line:
#LoadModule php5_module libexec/apache22/
Also make sure following two line (mime type) exists:
AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .phps

Save and close the file.

Step # 5: Restart Apache22

Finally, restart apache web server:
# /usr/local/etc/rc.d/apache22 restart

Step # 5: Test mod_fcgi

Use following small program to verify mod_fcgi is working properly:


You must see Server API as CGI/FastCGI as well as following screen:
FreeBSD PHP5 mod_fcgi
(Fig. 01: PHP5 Configured as FastCGI using mod_fcgi)

Further readings:

Updated for accuracy.


Posted by: Vivek Gite

The author is the creator of nixCraft and a seasoned sysadmin, DevOps engineer, and a trainer for the Linux operating system/Unix shell scripting. Get the latest tutorials on SysAdmin, Linux/Unix and open source topics via RSS/XML feed or weekly email newsletter.

21 comment

  1. What I’m missing in this article is why not to use fcgi.
    The most important reason to stick to the module, is when your site requires settings through php_value/php_flag apache configuration directives.
    For example, I have several aliases and virtual hosts use different include_paths.
    I now have to combine them in the system’s php.ini or maybe use php-cgi -c if the FCGIWrapper statement allows this.
    Also, you’re missing the:
    # cd /usr/ports/www/mod_fcgid

    Great article though, thanks for writing it up :)

  2. Mel,

    Thanks for pointing out /usr/ports/www/mod_fcgid. Yes -c is the best option for virtual hosting. You can always write your own FCGIWrapper if you want.

  3. Ok, I just got done troubleshooting why all documents were passed to php-cgi and as a result causing images and css to not be displayed, since php-cgi has no idea how to process png images :).

    So, simplified:
    . AddHandler binds a handler to a file extension
    . SetHandler binds the context location to a handler.

    [notice] mod_fcgid: process /usr/local/www/phpPgAdmin/images/themes/default/title.png(2905) exit(communication error), terminated by calling exit(), return code: 255

  4. @root user ,

    No I did not missed /usr/ports/www/mod_fcgid. Please read it carefully. Do you get any sort of error?

  5. Thanks for posting this Vivek …. While I was able to get the fastCGI to work with PHP by following your instructions, it broke something else and was wondering if you had any ideas.

    I now longer can access my regular webpages under the DocumentRoot as I am receiving the following error :

    You don’t have permission to access / on this server.

    Please note that the command: apachectl status also gives me the same error.

    I found that when I comment out the following three lines nested within the Directory directive, my apache doesn’t error out:

    SetHandler fcgid-script
    FCGIWrapper /usr/local/bin/php-cgi .php
    Options ExecCGI

    The /var/log/httpd-error.log reads:

    [warn] Init: Session Cache is not configured [hint: SSLSessionCache]
    [notice] Digest: generating secret for digest authentication …
    [notice] Digest: done
    [notice] Apache/2.2.6 (FreeBSD) mod_ssl/2.2.6 OpenSSL/0.9.8e DAV/2 configured — resuming normal operations

    I’m running Apache 2.2.6 against FreeBSD 7.0

    Could it be file or directory permissions ? If you have any suggestion, I’d be happy to hear them.



  6. I followed the directions exactly and this does not work properly. The only thing close I can get working properly is fcgid and when I disable the php5 module, virtual hosting goes for an absolute crapper. I also could not get the CGI/FastCGI to show up in phpinfo.php. I could however get fcgid to work.

  7. I have problem when i start apache

    srv# apachectl start
    Syntax error on line 187 of /usr/local/etc/apache22/httpd.conf:
    Invalid command ‘FCGIWrapper’, perhaps misspelled or defined by a module not included in the server configuration

    I running in FreeBSD 7.2 and Apache 2.2.11. How to fix it?


  8. Did you added the following to your config file?

    LoadModule fcgid_module libexec/apache22/
  9. yes. I added in httpd.conf. look like this right?

    LoadModule rewrite_module libexec/apache22/
    LoadModule fastcgi_module libexec/apache22/
    #LoadModule php5_module libexec/apache22/


  10. Oh! i get it…

    This right?
    LoadModule fcgid_module libexec/apache22/

    and This wrong?
    LoadModule fastcgi_module libexec/apache22/

  11. Great post! Thanks!

    Have you ever got this setup running in a jail? I’m getting a “not implemented” error preventing apache from starting, but only in jailed environments.

  12. @Fred,

    Yes, I’m running in FreeBSD jail without any problem. Are you talking about chroot(2) based jail or FreeBSD jail(8) or mod_chroot?

  13. Hello,

    thank you for this article. I have followed every step.

    no errors at apache22 startup, but can’t get working .html files, only php is working via fcig.

    when I enter http://url/index.php is ok, when I enter http://url/index.html got 500 error. File permisions is ok 644 and owner is ok ( same as index.php )

    where I’m wrong?

    Thank you

  14. i have the same probleme that found by SSJ, when i open index.php its ok, but if i open index.html i have 500 error. this is my dir_module on httpd.conf

    DirectoryIndex index.html index.shtml index.cgi index.php

    thanks before

  15. This is an oldish thread, but I had to comment on some ‘Whys?” rather than the list of “Hows?”.

    It is a common myth that mod_php is slower – it is faster in real world applications, but *only just* compared to fcgid. fgcid + eAccelerator is demonstrably fractionally slower than mod_php + eAccelerator. So why not just use mod_php? The answer is two fold.

    1. There are more security options using fcgid. This is only relevant when you have untrusted user scripts such as found in hosting environments.
    2. You can use worker-mpm on Apache. Let’s face it, Apache is still in the Stone-Age when it comes to threading. Worker-mpm improves resource utilization on high traffic sites significantly, but mod_php in such a configuration is not guaranteed. The reason is not mod_php (which is thread-safe) but all the various extensions you may use with it (which are often not thread-safe). By using mod_fcgid you can use threaded apache and not worry about php extension thread-safety.

    In the real-world I use both mod_php and fcgid depending on my requirements. mod_php for my mercurial server that is heavily fortified and has a limited user base, and mod_fcgid for load balanced high-performance sites, 80,000 or more hits per minute, where the pre-fork model is just not tenable.

    Real Story: A existing website with a following of more than 130,000 registered users and an awful lot of lurkers was re-engineered to not only look more modern but also link into a vast number of business processes. The site went live, and every one of the user base hit it in the first five minutes after launch. Despite the number of servers and virtual servers in the cluster the pre-fork model simply could not cope. Switching to worker-mpm handled the load easily, but some of the apache instances crashed randomly. Changing to use fcgid rather than mod_php sorted the crashing issue. I never did get an an answer as to which php optional extension (we used a lot of them) caused the issue. Now there’s a task for someone with time on their hands! :-)

  16. [Thu Feb 23 03:55:46 2012] [emerg] (78)Function not implemented: mod_fcgid: Can’t create shared memory for size 1192488 bytes

    I keep get this error as soon as I do LoadModule

  17. I looked at dozens of web sites on how to setup apache 2.2 + php 5.3 + mod_fcgi in centos linux and this is the only one that works for me. Thanks so much.

    Still, have a question? Get help on our forum!