Bug#604839: Bug#988472: Bug#604839: [installation-guide] Planned overhaul of chapter 4.3 "Preparing Files for USB Memory Stick Booting"
Hi,
Brian Potkin <claremont102@gmail.com> wrote (Sun, 3 Oct 2021 14:45:29 +0100):
> > You should be able to see to which device the USB stick was mapped
> > by running the command dmesg after inserting it.
>
> I would add lsblk, with a link to its manual page.
>
> You should be able to see to which device the USB stick was mapped
> by running the command lsblk before and after inserting it. The
> output of dmesg (as root) is another discovery method.
Ok, applied (similar).
> ----------------------------------------------------------------------
>
> > If you use the wrong device the result could be that all information
> > on for example a hard disk could be lost.
>
> Surely it would be quite surprising if all information was not lost?
> Why not continue the dire warning, particularly as the process is done
> as root? "would" instead of "could"?
I would simplify that to
"If you use the wrong device the result could be that all
information on for example a hard disk is lost."
>
> ---------------------------------------------------------------------
>
> > Debian installation images for this architecture are created using
> > the “isohybrid”...
>
> I do not understand why "isohybrid" needs to be enclosed in double
> quotes. Two links:
Ok, I replaced the quotes by a bold font.
> https://joeyh.name/blog/entry/Debian_USB_install_from_hybrid_iso/
> https://blog.einval.com/2011/01/07
>
> I have forgotten whether the Guide policy allows referencing pages
> outside the Debian infrastructure.
>
> -----------------------------------------------------------------------
>
> > If you have chosen the mini.iso to be written the USB stick, the
> > second partition doesn't have to be created, as - very nice - ...
>
> The original ("very nicely") is OK and better English (IMO).
Ok, applied.
Brian Potkin <claremont102@gmail.com> wrote (Sun, 3 Oct 2021 15:51:28 +0100):
> On Sat 02 Oct 2021 at 19:48:41 +0200, Holger Wansing wrote:
>
> [...]
>
> > I had some understanding issues, mostly in chapter
> > "Manually copying files to the USB stick — the flexible way"
>
> I have never really understood what is so special about syslinux and
> mbr.bin in the context of using hd-media. GRUB should always be at
> hand on a Linux machine. This is my flexible way:
>
> 1. dd if=/dev/zero of=/dev/sdb count=100
> (Could be omitted).
>
> 2. cfdisk /dev/sdb (FAT).
>
> 3. mkfs.vfat /dev/sdb1
> dosfslabel /dev/sdb1 LABEL.
> (Download dosfstools).
>
> 4. mount /dev/sdb1 /mnt
> grub-install --boot-directory=/mnt/boot /dev/sdb
>
> 5. cp vmlinuz /mnt/boot
> cp initrd.gz /mnt/boot
>
> 6. cp <installation_ISO> /mnt
>
> 7. # An example grub.cfg.
> menuentry 'Debian 11.0.0' {
> linux /boot/vmlinuz shared/ask_device=manual \
> shared/enter_device=/dev/disk/by-label/LABEL
> initrd /boot/initrd.gz
> }
>
> 8. cp grub.cfg /mnt/boot/grub
>
> 9. Boot.
>
> More detail at https://wiki.debian.org/Installation+Archive+USBStick.
> To declare an interest - I wrote that page.
I personally have no strict preference on syslinux.
However, the proposed alternative does not look much easier to me ...
(leaving only the pro, that syslinux does not need to be installed)
Other opinions?
Brian Potkin <claremont102@gmail.com> wrote (Sun, 3 Oct 2021 19:40:00 +0100):
> On Sat 02 Oct 2021 at 19:48:41 +0200, Holger Wansing wrote:
>
> [...]
>
> > - Because a long time has passed by since the last overhaul of this chapter,
> > maybe there is some more, that could be changed, for example because of
> > changed/new technology or experience?
>
> Regarding 4.3.2. at
>
> https://people.debian.org/~holgerw/installation-guide_2021-10-02/amd64/ch04s03.html
>
>
> > An alternative way to set up your USB stick is to manually copy
> > the installer files,...
>
> This section has been about since the dawn of time :). It predates the
> advent of isohybrid technology and could be said to have served its
> purpose and be retired. An alternative would be to leave it there and
> introduce it as follows:
>
> Prior to isohybrid technology being used for all Debian ISOs, this way
> was the method used to boot from a USB device. It has been superseded
> by the technique in Section 4.3.1 [LINK] but has been left here for
> educational and historical purposes and in case it proves of use to a
> user.
Basically I could follow that proposal, I have trimmed it a bit to:
"Prior to isohybrid technology being used for &debian; installation images, the
methods documented in the chapters below were used to prepare media for
booting from USB devices.
This has been superseded by the technique in <xref linkend="usb-copy-isohybrid"/>,
but has been left here for educational and historical purposes and in case it
proves of use to a user."
However, I am quite uncomfortable with the last sentence
"... and in case it proves of use to a user."
Could we use some sort of easier English for this (better understanding)?
Proposal?
>
> ------------------------------------------------------------------------
>
> > ...(smaller setups are possible if you follow Section 4.3.3,...
>
> I wonder about this. The Debian 11 netinst ISO is 480M. GRUB plus the
> boot files are 33M. Would they fit on a 512M USB stick (which is not
> really 512M)? Partially tested to say "no". My rule of thumb is 1G.
A 512MB stick is possible with netboot files.
The netboot files lead to a more minimal memory footprint (no need to copy
an ISO image to the stick), so I would leave that sentence in...
(Maybe that could be an argument for keeping this chapter at all!)
>
> ------------------------------------------------------------------------
>
> The link beginning
>
> http://http.us.debian.org/
>
> should be
>
> http://deb.debian.org/
>
> or
>
> https://deb.debian.org/
Hmm, that might be a point for a separate editing round, since there might
be some more occurrences of such links, which could be moved to deb.debian.org.
Will look into this.
>
> ------------------------------------------------------------------------
>
> The Note exercised my mind. It has nothing to do with the being able to
> use this method but refers to an after effect. "major disadvantage"
> refers to this after effect. An alarming term.
>
> > Note that, although convenient and successful, this method does have a
> > drawback affecting how the size of the USB device is seen because it
> > sets its logical size to 1 GB, even if the capacity of the USB stick is
> > larger. You will need to repartition the USB stick and create new file
> > systems to get its full capacity back if you ever want to use it for
> > some different purpose.
Basically I see your point, however from the reader's point of view, I think
the existing variant is easier to understand.
And since it's not strictly wrong, I would keep it as is.
A new diff is attached.
And I have updated the docs at
https://people.debian.org/~holgerw/installation-guide_2021-10-09/
Holger
--
Holger Wansing <hwansing@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
diff --git a/en/install-methods/boot-usb-files.xml b/en/install-methods/boot-usb-files.xml
index 64aeb0aff..4aeae14f4 100644
--- a/en/install-methods/boot-usb-files.xml
+++ b/en/install-methods/boot-usb-files.xml
@@ -13,8 +13,10 @@ it is not you should check that the usb-storage kernel module is loaded.
When the USB stick is inserted, it will be mapped to a device named
<filename>/dev/sdX</filename>, where the <quote>X</quote> is a letter
in the range a-z. You should be able to see to which device the USB
-stick was mapped by running the command <command>dmesg</command> after
-inserting it. To write to your stick, you may have to turn off its write
+stick was mapped by running the command <command>lsblk</command> before
+and after inserting it. The output of <command>dmesg</command> (as root) is
+another possible method for that.
+To write to your stick, you may have to turn off its write
protection switch.
</para><warning><para>
@@ -22,7 +24,7 @@ protection switch.
The procedures described in this section will destroy anything already
on the device! Make very sure that you use the correct device name for
your USB stick. If you use the wrong device the result could be that all
-information on for example a hard disk could be lost.
+information on for example a hard disk is lost.
</para></warning>
@@ -30,9 +32,11 @@ information on for example a hard disk could be lost.
<title>Preparing a USB stick using a hybrid CD/DVD image</title>
<para>
-Debian installation images can now be written directly to a USB stick,
-which is a very easy way to make a bootable USB stick. Simply choose
-an image (such as the netinst, CD, DVD-1, or netboot) that will fit
+Debian installation images for this architecture are created using the
+<command>isohybrid</command> technology;
+that means they can be written directly to a USB stick,
+which is a very easy way to make an installation media. Simply choose
+an image (such as the netinst, CD or DVD-1) that will fit
on your USB stick. See
<xref linkend="official-cdrom"/> to get an installation image.
@@ -82,25 +86,31 @@ device.
</para><para>
-Create a second, FAT partition on the stick, mount the partition
-and copy or unpack the firmware onto it. For example:
+To do so, use cfdisk or any other partitioning tool to create an additional
+partition on the stick. Then create a (FAT) filesystem on the partition,
+mount it and copy or unpack the firmware onto it, for example with:
<informalexample><screen>
-# mount /dev/<replaceable>sdX2</replaceable> /mnt
+# mkdosfs -n FIRMWARE /dev/sdX3
+# mount /dev/<replaceable>sdX3</replaceable> /mnt
# cd /mnt
# tar zxvf <replaceable>/path/to/</replaceable>firmware.tar.gz
# cd /
# umount /mnt
</screen></informalexample>
-</para><para arch="not-s390">
+Take care that you use the correct device name for your USB stick. The
+<command>mkdosfs</command> command is contained in the
+<classname>dosfstools</classname> &debian; package.
-You might have written the <filename>mini.iso</filename> to the USB
-stick. In this case the second partition doesn't have to be created as,
-very nicely, it will already be present. Unplugging and replugging the
+</para><note><para arch="not-s390">
+
+If you have chosen the <filename>mini.iso</filename> to be written to the USB
+stick, the second partition doesn't have to be created, as -
+very nicely - it will already be present. Unplugging and replugging the
USB stick should make the two partitions visible.
-</para>
+</para></note>
@@ -110,21 +120,31 @@ USB stick should make the two partitions visible.
<title>Manually copying files to the USB stick</title>
<para>
-An alternative way to set up your USB stick is to manually copy
-the installer files, and also an installation image to it.
+Prior to isohybrid technology being used for &debian; installation images, the
+methods documented in the chapters below were used to prepare media for
+booting from USB devices.
+This has been superseded by the technique in <xref linkend="usb-copy-isohybrid"/>,
+but has been left here for educational and historical purposes and in case it
+proves of use to a user.
+
+</para><para>
+
+An alternative to the method described above is to manually copy
+the installer files, and also an installation image to the stick.
Note that the USB stick should be at least 1 GB in size (smaller
-setups are possible if you follow <xref linkend="usb-copy-flexible"/>).
+setups are possible using the files from netboot, following
+<xref linkend="usb-copy-flexible"/>).
</para><para>
There is an all-in-one file &hdmedia-boot-img;
-which contains all the installer files (including the kernel)
-<phrase arch="x86">as well as <classname>syslinux</classname> and its
-configuration file</phrase>
-<phrase arch="powerpc">as well as <classname>yaboot</classname> and its
+which contains all the installer files (including the
+kernel)<phrase arch="x86"> as well as <classname>syslinux</classname> and its
+configuration file</phrase><phrase arch="powerpc"> as well as
+<classname>yaboot</classname> and its
configuration file</phrase>.
-</para><para>
+</para><note><para>
Note that, although convenient, this method does have one major
disadvantage: the logical size of the device will be limited to 1 GB,
@@ -132,9 +152,9 @@ even if the capacity of the USB stick is larger. You will need to
repartition the USB stick and create new file systems to get its full
capacity back if you ever want to use it for some different purpose.
-</para><para arch="x86">
+</para></note><para arch="x86">
-To use this image simply extract it directly to your USB stick:
+Simply extract this image directly to your USB stick:
<informalexample><screen>
# zcat boot.img.gz > /dev/<replaceable>sdX</replaceable>
@@ -160,7 +180,8 @@ After that, mount the USB memory stick
which will now have
<phrase arch="x86">a FAT filesystem</phrase>
<phrase arch="powerpc">an HFS filesystem</phrase>
-on it, and copy a &debian; ISO image (netinst or full CD/DVD) to it.
+on it, and copy a &debian; ISO image (netinst or full CD; see
+<xref linkend="official-cdrom"/>) to it.
Unmount the stick (<userinput>umount /mnt</userinput>) and you are done.
</para>
diff --git a/en/install-methods/usb-setup/x86.xml b/en/install-methods/usb-setup/x86.xml
index 569d06a76..328d0bc95 100644
--- a/en/install-methods/usb-setup/x86.xml
+++ b/en/install-methods/usb-setup/x86.xml
@@ -2,31 +2,45 @@
<!-- $Id$ -->
<sect3 arch="x86">
- <title>Partitioning the USB stick</title>
+ <title>Partitioning and adding a boot loader</title>
<para>
We will show how to set up the memory stick to use the first partition,
instead of the entire device.
+</para><para>
+
+In order to start the kernel after booting from the USB stick, we will
+put a boot loader on the stick. Although any boot loader
+should work, it's convenient to use
+<classname>syslinux</classname>, since it uses a FAT16 partition and can
+be reconfigured by just editing a text file. Any operating system
+which supports the FAT file system can be used to make changes to the
+configuration of the boot loader.
+
+</para><para>
+
+First, you need to install the <classname>syslinux</classname> and
+<classname>mtools</classname> packages on your system.
+
</para><note><para>
Since most USB sticks come pre-configured with a single FAT16
partition, you probably won't have to repartition or reformat the
stick. If you have to do that anyway, use <command>cfdisk</command>
-or any other partitioning tool to create a FAT16 partition<footnote>
+or any other partitioning tool to create a FAT16 partition now<footnote>
<para>
-Don't forget to set the <quote>bootable</quote> bootable flag.
+Don't forget to activate the <quote>bootable</quote> flag.
</para>
-</footnote>, install an MBR using:
+</footnote>, and then install an MBR using:
<informalexample><screen>
-# install-mbr /dev/<replaceable>sdX</replaceable>
+# cat /usr/lib/syslinux/mbr/mbr.bin >/dev/<replaceable>sdX</replaceable>
</screen></informalexample>
-The <command>install-mbr</command> command is contained in the
-<classname>mbr</classname> &debian; package. Then create the filesystem using:
+Now create the filesystem using:
<informalexample><screen>
# mkdosfs /dev/<replaceable>sdX1</replaceable>
@@ -38,19 +52,8 @@ Take care that you use the correct device name for your USB stick. The
</para></note><para>
-In order to start the kernel after booting from the USB stick, we will
-put a boot loader on the stick. Although any boot loader
-should work, it's convenient to use
-<classname>syslinux</classname>, since it uses a FAT16 partition and can
-be reconfigured by just editing a text file. Any operating system
-which supports the FAT file system can be used to make changes to the
-configuration of the boot loader.
-
-</para><para>
-
-To put <classname>syslinux</classname> on the FAT16 partition on your USB
-stick, install the <classname>syslinux</classname> and
-<classname>mtools</classname> packages on your system, and do:
+Having a correctly partitioned USB stick (now), you need to put
+<classname>syslinux</classname> on the FAT16 partition with:
<informalexample><screen>
# syslinux /dev/<replaceable>sdX1</replaceable>
@@ -65,12 +68,20 @@ procedure writes a boot sector to the partition and creates the file
</sect3>
<sect3 arch="x86">
- <title>Adding the installer image</title>
+ <title>Adding the installer files</title>
<para>
-Mount the partition
-(<userinput>mount /dev/<replaceable>sdX1</replaceable> /mnt</userinput>)
-and copy the following installer image files to the stick:
+There are two different installation variants to choose here:
+The hd-media variant needs an installation ISO file on the stick,
+to load installer modules and the base system from.
+The netboot installer however will load all that from a &debian; mirror.
+
+</para><para>
+
+According to your choice, you have to download some installer files from
+the hd-media or netboot subdirectory of
+<ulink url="&url-debian-installer;images">debian/dists/&releasename;/main/installer-&architecture;/current/images/</ulink>
+on any &debian; mirror:
<itemizedlist>
<listitem><para>
@@ -85,24 +96,35 @@ and copy the following installer image files to the stick:
</para></listitem>
</itemizedlist>
-You can choose between either the text-based or the graphical version
-of the installer. The latter can be found in the <filename>gtk</filename>
-subdirectory. If you want to rename the files, please note that
-<classname>syslinux</classname> can only process DOS (8.3) file names.
+You can choose between either the text-based version of the installer (the
+files can be found directly in hd-media or netboot) or the graphical
+version (these can be found in the respective <filename>gtk</filename>
+subdirectories).
+
+</para><para>
+
+Then mount the partition
+(<userinput>mount /dev/<replaceable>sdX1</replaceable> /mnt</userinput>)
+and copy the downloaded files to the root directory of the stick.
</para><para>
-Next you should create a <filename>syslinux.cfg</filename> configuration
-file, which at a bare minimum should contain the following line (change
-the name of the kernel binary to <quote><filename>linux</filename></quote>
-if you used a <filename>netboot</filename> image):
+Next you should create a text file named <filename>syslinux.cfg</filename>
+in the root directory of the stick as configuration file for syslinux, which at
+a bare minimum should contain the following line:
<informalexample><screen>
default vmlinuz initrd=initrd.gz
</screen></informalexample>
-For the graphical installer you should add <userinput>vga=788</userinput> to the
-line. Other parameters can be appended as desired.
+Change the name of the kernel binary to <quote><filename>linux</filename></quote>
+if you used files from <filename>netboot</filename>.
+
+</para><para>
+
+For the graphical installer (from <filename>gtk</filename>) you should add
+<userinput>vga=788</userinput> to the end of the line. Other parameters can be
+appended as desired.
</para><para>
@@ -111,17 +133,20 @@ To enable the boot prompt to permit further parameter appending, add a
</para><para>
-If you used an <filename>hd-media</filename> image, you should now copy the ISO file of a
-&debian; ISO image<footnote>
+If you used files from <filename>hd-media</filename>, you should now copy the
+ISO file of a &debian; installation image onto the stick. (For the
+<filename>netboot</filename> variant this is not needed.)
+
+</para><para>
-<para>
You can use either a netinst or a full CD/DVD image (see
-<xref linkend="official-cdrom"/>). Be sure to select one that fits.
+<xref linkend="official-cdrom"/>). Be sure to select one that fits on your stick.
Note that the <quote>netboot <filename>mini.iso</filename></quote> image is
not usable for this purpose.
-</para>
-</footnote> onto the stick. When you are done, unmount the USB memory stick
+</para><para>
+
+When you are done, unmount the USB memory stick
(<userinput>umount /mnt</userinput>).
</para>
Reply to: