| index : archinstall32 | |
| Archlinux32 installer | gitolite user |
| summaryrefslogtreecommitdiff |
| -rw-r--r-- | docs/installing/binary.rst | 52 | ||||
| -rw-r--r-- | docs/installing/guided.rst | 427 | ||||
| -rw-r--r-- | docs/installing/python.rst | 6 |
diff --git a/docs/installing/binary.rst b/docs/installing/binary.rst deleted file mode 100644 index eeb9d79d..00000000 --- a/docs/installing/binary.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. _installing.binary: - -Binary executable -================= - -Archinstall can be compiled into a standalone executable. -For Arch Linux based systems, there's a package for this called `archinstall <https://archlinux.org/packages/extra/any/archinstall/>`_. - -.. warning:: - This is not required if you're running archinstall on a pre-built ISO. The installation is only required if you're creating your own scripted installations. - -Using pacman ------------- - -Archinstall is on the `official repositories <https://wiki.archlinux.org/index.php/Official_repositories>`_. - -.. code-block:: console - - sudo pacman -S archinstall - -Using PKGBUILD --------------- - -The `source <https://github.com/archlinux/archinstall>`_ contains a binary `PKGBUILD <https://github.com/Torxed/archinstall/tree/master/PKGBUILD/archinstall>`_ which can be either copied straight off the website or cloned using :code:`git clone https://github.com/Torxed/archinstall`. - -Once you've obtained the `PKGBUILD`, building it is pretty straight forward. - -.. code-block:: console - - makepkg -s - -Which should produce an `archinstall-X.x.z-1.pkg.tar.zst` which can be installed using: - -.. code-block:: console - - sudo pacman -U archinstall-X.x.z-1.pkg.tar.zst - -.. note:: - - For a complete guide on the build process, please consult the `PKGBUILD on ArchWiki <https://wiki.archlinux.org/index.php/PKGBUILD>`_. - -Manual compilation ------------------- - -You can compile the source manually without using a custom mirror or the `PKGBUILD` that is shipped. -Simply clone or download the source, and while standing in the cloned folder `./archinstall`, execute: - -.. code-block:: console - - nuitka3 --standalone --show-progress archinstall - -This requires the `nuitka <https://archlinux.org/packages/community/any/nuitka/>`_ package as well as `python3` to be installed locally. diff --git a/docs/installing/guided.rst b/docs/installing/guided.rst index 4cb07ae1..90abedb4 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 - -| 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. + archinstall + +Since the `Guided Installer`_ is the default script, this is the equivalent 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. + +``--config`` +------------ + +This parameter takes a local or remote :code:`.json` file as argument and contains the overall configuration and menu answers for the guided installer. .. 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", - } + 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 diff --git a/docs/installing/python.rst b/docs/installing/python.rst index cf4f7882..edd55138 100644 --- a/docs/installing/python.rst +++ b/docs/installing/python.rst @@ -50,8 +50,10 @@ You can either move the folder into your project and simply do import archinstall -Or you can use `setuptools <https://pypi.org/project/setuptools/>`_ to install it into the module path. +Or you can PyPa's `build <https://github.com/pypa/build>`_ and `installer <https://github.com/pypa/installer>`_ to install it into pythons module path. .. code-block:: console - sudo python setup.py install
\ No newline at end of file + $ cd archinstall + $ python -m build . + $ python -m installer dist/*.whl
\ No newline at end of file |