From 7370e52cd67e5f126b762cae34c21e34e866ca9e Mon Sep 17 00:00:00 2001 From: Anton Hvornum Date: Tue, 21 Nov 2023 14:32:54 +0100 Subject: [PATCH] Added custom-commands docs, and improved some creds and known issue links --- docs/cli_parameters/config/config_options.csv | 2 +- .../cli_parameters/config/custom_commands.rst | 22 +++++++ docs/help/known_issues.rst | 3 +- docs/installing/guided.rst | 60 ++++++++++++++----- 4 files changed, 69 insertions(+), 18 deletions(-) create mode 100644 docs/cli_parameters/config/custom_commands.rst diff --git a/docs/cli_parameters/config/config_options.csv b/docs/cli_parameters/config/config_options.csv index 5762f22d94..1861b1e1db 100644 --- a/docs/cli_parameters/config/config_options.csv +++ b/docs/cli_parameters/config/config_options.csv @@ -8,7 +8,7 @@ disk_config,*Read more under* :ref:`disk config`,Contains the desired disk setup disk_encryption,*Read more about under* :ref:`disk encryption`,Parameters for disk encryption applied ontop of ``disk_config``,No hostname,``str``,A string definining your machines hostname on the network *(defaults to ``archinstall``)*,No kernels,[ `linux `_!, `linux-hardened `_!, `linux-lts `_!, `linux-rt `_!, `linux-rt-lts `_!, `linux-zen `_ ],Defines which kernels should be installed and setup in the boot loader options,Yes -custom-commands,[ !, !, ...],Custom commands that will be run post-install chrooted inside the installed system,No +custom-commands,*Read more under* :ref:`custom commands`,Custom commands that will be run post-install chrooted inside the installed system,No locale_config,{kb_layout: `lang `__!, sys_enc: `Character encoding `_!, sys_lang: `locale `_},Defines the keyboard key map!, system encoding and system locale,No mirror_config,{custom_mirrors: [ https://... ]!, mirror_regions: { "Worldwide": [ "https://geo.mirror.pkgbuild.com/$repo/os/$arch" ] } },Sets various mirrors *(defaults to ISO's ``/etc/pacman.d/mirrors`` if not defined)*,No network_config,*`see options under Network Configuration`*,Sets which type of *(if any)* network configuration should be used,No diff --git a/docs/cli_parameters/config/custom_commands.rst b/docs/cli_parameters/config/custom_commands.rst new file mode 100644 index 0000000000..c1529020b0 --- /dev/null +++ b/docs/cli_parameters/config/custom_commands.rst @@ -0,0 +1,22 @@ +.. _custom commands: + +Custom Commands +=============== + +| Custom commands is a configuration entry that allows for executing custom commands post-installation. +| The commands are executed with `arch-chroot `_. + +The option takes a list of arguments, an example is: + +.. code-block:: json + + { + "custom-commands": [ + "hostname new-hostname" + ] + } + +| The following example will set a new hostname in the installed system. +| The example is just to illustrate that the command is not run in the ISO but inside the installed system after the base system is installed. + +More examples can be found in the code repository under `examples/ `_ \ No newline at end of file diff --git a/docs/help/known_issues.rst b/docs/help/known_issues.rst index ddd010ad06..2f1f62cbf3 100644 --- a/docs/help/known_issues.rst +++ b/docs/help/known_issues.rst @@ -1,4 +1,4 @@ -.. _help.issues: +.. _help.known_issues: Known Issues ============ @@ -6,6 +6,7 @@ Known Issues | Some issues are out of the `archinstall`_ projects scope, and the ones we know of are listed below. .. _waiting for time sync: + Waiting for time sync `#2144`_ ------------------------------ diff --git a/docs/installing/guided.rst b/docs/installing/guided.rst index 822aa1077f..dcedfc105a 100644 --- a/docs/installing/guided.rst +++ b/docs/installing/guided.rst @@ -3,7 +3,7 @@ Guided installation =================== -Archinstall ships with a pre-programmed `Guided Installer `_ guiding you through the mandatory steps as well as some optional configurations that can be done. +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:: @@ -26,7 +26,7 @@ To start the installer, run the following in the latest Arch Linux ISO: archinstall -Since the guided installer is the default script, this is the equvilant of running :code:`archinstall guided` +Since the `Guided Installer`_ is the default script, this is the equvilant of running :code:`archinstall guided` 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. @@ -216,7 +216,13 @@ The contents of :code:`https://domain.lan/config.json`: ``--config`` options ^^^^^^^^^^^^^^^^^^^^ -*(Scroll to the right in the table to see required 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 @@ -224,6 +230,7 @@ The contents of :code:`https://domain.lan/config.json`: :escape: ! :header-rows: 1 +.. I'd like to keep this note, as this is the intended behavior of archinstall. .. note:: 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. @@ -240,20 +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": "" | List of regular user credentials, see configuration for reference | No | -| | "!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": "", + "!password": "", + "sudo": false + } + - List of regular user credentials, see configuration for reference + - Maybe + + +.. note:: + + ``!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:: - ``!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. + The key's start with ``!`` because internal log functions will mask any keys starting with explamation from logs and unrestricted configurations. -.. _scripts: https://github.com/archlinux/archinstall/tree/master/archinstall/scripts \ No newline at end of file +.. _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