[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#604839: [installation-guide] Planned overhaul of chapter 4.3 "Preparing Files for USB Memory Stick Booting"



Hi,

I'm thinking about (long overdue) updating chapter 
https://d-i.debian.org/doc/installation-guide/en.amd64/ch04s03.html
"Preparing Files for USB Memory Stick Booting".


Additionally to the issues mentioned in related bugreports
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=604839
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=988472
I had some understanding issues, mostly in chapter
"Manually copying files to the USB stick — the flexible way"


Therefore, I would welcome some help/review, to make sure I got everything
right.
I have prepared a patch (attached).

I have already tested everything documented in this chapter so far, and it works
(at least for me) as documented in my patched version, so it doesn't look that 
bad IMO, but double-checking might be good.

Notes:
- I would not call files like vmlinuz or initrd.gz an "image" (to not be
  confused with the installation ISO images); so I changed such occurrences
  into "files".
- I have fixed missing content/commands on several places.
- #988472 proposes to no longer use "install-mbr" to install an MBR on the
  stick, but use 'cat /usr/lib/syslinux/mbr.bin >/dev/sdX' instead.
  Any objections or comments on this?
  (Works fine for me so far.)
- 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?


If someone wants to read a complete html page, instead of the patch, I have
uploaded my version to https://people.debian.org/~holgerw/
(Reading the html might be easier; I have swapped some sentences around, to
get a better understandable and intuitive order. 
That makes the diff a lot more complex.)
See
https://people.debian.org/~holgerw/installation-guide_2021-10-02/amd64/ch04s03.html
or
https://people.debian.org/~holgerw/installation-guide_2021-10-02/arm64/ch04s03.html


Thanks a lot

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..f1d61392b 100644
--- a/en/install-methods/boot-usb-files.xml
+++ b/en/install-methods/boot-usb-files.xml
@@ -23,23 +23,25 @@ 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.
 
 </para></warning>
 
   <sect2 id="usb-copy-isohybrid" condition="isohybrid-supported">
   <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
+<quote>isohybrid</quote> 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.
 
 </para><para>
 
 Alternatively, 
 for very small USB sticks, only a few megabytes in size, you can download
 the &netboot-mini-iso; image from the <filename>netboot</filename>
 directory (at the location mentioned in <xref linkend="where-files"/>).
 
@@ -75,73 +77,79 @@ people with specialised needs.
 <para>
 
 The hybrid image on the stick does not occupy all the storage space, so
 it may be worth considering using the free space to hold firmware files
 or packages or any other files of your choice. This could be useful if
 you have only one stick or just want to keep everything you need on one
 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 the USB
+stick, the second partition doesn't have to be created, as -
+very nice - it will already be present. Unplugging and replugging the
 USB stick should make the two partitions visible.
 
-</para>
+</para></note>
 
 
 
   </sect2>
 
   <sect2 id="usb-copy-easy" condition="manual-usb-prep-supported">
   <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.
 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"/>).
 
 </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,
 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 &gt; /dev/<replaceable>sdX</replaceable>
 </screen></informalexample>
 
 </para><para arch="powerpc">
 
 Create a partition of type "Apple_Bootstrap" on your USB stick using
 <command>mac-fdisk</command>'s <userinput>C</userinput> command and
 extract the image directly to that:
@@ -153,21 +161,22 @@ extract the image directly to that:
 </para><para>
 
 After that, mount the USB memory stick
 <phrase arch="x86">(<userinput>mount
 /dev/<replaceable>sdX</replaceable> /mnt</userinput>),</phrase>
 <phrase arch="powerpc">(<userinput>mount
 /dev/<replaceable>sdX2</replaceable> /mnt</userinput>),</phrase>
 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>
   </sect2>
 
   <sect2 id="usb-copy-flexible" condition="manual-usb-prep-supported">
   <title>Manually copying files to the USB stick &mdash; the flexible way</title>
 <para>
 
 If you like more flexibility or just want to know what's going on, you
diff --git a/en/install-methods/usb-setup/x86.xml b/en/install-methods/usb-setup/x86.xml
index 569d06a76..ec463ec89 100644
--- a/en/install-methods/usb-setup/x86.xml
+++ b/en/install-methods/usb-setup/x86.xml
@@ -1,128 +1,153 @@
 <!-- retain these comments for translator revision tracking -->
 <!-- $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>
 </screen></informalexample>
 
 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.
 
 </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>
 </screen></informalexample>
 
 Again, take care that you use the correct device name. The partition
 must not be mounted when starting <command>syslinux</command>. This
 procedure writes a boot sector to the partition and creates the file
 <filename>ldlinux.sys</filename> which contains the boot loader code.
 
 </para>
    </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>
 
 <filename>vmlinuz</filename> or <filename>linux</filename> (kernel binary)
 
 </para></listitem>
 <listitem><para>
 
 <filename>initrd.gz</filename> (initial ramdisk image)
 
 </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>
 
 To enable the boot prompt to permit further parameter appending, add a
 <userinput>prompt 1</userinput> line.
 
 </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.
 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>
    </sect3>

Reply to: