"Curiosity is the very basis of education and if you tell me that curiosity killed the cat, I say only the cat died nobly." - Arnold Edinborough

The nginx source install (and by extension package managers) includes two FastCGI configuration files, fastcgi_params and fastcgi.conf that differ only a tiny bit. To this day, they still cause confusion amongst new users due to package managers.

The difference between the two files in the source install is the simple line of:

fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

The difference between the two files in most distribution’s package repositories is nothing, they essentially modified fastcgi_params to match fastcgi.conf.

What this line does is tell PHP which file it should execute, without this nginx and PHP cannot work together. This sounds like a good line to include in the shipped FastCGI configuration file and indeed, Igor Sysoev thought so as well. However, due to the configurations of the time, this wasn’t as easy as simply adding it in.

Back in the days of 0.6.x when I started using nginx and a few years before this change happened a typical configuration example would look like this.

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME /var/www/foo$fastcgi_script_name;
    fastcgi_pass backend;

Due to community documentation efforts on the wiki people slowly started using the $document_root variable instead of hard coding the root path, however, many people were still using the above configuration many years later.

Because of how array directives inherit and interact the people using the old configuration style made it impossible to include the line in fastcgi_params. Doing this would have meant that SCRIPT_FILENAME would be defined twice and both would be sent to the backend, potentially causing confusing behaviour.

In 0.8.30 (released: 15th of December 2009) Igor then included fastcgi.conf which was the same as fastcgi_params except including the improved SCRIPT_FILENAME fastcgi_param. This meant that the community could now start recommending people include fastcgi.conf instead of recommending moving SCRIPT_FILENAME into fastcgi_params. New articles on the wiki mostly used this, the popular articles were slowly changed to use it and we were promoting it in the IRC support channel.

Of course, an issue back then was that package managers gave nginx very little love and were many versions behind, usually something like 0.6.x versus 0.8.x. The fastcgi.conf file was not included for these people. When they eventually did update they shipped with a fastcgi.conf and a modified fastcgi_params leaving us with a situation where the source install actually differed from the repository install in a non-significant way. While not often, this does still cause the occasional confusion in the IRC channel.

As an aside, I actually prefer

fastcgi_param SCRIPT_FILENAME $request_filename;

as it takes the alias directive into account, fastcgi_new.conf anyone?

  • Jonathan Silverblood

    Posted: May 6, 2016

    I have spent almost a full workday trying to get the nginxphp connection working when using alias and to more time that passed, and the more time I read, the more complex and needlessly convoluted experiments I've tried, and then I read this.

    Thanks for clarifying the issue, the background and providing a suggestion for an alternative management of this variable. Reply

  • Hugh Secker-Walker

    Posted: November 18, 2016

    Hey thanks for the insightful post.

    And, your aside at the end about $request_filename being alias aware has solved a problem I've been stumbling around for some hours now! So thanks for that gem too! Reply

  • Philip Kupsch

    Posted: September 13, 2017

    Thank you for the well-written and explained blog for Nginx and for the suggestion of $request_filename. Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

This site uses Akismet to reduce spam. Learn how your comment data is processed.