Difference between revisions of "Archiso"

From ArchWiki
Jump to: navigation, search
Line 17: Line 17:
  $ cd archiso/archiso
  $ cd archiso/archiso
  $ sudo make install
  $ sudo make install
  $ sudo pacman -S mkinitcpio cdrkit squashfs-tools devtools syslinux mkinitcpio-nfs-utils nbd
  $ sudo pacman --needed -S mkinitcpio cdrkit squashfs-tools devtools syslinux mkinitcpio-nfs-utils nbd
== Configure our live medium ==
== Configure our live medium ==

Revision as of 00:23, 7 November 2010

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.

Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어

External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

What is it?

Archiso is a small set of bash scripts that is capable of building fully functional Arch Linux based live CD/DVD and 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!

Due to recent changes, Archiso will now automatically create ISO images that are also USB images! Separate CD/USB targets are therefore no longer necessary.

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 --needed -S mkinitcpio cdrkit squashfs-tools devtools syslinux mkinitcpio-nfs-utils nbd

Configure our live medium


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 myarch && cd myarch

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.
#  A list of packages to install, either space separated in a string or line separated in a file. Can include groups.
PACKAGES="$(shell cat packages.list) syslinux"
# The name of our ISO. Does not specify the architecture!
# Version will be appended to the ISO.
# Kernel version. You'll need this. Don't change it.
# Architecture will also be appended to the ISO name.
ARCH?=$(shell uname -m)
# Current working directory
PWD:=$(shell pwd)
# This is going to be the full name the final iso/img will carry

# Default make instruction to build everything.
all: myarch

# The following will first run the base-fs routine before creating the final iso image.
myarch: base-fs
	mkarchiso -p syslinux iso "$(WORKDIR)" "$(FULLNAME)".iso

# This is the main rule for make the working filesystem. It will run routines from left to right. 
# Thus, root-image is called first and syslinux is called last.
base-fs: root-image boot-files initcpio overlay iso-mounts syslinux

# 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: "$(WORKDIR)"/root-image/.arch-chroot
	mkarchiso -p $(PACKAGES) create "$(WORKDIR)"

# Rule for make /boot
boot-files: root-image
	cp -r "$(WORKDIR)"/root-image/boot "$(WORKDIR)"/iso/
	cp -r boot-files/* "$(WORKDIR)"/iso/boot/

# Rules for initcpio images
initcpio: "$(WORKDIR)"/iso/boot/myarch.img
"$(WORKDIR)"/iso/boot/myarch.img: mkinitcpio.conf "$(WORKDIR)"/root-image/.arch-chroot
	mkdir -p "$(WORKDIR)"/iso/boot
	mkinitcpio -c ./mkinitcpio.conf -b "$(WORKDIR)"/root-image -k $(shell grep ^ALL_kver $(kver_FILE) | cut -d= -f2) -g $@

# See: Overlay
	mkdir -p "$(WORKDIR)"/overlay/etc/pacman.d
	cp -r overlay "$(WORKDIR)"/
	wget -O "$(WORKDIR)"/overlay/etc/pacman.d/mirrorlist http://www.archlinux.org/mirrorlist/all/
	sed -i "s/#Server/Server/g" "$(WORKDIR)"/overlay/etc/pacman.d/mirrorlist

# Rule to process isomounts file.
iso-mounts: "$(WORKDIR)"/isomounts
"$(WORKDIR)"/isomounts: isomounts root-image
	sed "s|@ARCH@|$(ARCH)|g" isomounts > $@

# This routine is always executed just before generating the actual image. 
syslinux: root-image
	mkdir -p $(WORKDIR)/iso/boot/syslinux
	cp $(WORKDIR)/root-image/usr/lib/syslinux/*.c32 $(WORKDIR)/iso/boot/syslinux/
	cp $(WORKDIR)/root-image/usr/lib/syslinux/isolinux.bin $(WORKDIR)/iso/boot/syslinux/

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

.PHONY: all myarch
.PHONY: base-fs
.PHONY: root-image boot-files initcpio overlay iso-mounts
.PHONY: syslinux
.PHONY: clean

So if "make myarch" is called (as root!), the following is what effectively happens:

  • root-image downloads and installs all chosen packages into $WORKDIR
  • boot-files prepares generic bootloader files and then copies our custom bootloader settings
  • initcpio takes care of an initcpio for us
  • overlay copies our custom overlay files into the root-image in $WORKDIR
  • iso-mounts just a little sed magic so AUFS will be able to find its mount points at boot time
  • syslinux copies over our actual bootloader
  • myarch finally creates our bootable .iso file, ready for burning onto a CD/DVD or writing to a USB device

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


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 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.


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:


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!


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

Warning: There should be an enter [empty line] which represents EOF [end of file] at the end of isomounts file or else expect kernel panic!


You will add least need a "boot-files" directory and and a subdirectory "syslinux/" containing a "syslinux.cfg".

Warning: Due to recent changes, support for grub as a boot manager for Archiso live medium creation has been dropped. Please do not attempt to use grub. Instead, you will have to use syslinux's isolinux which will get you an iso that will double as a usb image for free.

Using isolinux

Using isolinux is easy:

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

Sample contents:

prompt 1
timeout 0
display myarch.msg
DEFAULT myarch

LABEL myarch
KERNEL /boot/vmlinuz26
APPEND initrd=/boot/myarch.img archisolabel=XXX locale=en_US.UTF-8

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

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

$ vim boot-files/syslinux/myarch.msg

This can be any arbitrary message in ASCII:


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. You can install it locally via pacman or you can find the binary package online if you don't want it locally installed. Put it in the boot-files/ directory for USB usage. I also had to rename the memtest*.bin file and remove the .bin extension, with .bin it booted a continuous display of "0104" (not sure if this is a stand alone issue or not). Edit your syslinux.cfg KERNEL line accordingly.

$ pacman -S memtest86+
$ cp /boot/memtest86+/memtest.bin boot-files/memtest

syslinux.cfg memtest entry:

LABEL memtest86+
KERNEL /boot/memtest

Due to the modular nature of isolinux, you are able to use lots of addons since all *.c32 files are copied and available to you. Take a look at the official syslinux site and the archiso git repo. Using said addons, it is possible to make visually attractive and complex menus. See here.


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

Adding a predefined user


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:


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 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 or for dd'ing onto a USB key:

dd if=my-image.iso of=/dev/some-usb-drive bs=8M
Note: If you an extra partition to your USB key, ensure to assign a LABEL to the filesystem, otherwise the live-medium will fail to boot


Warning: Careful with dd! If you use it on the wrong drive, a lot of precious data may be lost. Use with caution.
Note: If you get any errors during the process try one of the the following: a) enable [testing] and update mkinitcpio, b) replace "iso-mounts" with "isomounts" in the Makefile, c) replace "archiso-early" with "archiso_early" in mkinitcpio.conf. May or may not help.

See also