Difference between revisions of "Archiso"

From ArchWiki
Jump to: navigation, search
m (id -> {{ic|id}})
 
(170 intermediate revisions by 58 users not shown)
Line 1: Line 1:
 
[[Category:Live Arch systems]]
 
[[Category:Live Arch systems]]
 +
[[Category:Getting and installing Arch]]
 +
[[ar:Archiso]]
 
[[el:Archiso]]
 
[[el:Archiso]]
 +
[[es:Archiso]]
 
[[fr:Archiso]]
 
[[fr:Archiso]]
 
[[it:Archiso]]
 
[[it:Archiso]]
 +
[[ja:Archiso]]
 
[[nl:Archiso]]
 
[[nl:Archiso]]
 
[[ru:Archiso]]
 
[[ru:Archiso]]
 +
[[sk:Archiso]]
 
[[uk:Archiso]]
 
[[uk:Archiso]]
'''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.
+
[[zh-CN:Archiso]]
The heart and soul of Archiso is mkarchiso. All of its options are documented in its usage output, so its direct usage won't be covered here. Instead, this wiki article will act as a guide for rolling your own live mediums in no time!
+
{{Related articles start}}
 +
{{Related|Remastering the Install ISO}}
 +
{{Related|Archiso as pxe server}}
 +
{{Related|Archboot}}
 +
{{Related articles end}}
 +
'''Archiso''' is a small set of bash scripts capable of building fully functional Arch Linux live CD/DVD/USB images. It is the same tool used to generate the official images, but since it is a very generic tool, it can 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 will not be covered here. Instead, this wiki article will act as a guide for rolling your own live media in no time!
  
 
== Setup ==
 
== Setup ==
  
Before we begin, we need to grab the archiso scripts which carry out the beef of the work for
+
{{Note|
 +
* To use Archiso you must be running on a x86_64 platform. [https://projects.archlinux.org/archiso.git/tree/docs/README.build#n67]
 +
* It is recommended to act as root in all the following steps. If not, it is very likely to have problems with false permissions later.}}
 +
Before you begin, [[install]] the {{Pkg|archiso}} or {{AUR|archiso-git}} package.
  
# pacman -S archiso
+
Archiso comes with two "profiles": ''releng'' and ''baseline''.
  
{{Note|1=Alternatively, the GIT version can be built and installed [https://aur.archlinux.org/packages.php?ID=25996 from the AUR].}}
+
* 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 medium, with no pre-installed packages and a minimalistic configuration, use ''baseline''.
  
Create a directory to work within, this is where all the modifications to the live image will take place: ~/archlive should do fine.
+
Now, copy the profile of your choice to a directory where you can make adjustments and build it (we will use {{ic|~/archlive}}). Execute the following, replacing {{ic|'''profile'''}} with either {{ic|releng}} or {{ic|baseline}}.
  $ mkdir ~/archlive
+
  # cp -r /usr/share/archiso/configs/'''profile'''/* ~/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.
+
* If you are using the {{ic|releng}} profile to make a fully customised image, then you can proceed onto [[#Configure the live medium]].
Archiso comes with two "profiles": releng, and baseline.
+
* If you are using the {{ic|baseline}} profile to create a bare image, then you will not be needing to do any customisations and can proceed onto [[#Build the ISO]].
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'''.
+
== Configure the live medium ==
# cp -r /usr/share/archiso/configs/'''PROFILE'''/ ~USER/archlive
+
  
If you are using the 'releng' profile to make a fully customised image, then you can proceed onto [[Archiso#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.
  
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]]
+
Inside the {{ic|~/archlive}} directory there are a number of files and directories; we are only concerned with a few of these, mainly:
 +
* {{ic|packages.*}} - this is where you list, line by line, the packages you want to have installed, and
 +
* the {{ic|airootfs}} directory - this directory acts as an overlay and it is where you make all the customisations.
  
== Setup (manual way) ==
+
Generally, every administrative task that you would normally do after a fresh install except for package installation can be scripted into {{ic|~/archlive/airootfs/root/customize_airootfs.sh}}. It has to be written from the perspective of the new environment, so {{ic|/}} in the script means the root of the live-iso which is created.
{{Note|If you have already completed Setup the 'automatic' way, using the steps above, then you do not need to read this section.}}
+
  
Setup a base filesystem
+
=== Installing packages ===
# mkarchiso init
+
  
Install other packages (optional)
+
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 in packages.both and bake the image.
# mkarchiso -p "pkg1 pkg2 pkg3 ... pkgN" install
+
The {{ic|packages.i686}} and {{ic|packages.x86_64}} files allow you to install software on just 32-bit or 64-bit, respectively.
  
At this point, customize anything that you want in root-image, then exit when done.
+
{{Note|If you want to use a [[window manager]] in the Live CD then you must add the necessary and correct [[video drivers]], or the WM may freeze on loading.}}
  
# mkarchiso -r "bash" run
+
==== Custom local repository ====
  
Setup initramfs image.
+
{{Merge|Pacman tips#Custom local repository|Move the general information (e.g. repo tree) into the main article.}}
Copy needed hooks to root-image
+
  
# cp /usr/lib/initcpio/hooks/archiso work/root-image/usr/lib/initcpio/hooks
+
You can also [[custom local repository|create a custom local repository]] for the purpose of preparing custom packages or packages from [[AUR]]/[[ABS]]. When doing so with packages for both architectures, you should follow a certain directory order to not run into problems.
# cp /usr/lib/initcpio/install/archiso work/root-image/usr/lib/initcpio/install
+
  
Create a config for mkinitcpio '''work/root-image/etc/mkinitcpio-archiso.conf'''
+
For instance:
HOOKS="base udev archiso pata scsi sata usb fw filesystems usbinput"
+
COMPRESSION="xz"
+
  
Create a folder named as your PC's architecture, and generate the initramfs image:
+
*{{ic|~/customrepo}}
# mkdir work/root-image/boot/i686
+
**{{ic|~/customrepo/x86_64}}
# mkarchiso -r "mkinitcpio -c /etc/mkinitcpio-archiso.conf -k /boot/vmlinuz-linux -g /boot/i686/archiso.img" run
+
***{{ic|~/customrepo/x86_64/foo-x86_64.pkg.tar.xz}}
 +
***{{ic|~/customrepo/x86_64/customrepo.db.tar.gz}}
 +
***{{ic|~/customrepo/x86_64/customrepo.db}} (symlink created by {{ic|repo-add}})
 +
**{{ic|~/customrepo/i686}}
 +
***{{ic|~/customrepo/i686/foo-i686.pkg.tar.xz}}
 +
***{{ic|~/customrepo/i686/customrepo.db.tar.gz}}
 +
***{{ic|~/customrepo/i686/customrepo.db}} (symlink created by {{ic|repo-add}})
  
Move kernel/initramfs to boot/
+
You can then add your repository by putting the following into {{ic|~/archlive/pacman.conf}}, above the other repository entries (for top priority):
# 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
+
# custom repository
 +
[customrepo]
 +
SigLevel = Optional TrustAll
 +
Server = file:///home/'''user'''/customrepo/$arch
  
Create a directory for it.
+
So, the build scripts just look for the appropriate packages.
  # mkdir -p work/iso/arch/boot/syslinux
+
  
Create a '''work/iso/arch/boot/syslinux/syslinux.cfg''' file.
+
If this is not the case you will be running into error messages similar to this:
  
{{bc|1=
+
error: failed to prepare transaction (package architecture is not valid)
DEFAULT menu.c32
+
:: package foo-i686 does not have a valid architecture
PROMPT 0
+
MENU TITLE Arch Linux
+
TIMEOUT 300
+
  
LABEL arch
+
==== Avoid installation of packages belonging to base group ====
MENU LABEL Arch Linux
+
LINUX /arch/boot/i686/vmlinuz
+
INITRD /arch/boot/i686/archiso.img
+
APPEND archisolabel=MY_ARCH
+
  
ONTIMEOUT arch
+
By default, {{ic|/usr/bin/mkarchiso}}, a script which is used by {{ic|~/archlive/build.sh}}, calls one of the {{Pkg|arch-install-scripts}} named {{ic|pacstrap}} without the {{ic|-i}} flag, which causes [[Pacman]] to not wait for user input during the installation process.
}}
+
  
Copy menu.c32 needed by previous config.
+
When blacklisting base group packages by adding them to the {{ic|IgnorePkg}} line in {{ic|~/archlive/pacman.conf}}, [[Pacman]] asks if they still should be installed, which means they will when user input is bypassed. To get rid of these packages there are several options:
# cp work/root-image/usr/lib/syslinux/menu.c32 work/iso/arch/boot/syslinux/
+
  
Setup isolinux (optional, only needed for booteable iso)
+
* '''Dirty''': Add the {{ic|-i}} flag to each line calling {{ic|pacstrap}} in {{ic|/usr/bin/mkarchiso}}.
  
# mkdir work/iso/isolinux
+
* '''Clean''': Create a copy of {{ic|/usr/bin/mkarchiso}} in which you add the flag and adapt {{ic|~/archlive/build.sh}} so that it calls the modified version of the mkarchiso script.
# 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'''
+
* '''Advanced''': Create a function for {{ic|~/archlive/build.sh}} which explicitly removes the packages after the base installation. This would leave you the comfort of not having to type enter so much during the installation process.
{{bc|
+
DEFAULT loadconfig
+
  
LABEL loadconfig
+
==== Installing packages from multilib ====
  CONFIG /arch/boot/syslinux/syslinux.cfg
+
 
  APPEND /arch/boot/syslinux/
+
To install packages from the [[multilib]] repository you have to create two pacman configuration files: one for x86_64 and one for i686. Copy {{ic|pacman.conf}} to {{ic|pacmanx86_64.conf}} and {{ic|pacmani686.conf}}. Uncomment the following lines to enable ''multilib'' in {{ic|pacmanx86_64.conf}}:
 +
 +
{{hc|pacmanx86_64.conf|2=
 +
[multilib]
 +
SigLevel = PackageRequired
 +
Include = /etc/pacman.d/mirrorlist
 
}}
 
}}
  
Create an '''work/iso/arch/aitab''' file.
+
Then edit {{ic|build.sh}} with an editor. Replace the following lines:
# <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)
+
{{hc|build.sh|
# mkarchiso prepare
+
run_once make_pacman_conf
  
Generate an ISO 9660 with "El Torito" boot image (optional)
+
# Do all stuff for each airootfs
# mkarchiso -L "MY_ARCH" iso "my-arch.iso"
+
for arch in i686 x86_64; do
 +
    run_once make_basefs
 +
    run_once make_packages
 +
done
  
== Configure our live medium ==
+
run_once make_packages_efi
  
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.
+
for arch in i686 x86_64; do
 +
    run_once make_setup_mkinitcpio
 +
    run_once make_customize_airootfs
 +
done
 +
}}
  
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:  
+
with:
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 ===
+
{{hc|build.sh|
 +
cp -v releng/pacmanx86_64.conf releng/pacman.conf
 +
run_once make_pacman_conf
  
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.
+
# Do all stuff for each airootfs
Edit the packages.i686, or packages.x86_64 file depending on whether you are create a 32bit, or 64bit image, respectively.
+
for arch in x86_64; do
+
    run_once make_basefs
{{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!}}
+
    run_once make_packages
 +
    run_once make_packages_efi
 +
    run_once make_setup_mkinitcpio
 +
    run_once make_customize_airootfs
 +
done
  
=== Adding a user ===
+
echo make_pacman_conf i686
 +
cp -v releng/pacmani686.conf releng/pacman.conf
 +
cp -v releng/pacmani686.conf ${work_dir}/pacman.conf
  
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)
+
for arch in i686; do
e.g.
+
    run_once make_basefs
# cp /etc/{shadow,passwd,group} ~/archlive/releng/root-image/etc/
+
    run_once make_packages
 +
    run_once make_packages_efi
 +
    run_once make_setup_mkinitcpio
 +
    run_once make_customize_airootfs
 +
done
 +
}}
  
{{Warning|The shadow file will contain your encrypted password. I recommend before you copy the shadow file over, 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.}}
+
In this way packages for x86_64 and i686 will be installed with their own pacman configuration file.
  
 
=== Adding files to image ===
 
=== 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.}}
+
{{Note|You must be root to do this, do not change the ownership of any of the files you copy over, '''everything''' within the airootfs 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.
+
The airootfs 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:
 
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
+
  # cp -r /etc/iptables ~/archlive/airootfs/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.
+
Placing files in the users home directory is a little different. Do not place them within {{ic|airootfs/home}}, but instead create a skel directory within {{ic|airootfs/}} and place them there. We will then add the relevant commands to the {{ic|customize_airootfs.sh}} which we are going to use 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):
+
First, create the skel directory:
  # cd ~/archlive/releng/root-image/etc && mkdir skel
+
  # mkdir ~/archlive/airootfs/etc/skel
  
Now copy the 'home' files to the skel directory, again doing everything as root!
+
Now copy the 'home' files to the skel directory, e.g for {{ic|.bashrc}}:
e.g for .bashrc.
+
  # cp ~/.bashrc ~/archlive/airootfs/etc/skel/
  # 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:
+
When {{ic|~/archlive/airootfs/root/customize_airootfs.sh}} is executed and a new user is created, the files from the skel directory will automatically be copied over to the new home folder, permissions set right.
  
# cd ~/archlive/releng/root-image/etc && touch rc.local && chmod +x rc.local
+
Similarly, some care is required for special configuration files that reside somewhere down the hierarchy. As an example the {{ic|/etc/X11/xinit/xinitrc}} configuration file resides on a path that might be overwritten by installing a package. To place the configuration file one should put the custom {{ic|xinitrc}} in {{ic|~/archlive/airootfs/etc/skel/}} and then modify {{ic|customize_airootfs.sh}} to move it appropriately.
  
Now add the all of following to rc.local, replacing 'youruser' with the user you specified earlier.
+
=== Boot Loader ===
# Create the user directory for live session
+
if [ ! -d /home/'''youruser''' ]; then
+
    mkdir /home/'''youruser''' && chown '''youruser''' /home/'''youruser'''
+
fi
+
# Copy files over to home
+
su -c "cp -r /etc/skel/.[a-zA-Z0-9]* /home/'''youruser'''/" '''youruser'''
+
 
+
=== aitab ===
+
  
 
The default file should work fine, so you should not need to touch it.
 
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.
+
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 [http://syslinux.zytor.com/wiki/index.php/SYSLINUX official syslinux site] and the [https://projects.archlinux.org/archiso.git/tree/configs/syslinux-iso/boot-files archiso git repo]. Using said addons, it is possible to make visually attractive and complex menus. See [http://syslinux.zytor.com/wiki/index.php/Comboot/menu.c32 here].
It consists of some fields which define the behaviour of images.
+
  
# <img>        <mnt>                <arch>  <sfs_comp>  <fs_type>  <fs_size>
+
=== Login manager ===
  
; <img>: Image name without extension (.fs .fs.sfs .sfs).
+
Starting X at boot is done by enabling your login manager's [[systemd]] service. If you know which .service file needs a softlink: Great. If not, you can easily find out in case you are using the same program on the system you build your iso on. Just use:
; <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 }. 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 %
+
  
{{Note|Some combinations are invalid. Example both sfs_comp and fs_type are set to none}}
+
$ ls -l /etc/systemd/system/display-manager.service
  
=== Boot Loader ===
+
Now create the same softlink in {{ic|~/archlive/airootfs/etc/systemd/system}}. For LXDM:
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 [http://syslinux.zytor.com/wiki/index.php/SYSLINUX official syslinux site] and the [http://projects.archlinux.org/archiso.git/tree/configs/syslinux-iso/boot-files archiso git repo]. Using said addons, it is possible to make visually attractive and complex menus. See [http://syslinux.zytor.com/wiki/index.php/Comboot/menu.c32 here].
+
# ln -s /usr/lib/systemd/system/lxdm.service ~/archlive/airootfs/etc/systemd/system/display-manager.service
  
=== Finishing the root-image ===
+
This will enable LXDM at system start on your live system.
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
+
Alternatively you can just enable the service in {{ic|airootfs/root/customize_airootfs.sh}} along with other services that are enabled there.
*Configure the ''hosts'' file
+
 
*Configure ''rc.conf'' (no fancy modules required here)
+
 
*Configure ''sudoers''
+
If you want the graphical environment to actually start automatically during boot make sure to edit {{ic|airootfs/root/customize_airootfs.sh}} and replace
*Configure ''rc.local''
+
 
*Put additional artworks onto the medium
+
systemctl set-default multi-user.target
*Put arbitrary binary stuff into opt/
+
with
 +
systemctl set-default graphical.target
 +
 
 +
=== Changing Automatic Login ===
 +
 
 +
The configuration for getty's automatic login is located under {{ic|airootfs/etc/systemd/system/getty@tty1.service.d/autologin.conf}}.
 +
 
 +
You can modify this file to change the auto login user:
 +
 
 +
[Service]
 +
ExecStart=
 +
ExecStart=-/sbin/agetty --autologin '''isouser''' --noclear %I 38400 linux
 +
 
 +
Or remove it altogether to disable auto login.
  
 
== Build the ISO ==
 
== Build the ISO ==
  
 
Now you are ready to turn your files into the .iso which you can then burn to CD or USB:
 
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:
 
  
# ./build.sh -v build single
+
First create the {{ic|out/}} directory,
  
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/.
+
# mkdir ~/archlive/out/
 +
 
 +
then inside {{ic|~/archlive}}, execute:
 +
 
 +
# ./build.sh -v
 +
 
 +
The script will now download and install the packages you specified to {{ic|work/*/airootfs}}, create the kernel and init images, apply your customizations and finally build the iso into {{ic|out/}}.
 +
 
 +
=== Rebuild the ISO ===
 +
 
 +
Rebuilding the iso after modifications is not officially supported. However, it is easily possible by applying two steps. First you have to remove lock files in the work directory:
 +
 
 +
# rm -v work/build.make_*
 +
 
 +
Furthermore it is required to edit the script {{ic|airootfs/root/customize_airootfs.sh}}, and add an {{ic|id}} command in the beginning of the {{ic|useradd}} line as shown here. Otherwise the rebuild stops at this point because the user that is to be added already exists [https://bugs.archlinux.org/task/41865].
 +
 
 +
{{Style|typo?}}
 +
 
 +
! id arch && useradd -m -p "" -g users -G "adm,audio,floppy,log,network,rfkill,scanner,storage,optical,power,wheel" -s /usr/bin/zsh arch
 +
 
 +
Also remove persistent data such as created users or symlinks such as {{ic|/etc/sudoers}}.
 +
 
 +
{{Expansion|Report more data that needs to be removed or reset.}}
  
 
== Using the ISO ==
 
== Using the ISO ==
 +
 
=== CD ===
 
=== CD ===
Just burn the iso to a cd. You can follow [[CD Burning]] as you wish.
+
 
 +
Just burn the iso to a CD. You can follow [[Optical disc drive#Burning]] as you wish.
 +
 
 
=== USB ===
 
=== USB ===
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
+
See [[USB flash installation media]].
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.
+
 
 +
=== GRUB ===
 +
 
 +
See [[Multiboot USB drive#Arch Linux]].
 +
 
 
=== grub4dos ===
 
=== grub4dos ===
Grub4dos is a utility that can be used to create multiboot usbs, able to boot multiple linux distros from the same usb stick.
 
  
To boot the generated system on a usb with grub4dos already installed, loop mount the ISO and copy the entire {{ic|/arch}} directory to the '''root of the usb'''.
+
Grub4dos is a utility that can be used to create multiboot USBs, able to boot multiple linux distros from the same USB stick.
Then edit the {{ic|menu.lst}} file from the grub4dos (it must be on the usb root) and add this lines:
+
 
 +
To boot the generated system on a USB with grub4dos already installed, loop mount the ISO and copy the entire {{ic|/arch}} directory to the '''root of the USB'''.
 +
Then edit the {{ic|menu.lst}} file from the grub4dos (it must be on the USB root) and add these lines:
 +
 
 
{{bc|<nowiki>
 
{{bc|<nowiki>
 
title Archlinux x86_64
 
title Archlinux x86_64
Line 229: Line 274:
 
initrd /arch/boot/x86_64/archiso.img
 
initrd /arch/boot/x86_64/archiso.img
 
</nowiki>}}
 
</nowiki>}}
 +
 
Change the {{ic|x86_64}} part as necessary and put your '''real''' usb label there.
 
Change the {{ic|x86_64}} part as necessary and put your '''real''' usb label there.
 +
 +
== Installation without Internet access ==
 +
 +
If you wish to install the archiso (e.g. [https://www.archlinux.org/download/ the official monthly release]) as it is without an Internet connection, or, if you do not want to download the packages you want again:
 +
 +
First, follow the [[Installation guide]], skipping the [[Installation guide#Connect to the Internet]] section, until the [[Installation guide#Install the base packages]] step.
 +
 +
=== Install the archiso to the new root ===
 +
Instead of installing the packages with {{ic|pacstrap}} (which would try to download from the remote repositories), copy ''everything'' in the live environment to the new root:
 +
# time cp -ax / /mnt
 +
{{Note|The option ({{ic|-x}}) excludes some special directories, as they should not be copied to the new root.}}
 +
Then, copy the kernel image to the new root, in order to keep the integrity of the new system:
 +
# cp -vaT /run/archiso/bootmnt/arch/boot/$(uname -m)/vmlinuz /mnt/boot/vmlinuz-linux
 +
 +
After that, generate a fstab as described in [[Installation guide#Fstab]].
 +
 +
=== Chroot and configure the base system ===
 +
Next, chroot into your newly installed system:
 +
# arch-chroot /mnt /bin/bash
 +
 +
{{Note|Before performing the other [[Installation guide#Configure the system]] steps (e.g. locale, keymap, etc.), it is necessary to get rid of the trace of the Live environment (in other words, the customization of archiso which does not fit a non-Live environment).}}
 +
 +
==== Restore the configuration of journald ====
 +
[https://projects.archlinux.org/archiso.git/tree/configs/releng/airootfs/root/customize_airootfs.sh#n19 This customization of archiso] will lead to storing the system journal in RAM, it means that the journal will not be available after reboot:
 +
# sed -i 's/Storage=volatile/#Storage=auto/' /etc/systemd/journald.conf
 +
 +
==== Remove special udev rule ====
 +
[https://projects.archlinux.org/archiso.git/tree/configs/releng/airootfs/etc/udev/rules.d/81-dhcpcd.rules This rule of udev] starts the dhcpcd automatically if there are any wired network interfaces.
 +
 +
# rm /etc/udev/rules.d/81-dhcpcd.rules
 +
 +
==== Disable and remove the services created by archiso ====
 +
Some service files are created for the Live environment, please disable the services and remove the file as they are unnecessary for the new system:
 +
# systemctl disable pacman-init.service choose-mirror.service
 +
# rm -r /etc/systemd/system/{choose-mirror.service,pacman-init.service,etc-pacman.d-gnupg.mount,getty@tty1.service.d}
 +
# rm /etc/systemd/scripts/choose-mirror
 +
 +
==== Remove special scripts of the Live environment ====
 +
There are some scripts installed in the live system by archiso scripts, which are unnecessary for the new system:
 +
# rm /etc/systemd/system/getty@tty1.service.d/autologin.conf
 +
# rm /root/{.automated_script.sh,.zlogin}
 +
# rm /etc/mkinitcpio-archiso.conf
 +
# rm -r /etc/initcpio
 +
 +
==== Configure the system ====
 +
 +
Now you can follow the skipped steps of the [[Installation guide#Configure the system]] section (setting a locale, timezone, hostname, etc.) and finish the installation by creating an initial ramdisk as described in [[Installation guide#Initramfs]].
 +
 
== See also ==
 
== See also ==
*[http://projects.archlinux.org/?p=archiso.git;a=summary Archiso project page]
+
=== Documentation and tutorials ===
*[[Archiso_as_pxe_server|Archiso as pxe server]]
+
* [https://projects.archlinux.org/archiso.git Archiso project page]
*[https://kroweer.wordpress.com/2011/09/07/creating-a-custom-arch-linux-live-usb Step-by-step tutorial on using ArchISO]
+
* [https://projects.archlinux.org/archiso.git/tree/docs Official documentation]
*[http://didjix.blogspot.com/ A live DJ distribution powered by ArchLinux and built with Archiso]
+
 
 +
=== Example customization template ===
 +
* [http://didjix.blogspot.com/ A live DJ distribution powered by ArchLinux and built with Archiso]

Latest revision as of 01:58, 30 October 2016

Archiso is a small set of bash scripts capable of building fully functional Arch Linux live CD/DVD/USB images. It is the same tool used to generate the official images, but since it is a very generic tool, it can 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 will not be covered here. Instead, this wiki article will act as a guide for rolling your own live media in no time!

Setup

Note:
  • To use Archiso you must be running on a x86_64 platform. [1]
  • It is recommended to act as root in all the following steps. If not, it is very likely to have problems with false permissions later.

Before you begin, install the archiso or archiso-gitAUR package.

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 medium, with no pre-installed packages and a minimalistic configuration, use baseline.

Now, copy the profile of your choice to a directory where you can make adjustments and build it (we will use ~/archlive). 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 #Configure the live medium.
  • If you are using the baseline profile to create a bare image, then you will not be needing to do any customisations and can proceed onto #Build the ISO.

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

Inside the ~/archlive directory there are 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 airootfs directory - this directory acts as an overlay and it is where you make all the customisations.

Generally, every administrative task that you would normally do after a fresh install except for package installation can be scripted into ~/archlive/airootfs/root/customize_airootfs.sh. It has to be written from the perspective of the new environment, so / in the script means the root of the live-iso which is created.

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 in packages.both and bake the image. The packages.i686 and packages.x86_64 files allow you to install software on just 32-bit or 64-bit, respectively.

Note: If you want to use a window manager in the Live CD then you must add the necessary and correct video drivers, or the WM may freeze on loading.

Custom local repository

Merge-arrows-2.pngThis article or section is a candidate for merging with Pacman tips#Custom local repository.Merge-arrows-2.png

Notes: Move the general information (e.g. repo tree) into the main article. (Discuss in Talk:Archiso#)

You can also create a custom local repository for the purpose of preparing custom packages or packages from AUR/ABS. When doing so with packages for both architectures, you should follow a certain directory order to not run into problems.

For instance:

  • ~/customrepo
    • ~/customrepo/x86_64
      • ~/customrepo/x86_64/foo-x86_64.pkg.tar.xz
      • ~/customrepo/x86_64/customrepo.db.tar.gz
      • ~/customrepo/x86_64/customrepo.db (symlink created by repo-add)
    • ~/customrepo/i686
      • ~/customrepo/i686/foo-i686.pkg.tar.xz
      • ~/customrepo/i686/customrepo.db.tar.gz
      • ~/customrepo/i686/customrepo.db (symlink created by repo-add)

You can then add your repository by putting the following into ~/archlive/pacman.conf, above the other repository entries (for top priority):

# custom repository
[customrepo]
SigLevel = Optional TrustAll
Server = file:///home/user/customrepo/$arch

So, the build scripts just look for the appropriate packages.

If this is not the case you will be running into error messages similar to this:

error: failed to prepare transaction (package architecture is not valid)
:: package foo-i686 does not have a valid architecture

Avoid installation of packages belonging to base group

By default, /usr/bin/mkarchiso, a script which is used by ~/archlive/build.sh, calls one of the arch-install-scripts named pacstrap without the -i flag, which causes Pacman to not wait for user input during the installation process.

When blacklisting base group packages by adding them to the IgnorePkg line in ~/archlive/pacman.conf, Pacman asks if they still should be installed, which means they will when user input is bypassed. To get rid of these packages there are several options:

  • Dirty: Add the -i flag to each line calling pacstrap in /usr/bin/mkarchiso.
  • Clean: Create a copy of /usr/bin/mkarchiso in which you add the flag and adapt ~/archlive/build.sh so that it calls the modified version of the mkarchiso script.
  • Advanced: Create a function for ~/archlive/build.sh which explicitly removes the packages after the base installation. This would leave you the comfort of not having to type enter so much during the installation process.

Installing packages from multilib

To install packages from the multilib repository you have to create two pacman configuration files: one for x86_64 and one for i686. Copy pacman.conf to pacmanx86_64.conf and pacmani686.conf. Uncomment the following lines to enable multilib in pacmanx86_64.conf:

pacmanx86_64.conf
[multilib]
SigLevel = PackageRequired
Include = /etc/pacman.d/mirrorlist

Then edit build.sh with an editor. Replace the following lines:

build.sh
run_once make_pacman_conf

# Do all stuff for each airootfs
for arch in i686 x86_64; do
    run_once make_basefs
    run_once make_packages
done

run_once make_packages_efi

for arch in i686 x86_64; do
    run_once make_setup_mkinitcpio
    run_once make_customize_airootfs
done

with:

build.sh
cp -v releng/pacmanx86_64.conf releng/pacman.conf
run_once make_pacman_conf

# Do all stuff for each airootfs
for arch in x86_64; do
    run_once make_basefs
    run_once make_packages
    run_once make_packages_efi
    run_once make_setup_mkinitcpio
    run_once make_customize_airootfs
done

echo make_pacman_conf i686
cp -v releng/pacmani686.conf releng/pacman.conf
cp -v releng/pacmani686.conf ${work_dir}/pacman.conf


for arch in i686; do
    run_once make_basefs
    run_once make_packages
    run_once make_packages_efi
    run_once make_setup_mkinitcpio
    run_once make_customize_airootfs
done

In this way packages for x86_64 and i686 will be installed with their own pacman configuration file.

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 airootfs directory must be root owned. Proper ownerships will be sorted out shortly.

The airootfs 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/airootfs/etc

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

First, create the skel directory:

# mkdir ~/archlive/airootfs/etc/skel

Now copy the 'home' files to the skel directory, e.g for .bashrc:

# cp ~/.bashrc ~/archlive/airootfs/etc/skel/

When ~/archlive/airootfs/root/customize_airootfs.sh is executed and a new user is created, the files from the skel directory will automatically be copied over to the new home folder, permissions set right.

Similarly, some care is required for special configuration files that reside somewhere down the hierarchy. As an example the /etc/X11/xinit/xinitrc configuration file resides on a path that might be overwritten by installing a package. To place the configuration file one should put the custom xinitrc in ~/archlive/airootfs/etc/skel/ and then modify customize_airootfs.sh to move it appropriately.

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.

Login manager

Starting X at boot is done by enabling your login manager's systemd service. If you know which .service file needs a softlink: Great. If not, you can easily find out in case you are using the same program on the system you build your iso on. Just use:

$ ls -l /etc/systemd/system/display-manager.service

Now create the same softlink in ~/archlive/airootfs/etc/systemd/system. For LXDM:

# ln -s /usr/lib/systemd/system/lxdm.service ~/archlive/airootfs/etc/systemd/system/display-manager.service

This will enable LXDM at system start on your live system.

Alternatively you can just enable the service in airootfs/root/customize_airootfs.sh along with other services that are enabled there.


If you want the graphical environment to actually start automatically during boot make sure to edit airootfs/root/customize_airootfs.sh and replace

systemctl set-default multi-user.target

with

systemctl set-default graphical.target

Changing Automatic Login

The configuration for getty's automatic login is located under airootfs/etc/systemd/system/getty@tty1.service.d/autologin.conf.

You can modify this file to change the auto login user:

[Service]
ExecStart=
ExecStart=-/sbin/agetty --autologin isouser --noclear %I 38400 linux

Or remove it altogether to disable auto login.

Build the ISO

Now you are ready to turn your files into the .iso which you can then burn to CD or USB:

First create the out/ directory,

# mkdir ~/archlive/out/

then inside ~/archlive, execute:

# ./build.sh -v

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

Rebuild the ISO

Rebuilding the iso after modifications is not officially supported. However, it is easily possible by applying two steps. First you have to remove lock files in the work directory:

# rm -v work/build.make_*

Furthermore it is required to edit the script airootfs/root/customize_airootfs.sh, and add an id command in the beginning of the useradd line as shown here. Otherwise the rebuild stops at this point because the user that is to be added already exists [2].

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements.Tango-edit-clear.png

Reason: typo? (Discuss in Talk:Archiso#)
! id arch && useradd -m -p "" -g users -G "adm,audio,floppy,log,network,rfkill,scanner,storage,optical,power,wheel" -s /usr/bin/zsh arch

Also remove persistent data such as created users or symlinks such as /etc/sudoers.

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Report more data that needs to be removed or reset. (Discuss in Talk:Archiso#)

Using the ISO

CD

Just burn the iso to a CD. You can follow Optical disc drive#Burning as you wish.

USB

See USB flash installation media.

GRUB

See Multiboot USB drive#Arch Linux.

grub4dos

Grub4dos is a utility that can be used to create multiboot USBs, able to boot multiple linux distros from the same USB stick.

To boot the generated system on a USB with grub4dos already installed, loop mount the ISO and copy the entire /arch directory to the root of the USB. Then edit the menu.lst file from the grub4dos (it must be on the USB root) and add these lines:

title Archlinux x86_64
kernel /arch/boot/x86_64/vmlinuz archisolabel=<your usb label>
initrd /arch/boot/x86_64/archiso.img

Change the x86_64 part as necessary and put your real usb label there.

Installation without Internet access

If you wish to install the archiso (e.g. the official monthly release) as it is without an Internet connection, or, if you do not want to download the packages you want again:

First, follow the Installation guide, skipping the Installation guide#Connect to the Internet section, until the Installation guide#Install the base packages step.

Install the archiso to the new root

Instead of installing the packages with pacstrap (which would try to download from the remote repositories), copy everything in the live environment to the new root:

# time cp -ax / /mnt
Note: The option (-x) excludes some special directories, as they should not be copied to the new root.

Then, copy the kernel image to the new root, in order to keep the integrity of the new system:

# cp -vaT /run/archiso/bootmnt/arch/boot/$(uname -m)/vmlinuz /mnt/boot/vmlinuz-linux

After that, generate a fstab as described in Installation guide#Fstab.

Chroot and configure the base system

Next, chroot into your newly installed system:

# arch-chroot /mnt /bin/bash
Note: Before performing the other Installation guide#Configure the system steps (e.g. locale, keymap, etc.), it is necessary to get rid of the trace of the Live environment (in other words, the customization of archiso which does not fit a non-Live environment).

Restore the configuration of journald

This customization of archiso will lead to storing the system journal in RAM, it means that the journal will not be available after reboot:

# sed -i 's/Storage=volatile/#Storage=auto/' /etc/systemd/journald.conf

Remove special udev rule

This rule of udev starts the dhcpcd automatically if there are any wired network interfaces.

# rm /etc/udev/rules.d/81-dhcpcd.rules

Disable and remove the services created by archiso

Some service files are created for the Live environment, please disable the services and remove the file as they are unnecessary for the new system:

# systemctl disable pacman-init.service choose-mirror.service
# rm -r /etc/systemd/system/{choose-mirror.service,pacman-init.service,etc-pacman.d-gnupg.mount,getty@tty1.service.d}
# rm /etc/systemd/scripts/choose-mirror

Remove special scripts of the Live environment

There are some scripts installed in the live system by archiso scripts, which are unnecessary for the new system:

# rm /etc/systemd/system/getty@tty1.service.d/autologin.conf
# rm /root/{.automated_script.sh,.zlogin}
# rm /etc/mkinitcpio-archiso.conf
# rm -r /etc/initcpio

Configure the system

Now you can follow the skipped steps of the Installation guide#Configure the system section (setting a locale, timezone, hostname, etc.) and finish the installation by creating an initial ramdisk as described in Installation guide#Initramfs.

See also

Documentation and tutorials

Example customization template