README.rst 5.1 KB
Newer Older
1
2
3
4
=======
archiso
=======

5
The archiso project features scripts and configuration templates to build installation media (*.iso* images and
6
7
*.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.
8
9
10
11
12
13
14

Requirements
============

The following packages need to be installed to be able to create an image with the included scripts:

* arch-install-scripts
15
* awk
16
17
* dosfstools
* e2fsprogs
18
19
* erofs-utils (optional)
* findutils
20
* grub
21
22
* gzip
* libarchive
23
* libisoburn
24
* mtools
25
* openssl
26
27
* pacman
* sed
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
* 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/>`_
nl6720's avatar
nl6720 committed
45
(respectively). Both profiles are defined by files to be placed into overlays (e.g. airootfs  the image's ``/``).
46

nl6720's avatar
nl6720 committed
47
Read `README.profile.rst <docs/README.profile.rst>`_ to learn more about how to create profiles.
48

49
50
51
52
53
54
55
56
57
58
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
nl6720's avatar
nl6720 committed
59
writeable location, as ``/usr/share/archiso`` is tracked by the package manager and only writeable by root (changes will
60
61
62
63
be lost on update).

The examples below will assume an unmodified profile in a system location (unless noted otherwise).

64
It is advised to consult the help output of **mkarchiso**:
65

nl6720's avatar
nl6720 committed
66
.. code:: sh
67

nl6720's avatar
nl6720 committed
68
   mkarchiso -h
69
70
71
72

Create images with packaged archiso
-----------------------------------

nl6720's avatar
nl6720 committed
73
.. code:: sh
74

nl6720's avatar
nl6720 committed
75
   mkarchiso -w path/to/work_dir -o path/to/out_dir path/to/profile
76
77
78
79

Create images with local clone
------------------------------

80
Clone this repository and run:
81

nl6720's avatar
nl6720 committed
82
.. code:: sh
83

nl6720's avatar
nl6720 committed
84
   ./archiso/mkarchiso -w path/to/work_dir -o path/to/out_dir path/to/profile
85
86
87
88
89

Testing
=======

The convenience script **run_archiso** is provided to boot into the medium using qemu.
90
It is advised to consult its help output:
91

nl6720's avatar
nl6720 committed
92
.. code:: sh
93

nl6720's avatar
nl6720 committed
94
   run_archiso -h
95
96
97

Run the following to boot the iso using BIOS:

nl6720's avatar
nl6720 committed
98
.. code:: sh
99

nl6720's avatar
nl6720 committed
100
   run_archiso -i path/to/an/arch.iso
101
102
103

Run the following to boot the iso using UEFI:

nl6720's avatar
nl6720 committed
104
.. code:: sh
105

nl6720's avatar
nl6720 committed
106
   run_archiso -u -i path/to/an/arch.iso
107
108
109
110

The script can of course also be executed from this repository:


nl6720's avatar
nl6720 committed
111
.. code:: sh
112

nl6720's avatar
nl6720 committed
113
   ./scripts/run_archiso.sh -i path/to/an/arch.iso
114
115
116
117

Installation
============

nl6720's avatar
nl6720 committed
118
To install archiso system-wide use the included ``Makefile``:
119

nl6720's avatar
nl6720 committed
120
.. code:: sh
121

nl6720's avatar
nl6720 committed
122
   make install
123

nl6720's avatar
nl6720 committed
124
Optional features
125

nl6720's avatar
nl6720 committed
126
127
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.
128

nl6720's avatar
nl6720 committed
129
.. code:: sh
130
131
132
133
134
135

   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
136

David Runge's avatar
David Runge committed
137
138
139
Contribute
==========

nl6720's avatar
nl6720 committed
140
Development of archiso takes place on Arch Linux' Gitlab: https://gitlab.archlinux.org/archlinux/archiso.
David Runge's avatar
David Runge committed
141

nl6720's avatar
nl6720 committed
142
Please read our distribution-wide `Code of Conduct <https://wiki.archlinux.org/title/Code_of_conduct>`_ before
David Runge's avatar
David Runge committed
143
144
145
146
147
148
149
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
150
<ircs://irc.libera.chat/archlinux-releng>`_ on `Libera Chat <https://libera.chat/>`_.
David Runge's avatar
David Runge committed
151
152
153

All past and present authors of archiso are listed in `AUTHORS <AUTHORS.rst>`_.

154
155
156
Releases
========

157
`Releases of archiso <https://gitlab.archlinux.org/archlinux/archiso/-/tags>`_ are created by their current maintainers
158

159
160
161
162
163
164
- `David Runge <https://gitlab.archlinux.org/dvzrv>`_ (``C7E7849466FE2358343588377258734B41C31549``)
- `nl6720 <https://gitlab.archlinux.org/nl6720>`_ (``BB8E6F1B81CF0BB301D74D1CBF425A01E68B38EF``)

Tags are signed using respective PGP keys.

To verify a tag, first import the relevant PGP key(s):
165

nl6720's avatar
nl6720 committed
166
.. code:: sh
167

nl6720's avatar
nl6720 committed
168
  gpg --auto-key-locate wkd --search-keys dvzrv@archlinux.org
169

170
171
172
173
174
or

.. code:: sh

  gpg --auto-key-locate keyserver --recv-keys BB8E6F1B81CF0BB301D74D1CBF425A01E68B38EF
175
176
177

Afterwards a tag can be verified from a clone of this repository:

nl6720's avatar
nl6720 committed
178
.. code:: sh
179

nl6720's avatar
nl6720 committed
180
  git verify-tag <tag>
181

182
183
184
185
License
=======

Archiso is licensed under the terms of the **GPL-3.0-or-later** (see `LICENSE <LICENSE>`_).