From cc806d9c4ce29212c2848c15b4b184feace3e1ac Mon Sep 17 00:00:00 2001
From: Anton Hvornum <anton@hvornum.se>
Date: Tue, 21 Nov 2023 14:34:30 +0100
Subject: Started a re-write of the docs (#1967)

* Started a re-write of the docs, using CSV for tables and re-organizing parameter definitions

* Added final config options in --config, some have external references which needs to be populated

* Forgot to escape a comma

* Clarified a note

* Added disk configuration and disk encryption docs

* Changed way of installing using source and python

* Added a 'list script' that lists available scripts. This could be converted to a argparse later. But this does the trick for now. And it's added to ease documentation and listing of available options.

* Added a 'Known issues' section, as well as renamed the issues tab

* Finished up the known issues section

* Added a section regarding --plugin

* Added plugin description, tweaked disk_config to the latest changes from #2221

* Added custom-commands docs, and improved some creds and known issue links
---
 docs/installing/guided.rst | 425 ++++++++++++++++++++++++---------------------
 1 file changed, 231 insertions(+), 194 deletions(-)

(limited to 'docs/installing/guided.rst')

diff --git a/docs/installing/guided.rst b/docs/installing/guided.rst
index c5e7f1ed..dcedfc10 100644
--- a/docs/installing/guided.rst
+++ b/docs/installing/guided.rst
@@ -3,20 +3,16 @@
 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.
+Archinstall ships with a pre-programmed `Guided Installer`_ guiding you through the mandatory steps as well as some optional configurations that can be done.
 
 .. 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
+   Other pre-programmed scripts can be invoked by executing :code:`archinstall <script>` *(without .py)*. To see a complete list of scripts, run :code:`archinstall --script list` or check the source code `scripts`_ directory.
 
 .. 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.
+
+   It's recommended to run ``archinstall`` from the official Arch Linux ISO.
+
 
 .. 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.
@@ -28,128 +24,216 @@ To start the installer, run the following in the latest Arch Linux ISO:
 
 .. code-block:: sh
 
-    archinstall --script guided
+    archinstall
 
-| 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.
+Since the `Guided Installer`_ is the default script, this is the equvilant of running :code:`archinstall guided`
 
-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.
+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.
 
-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``.
+There are two configuration files, both are optional.
 
-.. 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)
+``--config``
+------------
 
-.. code-block:: json
+This parameter takes a local or remote :code:`.json` file as argument and contains the overall configuration and menu answers for the guided installer.
 
-    {
-        "audio_config": {"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",
-        "network_config": {
-            "type": "nm"
-        },
-        "ntp": true,
-        "packages": ["docker", "git", "wget", "zsh"],
-        "profile": "gnome",
-        "services": ["docker"],
-        "sys-encoding": "utf-8",
-        "sys-language": "en_US",
-        "timezone": "US/Eastern",
-    }
+.. note::
+
+   You can always get the latest options for this file with ``archinstall --dry-run``, this executes the guided installer in a safe mode where no permanent actions will be taken on your system but simulate a run and save the configuration to disk.
 
-To use it, assuming you put it on ``https://domain.lan/config.json``:
+Example usage
+^^^^^^^^^^^^^
 
 .. 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                                            |
-+----------------------+--------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------+
+The contents of :code:`https://domain.lan/config.json`:
+
+.. code-block:: json
+
+   {
+       "__separator__": null,
+       "additional-repositories": [],
+       "archinstall-language": "English",
+       "audio_config": null,
+       "bootloader": "Systemd-boot",
+       "config_version": "2.6.0",
+       "debug": false,
+       "disk_config": {
+           "config_type": "manual_partitioning",
+           "device_modifications": [
+               {
+                   "device": "/dev/sda",
+                   "partitions": [
+                       {
+                           "btrfs": [],
+                           "flags": [
+                               "Boot"
+                           ],
+                           "fs_type": "fat32",
+                           "length": {
+                               "sector_size": null,
+                               "total_size": null,
+                               "unit": "B",
+                               "value": 99982592
+                           },
+                           "mount_options": [],
+                           "mountpoint": "/boot",
+                           "obj_id": "369f31a8-2781-4d6b-96e7-75680552b7c9",
+                           "start": {
+                               "sector_size": {
+                                   "sector_size": null,
+                                   "total_size": null,
+                                   "unit": "B",
+                                   "value": 512
+                               },
+                               "total_size": null,
+                               "unit": "sectors",
+                               "value": 34
+                           },
+                           "status": "create",
+                           "type": "primary"
+                       },
+                       {
+                           "btrfs": [],
+                           "flags": [],
+                           "fs_type": "fat32",
+                           "length": {
+                               "sector_size": null,
+                               "total_size": null,
+                               "unit": "B",
+                               "value": 100000000
+                           },
+                           "mount_options": [],
+                           "mountpoint": "/efi",
+                           "obj_id": "13cf2c96-8b0f-4ade-abaa-c530be589aad",
+                           "start": {
+                               "sector_size": {
+                                   "sector_size": null,
+                                   "total_size": null,
+                                   "unit": "B",
+                                   "value": 512
+                               },
+                               "total_size": {
+                                   "sector_size": null,
+                                   "total_size": null,
+                                   "unit": "B",
+                                   "value": 16106127360
+                               },
+                               "unit": "MB",
+                               "value": 100
+                           },
+                           "status": "create",
+                           "type": "primary"
+                       },
+                       {
+                           "btrfs": [],
+                           "flags": [],
+                           "fs_type": "ext4",
+                           "length": {
+                               "sector_size": null,
+                               "total_size": null,
+                               "unit": "B",
+                               "value": 15805127360
+                           },
+                           "mount_options": [],
+                           "mountpoint": "/",
+                           "obj_id": "3e75d045-21a4-429d-897e-8ec19a006e8b",
+                           "start": {
+                               "sector_size": {
+                                   "sector_size": null,
+                                   "total_size": null,
+                                   "unit": "B",
+                                   "value": 512
+                               },
+                               "total_size": {
+                                   "sector_size": null,
+                                   "total_size": null,
+                                   "unit": "B",
+                                   "value": 16106127360
+                               },
+                               "unit": "MB",
+                               "value": 301
+                           },
+                           "status": "create",
+                           "type": "primary"
+                       }
+                   ],
+                   "wipe": false
+               }
+           ]
+       },
+       "disk_encryption": {
+           "encryption_type": "luks",
+           "partitions": [
+               "3e75d045-21a4-429d-897e-8ec19a006e8b"
+           ]
+       },
+       "hostname": "archlinux",
+       "kernels": [
+           "linux"
+       ],
+       "locale_config": {
+           "kb_layout": "us",
+           "sys_enc": "UTF-8",
+           "sys_lang": "en_US"
+       },
+       "mirror_config": {
+           "custom_mirrors": [],
+           "mirror_regions": {
+               "Sweden": [
+                   "https://mirror.osbeck.com/archlinux/$repo/os/$arch",
+                   "https://mirror.bahnhof.net/pub/archlinux/$repo/os/$arch",
+                   "https://ftp.myrveln.se/pub/linux/archlinux/$repo/os/$arch",
+                   "https://ftp.lysator.liu.se/pub/archlinux/$repo/os/$arch",
+                   "https://ftp.ludd.ltu.se/mirrors/archlinux/$repo/os/$arch",
+                   "https://ftp.acc.umu.se/mirror/archlinux/$repo/os/$arch",
+                   "http://mirror.bahnhof.net/pub/archlinux/$repo/os/$arch",
+                   "http://ftpmirror.infania.net/mirror/archlinux/$repo/os/$arch",
+                   "http://ftp.myrveln.se/pub/linux/archlinux/$repo/os/$arch",
+                   "http://ftp.lysator.liu.se/pub/archlinux/$repo/os/$arch",
+                   "http://ftp.acc.umu.se/mirror/archlinux/$repo/os/$arch"
+               ]
+           }
+       },
+       "network_config": {},
+       "no_pkg_lookups": false,
+       "ntp": true,
+       "offline": false,
+       "packages": [],
+       "parallel downloads": 0,
+       "profile_config": null,
+       "save_config": null,
+       "script": "guided",
+       "silent": false,
+       "swap": true,
+       "timezone": "UTC",
+       "version": "2.6.0"
+   }
+
+``--config`` options
+^^^^^^^^^^^^^^^^^^^^
+
+.. warning::
+
+   All key and value entries must conform to the JSON standard. Below is human readable examples with links, effectively breaking the syntax. Adapt the descriptions below to suit your needs and the JSON format.
+
+.. note::
+
+   Scroll to the right in the table to see required options.
+
+.. csv-table:: JSON options
+   :file: ../cli_parameters/config/config_options.csv
+   :widths: 15, 40, 40, 5
+   :escape: !
+   :header-rows: 1
 
+.. I'd like to keep this note, as this is the intended behavior of archinstall.
 .. note::
-    [1] If no entries are found in ``harddrives``, archinstall guided installation will use whatever is mounted currently under ``/mnt/archinstall``.
+
+   If no entries are found in ``disk_config``, archinstall guided installation will use whatever is mounted currently under ``/mnt/archinstall`` without performing any disk operations.
 
 Options for ``--creds``
 -----------------------
@@ -163,88 +247,41 @@ Options for ``--creds``
         "!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}                                  |                                                                                      |                                               |
-+----------------------+--------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
+.. list-table:: --creds options
+   :widths: 25 25 40 10
+   :header-rows: 1
+
+   * - Key
+     - Values
+     - Description
+     - Required
+   * - !encryption-password
+     - ``str``
+     - Password to encrypt disk, not encrypted if password not provided
+     - No
+   * - !root-password
+     - ``str``
+     - The root account password
+     - No
+   * - !users
+     - .. code-block:: json
+
+          {
+              "username": "<USERNAME>",
+              "!password": "<PASSWORD>",
+              "sudo": false   
+          }
+     - List of regular user credentials, see configuration for reference
+     - Maybe
+
 
 .. 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``
-------------------------------
+   ``!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.
 
 .. 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 key's start with ``!`` because internal log functions will mask any keys starting with explamation from logs and unrestricted configurations.
 
-| 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                                            |
-+----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+
+.. _scripts: https://github.com/archlinux/archinstall/tree/master/archinstall/scripts
+.. _Guided Installer: https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py
\ No newline at end of file
-- 
cgit v1.2.3-70-g09d2