FreeBSD Configure Apache 2.2 PHP with FastCGI mod_fcgi Module

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:

(Fig. 01: PHP5 Configured as FastCGI using mod_fcgi)

Further readings:

Updated for accuracy.

🐧 Get the latest tutorials on Linux, Open Source & DevOps via RSS feed or Weekly email newsletter.

🐧 21 comments so far... add one

CategoryList of Unix and Linux commands
Disk space analyzersdf ncdu pydf
File Managementcat cp mkdir tree
FirewallAlpine Awall CentOS 8 OpenSUSE RHEL 8 Ubuntu 16.04 Ubuntu 18.04 Ubuntu 20.04
Network UtilitiesNetHogs dig host ip nmap
OpenVPNCentOS 7 CentOS 8 Debian 10 Debian 8/9 Ubuntu 18.04 Ubuntu 20.04
Package Managerapk apt
Processes Managementbg chroot cron disown fg jobs killall kill pidof pstree pwdx time
Searchinggrep whereis which
User Informationgroups id lastcomm last lid/libuser-lid logname members users whoami who w
WireGuard VPNAlpine CentOS 8 Debian 10 Firewall Ubuntu 20.04
21 comments… add one
  • Ionut Apr 9, 2008 @ 18:18

    thanks, nice.

    # portsanp fetch update

    has to be:

    # portsnap fetch update

  • 🐧 nixCraft Apr 9, 2008 @ 18:41

    Thanks for the heads up. The faq has been updated.

  • Mel May 17, 2008 @ 12:28

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

  • 🐧 nixCraft May 17, 2008 @ 14:45


    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.

  • Mel May 20, 2008 @ 15:43

    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

  • root user Jan 1, 2009 @ 16:45

    Sucks. Doesnt work. Why you missed /usr/ports/www/mod_fcgid part?

  • 🐧 nixCraft Jan 1, 2009 @ 17:07

    @root user ,

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

  • Binit Feb 14, 2009 @ 22:54

    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.



  • Borg Jun 11, 2009 @ 8:27

    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.

  • Anderson Jul 10, 2009 @ 8:43

    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?


  • 🐧 nixCraft Jul 10, 2009 @ 9:04

    Did you added the following to your config file?

    LoadModule fcgid_module libexec/apache22/
  • Anderson Jul 10, 2009 @ 9:54

    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/


  • Anderson Jul 10, 2009 @ 10:08

    Oh! i get it…

    This right?
    LoadModule fcgid_module libexec/apache22/

    and This wrong?
    LoadModule fastcgi_module libexec/apache22/

  • Fred Aug 8, 2009 @ 18:58

    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.

  • 🐧 nixCraft Aug 8, 2009 @ 19:04


    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?

    • nsamu Jan 3, 2011 @ 18:56

      I receive the same error. I am running a FreeBSD jail created using ezjajil.

  • SSJ Jun 30, 2010 @ 10:28


    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

  • yudanta Oct 19, 2010 @ 4:29

    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

  • Aeomer Nov 10, 2011 @ 14:20

    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! :-)

  • alexus Feb 23, 2012 @ 3:58

    [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

  • Bruce Kirkpatrick Jun 22, 2012 @ 15:50

    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.

Leave a Reply

Your email address will not be published.

Use HTML <pre>...</pre> for code samples. Still have questions? Post it on our forum