May 5 2021

A troubling issue with ports and configuration files

This short page is an attempt to illustrate a troubling issue with the ports and package system in FreeBSD, in anticipation of having to explain the issue multiple times. Consider the following statement in 8.6.9 of the porters handbook:

 ...on deinstallation, remove the actual [configuration] file if it has not been modified.

I would like to suggest that this behavior is harmful, and that no configuration files should ever be deleted under any circumstances. My canonical example is the nginx port, as many might be familiar with it. For our example, consider that the port provides these files:

• fastcgi_params-dist
• mime.types-dist

Some people will simply copy these files to their intended destinations, e.g.:

• cp fastcgi_params-dist fastcgi_params
• cp mime.types-dist mime.types

and then include them in nginx.conf just as the default nginx.conf illustrates:

include mime.types;
...
location ~ \.php$ {
     root  html;
     fastcgi_pass http//127.0.0.1:9000;               
     ...
     include fastcgi_params;
}              

So what happens in this example on a pkg upgrade, a common use case? According to the man page:

    Package reinstall or update jobs are processed by removing the currently installed package
    and immediately installing the replacement.                 

According to the statement in the porters handbook, the first removal will result in the removal of both fastcgi_params and mime.types. Besides being rather surprising, there is no apparent reason for removing those files ... even if the distribution sample files have changed. So what happens in the example above if you remove those files? That results in a previously working nginx configuration breaking after a pkg upgrade.

I would like to suggest a policy change here. Instead of removing the configuraiton file if it has not been modified, refrain from removing the configuration file altogether. I consider this to be the safest course of action, as there are some times where the distribution's configuration file needs to stay in place if copied there.

Thank you for reading.