doc: Document how to repair Guix System from a chroot.
* doc/guix.texi (System Troubleshooting Tips): New chapter.
This commit is contained in:
		
							parent
							
								
									a860a5fa95
								
							
						
					
					
						commit
						4e93ca70da
					
				
					 1 changed files with 119 additions and 0 deletions
				
			
		
							
								
								
									
										119
									
								
								doc/guix.texi
									
										
									
									
									
								
							
							
						
						
									
										119
									
								
								doc/guix.texi
									
										
									
									
									
								
							|  | @ -169,6 +169,7 @@ Weblate} (@pxref{Translating Guix}). | ||||||
| * Introduction::                What is Guix about? | * Introduction::                What is Guix about? | ||||||
| * Installation::                Installing Guix. | * Installation::                Installing Guix. | ||||||
| * System Installation::         Installing the whole operating system. | * System Installation::         Installing the whole operating system. | ||||||
|  | * System Troubleshooting Tips:: When things don't go as planned. | ||||||
| * Getting Started::             Your first steps. | * Getting Started::             Your first steps. | ||||||
| * Package Management::          Package installation, upgrade, etc. | * Package Management::          Package installation, upgrade, etc. | ||||||
| * Channels::                    Customizing the package collection. | * Channels::                    Customizing the package collection. | ||||||
|  | @ -227,6 +228,10 @@ System Installation | ||||||
| * Installing Guix in a VM::     Guix System playground. | * Installing Guix in a VM::     Guix System playground. | ||||||
| * Building the Installation Image::  How this comes to be. | * Building the Installation Image::  How this comes to be. | ||||||
| 
 | 
 | ||||||
|  | System Troubleshooting Tips | ||||||
|  | 
 | ||||||
|  | * Chrooting into an existing system::  Fixing things from a chroot | ||||||
|  | 
 | ||||||
| Manual Installation | Manual Installation | ||||||
| 
 | 
 | ||||||
| * Keyboard Layout and Networking and Partitioning:: Initial setup. | * Keyboard Layout and Networking and Partitioning:: Initial setup. | ||||||
|  | @ -2368,6 +2373,7 @@ See the files under @file{/run/current-system/profile/share/keymaps} for | ||||||
| a list of available keyboard layouts.  Run @command{man loadkeys} for | a list of available keyboard layouts.  Run @command{man loadkeys} for | ||||||
| more information. | more information. | ||||||
| 
 | 
 | ||||||
|  | @anchor{manual-installation-networking} | ||||||
| @subsubsection Networking | @subsubsection Networking | ||||||
| 
 | 
 | ||||||
| Run the following command to see what your network interfaces are called: | Run the following command to see what your network interfaces are called: | ||||||
|  | @ -2821,6 +2827,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 | @code{A20-OLinuXino-Lime2} is the name of the board.  If you specify an invalid | ||||||
| board, a list of possible boards will be printed. | 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 | ||||||
|  | @ref{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 @kbd{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 @var{user} profile to setup the environment, where | ||||||
|  | @var{user} is the user name used for the Guix System you are attempting | ||||||
|  | to repair: | ||||||
|  | 
 | ||||||
|  | @example sh | ||||||
|  | source /home/@var{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 | ||||||
|  | source /home/@var{user}/.config/guix/current/etc/profile | ||||||
|  | @end example | ||||||
|  | 
 | ||||||
|  | @item | ||||||
|  | Start a minimal @command{guix-daemon} in the background: | ||||||
|  | 
 | ||||||
|  | @example sh | ||||||
|  | guix-daemon --build-users-group=guixbuild --disable-chroot & | ||||||
|  | @end example | ||||||
|  | 
 | ||||||
|  | @item | ||||||
|  | Edit your Guix System configuration if needed, then reconfigure with: | ||||||
|  | 
 | ||||||
|  | @example sh | ||||||
|  | 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 ********************************************************************* | @c ********************************************************************* | ||||||
| @node Getting Started | @node Getting Started | ||||||
| @chapter Getting Started | @chapter Getting Started | ||||||
|  |  | ||||||
		Reference in a new issue