ace88aaaca
README.rst: Add openssl as another dependency. Mention the export of netboot artifacts in the project introduction. Mention that archiso may be used on other operating systems as well.
182 lines
5.0 KiB
ReStructuredText
182 lines
5.0 KiB
ReStructuredText
=======
|
|
archiso
|
|
=======
|
|
|
|
The archiso project features scripts and configuration templates to build installation media (*.iso* images and
|
|
*.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.
|
|
|
|
Requirements
|
|
============
|
|
|
|
The following packages need to be installed to be able to create an image with the included scripts:
|
|
|
|
* arch-install-scripts
|
|
* awk
|
|
* dosfstools
|
|
* e2fsprogs
|
|
* erofs-utils (optional)
|
|
* findutils
|
|
* gzip
|
|
* libarchive
|
|
* libisoburn
|
|
* mtools
|
|
* openssl
|
|
* pacman
|
|
* sed
|
|
* 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/>`_
|
|
(respectively). Both profiles are defined by files to be placed into overlays (e.g. airootfs → the image's ``/``).
|
|
|
|
Read `README.profile.rst <docs/README.profile.rst>`_ to learn more about how to create profiles.
|
|
|
|
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
|
|
writeable location, as ``/usr/share/archiso`` is tracked by the package manager and only writeable by root (changes will
|
|
be lost on update).
|
|
|
|
The examples below will assume an unmodified profile in a system location (unless noted otherwise).
|
|
|
|
It is advised to consult the help output of **mkarchiso**:
|
|
|
|
.. code:: sh
|
|
|
|
mkarchiso -h
|
|
|
|
Create images with packaged archiso
|
|
-----------------------------------
|
|
|
|
.. code:: sh
|
|
|
|
mkarchiso -w path/to/work_dir -o path/to/out_dir path/to/profile
|
|
|
|
Create images with local clone
|
|
------------------------------
|
|
|
|
Clone this repository and run:
|
|
|
|
.. code:: sh
|
|
|
|
./archiso/mkarchiso -w path/to/work_dir -o path/to/out_dir path/to/profile
|
|
|
|
Testing
|
|
=======
|
|
|
|
The convenience script **run_archiso** is provided to boot into the medium using qemu.
|
|
It is advised to consult its help output:
|
|
|
|
.. code:: sh
|
|
|
|
run_archiso -h
|
|
|
|
Run the following to boot the iso using BIOS:
|
|
|
|
.. code:: sh
|
|
|
|
run_archiso -i path/to/an/arch.iso
|
|
|
|
Run the following to boot the iso using UEFI:
|
|
|
|
.. code:: sh
|
|
|
|
run_archiso -u -i path/to/an/arch.iso
|
|
|
|
The script can of course also be executed from this repository:
|
|
|
|
|
|
.. code:: sh
|
|
|
|
./scripts/run_archiso.sh -i path/to/an/arch.iso
|
|
|
|
Installation
|
|
============
|
|
|
|
To install archiso system-wide use the included ``Makefile``:
|
|
|
|
.. code:: sh
|
|
|
|
make install
|
|
|
|
Optionally install archiso's mkinitcpio hooks:
|
|
|
|
.. code:: sh
|
|
|
|
make install-initcpio
|
|
|
|
Optional features
|
|
|
|
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.
|
|
|
|
.. 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
|
|
|
|
Contribute
|
|
==========
|
|
|
|
Development of archiso takes place on Arch Linux' Gitlab: https://gitlab.archlinux.org/archlinux/archiso.
|
|
|
|
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>`_.
|
|
|
|
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
|
|
``C7E7849466FE2358343588377258734B41C31549``.
|
|
|
|
To verify a tag, first import the relevant PGP key:
|
|
|
|
.. code:: sh
|
|
|
|
gpg --auto-key-locate wkd --search-keys dvzrv@archlinux.org
|
|
|
|
|
|
Afterwards a tag can be verified from a clone of this repository:
|
|
|
|
.. code:: sh
|
|
|
|
git verify-tag <tag>
|
|
|
|
License
|
|
=======
|
|
|
|
Archiso is licensed under the terms of the **GPL-3.0-or-later** (see `LICENSE <LICENSE>`_).
|