Hi, On 25-03-2019 22:13, Paul Gevers wrote: > On 24-03-2019 23:27, Justin B Rye wrote: >> Also, when we first mention APT configuration we need to set out what >> we mean by "APT source-list files", if only by pointing at >> sources.list(5). > > I wanted to link to that man page as well, so let's find a place. I'm > nearly of to bed now, so if you find a good spot before I do tomorrow, > don't hesitate to mail. I have added a link to the manpages (3 places), but I am not totally happy with how it reads. What do you think? Paul
From 710a6ac851e47e6952087aec89a5b7e8397cf9be Mon Sep 17 00:00:00 2001
From: Paul Gevers <elbrus@debian.org>
Date: Sun, 24 Mar 2019 20:31:48 +0100
Subject: [PATCH] Generalize use of APT source-list files
Closes: #864017
---
en/old-stuff.dbk | 36 ++++++++++----------
en/upgrading.dbk | 85 +++++++++++++++++++++++++-----------------------
2 files changed, 63 insertions(+), 58 deletions(-)
diff --git a/en/old-stuff.dbk b/en/old-stuff.dbk
index 0a53d737..ec26ca91 100644
--- a/en/old-stuff.dbk
+++ b/en/old-stuff.dbk
@@ -27,14 +27,14 @@ upgraded to the latest &oldreleasename; point release.
</section>
<section id="old-sources">
-<title>Checking your sources list</title>
+<title>Checking your APT source-list files</title>
<para>
-If any of the lines in your <filename>/etc/apt/sources.list</filename>
-refer to <quote><literal>stable</literal></quote>, it effectively
-points to &releasename; already. This might not be what you want if
-you are not ready yet for the upgrade. If you have already run
-<command>apt update</command>, you can still get back without
-problems by following the procedure below.
+ If any of the lines in your APT source-list files (see <ulink
+ url="https://manpages.debian.org/&releasename;/apt/sources.list.5.en.html";>sources.list(5)</ulink>)
+ refer to <quote><literal>stable</literal></quote>, it effectively points to
+ &releasename; already. This might not be what you want if you are not ready
+ yet for the upgrade. If you have already run <command>apt update</command>,
+ you can still get back without problems by following the procedure below.
</para>
<para>
If you have also already installed packages from &releasename;, there probably
@@ -43,28 +43,28 @@ that case you will have to decide for yourself whether you want to continue or
not. It is possible to downgrade packages, but that is not covered here.
</para>
<para>
-Open the file <filename>/etc/apt/sources.list</filename> with your favorite
+ Open the relevant APT source-list file, e.g.
+ <filename>/etc/apt/sources.list</filename>, with your favorite
editor (as <literal>root</literal>) and check all lines beginning with
<literal>deb http:</literal>, <literal>deb https:</literal>,
-<literal>deb tor+http:</literal>, <literal>deb tor+https:</literal> or
-<literal>deb ftp:</literal> for a reference to
+<literal>deb tor+http:</literal>, <literal>deb tor+https:</literal>,
+<literal>URIs: http:</literal>,
+<literal>URIs: https:</literal>,
+<literal>URIs: tor+http:</literal> or <literal>URIs: tor+https:</literal>
+for a reference to
<quote><literal>stable</literal></quote>. If you find any, change
<literal>stable</literal> to <literal>&oldreleasename;</literal>.
</para>
-<note>
- <para>
- Lines in sources.list starting with <quote>deb ftp:</quote> and pointing to debian.org
- addresses should be changed into <quote>deb http:</quote> lines.
- </para>
-</note>
<para>
-If you have any lines starting with <literal>deb file:</literal>, you will have
+ If you have any lines starting with <literal>deb file:</literal> or
+ <literal>URIs: file:</literal>, you will have
to check for yourself if the location they refer to contains an
&oldreleasename; or a &releasename; archive.
</para>
<important>
<para>
- Do not change any lines that begin with <literal>deb cdrom:</literal>.
+ Do not change any lines that begin with <literal>deb cdrom:</literal> or
+ <literal>URIs: cdrom:</literal>.
Doing so would invalidate the line and you would have to
run <command>apt-cdrom</command> again. Do not be alarmed if a
<literal>cdrom:</literal> source line refers to <quote><literal>unstable</literal></quote>.
diff --git a/en/upgrading.dbk b/en/upgrading.dbk
index a22924f3..54a6eb9f 100644
--- a/en/upgrading.dbk
+++ b/en/upgrading.dbk
@@ -290,12 +290,14 @@ $ apt-forktracer | sort
</para>
<para>
Because of this you should review if there are any pending actions in the
- package manager <command>aptitude</command>. If a package is scheduled for
- removal or update in the package manager, it might negatively impact the
- upgrade procedure. Note that correcting this is only possible if your
- <filename>sources.list</filename> still points to <emphasis>&oldreleasename;</emphasis>
- and not to <emphasis>stable</emphasis> or <emphasis>&releasename;</emphasis>; see <xref
- linkend="old-sources"/>.
+ package manager <command>aptitude</command>. If a package is scheduled
+ for removal or update in the package manager, it might negatively impact
+ the upgrade procedure. Note that correcting this is only possible if
+ your APT source-list files, i.e. the files described in the <ulink
+ url="https://manpages.debian.org/&releasename;/apt/sources.list.5.en.html";>sources.list(5)</ulink>
+ manpage, still point to <emphasis>&oldreleasename;</emphasis> and not to
+ <emphasis>stable</emphasis> or <emphasis>&releasename;</emphasis>; see
+ <xref linkend="old-sources"/>.
</para>
<para>
To perform this review, launch <command>aptitude</command> in full-terminal mode and
@@ -381,7 +383,7 @@ $ apt-forktracer | sort
</para>
<para>
If there is anything you need to fix, it is best to make sure your
- <filename>sources.list</filename> still refers to &oldreleasename; as explained in <xref
+ APT source-list files still refer to &oldreleasename; as explained in <xref
linkend="old-sources"/>.
</para>
</section>
@@ -389,23 +391,23 @@ $ apt-forktracer | sort
<section id="proposed-updates">
<title>The proposed-updates section</title>
<para>
- If you have listed the <literal>proposed-updates</literal> section
- in your <filename>/etc/apt/sources.list</filename> file, you
- should remove it from that file before attempting to upgrade your
- system. This is a precaution to reduce the likelihood of
- conflicts.
+ If you have listed the <literal>proposed-updates</literal> section in
+ your APT source-list files, you should remove it from those files before
+ attempting to upgrade your system. This is a precaution to reduce the
+ likelihood of conflicts.
</para>
</section>
<section id="unofficial-sources">
<title>Unofficial sources</title>
<para>
- If you have any non-Debian packages on your system, you should be aware that
- these may be removed during the upgrade because of conflicting dependencies.
- If these packages were installed by adding an extra package archive in your
- <filename>/etc/apt/sources.list</filename>, you should check if that archive
- also offers packages compiled for &releasename; and change the source line accordingly
- at the same time as your source lines for Debian packages.
+ If you have any non-Debian packages on your system, you should be aware
+ that these may be removed during the upgrade because of conflicting
+ dependencies. If these packages were installed by adding an extra
+ package archive in your APT source-list files, you should check if that
+ archive also offers packages compiled for &releasename; and change the
+ source item accordingly at the same time as your source items for Debian
+ packages.
</para>
<para>
Some users may have <emphasis>unofficial</emphasis> backported <quote>newer</quote> versions of packages that
@@ -423,17 +425,19 @@ $ apt-forktracer | sort
</section>
<section id="upgrade-process">
- <title>Preparing sources for APT</title>
+ <title>Preparing APT source-list files</title>
<para>
Before starting the upgrade you must set up <systemitem
- role="package">apt</systemitem>'s configuration file for package lists,
- <filename>/etc/apt/sources.list</filename>.
+ role="package">apt</systemitem>'s configuration file(s) for package lists,
+ <filename>/etc/apt/sources.list</filename> and files under
+ <filename>/etc/apt/sources.list.d/</filename> (see <ulink
+ url="https://manpages.debian.org/&releasename;/apt/sources.list.5.en.html";>sources.list(5)</ulink>).
</para>
<para>
<systemitem role="package">apt</systemitem> will consider all packages that can
- be found via any <quote><literal>deb</literal></quote> line, and install the package with the
- highest version number, giving priority to the first line in the
- file (thus where you have multiple mirror locations, you'd typically first name a local
+ be found via any configured archive, and install the package with the
+ highest version number, giving priority to the first entry in the
+ files (thus where you have multiple mirror locations, you'd typically first name a local
hard disk, then <acronym>CD-ROM</acronym>s, and then remote mirrors).
</para>
@@ -528,16 +532,16 @@ $ apt-forktracer | sort
</para>
<para>
Again, after adding your new sources, disable the previously existing
- <quote><literal>deb</literal></quote> lines.
+ archive entries.
</para>
</section>
<section id="localmirror">
<title>Adding APT sources for a local mirror</title>
<para>
- Instead of using HTTP package mirrors, you may wish to modify
- <filename>/etc/apt/sources.list</filename> to use a mirror on a local disk
- (possibly mounted over <acronym>NFS</acronym>).
+ Instead of using HTTP package mirrors, you may wish to modify the APT
+ source-list files to use a mirror on a local disk (possibly mounted over
+ <acronym>NFS</acronym>).
</para>
<para>
For example, your package mirror may be under
@@ -558,7 +562,7 @@ $ apt-forktracer | sort
</para>
<para>
After adding your new sources, disable the previously existing
- <quote><literal>deb</literal></quote> lines in <filename>sources.list</filename> by placing a
+ archive entries in the APT source-list files by placing a
hash sign (<literal>#</literal>) in front of them.
</para>
</section>
@@ -566,10 +570,9 @@ $ apt-forktracer | sort
<section id="cdroms">
<title>Adding APT sources from optical media</title>
<para>
- If you want to use <emphasis>only</emphasis> CDs (or DVDs or Blu-ray Discs),
- comment out the existing
- <quote><literal>deb</literal></quote> lines in <filename>/etc/apt/sources.list</filename> by
- placing a hash sign (<literal>#</literal>) in front of them.
+ If you want to use <emphasis>only</emphasis> CDs (or DVDs or Blu-ray
+ Discs), comment out the existing entries in all the APT source-list files
+ by placing a hash sign (<literal>#</literal>) in front of them.
</para>
<para>
Make sure there is a line in <filename>/etc/fstab</filename> that enables
@@ -629,9 +632,11 @@ $ apt-forktracer | sort
</screen>
<para>
Next you should double-check that the APT source entries (in
- <filename>/etc/apt/sources.list</filename>) refer either to
- <quote><literal>&releasename;</literal></quote> or to <quote><literal>stable</literal></quote>. There should not be
- any sources entries pointing to &oldreleasename;.
+ <filename>/etc/apt/sources.list</filename> and files under
+ <filename>/etc/apt/sources.list.d/<filename>) refer either to
+ <quote><literal>&releasename;</literal></quote> or to
+ <quote><literal>stable</literal></quote>. There should not be any sources
+ entries pointing to &oldreleasename;.
<note>
<para>
Source lines for a CD-ROM might sometimes refer to
@@ -900,8 +905,8 @@ E: You don't have enough free space in /var/cache/apt/archives/.
<para>
- Note that in order to safely remove packages, it is advisable to switch your
- <filename>sources.list</filename> back to &oldreleasename; as described in <xref
+ Note that in order to safely remove packages, it is advisable to switch
+ your APT source-list files back to &oldreleasename; as described in <xref
linkend="old-sources"/>.
</para>
</section>
@@ -998,8 +1003,8 @@ E: Could not perform immediate configuration on '<replaceable>package</replaceab
</para>
<para>
Another possible workaround for this problem is to temporarily add both
- &oldreleasename; and &releasename; sources to your
- <filename>sources.list</filename> and run <command>apt update</command>.
+ &oldreleasename; and &releasename; sources to your APT source-list files
+ and run <command>apt update</command>.
</para>
</section>
--
2.20.1
Attachment:
signature.asc
Description: OpenPGP digital signature