Configuration File Upgrade Handling

Configuration File Upgrade Handling is the process by which the Pacman package manager manages changes to configuration files when packages are upgraded. It ensures that user-modified configuration files are preserved, while allowing package maintainers to provide updated default configuration files. This handling prevents overwriting important customizations and avoids configuration conflicts during package upgrades.

Principles of Configuration File Upgrade Handling

Preservation of User Modifications

When a package upgrade includes changes to configuration files, Pacman compares the existing configuration files on the system with the new ones provided by the package. If the existing file has been modified by the user, Pacman avoids overwriting it directly to prevent loss of custom settings.

Delivery of Updated Configuration Files

If the package maintainer has updated the configuration file, the new version needs to be delivered to the system. However, because the existing file may have local modifications, the new configuration file is typically saved separately to allow manual review and merging.

User Interaction and Automation

Pacman can be configured to either prompt the user during upgrades when configuration file conflicts occur or to follow automated policies such as:

• Always keeping the local configuration file.
• Always replacing with the new version.
• Renaming the new file with specific extensions for manual merging.

Mechanisms for Handling Configuration File Upgrades

File Marking and Identification

Pacman uses the .pacnew extension to indicate new configuration files installed during package upgrades when a conflicting local configuration file exists. This allows administrators to identify what has changed without losing their local settings.

For example, if /etc/example.conf is modified locally, the upgraded package will place the new default file as /etc/example.conf.pacnew.

Merging and Manual Review

The presence of .pacnew files requires the system administrator or user to review differences between the current configuration and the new default. Tools such as diff, vimdiff, or specialized merge utilities can be used to reconcile changes.

Handling Obsolete Configuration Files

Sometimes configuration files are removed or renamed upstream in package updates. Pacman may place obsolete configuration files with a .pacsave extension to preserve the user's last version before removal. This prevents accidental data loss.

Configuration Options Affecting Upgrade Handling

NoUpgrade Option

Within the package's .PKGINFO or packaging scripts, files can be marked with the NoUpgrade flag to prevent them from being replaced or renamed during upgrades. This is typically used for files that should remain untouched once installed.

Pacman Configuration File Settings

In /etc/pacman.conf, the NoUpgrade and NoExtract options can be specified under the [options] section to control upgrade behaviors globally or on a per-package basis, refining how configuration files are treated.

Hooks and User Scripts

Pacman supports hooks that can run before or after package operations. Administrators can create scripts to automatically merge .pacnew files or notify users when configuration files require attention.

Best Practices for Managing Configuration File Upgrades

Regular Review of .pacnew and .pacsave Files

System maintainers should regularly check for .pacnew and .pacsave files, especially after system upgrades, to ensure that configuration changes are integrated appropriately and obsolete files are cleaned up.

Using Version Control for Configuration Files

Storing /etc or other configuration directories under version control (e.g., git) allows tracking changes, merging updates safely, and reverting problematic configurations.

Automating Merges with Tools

Utilities like etckeeper or custom merge scripts can be used to automate the management of configuration file changes, reducing manual overhead and mistakes.

Summary of File Extensions Used in Upgrade Handling

Example Scenario

When upgrading a package foo, the package includes a configuration file /etc/foo.conf. The user has modified this file. Upon upgrade:

• Pacman detects the existing modified /etc/foo.conf.
• Instead of overwriting it, Pacman installs /etc/foo.conf.pacnew.
• The user is notified about the .pacnew file.
• The user compares /etc/foo.conf and /etc/foo.conf.pacnew using diff or vimdiff.
• After merging necessary changes, the user replaces /etc/foo.conf with the updated configuration.
• The .pacnew file may then be deleted.

Summary

Configuration File Upgrade Handling in Pacman is a careful process designed to balance the integrity of user-customized configurations with the need to deploy updated package defaults. By using automatic detection, renaming conventions, and configurable policies, Pacman minimizes configuration conflicts and empowers administrators to maintain system stability and security during package upgrades.