fastcgi_params versus fastcgi.conf – nginx config history

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?

Last updated:Wednesday, April 26, 2017

This is the original address：fastcgi_params versus fastcgi.conf – nginx config history