From cc806d9c4ce29212c2848c15b4b184feace3e1ac Mon Sep 17 00:00:00 2001 From: Anton Hvornum 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/help/issues.rst | 33 --------------- docs/help/known_issues.rst | 103 +++++++++++++++++++++++++++++++++++++++++++++ docs/help/report_bug.rst | 33 +++++++++++++++ 3 files changed, 136 insertions(+), 33 deletions(-) delete mode 100644 docs/help/issues.rst create mode 100644 docs/help/known_issues.rst create mode 100644 docs/help/report_bug.rst (limited to 'docs/help') diff --git a/docs/help/issues.rst b/docs/help/issues.rst deleted file mode 100644 index 7d690b65..00000000 --- a/docs/help/issues.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _help.issues: - -Issue tracker & bugs -==================== - -Issues and bugs should be reported over at `https://github.com/archlinux/archinstall/issues `_. - -General questions, enhancements and security issues can be reported over there too. -For quick issues or if you need help, head over to the Discord server which has a help channel. - -Log files ---------- - -| When submitting a help ticket, please include the :code:`/var/log/archinstall/install.log`. -| It can be found both on the live ISO but also in the installed filesystem if the base packages were strapped in. - -.. tip:: - | An easy way to submit logs is ``curl -F'file=@/var/log/archinstall/install.log' https://0x0.st``. - | Use caution when submitting other log files, but ``archinstall`` pledges to keep ``install.log`` safe for posting publicly! - -| There are additional log files under ``/var/log/archinstall/`` that can be useful: - - - ``/var/log/archinstall/user_configuration.json`` - Stores most of the guided answers in the installer - - ``/var/log/archinstall/user_credentials.json`` - Stores any usernames or passwords, can be passed to ``--creds`` - - ``/var/log/archinstall/user_disk_layouts.json`` - Stores the chosen disks and their layouts - - ``/var/log/archinstall/install.log`` - A log file over what steps were taken by archinstall - - ``/var/log/archinstall/cmd_history.txt`` - A complete command history, command by command in order - - ``/var/log/archinstall/cmd_output.txt`` - A raw output from all the commands that were executed by archinstall - -.. warning:: - - We only try to guarantee that ``/var/log/archinstall/install.log`` is free from sensitive information. - Any other log file should be pasted with **utmost care**! diff --git a/docs/help/known_issues.rst b/docs/help/known_issues.rst new file mode 100644 index 00000000..2f1f62cb --- /dev/null +++ b/docs/help/known_issues.rst @@ -0,0 +1,103 @@ +.. _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`_ +------------------------------ + +| The usual root cause of this is the network topology. +| More specifically `timedatectl show`_ cannot perform a proper time sync against the default servers. + +| A *"fix"* for this is mentioned in the issue above. +| That is to configure ``/etc/systemd/timesyncd.conf`` and restart ``systemd-timesyncd.service``. + +.. note:: + + A proposal to override the time sync check has been put up for discussion in `#2144`_. + +Missing Nvidia Proprietary Driver `#2002`_ +------------------------------------------ + +| In some instances, the nvidia driver might not have all the nessecary packages installed. +| This is due to the kernel selection and/or hardware setups requiring additional packages to work properly. + +A common workaround is to install the package `linux-headers`_ and `nvidia-dkms`_ + +ARM, 32bit and other CPU types error out `#1686`_, `#2185`_ +----------------------------------------------------------- + +| This is a bit of a catch-all known issue. +| Officially `x86_64`_ is only supported by Arch Linux. +| Hence little effort have been put into supporting other platforms. + +| In theory, other architectures should work but small quirks might arise. + +| PR's are welcome but please be respectful of the delays in merging. +| Other fixes, issues or features will be prioritized for the above reasons. + +Keyring is out of date `#2213`_ +------------------------------- + +| Missing key-issues tend to be that the `archlinux-keyring`_ package is out of date, usually as a result of an outdated ISO. +| There is an attempt from upstream to fix this issue, and it's the `archlinux-keyring-wkd-sync.service`_ + +| The service starts almost immediately during boot, and if network is not configured in time — the service will fail. +| Subsequently the ``archinstall`` run might operate on a old keyring despite there being an update service for this. + +| There is really no way to reliably over time work around this issue in ``archinstall``. +| Instead, efforts to the upstream service should be considered the way forward. And/or keys not expiring betwene a sane ammount of ISO's. + +.. note:: + + The issue can happen on new ISO's too even as little as a few days after release, as some keys might expire right after the keyring is *"burnt in"* to the ISO. + +.. note:: + + Another common issue relating to the network not being configured, is that time might not be set correctly - resulting in the keyring not being able to update. See :ref:`waiting for time sync`. + +AUR packages +------------ + +| This is also a catch-all issue. +| `AUR is unsupported `_, and until that changes we cannot use AUR packages to solve feature requests in ``archinstall``. + +| This means that feature requests like supporting filesystems such as `ZFS`_ can not be added, and issues cannot be solved by using AUR packages either. + +.. note:: + + But in spirit of giving the community options, ``archinstall`` supports :ref:`archinstall.Plugins`, which means you can run ``archinstall --plugin `` and source an AUR plugin. + + `torxed/archinstall-aur `_ is a reference implementation for plugins: + + .. code-block:: console + + # archinstall --plugin https://archlinux.life/aur-plugin + + `phisch/archinstall-aur `_ is another alternative: + + .. code-block:: console + + # archinstall --plugin https://raw.githubusercontent.com/phisch/archinstall-aur/master/archinstall-aur.py + + .. warning:: + + This will allow for unsupported usage of AUR during installation. + +.. _#2213: https://github.com/archlinux/archinstall/issues/2213 +.. _#2185: https://github.com/archlinux/archinstall/issues/2185 +.. _#2144: https://github.com/archlinux/archinstall/issues/2144 +.. _#2002: https://github.com/archlinux/archinstall/issues/2002 +.. _#1686: https://github.com/archlinux/archinstall/issues/1686 +.. _linux-headers: https://archlinux.org/packages/core/x86_64/linux-headers/ +.. _nvidia-dkms: https://archlinux.org/packages/extra/x86_64/nvidia-dkms/ +.. _x86_64: https://wiki.archlinux.org/title/Frequently_asked_questions#What_architectures_does_Arch_support? +.. _archlinux-keyring: https://archlinux.org/packages/core/any/archlinux-keyring/ +.. _archlinux-keyring-wkd-sync.service: https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/blob/7e672dad10652a80d1cc575d75cdb46442cd7f96/wkd_sync/archlinux-keyring-wkd-sync.service.in +.. _ZFS: https://aur.archlinux.org/packages/zfs-linux +.. _archinstall: https://github.com/archlinux/archinstall/ +.. _timedatectl show: https://github.com/archlinux/archinstall/blob/e6344f93f7e476d05bbcd642f2ed91fdde545870/archinstall/lib/installer.py#L136 \ No newline at end of file diff --git a/docs/help/report_bug.rst b/docs/help/report_bug.rst new file mode 100644 index 00000000..bd0ac50a --- /dev/null +++ b/docs/help/report_bug.rst @@ -0,0 +1,33 @@ +.. _help.issues: + +Report Issues & Bugs +==================== + +Issues and bugs should be reported over at `https://github.com/archlinux/archinstall/issues `_. + +General questions, enhancements and security issues can be reported over there too. +For quick issues or if you need help, head over to the Discord server which has a help channel. + +Log files +--------- + +| When submitting a help ticket, please include the :code:`/var/log/archinstall/install.log`. +| It can be found both on the live ISO but also in the installed filesystem if the base packages were strapped in. + +.. tip:: + | An easy way to submit logs is ``curl -F'file=@/var/log/archinstall/install.log' https://0x0.st``. + | Use caution when submitting other log files, but ``archinstall`` pledges to keep ``install.log`` safe for posting publicly! + +| There are additional log files under ``/var/log/archinstall/`` that can be useful: + + - ``/var/log/archinstall/user_configuration.json`` - Stores most of the guided answers in the installer + - ``/var/log/archinstall/user_credentials.json`` - Stores any usernames or passwords, can be passed to ``--creds`` + - ``/var/log/archinstall/user_disk_layouts.json`` - Stores the chosen disks and their layouts + - ``/var/log/archinstall/install.log`` - A log file over what steps were taken by archinstall + - ``/var/log/archinstall/cmd_history.txt`` - A complete command history, command by command in order + - ``/var/log/archinstall/cmd_output.txt`` - A raw output from all the commands that were executed by archinstall + +.. warning:: + + We only try to guarantee that ``/var/log/archinstall/install.log`` is free from sensitive information. + Any other log file should be pasted with **utmost care**! -- cgit v1.2.3-54-g00ecf