Skip to content

Making your own aerOS ISO

Jump to bottom
Debarka Kundu edited this page Jan 29, 2024 · 11 revisions

This is a deprecated wiki, Please follow Build aerOS wiki instead.

In this wiki page we are going to show you how to make your own aerOS ISO!

Do things before starting

  • Before we start doing things we need to do several things, first and important part is to get archiso package you can get it by running this command:

$ sudo pacman -S archiso

  • archiso only works with Arch Linux based distros except Manjaro for some reason, but it is recommended to do all this in normal Arch Linux, we need to also install zsh so that it compiles without any errors you can install it by running this command:

$ sudo pacman -S zsh

  • Now, If you are a bash user and want to be bash user and don't to use zsh as default, don't worry you can use zsh without setting it as default by running zsh then pressing the q key, this will quit the zsh setup then load zsh. To tell that zsh is running check weather the $ is replaced with % just like this:

Bash: [hewol@aerOS ~] $

zsh: aerOS%

  • Then we get git by running this command:

% sudo pacman -S git

  • Now we are ready to start doing actions!

Getting the needed files

  • Now if you are making a custom Arch Linux then you can run this command:

% cp -r /usr/share/archiso/configs/releng/ archlive

  • however, if you are making a custom aerOS then you have to clone files from our iso-profile repo, you can run this command to clone all files:

% git clone https://github.com/hewol/aerOS.git

  • after cloning the repo you will see few files and one folder, go to the archlive directory, now we can start customizing!

Information

Now before we start customizing we need to talk about some files..

packages.x86_64 (in archlive)

  • This file contains all packages that will be installed in the archiso

pacman.conf (in archlive)

  • The pacman.conf contains the pacman config when generating the ISo, so it will not be used inside the system.

pacman.conf (in archlive/airootfs/etc)

  • The pacman.conf inside the etc inside the airrootfs folder is the pacman config that will be used inside the system.

.zlogin (in archlive/airrootfs/root)

  • This is a script file where you can add commands that will execute at login, Note: This file is hidden.

Simple Customization

Now lets start customizing!

  • We can add packages in packages.x86_64 file in archlive directory, such as steam, gnome, firefox, etc. then we can add custom repo in pacman.conf file in archlive and archlive/airrootfs/etc.
  • If you are using aerOS iso-profile then calamares is already configured but you can change the configs to your own by going to the calamares directory but as of now, calamares configs are not ready yet and its not added into aerOS iso-profile, but it will be added later on.
  • We can also add custom files into the airrootfs folder.

Now we move to heavy customization! (For advanced users, If you are not a advanced user then go to compiling and building part.)

Heavy Customization

(NOTE: This part are copied from the ArchWiki)

Profile structure

  • An archiso profile contains configuration that defines the resulting ISO image. The profile structure is documented in /usr/share/doc/archiso/README.profile.rst[1].

Selecting packages

  • Edit packages.x86_64 to select which packages are to be installed on the live system image, listing packages line by line.

Custom local repository

  • To add packages not located in standard Arch repositories (e.g. custom packages or packages from AUR/ABS), set up a custom local repository and add your custom packages to it. Then add your repository to pacman.conf as follows:

archlive/pacman.conf

[customrepo]
SigLevel = Optional TrustAll
Server = file:///path/to/customrepo

Note: The ordering within pacman.conf matters. To give top priority to your custom repository, place it above the other repository entries. This pacman.conf is only used for building the image. It will not be used in the live environment. To do this, see #Adding repositories to the image.

Packages from multilib

  • To install packages from the multilib repository, simply uncomment that repository in pacman.conf.

Adding files to image

  • The airootfs directory is used as the starting point for the root directory (/) of the live system on the image. All its contents will be copied over to the working directory before packages are installed.

  • Place any custom files and/or directories in the desired location under airootfs/. For example, 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

  • Similarly, some care is required for special configuration files that reside somewhere down the hierarchy. Missing parts of the directory structure can be simply created with mkdir(1).

Tip: To add a file to the install user's home directory, place it in archlive/airootfs/root/. To add a file to all other users home directories, place it in archlive/airootfs/etc/skel/.

Note: Custom files that conflict with those provided by packages will be overwritten unless a package specifies them as backup files. By default, permissions will be 644 for files and 755 for directories. All of them will be owned by the root user. To set different permissions or ownership for specific files and/or folders, use the file_permissions associative array in profiledef.sh. See README.profile.rst for details.

Adding repositories to the image

  • To add a repository that can be used in the live environment, create a suitably modified pacman.conf and place it in archlive/airootfs/etc/.

  • If the repository also uses a key, place the key in archlive/airootfs/usr/share/pacman/keyrings/. The key file name must end with .gpg. Additionally, the key must be trusted. This can be accomplished by creating a GnuPG exported trust file in the same directory. The file name must end with -trusted. The first field is the key fingerprint, and the second is the trust. You can reference /usr/share/pacman/keyrings/archlinux-trusted for an example.

archzfs example The files in this example are:

airootfs
├── etc
│   ├── pacman.conf
│   └── pacman.d
│       └── archzfs_mirrorlist
└── usr
    └── share
        └── pacman
            └── keyrings
                ├── archzfs.gpg
                └── archzfs-trusted

airootfs/etc/pacman.conf

[archzfs]
Include = /etc/pacman.d/archzfs_mirrorlist

airootfs/etc/pacman.d/archzfs_mirrorlist

Server = https://archzfs.com/$repo/$arch
Server = https://mirror.sum7.eu/archlinux/archzfs/$repo/$arch
Server = https://mirror.biocrafting.net/archlinux/archzfs/$repo/$arch
Server = https://mirror.in.themindsmaze.com/archzfs/$repo/$arch
Server = https://zxcvfdsa.com/archzfs/$repo/$arch
airootfs/usr/share/pacman/keyrings/archzfs-trusted
DDF7DB817396A49B2A2723F7403BD972F75D9D76:4:

archzfs.gpg itself can be obtained directly from the repository site at https://archzfs.com/archzfs.gpg.

Kernel

  • Although both archiso's included profiles only have linux, ISOs can be made to include other or even multiple kernels.

  • First, edit packages.x86_64 to include kernel package names that you want. When mkarchiso runs, it will include all work_dir/airootfs/boot/vmlinuz-* and work_dir/boot/initramfs-*.img files in the ISO (and additionally in the FAT image used for UEFI booting).

  • mkinitcpio presets by default will build fallback initramfs images. For an ISO, the main initramfs image would not typically include the autodetect hook, thus making an additional fallback image unnecessary. To prevent the creation of an fallback initramfs image, so that it does not take up space or slow down the build process, place a custom preset in archlive/airootfs/etc/mkinitcpio.d/pkgbase.preset.

For example, for linux-lts:

archlive/airootfs/etc/mkinitcpio.d/linux-lts.preset

PRESETS=('archiso')

ALL_kver='/boot/vmlinuz-linux-lts'
ALL_config='/etc/mkinitcpio.conf'

archiso_image="/boot/initramfs-linux-lts.img"

Finally create boot loader configuration to allow booting the kernel(s).

Boot loader

Archiso supports syslinux for BIOS booting and GRUB or systemd-boot for UEFI booting. Refer to the articles of the boot loaders for information on their configuration syntax.

Tip: The releng profile by default builds into an ISO that supports both BIOS and UEFI booting when burned to an optical disc using El Torito, or when written to a hard disk (or USB flash drive, or similar) using Isohybrid. 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 [2].

  • mkarchiso expects that GRUB configuration is in the grub directory, systemd-boot configuration is in the efiboot directory, and syslinux configuration in syslinux and isolinux directories.

UEFI Secure Boot

systemd units

  • To enable systemd services/sockets/timers for the live environment, you need to manually create the symbolic links just as systemctl enable does it.

  • For example, to enable gpm.service, which contains WantedBy=multi-user.target, run:

% mkdir -p archlive/airootfs/etc/systemd/system/multi-user.target.wants

% ln -s /usr/lib/systemd/system/gpm.service archlive/airootfs/etc/systemd/system/multi-user.target.wants/

The required symlinks can be found out by reading the systemd unit, or if you have the service installed, by enabling it and observing the systemctl output.

Login manager

  • Starting X at boot is done by enabling your login manager's systemd service. If you do not know which .service to enable, 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 symlink 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.

Changing automatic login

  • The configuration for getty's automatic login is located under airootfs/etc/systemd/system/[email protected]/autologin.conf.

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

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

Or remove autologin.conf altogether to disable auto login.

If you are using the serial console, create airootfs/etc/systemd/system/[email protected]/autologin.conf with the following content instead:

[Service]
ExecStart=
ExecStart=-/sbin/agetty -o '-p -- \\u' --noclear --autologin root --keep-baud 115200,57600,38400,9600 - $TERM

Users and passwords

To create a user which will be available in the live environment, you must manually edit archlive/airootfs/etc/passwd, archlive/airootfs/etc/shadow, archlive/airootfs/etc/group and archlive/airootfs/etc/gshadow.

Note: If these files exist, they must contain the root user and group.

  • For example, to add a user archie. Add them to archlive/airootfs/etc/passwd following the passwd(5) syntax:

archlive/airootfs/etc/passwd

root:x:0:0:root:/root:/usr/bin/zsh
archie:x:1000:1000::/home/archie:/usr/bin/zsh

Generate a password hash with openssl passwd -6 and add it to archlive/airootfs/etc/shadow following the syntax of shadow(5). For example:

archlive/airootfs/etc/shadow

root::14871::::::
archie:$6$randomsalt$cij4/pJREFQV/NgAgh9YyBIoCRRNq2jp5l8lbnE5aLggJnzIRmNVlogAg8N6hEEecLwXHtMQIl2NX2HlDqhCU1:14871::::::

Add the user's group and the groups which they will part of to archlive/airootfs/etc/group according to group(5). For example:

archlive/airootfs/etc/group

root:x:0:root
adm:x:4:archie
wheel:x:10:archie
uucp:x:14:archie
archie:x:1000:

Create the appropriate archlive/airootfs/etc/gshadow according to gshadow(5):

archlive/airootfs/etc/gshadow

root:!*::root
archie:!*::

Make sure /etc/shadow and /etc/gshadow have the correct permissions:

archlive/profiledef.sh

file_permissions=(
  ...
  ["/etc/shadow"]="0:0:0400"
  ["/etc/gshadow"]="0:0:0400"
)

  • After package installation, mkarchiso will create all specified home directories for users listed in archlive/airootfs/etc/passwd and copy work_directory/x86_64/airootfs/etc/skel/* to them. The copied files will have proper user and group ownership.

  • Changing the distribution name used in the ISO

  • Start by copying the file /etc/os-release into the etc/ folder in the rootfs. Then, edit the file accordingly. You can also change the name inside of GRUB and syslinux.

Compiling and Building

  • Now after you are done doing things and modding its time to Compile our custom ISO. Its very simple to compile we first go to the archlive directory then we run this command.

% sudo mkarchiso -v .

  • then it will compile and build the custom ISO. Note it will take 20 - 40 GB depending what things you added and at least 2 hrs needed for it to compile and build. After its done a ISO file will be created in the out directory.

NOTE: Our package repository is hosted on github pages which might not work all the time so keep trying until it works :).

Finished

  • Now we can get our ISO from the out folder, test the ISO anywhere and if everything is alright, if not then you can create an issue in our aerOS repo. Anyways this is the END. of this wiki! Hope you enjoyed reading it and doing the things!
Clone this wiki locally