From Fedora Project Wiki
(Existing page)
 
(New packaging approach)
Line 1: Line 1:
 
= Fedora.next Per-Product Configuration Packaging =
 
= Fedora.next Per-Product Configuration Packaging =
 
This is an interim solution for Fedora 21 only. Work is in progress for Fedora 22 to simplify this using the new advanced dependencies available in RPM 4.11 and later
 
  
 
== Goals ==
 
== Goals ==
In the Fedora.next world, we will have a set of curated Fedora Products as well as the availability of classic Fedora. Historically, we have maintained a single set of configuration defaults for all Fedora installs, but different target use-cases have different needs. The goal of this document is to set out the guidelines for creating per-Product configuration defaults.
+
In the Fedora.next world, we have a set of curated Fedora Products as well as the availability of classic Fedora. Historically, we have maintained a single set of configuration defaults for all Fedora installs, but different target use-cases have different needs. The goal of this document is to set out the guidelines for creating per-Product configuration defaults.
  
 
We want to ensure that all packages have sensible defaults for whichever Product on which they are installed, while also avoiding situations where users would have some packages installed with one Product's defaults and some packages with another.
 
We want to ensure that all packages have sensible defaults for whichever Product on which they are installed, while also avoiding situations where users would have some packages installed with one Product's defaults and some packages with another.
Line 12: Line 10:
  
 
<b>Fedora.next</b>: Umbrella term for planning Fedora's future. Currently covering the creation of the Fedora Products, Fedora Base Design and Fedora Environments and Stacks.<br>
 
<b>Fedora.next</b>: Umbrella term for planning Fedora's future. Currently covering the creation of the Fedora Products, Fedora Base Design and Fedora Environments and Stacks.<br>
<b>$PRODUCT</b>: One of the Fedora.next Product deliverables, currently "cloud", "server" and "workstation".<br>
+
<b>$PRODUCT</b>: One of the Fedora.next Product deliverables, currently "Cloud", "Server" and "Workstation".<br>
<b>yum/dnf</b>: Package managers for Fedora used for installing and updating software.<br>
 
  
== Sub-package definition ==
+
 
{{admon/warning|These guidelines are not needed for all packages|Only packages whose defaults differ between Fedora Products are required to follow these instructions. Packages whose configuration is the same for all products can simply install the config files as they normally would.}}
+
== Per-product Configuation Packaging ==
 +
{{admon/warning|These guidelines are not needed for all packages|Only packages whose defaults differ between Fedora Products are required to follow these instructions. Packages whose configuration is the same for all products can simply install the config files as they normally would.}}
  
 
=== Requirements ===
 
=== Requirements ===
 
* All packages <b>must</b> have a global default configuration. This configuration will be used whenever a Product-specific default configuration is not required. (For example, if a non-Product install is in use or only Fedora Cloud has a custom configuration and Fedora Workstation was installed).
 
* All packages <b>must</b> have a global default configuration. This configuration will be used whenever a Product-specific default configuration is not required. (For example, if a non-Product install is in use or only Fedora Cloud has a custom configuration and Fedora Workstation was installed).
* Any package that requires a per-product default configuration <b>must</b> provide a sub-package containing that configuration.
+
* Any package that requires a per-product default configuration <b>must</b> provide all alternate configuration files in the same package.
** Such packages <b>must</b> "Requires: foo-config" which will be provided by the configuration sub-package.
 
 
* Any package that requires a configuration that differs between Products <b>must</b> obtain permission from that Product's Working Group before packaging it.
 
* Any package that requires a configuration that differs between Products <b>must</b> obtain permission from that Product's Working Group before packaging it.
  
 
=== Global Default Configuration ===
 
=== Global Default Configuration ===
* The global default configuration <b>must</b> be specified by a sub-package named "foo-config-standard", where foo is the base package name.
+
* The global default configuration <b>must</b> be provided by the package that requires it.
* The global default configuration sub-package <b>must</b> "Requires: foo = %{version}-%{release}" (or appropriate variant including epoch)
+
* The global default configuration <b>must</b> be named based on the package's normal naming scheme, with the main part of the name being suffixed by -default. For example, if the package normally uses foo.conf, then the global default configuration must be named foo-default.conf
* The global default configuration sub-package <b>must</b> include a virtual "Provides: foo-config"
 
* The global default configuration sub-package <b>must</b> explicitly "Conflicts: system-release-$PRODUCT" for all Products for which there exists a separate configuration.
 
* The global default configuration sub-package <b>must</b> explicitly "Conflicts: foo-config-$PRODUCT" for all Products for which there exists a separate configuration.
 
  
 
=== Per-Product Default Configuration ===
 
=== Per-Product Default Configuration ===
* For each Product requiring a unique default configuration, the packager <b>must</b> provide a sub-package named "foo-config-$PRODUCT", where foo is the base package name and $PRODUCT is the Fedora Product in question. If the global default is sufficient, the packager <b>must not</b> create a Product-specific sub-package.
+
* For each Product requiring a unique default configuration, the packager <b>must</b> provide a copy of the default configuration file, modified as appropriate for the specific product.
* Each Product sub-package <b>must</b> include a virtual "Provides: foo-config".
+
* The product-specific configuration file must be named based on the package's normal naming scheme, with the main part of the name being suffixed by -$product. For example, if the package normally uses foo.conf, then the Server version must be named foo-server.conf.
* Each Product sub-package <b>must</b> "Requires: foo = %{version}-%{release}" (or appropriate variant including epoch)
 
* Each Product sub-package <b>must</b> "Requires: system-release-$PRODUCT", for the matching Product.
 
* Each Product sub-package <b>must</b> explicitly "Conflicts: foo-config-standard"
 
* Each Product sub-package <b>must</b> explicitly "Conflicts: foo-config-$PRODUCT" for all other Products for which there exists a separate configuration.
 
  
{{admon/warning|RPM Limitation|RPM does not currently have the ability to provide [http://rpm.org/ticket/874 separate installroots for different subpackages]. You will need to create separate config files for each product in the installroot and symlink them in the %post section for that Product}}
+
=== Applying Configuration ===
 +
In order to apply the configuration, the packager must implement a mechanism in the <code>%posttrans</code> section of the specfile that behaves as follows:
 +
* It must first check whether the final config file already exists. If so, the script <b>must</b> make no changes.
 +
<pre>
 +
%posttrans
 +
if [ \! -e %{_sysconfdir}/foo/foo.conf ]; then
 +
    ...
 +
fi
 +
</pre>
 +
* It must then attempt to read the <code>VARIANT</code> attribute from <code>/etc/os-release</code>
 +
<pre>
 +
variant=$(awk -F "=" '/VARIANT/ {print $2}' /etc/os-release) || :
 +
</pre>
 +
* Lastly, it must use the value of the <code>VARIANT</code> to symlink one of the divergent config files (or the default) to the final config file location.
 +
<pre>
 +
    case $variant in
 +
        "Server")
 +
            ln -sf foo-server.conf %{_sysconfdir}/foo/foo.conf || :
 +
            ;;
 +
        *)
 +
            ln -sf foo-default.conf %{_sysconfdir}/foo/foo.conf
 +
            ;;
 +
        esac
 +
</pre>
  
 
=== Example (firewalld) ===
 
=== Example (firewalld) ===
Line 45: Line 58:
  
 
<pre>
 
<pre>
 +
%posttrans
 +
# If we don't yet have a symlink or existing file for firewalld.conf,
 +
# create it. Note: this will intentionally reset the policykit policy
 +
# at the same time, so they are in sync.
 +
if [ \! -e %{_sysconfdir}/firewalld/firewalld.conf ]; then
 +
    # Select the default config file based on /etc/os-release
 +
    variant=$(awk -F "=" '/VARIANT/ {print $2}' /etc/os-release) || :
  
Name: firewalld
+
    # Make sure that we remove any dangling links
Version: 0.3.10
+
    rm -f %{_sysconfdir}/firewalld/firewalld.conf || :
Release: 1{?dist}
+
    rm -f %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || :
Requires: firewalld-config
 
 
 
%package config-standard
 
Summary: Firewalld standard configuration settings
 
Provides: firewalld-config
 
Requires: firewalld = %{version}-%{release}
 
Conflicts: system-release-server
 
Conflicts: firewalld-config-server
 
Conflicts: system-release-workstation
 
Conflicts: firewalld-config-workstation
 
 
 
%package config-server
 
Summary: Firewalld server configuration settings
 
Provides: firewalld-config
 
Requires: firewalld = %{version}-%{release}
 
Requires: system-release-server
 
Conflicts: firewalld-config-workstation
 
Conflicts: firewalld-config-standard
 
 
 
%package config-workstation
 
Summary: Firewalld workstation configuration settings
 
Provides: firewalld-config
 
Requires: firewalld = %{version}-%{release}
 
Requires: system-release-workstation
 
Conflicts: firewalld-config-server
 
Conflicts: firewalld-config-standard
 
 
 
%files config-standard
 
%ghost %config(noreplace) %{_sysconfdir}/firewalld.conf
 
%config(noreplace) %{_sysconfdir}/firewalld-standard.conf
 
 
 
%files config-server
 
%ghost %config(noreplace) %{_sysconfdir}/firewalld.conf
 
%config(noreplace) %{_sysconfdir}/firewalld-server.conf
 
 
 
%files config-workstation
 
%ghost %config(noreplace) %{_sysconfdir}/firewalld.conf
 
%config(noreplace) %{_sysconfdir}/firewalld-workstation.conf
 
  
%post config-standard
+
    case $variant in
if [ $1 -eq 1 ]; then
+
        "Server")
    rm -f %{_sysconfdir}/firewalld/firewalld.conf
+
            ln -sf firewalld-server.conf %{_sysconfdir}/firewalld/firewalld.conf || :
    ln -sf %{_sysconfdir}/firewalld/firewalld-standard.conf %{_sysconfdir}/firewalld/firewalld.conf
+
            ln -sf org.fedoraproject.FirewallD1.server.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || :
 +
            ;;
 +
        "Workstation")
 +
            ln -sf firewalld-workstation.conf %{_sysconfdir}/firewalld/firewalld.conf || :
 +
            ln -sf org.fedoraproject.FirewallD1.desktop.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || :
 +
            ;;
 +
        *)
 +
            ln -sf firewalld-default.conf %{_sysconfdir}/firewalld/firewalld.conf
 +
            # The default firewalld policy will be the same as Server
 +
            ln -sf org.fedoraproject.FirewallD1.server.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || :
 +
            ;;
 +
        esac
 
fi
 
fi
  
%post config-server
 
if [ $1 -eq 1 ]; then
 
    rm -f %{_sysconfdir}/firewalld/firewalld.conf
 
    ln -sf %{_sysconfdir}/firewalld/firewalld-server.conf %{_sysconfdir}/firewalld/firewalld.conf
 
fi
 
 
%post config-workstation
 
if [ $1 -eq 1 ]; then
 
    rm -f %{_sysconfdir}/firewalld/firewalld.conf
 
    ln -sf %{_sysconfdir}/firewalld/firewalld-workstation.conf %{_sysconfdir}/firewalld/firewalld.conf
 
fi
 
 
</pre>
 
</pre>
  
== Reasoning ==
 
 
The configuration sub-packages Requires: the main package in order to guarantee that they always update together (since the reverse dependency is not versioned).
 
 
The version comparison algorithm used by yum will attempt to resolve the dependencies through whichever one best matches the Requires/Conflicts or whichever one will install the fewest dependencies. This should result in the appropriate Product configuration being installed or the standard configuration as the fallback.
 
 
 
== References ==
 
* http://yum.baseurl.org/wiki/CompareProviders
 
  
[[Category:Packaging guidelines]]
+
[[Category:Packaging guidelines drafts]]

Revision as of 18:16, 27 March 2015

Fedora.next Per-Product Configuration Packaging

Goals

In the Fedora.next world, we have a set of curated Fedora Products as well as the availability of classic Fedora. Historically, we have maintained a single set of configuration defaults for all Fedora installs, but different target use-cases have different needs. The goal of this document is to set out the guidelines for creating per-Product configuration defaults.

We want to ensure that all packages have sensible defaults for whichever Product on which they are installed, while also avoiding situations where users would have some packages installed with one Product's defaults and some packages with another.


Definitions

Fedora.next: Umbrella term for planning Fedora's future. Currently covering the creation of the Fedora Products, Fedora Base Design and Fedora Environments and Stacks.
$PRODUCT: One of the Fedora.next Product deliverables, currently "Cloud", "Server" and "Workstation".


Per-product Configuation Packaging

Warning.png
These guidelines are not needed for all packages
Only packages whose defaults differ between Fedora Products are required to follow these instructions. Packages whose configuration is the same for all products can simply install the config files as they normally would.

Requirements

  • All packages must have a global default configuration. This configuration will be used whenever a Product-specific default configuration is not required. (For example, if a non-Product install is in use or only Fedora Cloud has a custom configuration and Fedora Workstation was installed).
  • Any package that requires a per-product default configuration must provide all alternate configuration files in the same package.
  • Any package that requires a configuration that differs between Products must obtain permission from that Product's Working Group before packaging it.

Global Default Configuration

  • The global default configuration must be provided by the package that requires it.
  • The global default configuration must be named based on the package's normal naming scheme, with the main part of the name being suffixed by -default. For example, if the package normally uses foo.conf, then the global default configuration must be named foo-default.conf

Per-Product Default Configuration

  • For each Product requiring a unique default configuration, the packager must provide a copy of the default configuration file, modified as appropriate for the specific product.
  • The product-specific configuration file must be named based on the package's normal naming scheme, with the main part of the name being suffixed by -$product. For example, if the package normally uses foo.conf, then the Server version must be named foo-server.conf.

Applying Configuration

In order to apply the configuration, the packager must implement a mechanism in the %posttrans section of the specfile that behaves as follows:

  • It must first check whether the final config file already exists. If so, the script must make no changes.
%posttrans
if [ \! -e %{_sysconfdir}/foo/foo.conf ]; then
    ...
fi
  • It must then attempt to read the VARIANT attribute from /etc/os-release
variant=$(awk -F "=" '/VARIANT/ {print $2}' /etc/os-release) || :
  • Lastly, it must use the value of the VARIANT to symlink one of the divergent config files (or the default) to the final config file location.
    case $variant in
        "Server")
            ln -sf foo-server.conf %{_sysconfdir}/foo/foo.conf || :
            ;;
        *)
            ln -sf foo-default.conf %{_sysconfdir}/foo/foo.conf
            ;;
        esac

Example (firewalld)

We will assume for the sake of demonstration that firewalld will need a custom configuration for Fedora Server and Fedora Workstation, but that Fedora Cloud will not require any changes from the global default.

%posttrans
# If we don't yet have a symlink or existing file for firewalld.conf,
# create it. Note: this will intentionally reset the policykit policy
# at the same time, so they are in sync.
if [ \! -e %{_sysconfdir}/firewalld/firewalld.conf ]; then
    # Select the default config file based on /etc/os-release
    variant=$(awk -F "=" '/VARIANT/ {print $2}' /etc/os-release) || :

    # Make sure that we remove any dangling links
    rm -f %{_sysconfdir}/firewalld/firewalld.conf || :
    rm -f %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || :

    case $variant in
        "Server")
            ln -sf firewalld-server.conf %{_sysconfdir}/firewalld/firewalld.conf || :
            ln -sf org.fedoraproject.FirewallD1.server.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || :
            ;;
        "Workstation")
            ln -sf firewalld-workstation.conf %{_sysconfdir}/firewalld/firewalld.conf || :
            ln -sf org.fedoraproject.FirewallD1.desktop.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || :
            ;;
        *)
            ln -sf firewalld-default.conf %{_sysconfdir}/firewalld/firewalld.conf
            # The default firewalld policy will be the same as Server
            ln -sf org.fedoraproject.FirewallD1.server.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || :
            ;;
        esac
fi