Guidelines on handling configuration upgrades in packages

Inperpetuammemoriam

Are there any guidelines on how to handle changes concerning the configuration of a package?

I saw that for the core there is code referenced in the Developer Syle Guide that handles such cases in order to guarantee a clean config with no obsolete values after an upgrade.

Is there an equivalent or any other convention that should be compiied with when modifying package configurations?

bmeeks

Are you asking from the point of view of a package developer, or a user?

If developer, there is a post-install hook you can utilize that will cause the package install/re-install process in pfSense to call a PHP function or load and execute a PHP code module right before the package install (or re-install) terminates. That's where you would put code to make any necessary configuration upgrades, and do any other post-install housekeeping your package might require.

You include the reference to your post-install routine in your package manifest's XML file. Here is an example for the Snort package: https://github.com/pfsense/FreeBSD-ports/blob/devel/security/pfSense-pkg-snort/files/usr/local/pkg/snort.xml.

Notice this section near the bottom:

<custom_php_install_command>
		<![CDATA[
		include_once("/usr/local/pkg/snort/snort_post_install.php");
		]]>
	</custom_php_install_command>

That signals pfSense to load and execute the snort_post_install.php code just before the installation process ends. Within that module I included a call to a "configuration migration" section of code that makes any required configuration updates (new parameters, deprecation of old values, etc.).

Inperpetuammemoriam

I'm asking from the developer perspective.

Thanks! That should answer my question.

bmeeks

@inperpetuammemoriam said in Guidelines on handling configuration upgrades in packages:

I'm asking from the developer perspective.

Thanks! That should answer my question.

And there is also a package uninstall hook you can use if you need to clean up things your package might otherwise leave on a system. The one caveat with this hook is it gets called for a reinstall of a package as well as during an uninstall, and you can't tell which is happening. So you have to be careful what you clean up. This can be an issue if the user is simply reinstalling your package and not permanently removing it. The reinstall begins by removing the package, then installs it again. It would be neat if the package could get a hint of whether the user chose "reinstall" or "delete" from the Package Manager tab in pfSense. That's because some things you would rather leave be if it's just a reinstall of the package, while you would remove them on package deletion.

Inperpetuammemoriam

Thanks for the hint!