From ArchWiki
Revision as of 11:14, 1 May 2012 by Buergi (talk | contribs) (→‎Adding a user: Not 'passwd' contains password hash but 'shadow')
Jump to navigation Jump to search

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 – فارسی

Archiso is a small set of bash scripts that is capable of building fully functional Arch Linux based live CD and USB images. It is a very generic tool, so it could potentially be used to generate anything from rescue systems, 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!


Before we begin, we need to grab the archiso scripts which carry out the beef of the work for us. You can get archiso from Git (recommended) or from aur. We also need a few packages which archiso relies on; the following commands take care of this for us:

# pacman -S make git libisoburn squashfs-tools dosfstools rsync --needed
# git clone git://
# make -C archiso/archiso install

Create a directory to work within, this is where all the modifications to the live image will take place: ~/archlive should do fine.

$ mkdir ~/archlive

The archiso scripts that were installed to the host system earlier now need to be copied over into the newly created directory you will be working within. Archiso comes with two "profiles": releng, and baseline. If you wish to create a fully customised live version of Arch Linux, pre-installed with all your favourite programs and configurations, use "releng". If you just want to create the most basic live media, with no pre-installed packages and minimalistic configurations, then use "baseline".

So, depending on your needs, execute the following, replacing 'PROFILE' with either releng or baseline.

# cp -r /usr/share/archiso/configs/PROFILE/ ~/archlive

If you are using the 'releng' profile to make a fully customised image, then you can proceed onto Archiso#Configure_our_live_medium.

If you are using the 'baseline' profile to create a bare bones, installation image, then you won't be needing to do any customisations and can proceed onto Archiso#Build_the_ISO

Setup (manual way)

If you have already completed the setup the 'automatic' way, using the steps above, then you do not need to read this section. Setup a base filesystem

# mkarchiso init

Install other packages (optional)

# mkarchiso -p "pkg1 pkg2 pkg3 ... pkgN" install

At this point, customize anything what you want in root-image, then exit when done.

# mkarchiso-r "bash" run

Setup initramfs image. Copy needed hooks to root-image

# cp /lib/initcpio/hooks/archiso work/root-image/lib/initcpio/hooks
# cp /lib/initcpio/install/archiso work/root-image/lib/initcpio/install

Create a config for mkinitcpio work/root-image/etc/mkinitcpio-archiso.conf

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

Create a folder named as your PC's architecture, and generate the initramfs image:

# mkdir work/root-image/boot/i686
# mkarchiso -r "mkinitcpio -c /etc/mkinitcpio-archiso.conf -k /boot/vmlinuz-linux -g /boot/i686/archiso.img" run

Move kernel/initramfs to boot/

# mkdir -p work/iso/arch/boot/i686
# mv work/root-image/boot/vmlinuz-linux work/iso/arch/boot/i686/vmlinuz
# mv work/root-image/boot/i686/archiso.img work/iso/arch/boot/i686/archiso.img

Setup syslinux

Create a directory for it.

 # mkdir -p work/iso/arch/boot/syslinux

Create a work/iso/arch/boot/syslinux/syslinux.cfg file.

DEFAULT menu.c32

LABEL arch
LINUX /arch/boot/i686/vmlinuz
INITRD /arch/boot/i686/archiso.img
APPEND archisolabel=MY_ARCH


Copy menu.c32 needed by previous config.

# cp work/root-image/usr/lib/syslinux/menu.c32 work/iso/arch/boot/syslinux/

Setup isolinux (optional, only needed for booteable iso)

# mkdir work/iso/isolinux
# cp work/root-image/usr/lib/syslinux/isolinux.bin work/iso/isolinux/
# cp work/root-image/usr/lib/syslinux/isohdpfx.bin work/iso/isolinux/

Create a work/iso/isolinux/isolinux.cfg

DEFAULT loadconfig

LABEL loadconfig
  CONFIG /arch/boot/syslinux/syslinux.cfg
  APPEND /arch/boot/syslinux/

Create an work/iso/arch/aitab file.

# <img>         <mnt>                 <arch>   <sfs_comp>  <fs_type>  <fs_size>
root-image      /                     i686     xz          ext4       50%

Build all filesystem images specified in aitab (.fs .fs.sfs .sfs)

# mkarchiso prepare

Generate an ISO 9660 with "El Torito" boot image (optional)

# mkarchiso -L "MY_ARCH" iso "my-arch.iso"

Configure our live medium

This section details configuring the image you will be creating, allowing you to define the packages and configurations you want your live image to contain.

Change into the directory we created earlier (~/archlive/releng/ if you have been following this guide), you will see a number of files and directories; we are only concerned with a few of these, mainly: packages.* - this is where you list, line by line, the packages you want to have installed, and the root-image directory - this directory acts as an overlay and it is where you make all the customisations.

Installing packages

You will 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. This is great for special interest live CDs, just specify packages you want and bake the image. Edit the packages.i686, or packages.x86_64 file depending on whether you are create a 32bit, or 64bit image, respectively.

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!

Adding a user

There are two methods to creating a user: either by adding the relevant useradd command to rc.local, or by copying over (and modifying) /etc/shadow, /etc/passwd, and /etc/group. The latter method shall be discussed here.

Copy your /etc/shadow, /etc/passwd, and /etc/group from your host system to the /etc/ directory where you now working (which should be ~/archlive/releng/root-image/etc) e.g.

# cp /etc/{shadow,passwd,group} ~/archlive/releng/root-image/etc/
Warning: The shadow file will contain your encrypted password. I recommend before you copy the shadow file over to the, you change the password of your host user to that which you want your live user to have, copy the shadow file over, and then change back your password.

Adding files to image

Note: You must be root to do this, do not change the ownership of any of the files you copy over, everything within the root-image directory must be root owned. Proper ownerships will be sorted out shortly.

The root-image directory acts as an overlay, think of it as root directory '/' on your current system, so any files you place within this directory will be copied over on boot-up.

So if you have a set of iptables scripts on your current system you want to be used on you live image, copy them over as such:

# cp -r /etc/iptables ~/archlive/releng/root-image/etc

Placing files in the users home directory is a little different. Do not place them within root-image/home, but instead create a skel directory within root-image/ and place them there. We will then add the relevant commands to the rc.local we are going to create to copy them over on boot and sort out the permissions.

First, create the skel directory; making sure you are within ~/archlive/releng/root-image/etc directory (if this is where you are working from):

# cd ~/archlive/releng/root-image/etc && mkdir skel

Now copy the 'home' files to the skel directory, again doing everything as root! e.g for .bashrc.

# cp ~/.bashrc ~/archlive/releng/root-image/etc/skel/

Inside the root-image/etc/ directory, create the rc.local file, and make sure you make it executable:

# cd ~/archlive/releng/root-image/etc && touch rc.local && chmod +x rc.local

Now add the all of following to rc.local, replacing 'youruser' with the user you specified earlier.

# Create the user directory for live session
if [ ! -d /home/youruser ]; then
    mkdir /home/youruser && chown youruser /home/youruser
# Copy files over to home
su -c "cp -r /etc/skel/.[a-zA-Z0-9]* /home/youruser/" youruser


The default file should work fine, so you should not need to touch it.

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>
Image name without extension (.fs .fs.sfs .sfs).
Mount point.
Architecture { i686 | x86_64 | any }.
SquashFS compression type { gzip | lzo | xz }. A special value of "none" denotes no usage of SquashFS.
Set the filesystem type of the image { ext4 | ext3 | ext2 | xfs }. A special value of "none" denotes no usage of a filesystem. In that case all files are pushed directly to SquashFS filesystem.
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 %
Note: Some combinations are invalid. Example both sfs_comp and fs_type are set to none

Boot Loader

The default file should work fine, so you should not need to touch it.

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.

Finishing the root-image

Some tips that will not be covered in this article because there are other articles on this wiki that already do, but please feel free to add them here.

  • 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 additional artworks onto the medium
  • Put arbitrary binary stuff into opt/

Build the ISO

Now you are ready to turn your files into the .iso which you can then burn to CD or USB: Inside the directory you are working with, either ~/archlive/releng, or ~/archlive/baseline, execute:

# ./ -v build single netinstall

You can replace 'netinstall' with 'core' if you wish; however, doing so will cache all of the packages pacman downloads into the iso file, which will vastly inrease it's size.

The script will now download and install the packages you specified to work/*/root-image, create the kernel and init images, apply your customizations and finally build the iso into out/.

You can now dd the iso file onto a USB using dd, an example of which:

# dd if=~/archlive/releng/out/*.iso of=/dev/sdx

You will have to adjust accordingly, and make sure you choose the right output file! A simple mistake here will destory data on your harddisk.

See also