fastcgi_params Versus fastcgi.conf – Nginx Config History

comment5 Comments

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.

So why does NGINX include both files?

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?

Related Posts

5 Comments. Leave new

  • Jonathan Silverblood
    May 6, 2016 19:54

    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.

  • Hugh Secker-Walker
    November 18, 2016 20:19

    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!

  • […] The fastcgi_params file has been available for a much longer period of time. In order avoid breaking configurations that relied on fastcgi_params, when the decision was made to provide a default value for SCRIPT_FILENAME, a new file needed to be created. Not doing so may have resulted in that parameter being set in both the common file and FastCGI pass location. This is described in great detail in Martin Fjordvald’s excellent post on the history of these two files. […]

  • Philip Kupsch
    September 13, 2017 04:23

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

  • Thanks, very insightful


Leave a Reply

Your email address will not be published. Required fields are marked *

Fill out this field
Fill out this field
Please enter a valid email address.