Difference between revisions of "Archiso"

From ArchWiki
Jump to navigation Jump to search
m (I corrected the path of pacman.conf in the chapter "Custom local repository" from ~/archlive to ~/archlive/releng)
 
(166 intermediate revisions by 60 users not shown)
Line 1: Line 1:
 
[[Category:Live Arch systems]]
 
[[Category:Live Arch systems]]
[[Category:Getting and installing Arch]]
+
[[Category:Installation process]]
 +
[[Category:Arch projects]]
 
[[ar:Archiso]]
 
[[ar:Archiso]]
 
[[el:Archiso]]
 
[[el:Archiso]]
Line 6: Line 7:
 
[[fr:Archiso]]
 
[[fr:Archiso]]
 
[[it:Archiso]]
 
[[it:Archiso]]
 +
[[ja:Archiso]]
 
[[nl:Archiso]]
 
[[nl:Archiso]]
 +
[[pt:Archiso]]
 
[[ru:Archiso]]
 
[[ru:Archiso]]
[[uk:Archiso]]
+
[[sk:Archiso]]
[[zh-CN:Archiso]]
+
[[zh-hans:Archiso]]
'''Archiso''' is a small set of bash scripts capable of building fully functional Arch Linux based live CD and USB images. It is the tool used to generate the official CD/USB images, however it is a very generic tool and 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 won't be covered here. Instead, this wiki article will act as a guide for rolling your own live media in no time!
+
{{Related articles start}}
 +
{{Related|Remastering the Install ISO}}
 +
{{Related|Archiso as pxe server}}
 +
{{Related|Archboot}}
 +
{{Related|Offline installation}}
 +
{{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!
 +
 
 +
If you require a technical run-down of requirements and build steps only, have a look at the [https://git.archlinux.org/archiso.git/tree/docs official project documentation] too.
  
 
== Setup ==
 
== Setup ==
  
 
{{Note|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.}}
 
{{Note|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 we begin, we need to [[pacman|install]] {{Pkg|archiso}} from the [[official repositories]]. Alternatively, {{AUR|archiso-git}} can be found in the [[AUR]].
+
Before you begin, [[install]] the {{Pkg|archiso}} or {{AUR|archiso-git}} package.
 
 
Create a directory to work within, this is where all the modifications to the live image will take place: {{ic|~/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''.
 
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 wish to create a fully customized live version of Arch Linux, pre-installed with all your favorite programs and configurations, use ''releng''. This profile is also used for building an official Arch Linux ISO.
 +
* If you just want to create the most basic live medium, with no pre-installed packages and a minimalistic configuration, use ''baseline''.
  
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 (''archlive'' in the example below) where you can make adjustments and build it. Execute the following, replacing {{ic|'''profile'''}} with either {{ic|releng}} or {{ic|baseline}}.
  
So, depending on your needs, execute the following, replacing 'PROFILE' with either '''releng''' or '''baseline'''.
+
  # cp -r /usr/share/archiso/configs/'''profile'''/ ''archlive''
  # 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 our live medium]].
+
* If you are using the {{ic|releng}} profile to make a fully customized image, then you can proceed onto [[#Configure the live medium]].
 +
* If you are using the {{ic|baseline}} profile to create a bare image or using {{ic|releng}} to replicate an official ISO, then you will not be needing to do any customization and can proceed onto [[#Build the ISO]].
  
If you are using the ''baseline'' profile to create a bare image, then you won't be needing to do any customisations and can proceed onto [[#Build the ISO]].
+
== Configure the live medium ==
 
 
== 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.
 
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:  
+
Inside the {{ic|''archlive''}} directory created in [[#Setup]] 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
+
* {{ic|packages.x86_64}} - 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.
+
* the {{ic|airootfs}} directory - this directory acts as an overlay and it is where you make all the customizations.
  
Generally, every admininistrative task that you would normally do after a fresh install except for package installation can be scripted into {{ic|~/archlive/releng/root-image/root/customize-root-image.sh}}. It has to be written from the perpective of the new environment, so / in the script means the root of the live-iso which is created.
+
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 to be created.
  
 
=== Installing packages ===
 
=== 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.
+
Edit the lists of packages in {{ic|packages.x86_64}} to indicate which packages are to be installed on the live medium.
The packages.i686 and packages.x86_64 files allow you to install software on just 32bit or 64bit, respectively.
 
  
I recommend installing "rsync" if you wish to install the system later on with no internet connection or skipping downloading it all over again. ([[#Installation]])
+
{{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 ====
 
==== Custom local repository ====
  
{{Merge|Pacman tips#Custom local repository|Move the general information (e.g. repo tree) into the main article.}}
+
For the purpose of preparing custom packages or packages from [[AUR]]/[[ABS]], you could also [[custom local repository|create a custom local repository]].
 
 
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.
 
 
 
For instance:
 
 
 
*{{ic|~/customrepo}}
 
**{{ic|~/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 {{ic|repo-add}})
 
**{{ic|~/customrepo/i686}}
 
***~/customrepo/i686/foo-i686.pkg.tar.xz
 
***~/customrepo/i686/customrepo.db.tar.gz
 
***~/customrepo/i686/customrepo.db (symlink created by {{ic|repo-add}})
 
 
 
 
You can then add your repository by putting the following into {{ic|~/archlive/releng/pacman.conf}}, above the other repository entries (for top priority):
 
You can then add your repository by putting the following into {{ic|~/archlive/releng/pacman.conf}}, above the other repository entries (for top priority):
  
# custom repository
+
{{hc|~/archlive/releng/pacman.conf|...
[customrepo]
+
# custom repository
SigLevel = Optional TrustAll
+
[customrepo]
Server = file:///home/'''user'''/customrepo/$arch
+
SigLevel <nowiki>=</nowiki> Optional TrustAll
 +
Server <nowiki>=</nowiki> file:///home/'''user'''/customrepo/$arch
 +
...}}
  
So, the build scripts just look for the appropriate packages.
+
==== Preventing installation of packages belonging to base group ====
  
If this is not the case you will be running into error messages similar to this:
+
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.
  
error: failed to prepare transaction (package architecture is not valid)
+
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:
:: package foo-i686 does not have a valid architecture
 
 
 
==== Avoid installation of packages belonging to base group ====
 
 
 
By, default {{ic|/usr/bin/mkarchiso}}, a script which is used by {{ic|~/archlive/releng/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.
 
 
 
When blacklisting base group packages by adding them to the {{ic|IgnorePkg}} line in {{ic|~/archlive/releng/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 {{ic|-i}} flag to each line calling {{ic|pacstrap}} in {{ic|/usr/bin/mkarchiso}}.
 
* '''Dirty''': Add the {{ic|-i}} flag to each line calling {{ic|pacstrap}} in {{ic|/usr/bin/mkarchiso}}.
  
* '''Clean''': Create a copy of {{ic|/usr/bin/mkarchiso}} in which you add the flag and adapt {{ic|~/archlive/releng/build.sh}} so that it calls the modifed version of the mkarchiso script.
+
* '''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.
  
* '''Advanced''': Create a function for {{ic|~/archlive/releng/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.
+
* '''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.
  
=== Adding a user ===
+
==== Installing packages from multilib ====
  
User management can be handled the same way as during the normal installation process, except you put  your commands scripted into {{ic|~/archlive/releng/root-image/root/customize-root-image.sh}}. For further information have a look at [[Users and groups#User management|User management]].
+
To install packages from the [[multilib]] repository simply uncomment the repository in {{ic|~/archlive/pacman.conf}}:
 +
 +
{{hc|pacman.conf|2=
 +
[multilib]
 +
SigLevel = PackageRequired
 +
Include = /etc/pacman.d/mirrorlist
 +
}}
  
 
=== 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 customize_root_image.sh which we are going to use 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/
 
  
When {{ic|~/archlive/releng/root-image/root/customize-root-image.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.
+
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.
  
=== aitab ===
+
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.
  
The default file should work fine, so you should not need to touch it.
+
=== Boot Loader ===
 
 
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 %
 
  
{{Note|Some combinations are invalid. Example both {{ic|sfs_comp}} and {{ic|fs_type}} are set to none}}
 
 
=== mkinitcpio.conf ===
 
 
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.
  
An ''initcpio'' is necessary for creating a system that is able to "wake-up" from a CD/DVD/USB,
+
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].
  
The default list will get you a system that can be booted off a CD/DVD or a USB device. It is worth mentioning that hardware auto-detection and things of that nature do not belong here. Only what is 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.
+
==== UEFI Secure Boot ====
  
=== Boot Loader ===
+
If you want to make your Archiso bootable on a UEFI Secure Boot enabled environment, you must use a signed bootloader. You can follow the instructions on [[Secure Boot#Booting an install media]].
  
The default file should work fine, so you should not need to touch it.
+
=== Login manager ===
  
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].
+
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:
  
=== Login manager ===
+
$ ls -l /etc/systemd/system/display-manager.service
  
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're using the same program on the system you build your iso on. Just use
+
Now create the same softlink in {{ic|~/archlive/airootfs/etc/systemd/system}}. For LXDM:
  
  # systemctl disable '''nameofyourloginmanager'''
+
  # ln -s /usr/lib/systemd/system/lxdm.service ~/archlive/airootfs/etc/systemd/system/display-manager.service
  
to temporarily turn it off. Next type the same command again and replace "disable" with "enable" to activate it again. Systemctl prints information about softlink it creates. Now change to ~/archiso/releng/root-image/etc/systemd/system and create the same softlink there.
+
This will enable LXDM at system start on your live system.
  
An example (make sure you're either in ~/archiso/releng/root-image/etc/systemd/system or add it to the command):
+
Alternatively you can just enable the service in {{ic|airootfs/root/customize_airootfs.sh}} along with other services that are enabled there.
  
# ln -s /usr/lib/systemd/system/lxdm.service display-manager.service
+
If you want the graphical environment to actually start automatically during boot make sure to edit {{ic|airootfs/root/customize_airootfs.sh}} and replace
  
This will enable LXDM at system start on your live system.
+
systemctl set-default multi-user.target
 +
with
 +
systemctl set-default graphical.target
  
 
=== Changing Automatic Login ===
 
=== Changing Automatic Login ===
  
The configuration for getty's automatic login is located under root-image/etc/systemd/system/getty@tty1.service.d/autologin.conf.
+
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:
 
You can modify this file to change the auto login user:
Line 179: Line 155:
 
== 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:
+
 
 +
Inside {{ic|~/archlive}}, execute:
  
 
  # ./build.sh -v
 
  # ./build.sh -v
  
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/.
+
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_*
  
== Using the ISO ==
+
If you have edited {{ic|airootfs/root/customize_airootfs.sh}} to create an unprivileged user, the rebuild will fail when creating it because the user will already exist ({{Bug|41865}}). To avoid this issue, you need to check if the user exists before running {{ic|useradd}}, e.g. by running {{ic|id}}:
  
=== CD ===
+
! id arch && useradd -m -p "" -g users -G "adm,audio,floppy,log,network,rfkill,scanner,storage,optical,power,wheel" -s /usr/bin/zsh arch
  
Just burn the iso to a cd. You can follow [[CD Burning]] as you wish.
+
Also remove persistent data such as created users or symlinks such as {{ic|/etc/sudoers}}.
  
=== USB ===
+
{{Expansion|Report more data that needs to be removed or reset.}}
  
See [[USB Flash Installation Media]].
+
Rebuilds can be sped up slightly by editing the pacstrap script (located at /bin/pacstrap) and changing the following at line 361:
  
=== grub4dos ===
+
Before:
  
Grub4dos is a utility that can be used to create multiboot usbs, able to boot multiple linux distros from the same usb stick.
+
if ! pacman -r "$newroot" -Sy "${pacman_args[@]}"; then
  
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'''.
+
After:
Then edit the {{ic|menu.lst}} file from the grub4dos (it must be on the usb root) and add these lines:
 
  
{{bc|<nowiki>
+
if ! pacman -r "$newroot" -Sy --needed "${pacman_args[@]}"; then
title Archlinux x86_64
 
kernel /arch/boot/x86_64/vmlinuz archisolabel=<your usb label>
 
initrd /arch/boot/x86_64/archiso.img
 
</nowiki>}}
 
  
Change the {{ic|x86_64}} part as necessary and put your '''real''' usb label there.
+
This increases the speed of the initial bootstrap, since it does not have to download and install any of the base packages that are already installed.
  
=== Installation ===
+
=== Removal of work directory ===
  
Boot the created CD/DVD/USB. If you wish to install the Archiso you created '''-as it is-''', there are several ways to do this, but either way we're following the [[Beginners' guide]] mostly.
+
The temporary files are copied into work directory. If it happens that the build.sh script is interrupted, make sure there are no mount binds before deleting it - otherwise, you may lose data (e.g. an external device mounted at {{ic|/run/media/$user/$label}} gets bound within {{ic|work/x86_64/airootfs/run/media/$user/$label}} during the build process).
  
If you don't have an internet connection on that PC, or if you don't want to download every packages you want again, follow the guide, and when you get to [[Beginners' guide#Install_the_base_system]], instead of downloading, use this: [[Full system backup with rsync]]. (more info here: [[Talk:Archiso]])
+
== Using the ISO ==
  
You can also try: [[Archboot]], GUI installer.
+
See the [[Installation guide]] article for various options.
  
 
== See also ==
 
== See also ==
 +
=== Documentation and tutorials ===
 +
* [https://projects.archlinux.org/archiso.git  Archiso project page]
 +
* [https://projects.archlinux.org/archiso.git/tree/docs Official documentation]
 +
 +
=== Example customization template ===
 +
* [http://easy.open.and.free.fr/didjix/ A live DJ distribution powered by ArchLinux and built with Archiso]
 +
 +
=== Creating a offline installation ISO ===
 +
* [[Archiso offline]]
  
* [https://projects.archlinux.org/?p=archiso.git;a=summary Archiso project page]
+
=== Find a previous version of an ISO image ===
* [[Archiso_as_pxe_server|Archiso as pxe server]]
+
* [[Arch Linux Archive]]
* [http://blog.jak.me/2011/09/07/creating-a-custom-arch-linux-live-usb/ Creating a custom Arch Linux live USB tutorial]
 
* [http://didjix.blogspot.com/ A live DJ distribution powered by ArchLinux and built with Archiso]
 

Latest revision as of 16:03, 16 October 2019

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!

If you require a technical run-down of requirements and build steps only, have a look at the official project documentation too.

Setup

Note: 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 customized live version of Arch Linux, pre-installed with all your favorite programs and configurations, use releng. This profile is also used for building an official Arch Linux ISO.
  • 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 (archlive in the example below) where you can make adjustments and build it. 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 customized image, then you can proceed onto #Configure the live medium.
  • If you are using the baseline profile to create a bare image or using releng to replicate an official ISO, then you will not be needing to do any customization 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 created in #Setup there are a number of files and directories; we are only concerned with a few of these, mainly:

  • packages.x86_64 - 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 customizations.

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 to be created.

Installing packages

Edit the lists of packages in packages.x86_64 to indicate which packages are to be installed on the live medium.

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

For the purpose of preparing custom packages or packages from AUR/ABS, you could also create a custom local repository. You can then add your repository by putting the following into ~/archlive/releng/pacman.conf, above the other repository entries (for top priority):

~/archlive/releng/pacman.conf
...
# custom repository
[customrepo]
SigLevel = Optional TrustAll
Server = file:///home/user/customrepo/$arch
...

Preventing 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 simply uncomment the repository in ~/archlive/pacman.conf:

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

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.

UEFI Secure Boot

If you want to make your Archiso bootable on a UEFI Secure Boot enabled environment, you must use a signed bootloader. You can follow the instructions on Secure Boot#Booting an install media.

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.

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_*

If you have edited airootfs/root/customize_airootfs.sh to create an unprivileged user, the rebuild will fail when creating it because the user will already exist (FS#41865). To avoid this issue, you need to check if the user exists before running useradd, e.g. by running id:

! 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#)

Rebuilds can be sped up slightly by editing the pacstrap script (located at /bin/pacstrap) and changing the following at line 361:

Before:

if ! pacman -r "$newroot" -Sy "${pacman_args[@]}"; then

After:

if ! pacman -r "$newroot" -Sy --needed "${pacman_args[@]}"; then

This increases the speed of the initial bootstrap, since it does not have to download and install any of the base packages that are already installed.

Removal of work directory

The temporary files are copied into work directory. If it happens that the build.sh script is interrupted, make sure there are no mount binds before deleting it - otherwise, you may lose data (e.g. an external device mounted at /run/media/$user/$label gets bound within work/x86_64/airootfs/run/media/$user/$label during the build process).

Using the ISO

See the Installation guide article for various options.

See also

Documentation and tutorials

Example customization template

Creating a offline installation ISO

Find a previous version of an ISO image