Commit 753d2038 authored by Gerardo Exequiel Pozzi's avatar Gerardo Exequiel Pozzi
Browse files

[archiso] Split README file



Signed-off-by: default avatarGerardo Exequiel Pozzi <vmlinuz386@yahoo.com.ar>
parent 1746e310
......@@ -4,11 +4,15 @@ INSTALL_FILES=$(wildcard archiso/initcpio/install/*)
HOOKS_FILES=$(wildcard archiso/initcpio/hooks/*)
SCRIPT_FILES=$(wildcard archiso/initcpio/script/*)
INSTALL_DIR=$(DESTDIR)/usr/lib/initcpio/install
HOOKS_DIR=$(DESTDIR)/usr/lib/initcpio/hooks
SCRIPT_DIR=$(DESTDIR)/usr/lib/initcpio
DOC_FILES=$(wildcard docs/*)
DOC_DIR=$(DESTDIR)/usr/share/doc/archiso
all:
install: install-program install-initcpio install-examples install-doc
......@@ -27,7 +31,8 @@ install-examples:
cp -a --no-preserve=ownership configs $(DESTDIR)/usr/share/archiso/
install-doc:
install -D -m 644 README $(DESTDIR)/usr/share/doc/archiso/README
install -d $(DOC_DIR)
install -m 644 -t $(DOC_DIR) $(DOC_FILES)
dist:
git archive --format=tar --prefix=archiso-$(V)/ v$(V) | gzip -9 > archiso-$(V).tar.gz
......
INDEX
-----
* Alternative boot methods (configs/releng)
* ISO in loopback mode
* ISO in memdisk mode
* Network booting (PXE) [first stage]
* DHCP + TFTP
* DHCP + HTTP
* HTTP/NFS/NBD [second stage]
*** Alternative boot methods (configs/releng)
ISO images names consist of: archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
Where:
<YYYY> Year
<MM> Month
<DD> Day
<ARCH> i686 | x86_64 | dual(*)
(*) "dual" includes both i686 and x86_64 architectures.
** ISO in loopback mode.
Note: Described method is for using with GRUB2.
GRUB2 is installed on target media and archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
is at path <TARGET-PATH> on disk <D> and partition <P>,
where filesystem is labeled as <TARGET-FS-LABEL>.
menuentry "Arch Linux (x86_64)" {
set isofile="/<TARGET-PATH>/archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso"
loopback loop (hd<D>,<P>)$isofile
linux (loop)/arch/boot/x86_64/vmlinuz archisolabel=<FS-LABEL> img_label=<TARGET-FS-LABEL> img_loop=$isofile
initrd (loop)/arch/boot/x86_64/archiso.img
}
menuentry "Arch Linux (i686)" {
set isofile="/<TARGET-PATH>/archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso"
loopback loop (hd<D>,<P>)$isofile
linux (loop)/arch/boot/i686/vmlinuz archisolabel=<FS-LABEL> img_label=<TARGET-FS-LABEL> img_loop=$isofile
initrd (loop)/arch/boot/i686/archiso.img
}
** ISO in memdisk mode.
Note: Described method is for using with SYSLINUX. Anyway MEMDISK from SYSLINUX can work
with other bootloaders.
SYSLINUX is installed on target media and archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
is at path <TARGET-PATH>.
On 32-bit systems, is needed to pass vmalloc=nnM to the kernel, where nn is the size
of the ISO image plus 64 MiB (or 128 MiB).
LABEL arch_x64
LINUX memdisk
INITRD /<TARGET-PATH>/archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
APPEND iso
LABEL arch_x32
LINUX memdisk
INITRD /<TARGET-PATH>/archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
APPEND iso
** Network booting (PXE).
All ISOs are ready to act as PXE server, some manual steps are needed
to setup the desired PXE boot mode.
Alternatively it is possible to use an existing PXE server following the same logic.
Note: Setup network first, adjust IP adresses, and respect all slashes "/".
First stage is for loading kernel and initramfs via PXE, two methods described here:
* DHCP + TFTP
Note: All NIC firmwares should support this.
# dnsmasq --port=0 \
--enable-tftp \
--tftp-root=/run/archiso/bootmnt \
--dhcp-range=192.168.0.2,192.168.0.254,86400 \
--dhcp-boot=/arch/boot/syslinux/gpxelinux.0 \
--dhcp-option-force=209,boot/syslinux/archiso.cfg \
--dhcp-option-force=210,/arch/
* DHCP + HTTP
Note: Not all NIC firmware supports HTTP and DNS (if domain name is used).
At least this works with iPXE and gPXE.
# dnsmasq --port=0 \
--dhcp-range=192.168.0.2,192.168.0.254,86400 \
--dhcp-boot=http://192.168.0.7/arch/boot/syslinux/gpxelinux.0 \
--dhcp-option-force=209,boot/syslinux/archiso.cfg \
--dhcp-option-force=210,http://192.168.0.7/arch/
Once the kernel is started from PXE, SquashFS files and other misc files
inside "arch" directory must be loaded (second stage). One of the following
methods can be used to serve the rest of live-medium.
* HTTP
# darkhttpd /run/archiso/bootmnt
* NFS
# echo "/run/archiso/bootmnt 192.168.0.*(ro,no_subtree_check,no_root_squash)" >> /etc/exports
# rc.d start rpcbind nfs-common nfs-server
* NBD
Note: Adjust ARCH_201207 as needed.
# cat << EOF > /tmp/nbd-server.conf
[generic]
[archiso]
readonly = true
exportname = /dev/disk/by-label/ARCH_201207
EOF
# nbd-server -C /tmp/nbd-server.conf
......@@ -8,26 +8,6 @@ INDEX
* hooks/archiso_pxe_http
* hooks/archiso_pxe_nfs
* hooks/archiso_loop_mnt
* Transfer ISO file to target medium (configs/releng)
* To -> CD / DVD / BD
* To -> USB-key / SD / HDD / SSD
* PC-BIOS (MBR)
* PC-BIOS (ISOHYBRID-MBR)
* PC-EFI (GPT) [x86_64 only]
* Alternative boot methods (configs/releng)
* ISO in loopback mode
* ISO in memdisk mode
* Network booting (PXE) [first stage]
* DHCP + TFTP
* DHCP + HTTP
* HTTP/NFS/NBD [second stage]
* Build requirements
* Image types generated by mkarchiso.
* File format for aitab.
* Why the /isolinux and /arch/boot/syslinux directories?
* Know issues
* Building the most basic Arch Linux live media. (configs/baseline)
* Building official Arch Linux live media. (configs/releng)
......@@ -145,343 +125,3 @@ INDEX
Default: (unset) or "/dev/disk/by-label/${img_label}"
* img_loop= Full path where archiso-image.iso is located on ${img_dev}
Default: (unset)
*** Transfer ISO image to target medium (configs/releng)
ISO images names consist of: archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
Where:
<YYYY> Year
<MM> Month
<DD> Day
<ARCH> i686 | x86_64 | dual(*)
(*) "dual" includes both i686 and x86_64 architectures.
** To -> CD / DVD / BD
Note: All ISO images are booteable on a PC-BIOS via "El Torito" in no-emulation mode,
All x86_64 ISO images are booteable on a PC-EFI via "El Torito" in no-emulation mode.
Nomeclature:
<B> scsibus number
<T> target number
<L> lun number
(Note: see cdrecord -scanbus, for these numbers)
1) Write it directly using your favorite recording program.
# cdrecord dev=<B>,<T>,<L> -dao archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
** To -> USB Flash Drive (USB-key) / Memory card (SD) /
Hard-Disk Drive (HDD) / Solid-State Drive (SSD)
Note: These steps are the general workflow, you can skip some of them,
using another filesystem if your bootloader supports it,
installing to another directory than "arch/" or using more than
one partition. Just ensure that main boot params options
(archisolabel= and archisobasedir=) are set correctly according to your setup.
Nomeclature:
<DEV-TARGET>: Device node of the drive where ISO contents should be copied
(example: /dev/sdx)
<DEV-TARGET-N>: Device node of the partition on <DEV-TARGET>
(example: /dev/sdx1)
<MNT-TARGET-N>: Mount point path where <DEV-TARGET-N> is mounted
(example: /mnt/sdx/1)
<ISO-SOURCE>: Path to the ISO file archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
(example: ~/archlinux-2012.07.22-x86_64.iso)
<FS-LABEL>: Represents the filesystem label of the <ISO-SOURCE>
(example: ARCH_201207 [for all ~/archlinux-2012.07.*.iso])
* PC-BIOS (MBR):
Note: Using here a MBR partition mode as example, but GPT should also works
if machine firmware is not broken.
Just ensure that partition is set with attribute "2: legacy BIOS bootable"
and use gptmbr.bin instead of mbr.bin for syslinux.
1) Create one partition entry in MBR (of type "b" for FAT32 or "83" for EXTFS)
and mark it as "active" (bootable).
# fdisk <DEV-TARGET>
2) Create a FAT32 or EXTFS filesystem on such partition and setup a label.
# mkfs.vfat -F 32 -n <FS-LABEL> <DEV-TARGET-N>
# mkfs.ext4 -L <FS-LABEL> <DEV-TARGET-N>
3) Mount target filesystem.
# mount <DEV-TARGET-N> <MNT-TARGET-N>
4) Extract ISO image on target filesystem.
# bsdtar -x --exclude=isolinux/ --exclude=EFI/ --exclude=loader/ -f <ISO-SOURCE> -C <MNT-TARGET-N>
5) Install syslinux bootloader on target filesystem. (See know issue (2) if using FAT)
# extlinux -i <MNT-TARGET-N>/arch/boot/syslinux
6) Unmount target filesystem.
# umount <MNT-TARGET-N>
7) Install syslinux MBR boot code on target drive.
# dd bs=440 count=1 conv=notrunc if=/usr/lib/syslinux/mbr.bin of=<DEV-TARGET>
* PC-BIOS (ISOHYBRID-MBR):
Note: This method is the most easily, quick and dirty, but is the most limited
if you want to use your target medium for other purposes.
1) Dump ISO file to target medium.
# dd if=<ISO-SOURCE> of=<DEV-TARGET>
* PC-EFI (GPT) [x86_64 only]
Note: Using here a GPT partition mode as example, but MBR should also works
if machine firmware is not broken.
1) Create one partition entry in GPT (of type "ef00")
# gdisk <DEV-TARGET>
2) Create a FAT32 filesystem on such partition and setup a label.
# mkfs.vfat -F 32 -n <FS-LABEL> <DEV-TARGET-N>
3) Mount target filesystem.
# mount <DEV-TARGET-N> <MNT-TARGET-N>
4) Extract ISO image on target filesystem.
# bsdtar -x --exclude=isolinux/ --exclude=EFI/archiso/ --exclude=arch/boot/syslinux/ -f <ISO-SOURCE> -C <MNT-TARGET-N>
5) Unmount target filesystem.
# umount <MNT-TARGET-N>
*** Alternative boot methods (configs/releng)
** ISO in loopback mode.
Note: Described method is for using with GRUB2.
GRUB2 is installed on target media and archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
is at path <TARGET-PATH> on disk <D> and partition <P>,
where filesystem is labeled as <TARGET-FS-LABEL>.
menuentry "Arch Linux (x86_64)" {
set isofile="/<TARGET-PATH>/archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso"
loopback loop (hd<D>,<P>)$isofile
linux (loop)/arch/boot/x86_64/vmlinuz archisolabel=<FS-LABEL> img_label=<TARGET-FS-LABEL> img_loop=$isofile
initrd (loop)/arch/boot/x86_64/archiso.img
}
menuentry "Arch Linux (i686)" {
set isofile="/<TARGET-PATH>/archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso"
loopback loop (hd<D>,<P>)$isofile
linux (loop)/arch/boot/i686/vmlinuz archisolabel=<FS-LABEL> img_label=<TARGET-FS-LABEL> img_loop=$isofile
initrd (loop)/arch/boot/i686/archiso.img
}
** ISO in memdisk mode.
Note: Described method is for using with SYSLINUX. Anyway MEMDISK from SYSLINUX can work
with other bootloaders.
SYSLINUX is installed on target media and archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
is at path <TARGET-PATH>.
On 32-bit systems, is needed to pass vmalloc=nnM to the kernel, where nn is the size
of the ISO image plus 64 MiB (or 128 MiB).
LABEL arch_x64
LINUX memdisk
INITRD /<TARGET-PATH>/archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
APPEND iso
LABEL arch_x32
LINUX memdisk
INITRD /<TARGET-PATH>/archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
APPEND iso
** Network booting (PXE).
All ISOs are ready to act as PXE server, some manual steps are needed
to setup the desired PXE boot mode.
Alternatively it is possible to use an existing PXE server following the same logic.
Note: Setup network first, adjust IP adresses, and respect all slashes "/".
First stage is for loading kernel and initramfs via PXE, two methods described here:
* DHCP + TFTP
Note: All NIC firmwares should support this.
# dnsmasq --port=0 \
--enable-tftp \
--tftp-root=/run/archiso/bootmnt \
--dhcp-range=192.168.0.2,192.168.0.254,86400 \
--dhcp-boot=/arch/boot/syslinux/gpxelinux.0 \
--dhcp-option-force=209,boot/syslinux/archiso.cfg \
--dhcp-option-force=210,/arch/
* DHCP + HTTP
Note: Not all NIC firmware supports HTTP and DNS (if domain name is used).
At least this works with iPXE and gPXE.
# dnsmasq --port=0 \
--dhcp-range=192.168.0.2,192.168.0.254,86400 \
--dhcp-boot=http://192.168.0.7/arch/boot/syslinux/gpxelinux.0 \
--dhcp-option-force=209,boot/syslinux/archiso.cfg \
--dhcp-option-force=210,http://192.168.0.7/arch/
Once the kernel is started from PXE, SquashFS files and other misc files
inside "arch" directory must be loaded (second stage). One of the following
methods can be used to serve the rest of live-medium.
* HTTP
# darkhttpd /run/archiso/bootmnt
* NFS
# echo "/run/archiso/bootmnt 192.168.0.*(ro,no_subtree_check,no_root_squash)" >> /etc/exports
# rc.d start rpcbind nfs-common nfs-server
* NBD
Note: Adjust ARCH_201207 as needed.
# cat << EOF > /tmp/nbd-server.conf
[generic]
[archiso]
readonly = true
exportname = /dev/disk/by-label/ARCH_201207
EOF
# nbd-server -C /tmp/nbd-server.conf
*** Build requirements
** For mkarchiso script needs these packages (build host):
+ squashfs-tools for mksquashfs
+ libisoburn for xorriso
+ btrfs-progs for mkfs.btrfs (optional)
** For configs/releng build.sh needs theses packages (build host):
+ dosfstools for mkfs.vfat
+ patch for patch
+ lynx for fetching the latest installation guide
** For these hooks needs these packages (on target root-image)
* archiso
+ (none)
* archiso_loop_mnt
+ (none)
* archiso_pxe_common
+ mkinitcpio-nfs-utils for ipconfig
* archiso_pxe_nbd
+ nbd for nbd-client
* archiso_pxe_http
+ curl for curl
* archiso_pxe_nfs
+ mkinitcpio-nfs-utils for nfsmount
* archiso_shutdown
+ (none)
*** Image types generated by mkarchiso.
* image-name.sfs SquashFS image with all files directly on it.
* image-name.fs.sfs SquashFS with only one file inside (image-name.fs),
which is an image of some type of filesystem
(ext4, ext3, ext2, xfs), all files reside on it.
*** File format for aitab.
The aitab file holds information about the filesystems images that must be
created by mkarchiso and mounted at initramfs stage from the archiso hook.
It consists of some fields which define the behaviour of images.
# <img> <mnt> <arch> <sfs_comp> <fs_type> <fs_size>
<img> Image name without extension (.fs .fs.sfs .sfs).
<mnt> Mount point.
<arch> Architecture { i686 | x86_64 | any }.
<sfs_comp> SquashFS compression type { gzip | lzo | xz }.
<fs_type> Set the filesystem type of the image
{ ext4 | ext3 | ext2 | xfs | btrfs }.
A special value of "none" denotes no usage of a filesystem.
In that case all files are pushed directly to SquashFS filesystem.
<fs_size> An absolute value of file system image size in MiB.
(example: 100, 1000, 4096, etc)
A relative value of file system free space [in percent].
{1%..99%} (example 50%, 10%, 7%).
This is an estimation, and calculated in a simple way.
Space used + 10% (estimated for metadata overhead) + desired %
*** Why the /isolinux and /arch/boot/syslinux directories?
The /isolinux directory holds files needed for the ISOLINUX boot loader
module of SYSLINUX. ISOLINUX can not find config files on
/arch/boot/syslinux, like other boot loaders modules (EXTLINUX, SYSLINUX, etc).
When make your custom boot-pendrive, you need to copy /arch directory to it.
/isolinux/isolinux.cfg just holds /arch/boot/syslinux/syslinux.cfg
*** Know issues
** (1) On shutdown lots of messages from systemd like:
"Could not unmount /run/archiso/<ABC>: Device or resource busy"
"Could not delete loopback /dev/loop<N>: Device or resource busy"
This is not a real issue since, all mounted filesystem, loopback devices
and device mapper devices made by archiso will be "free" on "shutdown tmpfs"
(A.K.A deinitramfs), build at initramfs by [archiso_shutdown] initcpio hook.
Proper shutdown is mostly important when persistent is used.
** (2) syslinux 4.05 bug with relative directories on FAT:
"Could not find kernel image: boot/syslinux/whichsys.c32"
This should be fixed in 4.06. For now, workaround with:
sed -i "s|../../|/arch|" /<MNT-TARGET-N>/arch/boot/syslinux/syslinux.cfg
*** Building the most basic Arch Linux live media. (configs/baseline)
* Install needed packages.
# pacman -S git make squashfs-tools libisoburn rsync --needed
* Install archiso.
# git clone git://projects.archlinux.org/archiso.git
# make -C archiso install
* Build a basic iso.
# /usr/share/archiso/configs/baseline/build.sh
Note: If you want to customize, just see the configs/releng directory which is
used to build official images with much more things.
*** Building official Arch Linux live media. (configs/releng)
* Install needed packages.
# pacman -S git make squashfs-tools libisoburn dosfstools lynx patch --needed
* Install archiso.
# git clone git://projects.archlinux.org/archiso.git
# make -C archiso install
* Build them!
# /usr/share/archiso/configs/releng/build.sh build all
Note: See build.sh -h for more options.
INDEX
-----
* Build requirements
* Image types generated by mkarchiso.
* File format for aitab.
* Why the /isolinux and /arch/boot/syslinux directories?
* Building the most basic Arch Linux live media. (configs/baseline)
* Building official Arch Linux live media. (configs/releng)
*** Build requirements
** For mkarchiso script needs these packages (build host):
+ squashfs-tools for mksquashfs
+ libisoburn for xorriso
+ btrfs-progs for mkfs.btrfs (optional)
** For configs/releng build.sh needs theses packages (build host):
+ dosfstools for mkfs.vfat
+ patch for patch
+ lynx for fetching the latest installation guide
** For these hooks needs these packages (on target root-image)
* archiso
+ (none)
* archiso_loop_mnt
+ (none)
* archiso_pxe_common
+ mkinitcpio-nfs-utils for ipconfig
* archiso_pxe_nbd
+ nbd for nbd-client
* archiso_pxe_http
+ curl for curl
* archiso_pxe_nfs
+ mkinitcpio-nfs-utils for nfsmount
* archiso_shutdown
+ (none)
*** Image types generated by mkarchiso.
* image-name.sfs SquashFS image with all files directly on it.
* image-name.fs.sfs SquashFS with only one file inside (image-name.fs),
which is an image of some type of filesystem
(ext4, ext3, ext2, xfs), all files reside on it.
*** File format for aitab.
The aitab file holds information about the filesystems images that must be
created by mkarchiso and mounted at initramfs stage from the archiso hook.
It consists of some fields which define the behaviour of images.
# <img> <mnt> <arch> <sfs_comp> <fs_type> <fs_size>
<img> Image name without extension (.fs .fs.sfs .sfs).
<mnt> Mount point.
<arch> Architecture { i686 | x86_64 | any }.
<sfs_comp> SquashFS compression type { gzip | lzo | xz }.
<fs_type> Set the filesystem type of the image
{ ext4 | ext3 | ext2 | xfs | btrfs }.
A special value of "none" denotes no usage of a filesystem.
In that case all files are pushed directly to SquashFS filesystem.
<fs_size> An absolute value of file system image size in MiB.
(example: 100, 1000, 4096, etc)
A relative value of file system free space [in percent].
{1%..99%} (example 50%, 10%, 7%).
This is an estimation, and calculated in a simple way.
Space used + 10% (estimated for metadata overhead) + desired %
*** Why the /isolinux and /arch/boot/syslinux directories?
The /isolinux directory holds files needed for the ISOLINUX boot loader
module of SYSLINUX. ISOLINUX can not find config files on
/arch/boot/syslinux, like other boot loaders modules (EXTLINUX, SYSLINUX, etc).
When make your custom boot-pendrive, you need to copy /arch directory to it.
/isolinux/isolinux.cfg just holds /arch/boot/syslinux/syslinux.cfg
*** Building the most basic Arch Linux live media. (configs/baseline)
* Install needed packages.
# pacman -S git make squashfs-tools libisoburn rsync --needed
* Install archiso.
# git clone git://projects.archlinux.org/archiso.git
# make -C archiso install
* Build a basic iso.
# /usr/share/archiso/configs/baseline/build.sh
Note: If you want to customize, just see the configs/releng directory which is
used to build official images with much more things.
*** Building official Arch Linux live media. (configs/releng)
* Install needed packages.
# pacman -S git make squashfs-tools libisoburn dosfstools lynx patch --needed
* Install archiso.
# git clone git://projects.archlinux.org/archiso.git
# make -C archiso install
* Build them!
# /usr/share/archiso/configs/releng/build.sh build all
Note: See build.sh -h for more options.
*** Know issues
** (1) On shutdown lots of messages from systemd like:
"Could not unmount /run/archiso/<ABC>: Device or resource busy"
"Could not delete loopback /dev/loop<N>: Device or resource busy"
This is not a real issue since, all mounted filesystem, loopback devices
and device mapper devices made by archiso will be "free" on "shutdown tmpfs"
(A.K.A deinitramfs), build at initramfs by [archiso_shutdown] initcpio hook.
Proper shutdown is mostly important when persistent is used.
** (2) syslinux 4.05 bug with relative directories on FAT:
"Could not find kernel image: boot/syslinux/whichsys.c32"
This should be fixed in 4.06. For now, workaround with:
sed -i "s|../../|/arch|" /<MNT-TARGET-N>/arch/boot/syslinux/syslinux.cfg