Configuration

class plinth.config.DropinConfigs(component_id, etc_paths=None, copy_only=False)

Component to manage config files dropped into /etc.

When configuring a daemon, it is often simpler to ship a configuration file into the daemon’s configuration directory. However, if the user modifies this configuration file and freedombox ships a new version of this configuration file, then a conflict arises between user’s changes and changes in the new version of configuration file shipped by freedombox. This leads to freedombox package getting marked by unattended-upgrades as not automatically upgradable. Dpkg’s solution of resolving the conflicts is to present the option to the user which is also not acceptable.

Further, if a package is purged from the system, sometimes the configuration directories are fully removed by deb’s scripts. This removes files installed by freedombox package. Dpkg treats these files as if user has explictly removed them and may lead to a configuration conflict described above.

The approach freedombox takes to address these issues is using this component. Files are shipped into /usr/share/freedombox/etc/ instead of /etc/ (keeping the subpath unchanged). Then when an app is enabled, a symlink or copy is created from the /usr/share/freedombox/etc/ into /etc/. This way, user’s understand the configuration file is not meant to be edited. Even if they do, next upgrade of freedombox package will silently overwrite those changes without causing merge conflicts. Also when purging a package removes entire configuration directory, only symlinks/copies are lost. They will recreated when the app is reinstalled/enabled.

__init__(component_id, etc_paths=None, copy_only=False)

Initialize the drop-in configuration component.

component_id should be a unique ID across all components of an app and across all components.

etc_paths is a list of all drop-in configuration files as absolute paths in /etc/ which need to managed by this component. For each of the paths, it is expected that the actual configuration file exists in /usr/share/freedombox/etc/. A link to the file or copy of the file is created in /etc/ when app is enabled and the link or file is removed when app is disabled. For example, if etc_paths contains /etc/apache/conf-enabled/myapp.conf then /usr/share/freedombox/etc/apache/conf-enabled/myapp.conf must be shipped and former path will be link to or be a copy of the latter when app is enabled.

diagnose()

Check all links/copies and return generate diagnostic results.

disable()

Remove the links/copies in /etc/ of the configuration files.

enable()

Create a symlink or copy in /etc/ of the configuration file.

setup(old_version)

Create symlinks or copies of files during app update.

During the transition from shipped configs to the symlink/copy approach, files in /etc will be removed during .deb upgrade. This method ensures that symlinks or copies are properly recreated.