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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
.. _guided:
Guided installation
===================
| This is the default script the Arch Linux `Archinstall package <https://archlinux.org/packages/extra/any/archinstall/>`_.
| It will guide you through a very basic installation of Arch Linux.
.. note::
There are other scripts and they can be invoked by executing `archinstall <script>` *(without .py)*. To see a complete list of scripts, see the source code directory `examples/ <https://github.com/archlinux/archinstall/tree/master/examples>`_
The installer has three pre-requisites:
* The latest version of `Arch Linux ISO <https://archlinux.org/download/>`_
* A physical or virtual machine to install on
* A `working internet connection <https://wiki.archlinux.org/title/installation_guide#Connect_to_the_internet>`_ prior to running archinstall
.. note::
A basic understanding of machines, ISO-files and command line arguments are needed.
Please read the official `Arch Linux Wiki <https://wiki.archlinux.org/>`_ to learn more about your future operating system.
.. warning::
The installer will not configure WiFi before the installation begins. You need to read up on `Arch Linux networking <https://wiki.archlinux.org/index.php/Network_configuration>`_ before you continue.
Running the guided installation
-------------------------------
To start the installer, run the following in the latest Arch Linux ISO:
.. code-block:: sh
archinstall --script guided
| The ``--script guided`` argument is optional as it's the default behavior.
| But this will use our most guided installation and if you skip all the option steps it will install a minimal Arch Linux experience.
Installing directly from a configuration file
---------------------------------------------
| The guided installation also supports installing with pre-configured answers to all the guided steps.
| This can be a quick and convenient way to re-run one or several installations.
|
| After each successful installation a pre-configured configuration will be found at ``/var/log/archinstall`` both on the live media and the installed system.
There are three different configuration files, all of which are optional.
* ``--config`` that deals with the general configuration of language and which profiles to use.
* ``--creds`` which takes any ``superuser``, ``user`` or ``root`` account data.
* ``--disk_layouts`` for defining the desired partition strategy on the selected ``"harddrives"`` in ``--config``.
.. note::
You can always get the latest options with ``archinstall --dry-run``, but edit the following json according to your needs.
Save the configuration as a ``.json`` file. Archinstall can source it via a local or remote path (URL)
.. code-block:: json
{
"audio": "pipewire",
"bootloader": "systemd-bootctl",
"custom-commands": [
"cd /home/devel; git clone https://aur.archlinux.org/paru.git",
"chown -R devel:devel /home/devel/paru",
"usermod -aG docker devel"
],
"filesystem": "btrfs",
"gfx_driver": "VMware / VirtualBox (open-source)",
"harddrives": [
"/dev/nvme0n1"
],
"swap": true,
"hostname": "development-box",
"kernels": [
"linux"
],
"keyboard-language": "us",
"mirror-region": "Worldwide",
"nic": {
"type": "NM"
},
"ntp": true,
"packages": ["docker", "git", "wget", "zsh"],
"profile": "gnome",
"services": ["docker"],
"sys-encoding": "utf-8",
"sys-language": "en_US",
"timezone": "US/Eastern",
}
To use it, assuming you put it on ``https://domain.lan/config.json``:
.. code-block:: sh
archinstall --config https://domain.lan/config.json
Options for ``--config``
------------------------
*(To see which keys are required, scroll to the right in the above table.)*
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| Key | Values | Description | Required |
| | | | |
+======================+========================================================+=============================================================================================+===============================================+
| audio | pipewire/pulseaudio | Audioserver to be installed | No |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| bootloader | systemd-bootctl/grub-install | Bootloader to be installed *(grub being mandatory on BIOS machines)* | Yes |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| custom-commands | [ <command1>, <command2>, ...] | Custom commands to be run post install | No |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| gfx_driver | - "VMware / VirtualBox (open-source)" | Graphics Drivers to install | No |
| | - "Nvidia" | | |
| | - "Intel (open-source)" | | |
| | - "AMD / ATI (open-source)" | | |
| | - "All open-source (default)" | | |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| harddrives | [ <path of device>, <path of second device>, ... } | Multiple paths to block devices to be formatted | No[1] |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| hostname | any | Hostname of machine after installation. Default will be ``archinstall`` | No |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| kernels | [ "kernel1", "kernel2"] | List of kernels to install eg: linux, linux-lts, linux-zen etc | At least 1 |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| keyboard-layout | Any valid layout given by ``localectl list-keymaps`` | eg: ``us``, ``de`` or ``de-latin1`` etc. Defaults to ``us`` | No |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| mirror-region | | {"<Region Name>": { "Mirror URL": True/False}, ..} | | Defaults to automatic selection. | No |
| | | "Worldwide" or "Sweden" | | Either takes a dictionary structure of region and a given set of mirrors. | |
| | | | Or just a region and archinstall will source any mirrors for that region automatically | |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| nic | | { type: <ISO|NM|MANUAL> } | | Type must be one of ISO, NM, MANUAL. ISO will copy the configuration on the image, | No |
| | | | | NM configures NetworkManager and MANUAL allows to specify custom configuration | |
| | | { "iface": "eth0"} | | Only MANUAL: name of the interface | |
| | | { "dhcp": <boolean>} | | Only MANUAL: If set to true DHCP auto will be setup and all further configs ignored | |
| | | { "ip": <ip>} | | Only MANUAL: Ip address to set, is MANDATORY | |
| | | { "gateway": <ip>} | | Only MANUAL: Optional gateway | |
| | | { "dns": [<ip>]} | | Only MANUAL: Optional DNS servers | |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| ntp | <boolean> | Set to true to set-up ntp post install | No |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| packages | [ "package1", "package2", ..] | List of packages to install post-installation | No |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| profile | Name of the profile to install | Profiles are present in | No |
| | | `profiles/ <https://github.com/archlinux/archinstall/tree/master/profiles>`_, | |
| | | use the name of a profile to install it without the ``.py`` extension. | |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| services | [ "service1", "service2", ..] | Services to enable post-installation | No |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| sys-encoding | "utf-8" | Set to change system encoding post-install, ignored if --advanced flag is not passed | No |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| sys-language | "en_US" | Set to change system language post-install, ignored if --advanced flag is not passed | No |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
| timezone | Timezone to configure in installation | Timezone eg: UTC, Asia/Kolkata etc. Defaults to UTC | No |
+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
.. note::
[1] If no entries are found in ``harddrives``, archinstall guided installation will use whatever is mounted currently under ``/mnt/archinstall``.
Options for ``--creds``
-----------------------
| Creds is a separate configuration file to separate normal options from more sensitive data like passwords.
| Below is an example of how to set the root password and below that are description of other values that can be set.
.. code-block:: json
{
"!root-password" : "SecretSanta2022"
}
+----------------------+--------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
| Key | Values | Description | Required |
+======================+========================================================+======================================================================================+===============================================+
| !encryption-password | any | Password to encrypt disk, not encrypted if password not provided | No |
+----------------------+--------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
| !root-password | any | The root account password | No |
+----------------------+--------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
| !users | { "username": "<USERNAME>" | List of regular user credentials, see configuration for reference | No |
| | "!password": "<PASSWORD>", | | |
| | "sudo": false|true} | | |
+----------------------+--------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
.. note::
[1] ``!users`` is optional only if ``!root-password`` was set. ``!users`` will be enforced otherwise and the minimum amount of users with sudo privileges required will be set to 1.
Options for ``--disk_layouts``
------------------------------
.. note::
| The layout of ``--disk_layouts`` is a bit complicated.
| It's highly recommended that you generate it using ``--dry-run`` which will simulate an installation, without performing any damaging actions on your machine. *(no formatting is done)*
.. code-block:: json
{
"/dev/loop0": {
"partitions": [
{
"boot": true,
"encrypted": false,
"filesystem": {
"format": "fat32"
},
"wipe": true,
"mountpoint": "/boot",
"size": "513MB",
"start": "5MB",
"type": "primary"
},
{
"btrfs": {
"subvolumes": {
"@.snapshots": "/.snapshots",
"@home": "/home",
"@log": "/var/log",
"@pkgs": "/var/cache/pacman/pkg"
}
},
"encrypted": true,
"filesystem": {
"format": "btrfs"
},
"wipe": true,
"mountpoint": "/",
"size": "100%",
"start": "518MB",
"type": "primary"
}
],
"wipe": true
}
}
| The overall structure is that of ``{ "blockdevice-path" : ...}`` followed by options for that blockdevice.
| Each partition has it's own settings, and the formatting is executed in order *(top to bottom in the above example)*.
| Mountpoints is later mounted in order of path traversal, ``/`` before ``/home`` etc.
+----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
| Key | Values | Description | Required |
| | | | |
+======================+=====================================================+======================================================================================+===============================================+
| filesystem | { "format": "ext4 / btrfs / fat32 etc." } | Filesystem for root and other partitions | Yes |
+----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
| boot | <bool> | Marks the partition as bootable | No |
+----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
| encrypted | <bool> | Mark the partition for encryption | No |
+----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
| mountpoint | /path | Relative to the inside of the installation, where should the partition be mounted | Yes |
+----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
| start | <size><B, MiB, GiB, %, etc> | The start position of the partition | Yes |
+----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
| type | primary | Only used if MBR and BIOS is used. Marks what kind of partition it is. | No |
+----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
| btrfs | { "subvolumes": {"subvolume": "mountpoint"}} | Support for btrfs subvolumes for a given partition | No |
+----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
|