Added custom-commands docs, and improved some creds and known issue l…

…inks
archlinux · Nov 21, 2023 · 7370e52 · 7370e52
1 parent 6fec39a
commit 7370e52
Show file tree

Hide file tree

Showing 4 changed files with 69 additions and 18 deletions.
diff --git 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 <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-hardened <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-lts <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-rt <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-rt-lts <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-zen <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_ ],Defines which kernels should be installed and setup in the boot loader options,Yes
-custom-commands,[ <command1>!, <command2>!, ...],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 <https://wiki.archlinux.org/title/Linux_console/Keyboard_configuration>`__!, sys_enc: `Character encoding <https://wiki.archlinux.org/title/Locale>`_!, sys_lang: `locale <https://wiki.archlinux.org/title/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
@@ -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 <https://man.archlinux.org/man/extra/arch-install-scripts/arch-chroot.8.en>`_.
+
+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/ <https://github.com/archlinux/archinstall/tree/e6344f93f7e476d05bbcd642f2ed91fdde545870/examples>`_
diff --git a/docs/help/known_issues.rst b/docs/help/known_issues.rst
@@ -1,11 +1,12 @@
-.. _help.issues:
+.. _help.known_issues:
 
 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
@@ -3,7 +3,7 @@
 Guided installation
 ===================
 
-Archinstall ships with a pre-programmed `Guided Installer <https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py>`_ 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,14 +216,21 @@ 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
    :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::
 
    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": "<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::
+
+   ``!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
+.. _scripts: https://github.com/archlinux/archinstall/tree/master/archinstall/scripts
+.. _Guided Installer: https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py