2020-05-30 00:01:28 +02:00
|
|
|
=======
|
|
|
|
|
archiso
|
|
|
|
|
=======
|
|
|
|
|
|
2021-05-02 20:33:25 +02:00
|
|
|
The archiso project features scripts and configuration templates to build installation media (*.iso* images and
|
2021-05-09 23:03:48 +02:00
|
|
|
*.tar.gz* bootstrap images) as well as netboot artifacts for BIOS and UEFI based systems on the x86_64 architecture.
|
|
|
|
|
Currently creating the images is only supported on Arch Linux but may work on other operating systems as well.
|
2020-05-30 00:01:28 +02:00
|
|
|
|
|
|
|
|
Requirements
|
|
|
|
|
============
|
|
|
|
|
|
|
|
|
|
The following packages need to be installed to be able to create an image with the included scripts:
|
|
|
|
|
|
|
|
|
|
* arch-install-scripts
|
2021-05-02 20:33:25 +02:00
|
|
|
* awk
|
2020-05-30 00:01:28 +02:00
|
|
|
* dosfstools
|
|
|
|
|
* e2fsprogs
|
2021-05-02 20:33:25 +02:00
|
|
|
* erofs-utils (optional)
|
|
|
|
|
* findutils
|
|
|
|
|
* gzip
|
|
|
|
|
* libarchive
|
2020-05-30 00:01:28 +02:00
|
|
|
* libisoburn
|
2020-09-02 18:10:07 +02:00
|
|
|
* mtools
|
2021-05-09 23:03:48 +02:00
|
|
|
* openssl
|
2021-05-02 20:33:25 +02:00
|
|
|
* pacman
|
|
|
|
|
* sed
|
2020-05-30 00:01:28 +02:00
|
|
|
* squashfs-tools
|
|
|
|
|
|
|
|
|
|
For running the images in a virtualized test environment the following packages are required:
|
|
|
|
|
|
|
|
|
|
* edk2-ovmf
|
|
|
|
|
* qemu
|
|
|
|
|
|
|
|
|
|
For linting the shell scripts the following package is required:
|
|
|
|
|
|
|
|
|
|
* shellcheck
|
|
|
|
|
|
|
|
|
|
Profiles
|
|
|
|
|
========
|
|
|
|
|
|
|
|
|
|
Archiso comes with two profiles: **baseline** and **releng**. While both can serve as starting points for creating
|
|
|
|
|
custom live media, **releng** is used to create the monthly installation medium.
|
|
|
|
|
They can be found below `configs/baseline/ <configs/baseline/>`_ and `configs/releng/ <configs/releng/>`_
|
2021-03-22 14:23:14 +01:00
|
|
|
(respectively). Both profiles are defined by files to be placed into overlays (e.g. airootfs → the image's ``/``).
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:43:01 +01:00
|
|
|
Read `README.profile.rst <docs/README.profile.rst>`_ to learn more about how to create profiles.
|
2020-10-28 21:57:15 +01:00
|
|
|
|
2020-05-30 00:01:28 +02:00
|
|
|
Create images
|
|
|
|
|
=============
|
|
|
|
|
|
|
|
|
|
Usually the archiso tools are installed as a package. However, it is also possible to clone this repository and create
|
|
|
|
|
images without installing archiso system-wide.
|
|
|
|
|
|
|
|
|
|
As filesystems are created and various mount actions have to be done when creating an image, **root** is required to run
|
|
|
|
|
the scripts.
|
|
|
|
|
|
|
|
|
|
When archiso is installed system-wide and the modification of a profile is desired, it is necessary to copy it to a
|
2021-03-22 14:23:14 +01:00
|
|
|
writeable location, as ``/usr/share/archiso`` is tracked by the package manager and only writeable by root (changes will
|
2020-05-30 00:01:28 +02:00
|
|
|
be lost on update).
|
|
|
|
|
|
|
|
|
|
The examples below will assume an unmodified profile in a system location (unless noted otherwise).
|
|
|
|
|
|
Pass profile directory as parameter to mkarchiso
**archiso/mkarchiso**:
Change all override option parameters (i.e. `-A`, `-C`, `-D`, `-L`, `-P` and `-g`) to not directly override the global
variable they are tied to, but instead using an `override_` prefixed variable.
Add `_set_overrides()` to use `override_` prefixed variables (if set) to override those without a prefix.
Remove `-B` (a profile directory) from the list of parameters. The profile directory is now provided as separate
non-option parameter.
Add a call to `_read_profile()`, `_set_overrides()` and `command_build_profile()` to the fallthrough option of the
switch-case checking `command_name` - a non-option parameter to mkarchiso. This effectively provides the possibility to
set the profile directory using a non-option parameter, while still maintaining compatibility to legacy named arguments
used in the configs' `build.sh` scripts.
Extend the warning in regards to legacy `build.sh` based commands to mkarchiso by providing an EOL with archiso v49.
Change the help output to reflect the changes and further elaborate on the legacy commands used by `build.sh` scripts.
Change help output to be ordered alphabetically.
Add help output for `-r` and `-g` options.
Call `_set_overrides()` for legacy commands that accept one or more of the overriden options (i.e. `command_init`,
`command_install`, `command_prepare` and `command_iso`).
Various style fixes.
**configs/{baseline,releng}/build.sh**:
Change call to mkarchiso to use the profile's directory as a named argument instead of an option-argument.
**README.rst**:
Fix documentation on how to call mkarchiso with a profile directory.
Fix wording and ordering of option arguments for run_archiso documentation.
Fixes #52
2020-08-24 17:53:10 +02:00
|
|
|
It is advised to consult the help output of **mkarchiso**:
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
.. code:: sh
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
mkarchiso -h
|
2020-05-30 00:01:28 +02:00
|
|
|
|
|
|
|
|
Create images with packaged archiso
|
|
|
|
|
-----------------------------------
|
|
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
.. code:: sh
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
mkarchiso -w path/to/work_dir -o path/to/out_dir path/to/profile
|
2020-05-30 00:01:28 +02:00
|
|
|
|
|
|
|
|
Create images with local clone
|
|
|
|
|
------------------------------
|
|
|
|
|
|
2020-08-12 17:24:30 +02:00
|
|
|
Clone this repository and run:
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
.. code:: sh
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
./archiso/mkarchiso -w path/to/work_dir -o path/to/out_dir path/to/profile
|
2020-05-30 00:01:28 +02:00
|
|
|
|
|
|
|
|
Testing
|
|
|
|
|
=======
|
|
|
|
|
|
|
|
|
|
The convenience script **run_archiso** is provided to boot into the medium using qemu.
|
Pass profile directory as parameter to mkarchiso
**archiso/mkarchiso**:
Change all override option parameters (i.e. `-A`, `-C`, `-D`, `-L`, `-P` and `-g`) to not directly override the global
variable they are tied to, but instead using an `override_` prefixed variable.
Add `_set_overrides()` to use `override_` prefixed variables (if set) to override those without a prefix.
Remove `-B` (a profile directory) from the list of parameters. The profile directory is now provided as separate
non-option parameter.
Add a call to `_read_profile()`, `_set_overrides()` and `command_build_profile()` to the fallthrough option of the
switch-case checking `command_name` - a non-option parameter to mkarchiso. This effectively provides the possibility to
set the profile directory using a non-option parameter, while still maintaining compatibility to legacy named arguments
used in the configs' `build.sh` scripts.
Extend the warning in regards to legacy `build.sh` based commands to mkarchiso by providing an EOL with archiso v49.
Change the help output to reflect the changes and further elaborate on the legacy commands used by `build.sh` scripts.
Change help output to be ordered alphabetically.
Add help output for `-r` and `-g` options.
Call `_set_overrides()` for legacy commands that accept one or more of the overriden options (i.e. `command_init`,
`command_install`, `command_prepare` and `command_iso`).
Various style fixes.
**configs/{baseline,releng}/build.sh**:
Change call to mkarchiso to use the profile's directory as a named argument instead of an option-argument.
**README.rst**:
Fix documentation on how to call mkarchiso with a profile directory.
Fix wording and ordering of option arguments for run_archiso documentation.
Fixes #52
2020-08-24 17:53:10 +02:00
|
|
|
It is advised to consult its help output:
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
.. code:: sh
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
run_archiso -h
|
2020-05-30 00:01:28 +02:00
|
|
|
|
|
|
|
|
Run the following to boot the iso using BIOS:
|
|
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
.. code:: sh
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
run_archiso -i path/to/an/arch.iso
|
2020-05-30 00:01:28 +02:00
|
|
|
|
|
|
|
|
Run the following to boot the iso using UEFI:
|
|
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
.. code:: sh
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
run_archiso -u -i path/to/an/arch.iso
|
2020-05-30 00:01:28 +02:00
|
|
|
|
|
|
|
|
The script can of course also be executed from this repository:
|
|
|
|
|
|
|
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
.. code:: sh
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
./scripts/run_archiso.sh -i path/to/an/arch.iso
|
2020-05-30 00:01:28 +02:00
|
|
|
|
|
|
|
|
Installation
|
|
|
|
|
============
|
|
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
To install archiso system-wide use the included ``Makefile``:
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
.. code:: sh
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
make install
|
2020-05-30 00:01:28 +02:00
|
|
|
|
2020-07-29 18:23:58 +02:00
|
|
|
Optionally install archiso's mkinitcpio hooks:
|
|
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
.. code:: sh
|
2020-07-29 18:23:58 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
make install-initcpio
|
2020-07-29 18:23:58 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
Optional features
|
2021-01-06 11:59:53 +01:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
The iso image contains a GRUB environment block holding the iso name and version. This allows to
|
|
|
|
|
boot the iso image from GRUB with a version specific cow directory to mitigate overlay clashes.
|
2021-01-06 11:59:53 +01:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
.. code:: sh
|
|
|
|
|
loopback loop archlinux.iso
|
|
|
|
|
load_env -f (loop)/arch/grubenv
|
|
|
|
|
linux (loop)/arch/boot/x86_64/vmlinuz-linux ... \
|
|
|
|
|
cow_directory=${NAME}/${VERSION} ...
|
|
|
|
|
initrd (loop)/arch/boot/x86_64/initramfs-linux-lts.img
|
2021-01-06 11:59:53 +01:00
|
|
|
|
2020-10-09 10:57:40 +02:00
|
|
|
Contribute
|
|
|
|
|
==========
|
|
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
Development of archiso takes place on Arch Linux' Gitlab: https://gitlab.archlinux.org/archlinux/archiso.
|
2020-10-09 10:57:40 +02:00
|
|
|
|
|
|
|
|
Please read our distribution-wide `Code of Conduct <https://wiki.archlinux.org/index.php/Code_of_conduct>`_ before
|
|
|
|
|
contributing, to understand what actions will and will not be tolerated.
|
|
|
|
|
|
|
|
|
|
Read our `contributing guide <CONTRIBUTING.rst>`_ to learn more about how to provide fixes or improvements for the code
|
|
|
|
|
base.
|
|
|
|
|
|
|
|
|
|
Discussion around archiso takes place on the `arch-releng mailing list
|
|
|
|
|
<https://lists.archlinux.org/listinfo/arch-releng>`_ and in `#archlinux-releng
|
|
|
|
|
<ircs://chat.freenode.net/archlinux-releng>`_ on `freenode.net <https://freenode.net/>`_.
|
|
|
|
|
|
|
|
|
|
All past and present authors of archiso are listed in `AUTHORS <AUTHORS.rst>`_.
|
|
|
|
|
|
2021-03-29 21:27:44 +02:00
|
|
|
Releases
|
|
|
|
|
========
|
|
|
|
|
|
|
|
|
|
`Releases of archiso <https://gitlab.archlinux.org/archlinux/archiso/-/tags>`_ are created by its current maintainer
|
|
|
|
|
`David Runge <https://gitlab.archlinux.org/dvzrv>`_. Tags are signed using the PGP key with the ID
|
2021-03-22 14:23:14 +01:00
|
|
|
``C7E7849466FE2358343588377258734B41C31549``.
|
2021-03-29 21:27:44 +02:00
|
|
|
|
|
|
|
|
To verify a tag, first import the relevant PGP key:
|
|
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
.. code:: sh
|
2021-03-29 21:27:44 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
gpg --auto-key-locate wkd --search-keys dvzrv@archlinux.org
|
2021-03-29 21:27:44 +02:00
|
|
|
|
|
|
|
|
|
|
|
|
|
Afterwards a tag can be verified from a clone of this repository:
|
|
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
.. code:: sh
|
2021-03-29 21:27:44 +02:00
|
|
|
|
2021-03-22 14:23:14 +01:00
|
|
|
git verify-tag <tag>
|
2021-03-29 21:27:44 +02:00
|
|
|
|
2020-05-30 00:01:28 +02:00
|
|
|
License
|
|
|
|
|
=======
|
|
|
|
|
|
|
|
|
|
Archiso is licensed under the terms of the **GPL-3.0-or-later** (see `LICENSE <LICENSE>`_).
|