summaryrefslogtreecommitdiff
path: root/README.rst
blob: e8f782e5c3fb7868279effeffc11a3730238bbd7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
===========
parabolaiso
===========

The parabolaiso project features scripts and configuration templates to build installation media (*.iso* images) for BIOS
and UEFI based systems on the x86_64 and i686 architectures. It is based in `archiso <https://gitlab.archlinux.org/archlinux/archiso>`_
and `archiso32 <https://git.archlinux32.org/archiso32>`_.
Currently creating the images is only supported on Parabola GNU/Linux-libre.

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
========

parabolaiso comes with the following profiles: **baseline**, **releng**, **releng-openrc**, **lxde-openrc** and **talkingparabola**.
They can be found below `configs/baseline/ <configs/baseline/>`_, `configs/releng/ <configs/releng/>`_,
`configs/releng-openrc/ <configs/releng-openrc/>`_, `configs/lxde-openrc/ <configs/lxde-openrc/>`_, `configs/talkingparabola/ <configs/talkingparabola/>`_
(respectively). 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 parabolaiso tools are installed as a package. However, it is also possible to clone this repository and create
images without installing parabolaiso 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 parabolaiso 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/parabolaiso`` 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 **mkparabolaiso**:

.. code:: sh

   mkparabolaiso -h

Create images with packaged parabolaiso
---------------------------------------

.. code:: sh

  mkparabolaiso -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

  ./parabolaiso/mkparabolaiso -w path/to/work_dir -o path/to/out_dir path/to/profile

Testing
=======

The convenience script **run_parabolaiso** is provided to boot into the medium using qemu.
It is advised to read its help information:

.. code:: sh

  run_parabolaiso -h

Run the following to boot the iso using BIOS:

.. code:: sh

  run_parabolaiso -i path/to/a/parabola.iso

Run the following to boot the iso using UEFI:

.. code:: sh

  run_parabolaiso -u -i path/to/a/parabola.iso

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


.. code:: sh

  ./scripts/run_parabolaiso.sh -i path/to/a/parabola.iso

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

To install parabolaiso system-wide use the included ``Makefile``:

.. code:: sh

  make install

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 parabola.iso
  load_env -f (loop)/parabola/grubenv
  linux (loop)/parabola/boot/x86_64/vmlinuz-linux-libre ... \
      cow_directory=parabola/${VERSION} ...
  initrd (loop)/parabola/boot/x86_64/initramfs-linux-libre-lts.img

Contribute
==========

Development of parabolaiso takes place on Parabola GNU/Linux-libre' Git: https://git.parabola.nu/parabolaiso.git.

Read our `contributing guide <CONTRIBUTING.rst>`_ to learn more about how to provide fixes or improvements for the code
base.

Discussion around parabolaiso takes place on the `dev mailing list
<https://lists.parabola.nu/listinfo/dev>`_ and in `#parabola
<ircs://irc.libera.chat/parabola>`_ on `freenode.net <ircs://irc.libera.chat/>`_.

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

Releases
========

`Releases of parabolaiso <https://git.parabola.nu/parabolaiso.git/refs/tags>`_ are created by their current maintainers

- `David P <https://www.parabola.nu/people/hackers/#megver83>`_ (``6DB9C4B4F0D8C0DC432CF6E4227CA7C556B2BA78``)

Tags are signed using respective PGP keys.

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

.. code:: sh

  gpg --auto-key-locate wkd --search-keys megver83@parabola.nu

or

.. code:: sh

  gpg --auto-key-locate keyserver --recv-keys 6DB9C4B4F0D8C0DC432CF6E4227CA7C556B2BA78

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

.. code:: sh

  git verify-tag <tag>

License
=======

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