Archiso

From ArchWiki

Jump to: navigation, search

Contents

What is it?

Archiso is a small set of bash scripts that is capable of building fully functional Arch Linux based live CD/DVD or USB images. It is a very generic tool, so it could potentially be used to generate anything from rescue systems, to install disks, to special interest live CD/DVD/USB systems, and who knows what else. Simply put, if it involves Arch on a shiny coaster, it can do it. The heart and soul of Archiso is mkarchiso. All of its options are documented in its usage output, so its direct usage wont be covered here. Instead, this wiki article will act as a guide for rolling your own live mediums in no time!

Install Archiso

You have two options to get Archiso:

$ git clone git://projects.archlinux.org/archiso.git
$ cd archiso/archiso
$ sudo make install
$ sudo pacman -S mkinitcpio cdrkit squashfs-tools devtools aufs2-util syslinux

Note: As of the current date, the archiso in extra is not up-to-date enough to follow this guide and its usage is therefore not recommended.

Configure our live medium

Makefile

The very first thing you should do is creating a directory to work in, and cd to it. This'll help keep things organized.

$ mkdir my-arch && cd my-arch

Next, you'll want to create a Makefile and put our building instructions in there. The Makefile will define all actions that mkarchiso is going to execute. You could say it is our project file.

$ vim Makefile

Below you will find a sample Makefile that should work for most stuff you want and that works with everything described in this article.

Warning: All indents within the makefile are with tabs. Using spaces gives a missing separator error
Warning: Earlier versions of this makefile worked with "mkinitcpio -c mkinitcpio.conf..." however (possibly due to recent updates?) this may no longer work. If you see a warning regarding not being able to find the mkinitcpio.conf file, use the full path to the file, or "./". Otherwise you may get an empty initcpio, which will render the system unbootable (VFS error, kernel panic)

#### Change these settings to modify how this ISO is built.
#  The directory that you'll be using for the actual build process.
WORKDIR=work
#  A list of packages to install, either space separated in a string or line separated in a file. Can include groups.
PACKAGES="`cat packages.list` $(BOOTLOADER)"
# The name of our ISO. Does not specify the architecture!
NAME=my-arch
# Version will be appended to the ISO.
VER=1.00
# Kernel version. You'll need this.
KVER=2.6.29-ARCH
# Architecture will also be appended to the ISO name.
ARCH?=`uname -m`
# Bootloader for our livecd/liveusb to use. For a list of available bootloader see below.
BOOTLOADER?=grub-gfx
# Current working directory
PWD:=`pwd`
# This is going to be the full name the final iso/img will carry
FULLNAME=$(PWD)/$(NAME)-$(VER)-$(ARCH)

# In case "make all" is called, the next line tries to build both, iso and usb-img.
all: my-arch-iso my-arch-usb
# The following line firstly executes overlay (defined below) and then executes the grub-gfx (which is also defined below).
# It will execute itself only after it has executed overlay and then grub-gfx (or whatever you set BOOTLOADER to above).
# Changing $BOOTLOADER to only grub, will result in GRUB losing its ability to display graphical images but you might gain 
# more compatibility and loading speed.
# Setting $BOOTLOADER to isolinux will make the resulting image a lot more compatible with really old systems. 
# Therefore, if you are building a live cd for really old systems, you will want to use isolinux. 
# When my-arch-iso/usb is finally executed, it will create the final image file from the $WORKDIR using mkarchiso. 
# Since this is the last step of any image creation procedure, this routine is always called at the very end. Let's move on.
my-arch-usb: overlay $(BOOTLOADER)
	mkarchiso -f -p $(BOOTLOADER) usb "$(WORKDIR)" "$(FULLNAME)".img
my-arch-iso: overlay $(BOOTLOADER)
	mkarchiso -f -p $(BOOTLOADER) iso "$(WORKDIR)" "$(FULLNAME)".iso

# See: Overlay
# When overlay is called, it will first execute base-iso. 
# The overlay routine is therefore always executed third.
overlay: base-iso
	cp -r overlay "$(WORKDIR)/"

# The next routine base-iso is always executed second.
# It executes root-image and then itself. base-iso is used for adding a bootloader and an initrd into 
# the then already existing base-system which is created by root-image.
base-iso: root-image
	mv "$(WORKDIR)/root-image/boot" "$(WORKDIR)/iso/"
	cp -r boot-files/* "$(WORKDIR)/iso/boot/"
	cp isomounts "$(WORKDIR)"
	sed -i "s|@ARCH@|$(ARCH)|g" "$(WORKDIR)/isomounts"
	mkinitcpio -c /path/to/mkinitcpio.conf -b "$(WORKDIR)/root-image" -k $(KVER) -g "$(WORKDIR)/iso/boot/my-arch".img

# The root-image' routine is always executed first. 
# It only downloads and installs all packages into the $WORKDIR, giving you a basic system to use as a base.
root-image:
	mkarchiso -p $(PACKAGES) create "$(WORKDIR)"

# In case "make clean" is called, the following routine gets rid of all files created by this Makefile.
clean:
	rm -rf "$(WORKDIR)" "$(FULLNAME)".img "$(FULLNAME)".iso

# Your choice for $BOOTLOADER above determines which routine is executed here.
# This routine is always executed fourth, just before generating the actual image. 
grub-gfx:
	cp -r "$(WORKDIR)/root-image/usr/lib/grub/i386-pc/"* "$(WORKDIR)/iso/boot/grub"
grub:
	cp -r "$(WORKDIR)/root-image/usr/lib/grub/i386-pc/"* "$(WORKDIR)/iso/boot/grub"
syslinux:
	cp -r "$(WORKDIR)/root-image/usr/lib/syslinux/isolinux.bin" "$(WORKDIR)/iso/boot/isolinux"

So, if, for example, "make my-arch-iso" is called (as root!), the following is what effectively happens:

  • root-image downloads and installs all chosen packages into $WORKDIR
  • base-image copies our boot-files and takes care of an initcpio
  • overlay copies our custom files into the root-image in $WORKDIR
  • grub-gfx copies over our actual bootloader
  • my-arch-iso finally creates our bootable .iso file, ready for burning onto a CD/DVD

A Makefile itself won't suffice, so you'll need to create some additional files which will be covered below.

mkinitcpio.conf

An initcpio is necessary for creating a system that is able to "wake-up" from a CD/DVD/USB.

Therefore, you should create a mkinitcpio.conf that holds a list of our hooks:

$ vim mkinitcpio.conf

A typical set of hooks for archiso looks something like this:

HOOKS="base archiso-early udev archiso pata scsi sata usb fw filesystems usbinput"

This list will get you a system that can be booted off a CD/DVD or a USB device. It's worth mentioning that hardware auto-detection and things of that nature do not belong here. Only what's necessary to get the system on its feet, and out of the initcpio really belong here, fancier stuff can be done on the booted system anyway.

packages.list

You'll also want to create a list of packages you want installed on your live CD system. A file full of package names, one-per-line, is the format for this. Typically you'll want base and kernel26 as a bare minimum, but you're free to install whatever else you want. This is great for special interest live CDs, just specify packages you want and bake the image.

Note: mkarchiso will use your local build machine's /etc/pacman.conf for sources. If you have activated [testing] in there, it will also be used for grabbing the packages for the live medium. If you want to use another pacman.conf, you can copy it to the local project folder and use mkarchiso -c pacman.conf to use your local pacman.conf. For this to work when building the ISO, you will have to add -c pacman.conf to all calls to mkarchiso in the Makefile.
$ vim packages.list

You may want to put at least the following into there:

aufs2
aufs2-util
base
bash
coreutils
cpio
dhcpcd
dnsutils
file
fuse
kernel26
nano

This should already get you a booting system without much else. Be aware, though, that it lacks quite a lot drivers that aren't directly included in the kernel, notably wireless and graphics drivers and of course special purpose devices. Just add in driver packages as desired. A lot of hardware should run anyway, though. For some suggestions for different configurations, see the included examples for Archiso.

Tip: You can also create a custom local repository for the purpose of preparing custom packages or packages from AUR/ABS. Just add your local repository at the first position (for top priority) of your build machine's pacman.conf and you are good to go!

isomounts

You will need a small file that holds information about the file systems that are going to be mounted once the live medium boots.

$ vim isomounts

A sample isomounts for your convenience:

# archiso isomounts file
# img - location of image/directory to mount relative to addons directory
# arch - architecture of this image
# mount point - absolute location on the post-initrd root
# type - either 'bind' or 'squashfs' for now
# syntax: <img> <arch> <mount point> <type>
# ORDER MATTERS! Files take top-down precedence. Be careful
overlay.sqfs @ARCH@ / squashfs
root-image.sqfs @ARCH@ / squashfs

boot-files

Depending on the bootloader you choose, you will add least need a "boot-files" directory and and a subdirectory "grub/" containing a "menu.lst" or "isolinux/" containing a "isolinux.cfg".

Using grub/grub-gfx

If you're going to use grub-gfx (recommended for the samples given in this article), you will at least have to create a menu.lst to make it work:

$ mkdir -p boot-files/grub/
$ vim boot-files/grub/menu.lst

Familiarity with grub's menu.lst is assumed here but not a necessity.

In any case, below you will find a sample menu.lst that you can use:

timeout 30
default 0
color light-blue/blue black/light-grey
splashimage=/boot/splash.xpm.gz

title Boot my-arch
kernel /boot/vmlinuz26 lang=en locale=en_US.UTF-8 usbdelay=5 ramdisk_size=75% archisolabel=x
initrd /boot/my-arch.img

title Run Memtest86+ (memory testing)
kernel /boot/memtest86+-2.10.bin
#http://www.memtest.org/#downiso

title Run x86test (CPU info)
kernel /boot/x86test_zImage.bin
#wget http://www.vortex.prodigynet.co.uk/x86test/x86test_zImage.bin

title Shutdown the Computer
halt

title Reboot the Computer
reboot

Be aware, though, that in order to use the example menu.lst given above, you will need a correctly created splashimage, else booting will fail. You might as well comment it out. In case you want to use a splashimage, you need to make sure that it complies to the specifications. Please see Grub-gfx for more information.

Using the additional diagnostic tools like Memtest86+ is not necessary but recommended. You will need to get them individually and put the resulting .bin files into the boot-files directory, not boot-files/grub!.

Using isolinux

Using isolinux instead of grub-gfx is easy:

$ mkdir -p boot-files/isolinux/
$ vim boot-files/isolinux/isolinux.cfg

Sample contents:

prompt 1
timeout 0
display my-arch.msg
DEFAULT my-arch

LABEL my-arch
KERNEL /boot/vmlinuz26
APPEND lang=en locale=en_US.UTF-8 usbdelay=5 ramdisk_size=75% initrd=/boot/my-arch.img archisolabel=x

LABEL memtest86+
KERNEL /boot/memtest86+-2.10.bin

Additionally, you may want a message to be shown above the boot line:

$ vim boot-files/isolinux/my-arch.msg

This can be any arbitrary message in ASCII:

HI GENTLEMEN LOL
WELCOME TO MY DISTRO
I HOPE U ENJOY MAKE UR TIME
HA-HA-HA

Please do note that you will first have to manually get the memtest*.bin from somewhere first because it won't be put there for you. If you do not want to use it, please comment it out.

overlay

The last item of importance is the overlay. Basically this means any other stuff you might want to include on your live medium, including binary package repositories, special configurations, random files, anything you can think of. mkarchiso expects them all to be put in a single directory. The overlay will, as the name implies, be layered on top the base system at boot time using AUFS. The structure inside the overlay is that of a root filesystem.

All non-existing files and directories which are included in the overlay but do not exist in the base system will be created. All existing files and directories which do exist in the base system are overwritten with the files from the overlay.

Next, create the overlay:

$ mkdir overlay && cd overlay/

Woah, that was easy! Now, you still need to add some useful stuff in there. A couple of examples:

Note: It is important that all files in the overlay carry the proper permissions. You are therefore advised to use the root account to commit changes to this directory. Remember, it is an actual root filesystem layer.

Adding a fstab

It is required to add a fstab file in /etc:

$ mkdir etc
$ vim etc/fstab
aufs                   /             aufs      noauto              0      0
none                   /dev/pts      devpts    defaults            0      0
none                   /dev/shm      tmpfs     defaults            0      0
/dev/cdrom             /bootcd       iso9660   ro,user,noauto      0      0

Adding a predefined user

Manually

You will want a user in your live session. There are many ways to do that. One way to do it is to manually add the user and all groups you may want as files in etc/, without calling any commands. This can be accomplished by using your host system's /etc files and modifying them to make them fit the purpose:

$ cp /etc/group etc/group
$ cp /etc/passwd etc/passwd
$ cp /etc/shadow etc/shadow

Note: Be very careful not to leave your encrypted passwords in the passwd or shadow file! Your password is at the second position (after the first ':'). You must not leave it in there!

To make a password-less user, simply clear the second position like so:

root::99999::::::

Additionally, the user will need a home directory or many things will fail (remember to change the home directory correctly in passwd). You will want to use rc.local to create a home directory at boot time and fill it with /etc/skel. If you don't know about /etc/skel, you should read up on that.

$ vim etc/rc.local
mkdir /home/archie && chown archie:archie /home/archie
su -c "cp -r /etc/skel/.[a-zA-Z0-9]* /home/archie/" archie
Using useradd

Another way of adding the user (which is probably preferred but untested) is using etc/rc.local to create the user at boot time:

$ vim etc/rc.local
useradd -u 1000 -g users -G storage,floppy,optical,audio,video,network,games,wheel,disk -d /home/archie archie

This should take care of the user and his home directory.

Putting stuff into the user's home directory at boot time

It might be desirable to put some pre-defined user settings in place when the live user enters his session. Luckily, there is a directory which automatically copies itself into each new user's home directory: /etc/skel.

You will need to create that directory and then put your stuff in there:

$ mkdir etc/skel

And for example:

$ vim etc/skel/.bashrc 
alias ls='ls --color=auto'
PS1='[\u@\h \W]\$ '

Covering all the magic that could be done to a user at boot time is vastly beyond this article's scope.

Note: You may NOT directly create any user's home directory directly in the overlay by putting stuff into /home/user/, it will break permissions in the guest system! Use /etc/skel/.

Finishing the overlay

Some tips that will not be covered in this article because there are other articles on this wiki that already do:

  • Configure an inittab to start into X at boot time
  • Configure the hosts file
  • Configure rc.conf (no fancy modules required here)
  • Configure sudoers
  • Configure rc.local
  • Put more stuff into etc/skel
  • Put additional artworks onto the medium
  • Put arbitrary binary stuff into opt/

Generate your live medium

After so much time spent on configuring, here comes the fun part: Baking the image.

It's quite easy, too: As root (important!) execute the following in your project directory (where your Makefile is located):

$ make all

You will receive a .iso, ready for burning onto a CD/DVD and a .img, ready for dd'ing onto a USB key.

Enjoy!

Links

Archiso project page

Personal tools