From patchwork Tue May 24 14:57:38 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maxim Cournoyer X-Patchwork-Id: 39595 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 0C4C627BBEA; Tue, 24 May 2022 16:02:12 +0100 (BST) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-2.7 required=5.0 tests=BAYES_00,DKIM_ADSP_CUSTOM_MED, DKIM_INVALID,DKIM_SIGNED,FREEMAIL_FROM,MAILING_LIST_MULTI, SPF_HELO_PASS,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 642F727BBE9 for ; Tue, 24 May 2022 16:02:11 +0100 (BST) Received: from localhost ([::1]:54286 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ntW30-0003GX-IR for patchwork@mira.cbaines.net; Tue, 24 May 2022 11:02:10 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59916) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ntVzy-0001h4-4w for guix-patches@gnu.org; Tue, 24 May 2022 10:59:02 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:59175) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ntVzx-00068F-Ry for guix-patches@gnu.org; Tue, 24 May 2022 10:59:01 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ntVzx-0000PP-Rj for guix-patches@gnu.org; Tue, 24 May 2022 10:59:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#55613] [PATCH] doc: Document how to repair Guix System from a chroot. Resent-From: Maxim Cournoyer Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Tue, 24 May 2022 14:59:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 55613 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 55613@debbugs.gnu.org Cc: Maxim Cournoyer X-Debbugs-Original-To: guix-patches@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.16534042851508 (code B ref -1); Tue, 24 May 2022 14:59:01 +0000 Received: (at submit) by debbugs.gnu.org; 24 May 2022 14:58:05 +0000 Received: from localhost ([127.0.0.1]:53072 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ntVz2-0000OE-QN for submit@debbugs.gnu.org; Tue, 24 May 2022 10:58:05 -0400 Received: from lists.gnu.org ([209.51.188.17]:49768) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ntVyl-0000Na-G8 for submit@debbugs.gnu.org; Tue, 24 May 2022 10:58:02 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59568) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ntVyl-0008JL-43 for guix-patches@gnu.org; Tue, 24 May 2022 10:57:47 -0400 Received: from mail-qt1-x834.google.com ([2607:f8b0:4864:20::834]:34322) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ntVyi-00061G-J0 for guix-patches@gnu.org; Tue, 24 May 2022 10:57:46 -0400 Received: by mail-qt1-x834.google.com with SMTP id q20so5139181qtw.1 for ; Tue, 24 May 2022 07:57:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=nfV6en7WPtl6Y2NR0ExW/KX56RagsQHaMEy+60ZBLc8=; b=axfQqVQ3DJUov8VS3AoUm2W4tCsvZRoV525xbBSTpCObR7ARZaRVLcycTleKU/hHUn XhROWgITKueUBB5bA9twLVqg4+VBhBXEgYxbM12TLaCkKIKVaF7zyhFx8l0ayN9b/iqS D6J5PlbOJik/edVuV/8vCJwsPPJsN7nN4jCHXOpMV3OhLQtSpTh1K+1qDeN3UACroE87 498U1IASU3L5mz/sJdcJsjurdLfY6MKERVe1OgCf+SrhN6k5cbxv/kVC7sG3KfbpMUD8 EbHjuX37EMKWD4RVY5/NoX41LJjJV4yAsexd2O6b6WuieEbpGsJOi+mpkOwVw633geb6 MH2Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=nfV6en7WPtl6Y2NR0ExW/KX56RagsQHaMEy+60ZBLc8=; b=fqVgm6q/SDRuL480tixVrEyoSyxejiPUqJ7yw2sY4N9dEJ+FSPzM94o2QAOnAZ9HOm zjxkrUADzcPo0DO2rlsts/wSbVv/lWiqr69g9FX1al0/VxEc6l9ESxr6dVh/9k73P30V P8SqtA1p+0tvXMw8H4iB+VvbjdGRaXIxr6vXiThJllP3Hq9LMsYmVLbSD+H6Kz2z84MC NUqBBWXd+YjhOm3Dpaivaac+URr3AiC5be4rjC1JQF+n7+o4Ts0lCtLCILWkkTwBJXAy ZKbnTt/C19wSzmPRm4ukxtZMM7YMD5/EA/OsdXylbmd8zhJtyWSUazWsYluBpuM2u2lv 699Q== X-Gm-Message-State: AOAM532JFPtF3ZdSc5kyKk8/UMcL80NCYEozG4uVpKbNLK0Q4eSvbTyK z5CaQ1Tkrox91iUYIh8g/jYMhMNaabt1+Q== X-Google-Smtp-Source: ABdhPJxIF+m0QQHWB9QUZPNIt1VFsRUjtxgT8+E4Yr/rU3ITsQ+z8EH0YEMFFbCuwhSzYpEsRbq+2A== X-Received: by 2002:a05:622a:1786:b0:2f9:3071:c3cb with SMTP id s6-20020a05622a178600b002f93071c3cbmr10347338qtk.31.1653404261682; Tue, 24 May 2022 07:57:41 -0700 (PDT) Received: from localhost.localdomain (dsl-157-33.b2b2c.ca. [66.158.157.33]) by smtp.gmail.com with ESMTPSA id i6-20020a378606000000b0069fc13ce23esm6204446qkd.111.2022.05.24.07.57.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 24 May 2022 07:57:41 -0700 (PDT) From: Maxim Cournoyer Date: Tue, 24 May 2022 10:57:38 -0400 Message-Id: <20220524145738.4547-1-maxim.cournoyer@gmail.com> X-Mailer: git-send-email 2.36.0 MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::834; envelope-from=maxim.cournoyer@gmail.com; helo=mail-qt1-x834.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: "Guix-patches" X-getmail-retrieved-from-mailbox: Patches * doc/guix.texi (System Troubleshooting Tips): New chapter. --- doc/guix.texi | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) diff --git a/doc/guix.texi b/doc/guix.texi index 184206bec8..e09daee512 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -168,6 +168,7 @@ Weblate} (@pxref{Translating Guix}). * Introduction:: What is Guix about? * Installation:: Installing Guix. * System Installation:: Installing the whole operating system. +* System Troubleshooting Tips:: When things don't go as planned. * Getting Started:: Your first steps. * Package Management:: Package installation, upgrade, etc. * Channels:: Customizing the package collection. @@ -226,6 +227,10 @@ System Installation * Installing Guix in a VM:: Guix System playground. * Building the Installation Image:: How this comes to be. +System Troubleshooting Tips + +* Chrooting into an existing system:: Fixing things from a chroot + Manual Installation * Keyboard Layout and Networking and Partitioning:: Initial setup. @@ -2367,6 +2372,7 @@ See the files under @file{/run/current-system/profile/share/keymaps} for a list of available keyboard layouts. Run @command{man loadkeys} for more information. +@anchor{Manual Installation - Networking} @subsubsection Networking Run the following command to see what your network interfaces are called: @@ -2820,6 +2826,119 @@ guix system image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-b @code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid board, a list of possible boards will be printed. +@c ********************************************************************* +@cindex troubleshooting, guix system +@cindex guix system troubleshooting +@node System Troubleshooting Tips +@chapter System Troubleshooting Tips + +Guix System allows rebooting into a previous generation should the last +one be malfunctioning, which makes it quite robust against being broken +irreversibly. This feature depends on GRUB being correctly functioning +though, which means that if for whatever reasons your GRUB installation +becomes corrupted during a system reconfiguration, you may not be able +to easily boot into a previous generation. A technique that can be used +in this case is to @i{chroot} into your broken system and reconfigure it +from there. Such technique is explained below. + +@cindex chroot, guix system +@cindex chrooting, guix system +@cindex repairing GRUB, via chroot +@node Chrooting into an existing system +@section Chrooting into an existing system + +This section details how to @i{chroot} to an already installed Guix +System with the aim of reconfiguring it, for example to fix a broken +GRUB installation. The process is similar to how it would be done on +other GNU/Linux systems, but there are some Guix System particularities +such as the daemon and profiles that make it worthy of explaining here. + +@enumerate +@item +Obtain a bootable image of Guix System. It is recommended the latest +development snapshot so the kernel and the tools used are at least as as +new as those of your installed system; it can be retrieved from the +@url{https://ci.guix.gnu.org/search/latest/ISO-9660?query=spec:images+status:success+system:x86_64-linux+image.iso, +https://ci.guix.gnu.org} URL. Follow the @pxref{USB Stick and DVD +Installation} section for copying it to a bootable media. + +@item +Boot the image, and proceed with the graphical text-based installer +until your network is configured. Alternatively, you could configure +the network manually by following the @pxref{Manual Installation - +Networking} section. If you get the error @samp{RTNETLINK answers: +Operation not possible due to RF-kill}, try @samp{rfkill list} followed +by @samp{rfkill unblock 0}, where @samp{0} is your device identifier +(ID). + +@item +Switch to a virtual console (tty) if you haven't already by pressing +simultaneously the @samp{Control + Alt + F4} keys. Mount your file +system at @file{/mnt}. Assuming your root partition is +@file{/dev/sda2}, you would do: + +@example sh +# mount /dev/sda2 /mnt +@end example + +@item +Mount special block devices and Linux-specific directories: + +@example sh +# mount --bind /proc /mnt/proc +# mount --bind /sys /mnt/sys +# mount --bind /dev /mnt/dev +@end example + +If your system is EFI-based, you must also mount the ESP partition. +Assuming it is @file{/dev/sda1}, you can do so with: + +@example sh +# mount /dev/sda1 /mnt/boot/efi +@end example + +@item +Enter your system via chroot: + +@example sh +# chroot /mnt /bin/sh +@end example + +@item +Source your user profile to setup the environment, where +@samp{$YOUR_USER} is adjusted to the user name used for the Guix System +you are attempting to repair. + +@example sh +sh-5.1# source /home/$YOUR_USER/.guix-profile/etc/profile +@end example + +To ensure you are working with the Guix revision you normally would as +your normal user, also source your current Guix profile: + +@example sh +sh-5.1# source /home/$YOUR_USER/.config/guix/current/etc/profile +@end example + +@item +Start a minimal guix-daemon in the background: + +@example sh +sh-5.1# guix-daemon --build-users-group=guixbuild --disable-chroot & +@end example + +@item +Edit your Guix System configuration if needed, then reconfigure with: + +@example sh +sh-5.1# guix system reconfigure your-config.scm +@end example + +@item +Finally, you should be good to reboot the system to test your fix. + +@end enumerate + @c ********************************************************************* @node Getting Started @chapter Getting Started