summaryrefslogtreecommitdiff
path: root/doc/apt_preferences.5.xml
diff options
context:
space:
mode:
authorJulian Andres Klode <julian.klode@canonical.com>2020-08-10 20:16:11 +0200
committerJulian Andres Klode <julian.klode@canonical.com>2021-01-08 14:48:47 +0100
commitc5bc86d45e003905ef411146e66b414d26fb1ff8 (patch)
tree31c634c53df882a26dcbdb8b489c6c23101ec285 /doc/apt_preferences.5.xml
parent4d28ddc501738d571c21ff6d41168f6c53ea462d (diff)
Add support for Phased-Update-Percentage
This adds support for Phased-Update-Percentage by pinning upgrades that are not to be installed down to 1. The output of policy has been changed to add the level of phasing, and documentation has been improved to document how phased updates work. The patch detects if it is running in a chroot, and if so, always includes phased updates, restoring classic apt behavior to avoid behavioral changes on buildd chroots. Various options are added to control this all: * APT::Get::{Always,Never}-Include-Phased-Updates and their legacy update-manager equivalents to always or never include phased updates * APT::Machine-ID can be set to a UUID string to have all machines in a fleet phase the same * Dir::Etc::Machine-ID is weird in that it's default is sort of like ../machine-id, but not really, as ../machine-id would look up $PWD/../machine-id and not relative to Dir::Etc; but it allows you to override the path to machine-id (as opposed to the value) * Dir::Bin::ischroot is the path to the ischroot(1) binary which is used to detect whether we are running in a chroot.
Diffstat (limited to 'doc/apt_preferences.5.xml')
-rw-r--r--doc/apt_preferences.5.xml19
1 files changed, 18 insertions, 1 deletions
diff --git a/doc/apt_preferences.5.xml b/doc/apt_preferences.5.xml
index 4ef5282e7..23f2d2d6b 100644
--- a/doc/apt_preferences.5.xml
+++ b/doc/apt_preferences.5.xml
@@ -102,7 +102,8 @@ algorithm to set the priorities of the versions of a package. Assign:
<term>priority 1</term>
<listitem><simpara>to the versions coming from archives which in their <filename>Release</filename>
files are marked as "NotAutomatic: yes" but <emphasis>not</emphasis> as "ButAutomaticUpgrades: yes"
-like the Debian <literal>experimental</literal> archive.</simpara></listitem>
+like the Debian <literal>experimental</literal> archive.</simpara></listitem>,
+as well as versions that are not phased on this systems.
</varlistentry>
<varlistentry>
@@ -175,6 +176,22 @@ because at least <emphasis>one</emphasis> of the available versions has a higher
priority than the installed version.</para>
</refsect2>
+<refsect2><title>Phased Updates</title>
+<para>APT understands a field called <literal>Phased-Update-Percentage</literal>
+which can be used to control the rollout of a new version. It is an integer between
+0 and 100.</para>
+
+<para>A system's eligibility to a phased update is determined by seeding
+random number generator with the package source name, the version number,
+and /etc/machine-id, and then calculating an integer in the range [0, 100].
+If this integer is larger than the <literal>Phased-Update-Percentage</literal>,
+the version is pinned to 1, and thus held back. Otherwise, normal policy rules apply.
+</para>
+
+<para>In case you have multiple systems that you want to receive the same set of updates, you can set
+<code>APT::Machine-ID</code> to a UUID such that they all phase the same, or set <code>APT::Get::Never-Include-Phased-Updates</code>
+or <code>APT::Get::Always-Include-Phased-Updates</code> to true such that APT will never/always consider phased updates.</para>
+</refsect2>
<refsect2><title>The Effect of APT Preferences</title>
<para>The APT preferences file allows the system administrator to control the