doc: Move “System Troubleshooting Tips” below.
So far this section would appear before “Getting Started”. This moves it right after “System Configuration”. * doc/guix.texi (System Troubleshooting Tips): Move after “System Configuration”.
This commit is contained in:
Ludovic Courtès
parent
d22d2a05c3
commit
978b9619a8
1 changed files with 123 additions and 122 deletions
245
doc/guix.texi
245
doc/guix.texi
|
|
@ -185,7 +185,6 @@ 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.
|
||||||
|
|
@ -194,6 +193,7 @@ Weblate} (@pxref{Translating Guix}).
|
||||||
* Utilities:: Package management commands.
|
* Utilities:: Package management commands.
|
||||||
* Foreign Architectures:: Build for foreign architectures.
|
* Foreign Architectures:: Build for foreign architectures.
|
||||||
* System Configuration:: Configuring the operating system.
|
* System Configuration:: Configuring the operating system.
|
||||||
|
* System Troubleshooting Tips:: When things don't go as planned.
|
||||||
* Home Configuration:: Configuring the home environment.
|
* Home Configuration:: Configuring the home environment.
|
||||||
* Documentation:: Browsing software user manuals.
|
* Documentation:: Browsing software user manuals.
|
||||||
* Platforms:: Defining platforms.
|
* Platforms:: Defining platforms.
|
||||||
|
|
@ -251,10 +251,6 @@ Manual Installation
|
||||||
* Keyboard Layout and Networking and Partitioning:: Initial setup.
|
* Keyboard Layout and Networking and Partitioning:: Initial setup.
|
||||||
* Proceeding with the Installation:: Installing.
|
* Proceeding with the Installation:: Installing.
|
||||||
|
|
||||||
System Troubleshooting Tips
|
|
||||||
|
|
||||||
* Chrooting into an existing system::
|
|
||||||
|
|
||||||
Package Management
|
Package Management
|
||||||
|
|
||||||
* Features:: How Guix will make your life brighter.
|
* Features:: How Guix will make your life brighter.
|
||||||
|
|
@ -427,6 +423,10 @@ Defining Services
|
||||||
* Shepherd Services:: A particular type of service.
|
* Shepherd Services:: A particular type of service.
|
||||||
* Complex Configurations:: Defining bindings for complex configurations.
|
* Complex Configurations:: Defining bindings for complex configurations.
|
||||||
|
|
||||||
|
System Troubleshooting Tips
|
||||||
|
|
||||||
|
* Chrooting into an existing system::
|
||||||
|
|
||||||
Home Configuration
|
Home Configuration
|
||||||
|
|
||||||
* Declaring the Home Environment:: Customizing your Home.
|
* Declaring the Home Environment:: Customizing your Home.
|
||||||
|
|
@ -2978,123 +2978,6 @@ 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
|
|
||||||
@menu
|
|
||||||
* Chrooting into an existing system::
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@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 --rbind /proc /mnt/proc
|
|
||||||
mount --rbind /sys /mnt/sys
|
|
||||||
mount --rbind /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 the system profile as well as 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 /var/guix/profiles/system/profile/etc/profile
|
|
||||||
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
|
||||||
|
|
@ -43113,6 +42996,124 @@ is-married = true
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
|
|
||||||
|
@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
|
||||||
|
@menu
|
||||||
|
* Chrooting into an existing system::
|
||||||
|
@end menu
|
||||||
|
|
||||||
|
@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 --rbind /proc /mnt/proc
|
||||||
|
mount --rbind /sys /mnt/sys
|
||||||
|
mount --rbind /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 the system profile as well as 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 /var/guix/profiles/system/profile/etc/profile
|
||||||
|
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
|
||||||
|
|
||||||
@node Home Configuration
|
@node Home Configuration
|
||||||
@chapter Home Configuration
|
@chapter Home Configuration
|
||||||
@cindex home configuration
|
@cindex home configuration
|
||||||
|
|
|
||||||
Reference in a new issue