[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug#34156] [PATCH 2/4] doc: Move "System Installation" right after "Ins
|
From: |
Ludovic Courtès |
|
Subject: |
[bug#34156] [PATCH 2/4] doc: Move "System Installation" right after "Installation". |
|
Date: |
Mon, 21 Jan 2019 12:02:36 +0100 |
* doc/guix.texi (System Installation): Move right after "Installation".
---
doc/guix.texi | 1327 +++++++++++++++++++++++++------------------------
1 file changed, 664 insertions(+), 663 deletions(-)
diff --git a/doc/guix.texi b/doc/guix.texi
index 0fa4ec27a6..42c7f4eeb1 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -117,10 +117,10 @@ Project}.
@menu
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
+* System Installation:: Installing the whole operating system.
* Package Management:: Package installation, upgrade, etc.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
-* System Installation:: Installing the whole operating system.
* System Configuration:: Configuring the operating system.
* Documentation:: Browsing software user manuals.
* Installing Debugging Files:: Feeding the debugger.
@@ -154,6 +154,16 @@ Setting Up the Daemon
* Daemon Offload Setup:: Offloading builds to remote machines.
* SELinux Support:: Using an SELinux policy for the daemon.
+System Installation
+
+* Limitations:: What you can expect.
+* Hardware Considerations:: Supported hardware.
+* USB Stick and DVD Installation:: Preparing the installation medium.
+* Preparing for Installation:: Networking, partitioning, etc.
+* Proceeding with the Installation:: The real thing.
+* Installing GuixSD in a VM:: GuixSD playground.
+* Building the Installation Image:: How this comes to be.
+
Package Management
* Features:: How Guix will make your life brighter.
@@ -218,16 +228,6 @@ Invoking @command{guix build}
* Additional Build Options:: Options specific to 'guix build'.
* Debugging Build Failures:: Real life packaging experience.
-System Installation
-
-* Limitations:: What you can expect.
-* Hardware Considerations:: Supported hardware.
-* USB Stick and DVD Installation:: Preparing the installation medium.
-* Preparing for Installation:: Networking, partitioning, etc.
-* Proceeding with the Installation:: The real thing.
-* Installing GuixSD in a VM:: GuixSD playground.
-* Building the Installation Image:: How this comes to be.
-
System Configuration
* Using the Configuration System:: Customizing your GNU system.
@@ -1744,6 +1744,659 @@ store you need to define the environment variable
@c TODO What else?
address@hidden
*********************************************************************
address@hidden System Installation
address@hidden System Installation
+
address@hidden installing GuixSD
address@hidden Guix System Distribution
+This section explains how to install the Guix System Distribution (GuixSD)
+on a machine. The Guix package manager can
+also be installed on top of a running GNU/Linux system,
address@hidden
+
address@hidden
address@hidden Note
address@hidden This paragraph is for people reading this from tty2 of the
address@hidden installation image.
+You are reading this documentation with an Info reader. For details on
+how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
+link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU
+Info}. Hit @kbd{l} afterwards to come back here.
+
+Alternately, run @command{info info} in another tty to keep the manual
+available.
address@hidden quotation
address@hidden ifinfo
+
address@hidden
+* Limitations:: What you can expect.
+* Hardware Considerations:: Supported hardware.
+* USB Stick and DVD Installation:: Preparing the installation medium.
+* Preparing for Installation:: Networking, partitioning, etc.
+* Proceeding with the Installation:: The real thing.
+* Installing GuixSD in a VM:: GuixSD playground.
+* Building the Installation Image:: How this comes to be.
address@hidden menu
+
address@hidden Limitations
address@hidden Limitations
+
+As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
+not production-ready. It may contain bugs and lack important
+features. Thus, if you are looking for a stable production system that
+respects your freedom as a computer user, a good solution at this point
+is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
+the more established GNU/Linux distributions}. We hope you can soon switch
+to the GuixSD without fear, of course. In the meantime, you can
+also keep using your distribution and try out the package manager on top
+of it (@pxref{Installation}).
+
+Before you proceed with the installation, be aware of the following
+noteworthy limitations applicable to version @value{VERSION}:
+
address@hidden
address@hidden
+The installation process does not include a graphical user interface and
+requires familiarity with GNU/Linux (see the following subsections to
+get a feel of what that means.)
+
address@hidden
+Support for the Logical Volume Manager (LVM) is missing.
+
address@hidden
+More and more system services are provided (@pxref{Services}), but some
+may be missing.
+
address@hidden
+More than 8,500 packages are available, but you might
+occasionally find that a useful package is missing.
+
address@hidden
+GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
+as well as a number of X11 window managers. However, some graphical
+applications may be missing, as well as KDE.
address@hidden itemize
+
+You have been warned! But more than a disclaimer, this is an invitation
+to report issues (and success stories!), and to join us in improving it.
address@hidden, for more info.
+
+
address@hidden Hardware Considerations
address@hidden Hardware Considerations
+
address@hidden hardware support on GuixSD
address@hidden focuses on respecting the user's computing freedom. It
+builds around the kernel Linux-libre, which means that only hardware for
+which free software drivers and firmware exist is supported. Nowadays,
+a wide range of off-the-shelf hardware is supported on
+GNU/Linux-libre---from keyboards to graphics cards to scanners and
+Ethernet controllers. Unfortunately, there are still areas where
+hardware vendors deny users control over their own computing, and such
+hardware is not supported on GuixSD.
+
address@hidden WiFi, hardware support
+One of the main areas where free drivers or firmware are lacking is WiFi
+devices. WiFi devices known to work include those using Atheros chips
+(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
+driver, and those using Broadcom/AirForce chips (BCM43xx with
+Wireless-Core Revision 5), which corresponds to the @code{b43-open}
+Linux-libre driver. Free firmware exists for both and is available
+out-of-the-box on GuixSD, as part of @var{%base-firmware}
+(@pxref{operating-system Reference, @code{firmware}}).
+
address@hidden RYF, Respects Your Freedom
+The @uref{https://www.fsf.org/, Free Software Foundation} runs
address@hidden://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a
+certification program for hardware products that respect your freedom
+and your privacy and ensure that you have control over your device. We
+encourage you to check the list of RYF-certified devices.
+
+Another useful resource is the @uref{https://www.h-node.org/, H-Node}
+web site. It contains a catalog of hardware devices with information
+about their support in GNU/Linux.
+
+
address@hidden USB Stick and DVD Installation
address@hidden USB Stick and DVD Installation
+
+An ISO-9660 installation image that can be written to a USB stick or
+burnt to a DVD can be downloaded from
address@hidden://alpha.gnu.org/gnu/guix/address@hidden@var{system}.iso.xz},
+where @var{system} is one of:
+
address@hidden @code
address@hidden x86_64-linux
+for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
+
address@hidden i686-linux
+for a 32-bit GNU/Linux system on Intel-compatible CPUs.
address@hidden table
+
address@hidden start duplication of authentication part from ``Binary
Installation''
+Make sure to download the associated @file{.sig} file and to verify the
+authenticity of the image against it, along these lines:
+
address@hidden
+$ wget https://alpha.gnu.org/gnu/guix/address@hidden@var{system}.iso.xz.sig
+$ gpg --verify address@hidden@var{system}.iso.xz.sig
address@hidden example
+
+If that command fails because you do not have the required public key,
+then run this command to import it:
+
address@hidden
+$ gpg --keyserver @value{KEY-SERVER} \
+ --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
address@hidden example
+
address@hidden
+and rerun the @code{gpg --verify} command.
address@hidden end duplication
+
+This image contains the tools necessary for an installation.
+It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
+
address@hidden Copying to a USB Stick
+
+To copy the image to a USB stick, follow these steps:
+
address@hidden
address@hidden
+Decompress the image using the @command{xz} command:
+
address@hidden
+xz -d address@hidden@var{system}.iso.xz
address@hidden example
+
address@hidden
+Insert a USB stick of address@hidden or more into your machine, and determine
+its device name. Assuming that the USB stick is known as @file{/dev/sdX},
+copy the image with:
+
address@hidden
+dd address@hidden@var{system}.iso of=/dev/sdX
+sync
address@hidden example
+
+Access to @file{/dev/sdX} usually requires root privileges.
address@hidden enumerate
+
address@hidden Burning on a DVD
+
+To copy the image to a DVD, follow these steps:
+
address@hidden
address@hidden
+Decompress the image using the @command{xz} command:
+
address@hidden
+xz -d address@hidden@var{system}.iso.xz
address@hidden example
+
address@hidden
+Insert a blank DVD into your machine, and determine
+its device name. Assuming that the DVD drive is known as @file{/dev/srX},
+copy the image with:
+
address@hidden
+growisofs -dvd-compat -Z /dev/address@hidden@var{system}.iso
address@hidden example
+
+Access to @file{/dev/srX} usually requires root privileges.
address@hidden enumerate
+
address@hidden Booting
+
+Once this is done, you should be able to reboot the system and boot from
+the USB stick or DVD. The latter usually requires you to get in the
+BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
+
address@hidden GuixSD in a VM}, if, instead, you would like to install
+GuixSD in a virtual machine (VM).
+
+
address@hidden Preparing for Installation
address@hidden Preparing for Installation
+
+Once you have successfully booted your computer using the installation medium,
+you should end up with the welcome page of the graphical installer. The
+graphical installer is a text-based user interface built upon the newt
+library. It shall guide you through all the different steps needed to install
+GNU GuixSD. However, as the graphical installer is still under heavy
+development, you might want to fallback to the original, shell based install
+process, by switching to TTYs 3 to 6 with the shortcuts CTRL-ALT-F[3-6]. The
+following sections describe the installation procedure assuming you're using
+one of those TTYs. They are configured and can be used to run commands as
+root.
+
+TTY2 shows this documentation, browsable using the Info reader commands
+(@pxref{Top,,, info-stnd, Stand-alone GNU Info}). The installation system
+runs the GPM mouse daemon, which allows you to select text with the left mouse
+button and to paste it with the middle button.
+
address@hidden Note
+Installation requires access to the Internet so that any missing
+dependencies of your system configuration can be downloaded. See the
+``Networking'' section below.
address@hidden quotation
+
+The installation system includes many common tools needed for this task.
+But it is also a full-blown GuixSD system, which means that you can
+install additional packages, should you need it, using @command{guix
+package} (@pxref{Invoking guix package}).
+
address@hidden Keyboard Layout
+
address@hidden keyboard layout
+The installation image uses the US qwerty keyboard layout. If you want
+to change it, you can use the @command{loadkeys} command. For example,
+the following command selects the Dvorak keyboard layout:
+
address@hidden
+loadkeys dvorak
address@hidden example
+
+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.
+
address@hidden Networking
+
+Run the following command to see what your network interfaces are called:
+
address@hidden
+ifconfig -a
address@hidden example
+
address@hidden
address@hidden or, using the GNU/Linux-specific @command{ip} command:
+
address@hidden
+ip a
address@hidden example
+
address@hidden
http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
+Wired interfaces have a name starting with @samp{e}; for example, the
+interface corresponding to the first on-board Ethernet controller is
+called @samp{eno1}. Wireless interfaces have a name starting with
address@hidden, like @samp{w1p2s0}.
+
address@hidden @asis
address@hidden Wired connection
+To configure a wired network run the following command, substituting
address@hidden with the name of the wired interface you want to use.
+
address@hidden
+ifconfig @var{interface} up
address@hidden example
+
address@hidden Wireless connection
address@hidden wireless
address@hidden WiFi
+To configure wireless networking, you can create a configuration file
+for the @command{wpa_supplicant} configuration tool (its location is not
+important) using one of the available text editors such as
address@hidden:
+
address@hidden
+nano wpa_supplicant.conf
address@hidden example
+
+As an example, the following stanza can go to this file and will work
+for many wireless networks, provided you give the actual SSID and
+passphrase for the network you are connecting to:
+
address@hidden
address@hidden
+ ssid="@var{my-ssid}"
+ key_mgmt=WPA-PSK
+ psk="the network's secret passphrase"
address@hidden
address@hidden example
+
+Start the wireless service and run it in the background with the
+following command (substitute @var{interface} with the name of the
+network interface you want to use):
+
address@hidden
+wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
address@hidden example
+
+Run @command{man wpa_supplicant} for more information.
address@hidden table
+
address@hidden DHCP
+At this point, you need to acquire an IP address. On a network where IP
+addresses are automatically assigned @i{via} DHCP, you can run:
+
address@hidden
+dhclient -v @var{interface}
address@hidden example
+
+Try to ping a server to see if networking is up and running:
+
address@hidden
+ping -c 3 gnu.org
address@hidden example
+
+Setting up network access is almost always a requirement because the
+image does not contain all the software and tools that may be needed.
+
address@hidden installing over SSH
+If you want to, you can continue the installation remotely by starting
+an SSH server:
+
address@hidden
+herd start ssh-daemon
address@hidden example
+
+Make sure to either set a password with @command{passwd}, or configure
+OpenSSH public key authentication before logging in.
+
address@hidden Disk Partitioning
+
+Unless this has already been done, the next step is to partition, and
+then format the target partition(s).
+
+The installation image includes several partitioning tools, including
+Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
address@hidden, and @command{cfdisk}. Run it and set up your disk with
+the partition layout you want:
+
address@hidden
+cfdisk
address@hidden example
+
+If your disk uses the GUID Partition Table (GPT) format and you plan to
+install BIOS-based GRUB (which is the default), make sure a BIOS Boot
+Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB
+manual}).
+
address@hidden EFI, installation
address@hidden UEFI, installation
address@hidden ESP, EFI system partition
+If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition}
+(ESP) is required. This partition should be mounted at @file{/boot/efi} and
+must have the @code{esp} flag set. E.g., for @command{parted}:
+
address@hidden
+parted /dev/sda set 1 esp on
address@hidden example
+
address@hidden Note
address@hidden grub-bootloader
address@hidden grub-efi-bootloader
+Unsure whether to use EFI- or BIOS-based GRUB? If the directory
address@hidden/sys/firmware/efi} exists in the installation image, then you
should
+probably perform an EFI installation, using @code{grub-efi-bootloader}.
+Otherwise you should use the BIOS-based GRUB, known as
address@hidden @xref{Bootloader Configuration}, for more info on
+bootloaders.
address@hidden quotation
+
+Once you are done partitioning the target hard disk drive, you have to
+create a file system on the relevant partition(s)@footnote{Currently
+GuixSD only supports ext4 and btrfs file systems. In particular, code
+that reads file system UUIDs and labels only works for these file system
+types.}. For the ESP, if you have one and assuming it is
address@hidden/dev/sda1}, run:
+
address@hidden
+mkfs.fat -F32 /dev/sda1
address@hidden example
+
+Preferably, assign file systems a label so that you can easily and
+reliably refer to them in @code{file-system} declarations (@pxref{File
+Systems}). This is typically done using the @code{-L} option of
address@hidden and related commands. So, assuming the target root
+partition lives at @file{/dev/sda2}, a file system with the label
address@hidden can be created with:
+
address@hidden
+mkfs.ext4 -L my-root /dev/sda2
address@hidden example
+
address@hidden encrypted disk
+If you are instead planning to encrypt the root partition, you can use
+the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
address@hidden://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
address@hidden cryptsetup}} for more information.) Assuming you want to
+store the root partition on @file{/dev/sda2}, the command sequence would
+be along these lines:
+
address@hidden
+cryptsetup luksFormat /dev/sda2
+cryptsetup open --type luks /dev/sda2 my-partition
+mkfs.ext4 -L my-root /dev/mapper/my-partition
address@hidden example
+
+Once that is done, mount the target file system under @file{/mnt}
+with a command like (again, assuming @code{my-root} is the label of the
+root file system):
+
address@hidden
+mount LABEL=my-root /mnt
address@hidden example
+
+Also mount any other file systems you would like to use on the target
+system relative to this path. If you have @file{/boot} on a separate
+partition for example, mount it at @file{/mnt/boot} now so it is found
+by @code{guix system init} afterwards.
+
+Finally, if you plan to use one or more swap partitions (@pxref{Memory
+Concepts, swap space,, libc, The GNU C Library Reference Manual}), make
+sure to initialize them with @command{mkswap}. Assuming you have one
+swap partition on @file{/dev/sda3}, you would run:
+
address@hidden
+mkswap /dev/sda3
+swapon /dev/sda3
address@hidden example
+
+Alternatively, you may use a swap file. For example, assuming that in
+the new system you want to use the file @file{/swapfile} as a swap file,
+you would address@hidden example will work for many types of file
+systems (e.g., ext4). However, for copy-on-write file systems (e.g.,
+btrfs), the required steps may be different. For details, see the
+manual pages for @command{mkswap} and @command{swapon}.}:
+
address@hidden
+# This is 10 GiB of swap space. Adjust "count" to change the size.
+dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
+# For security, make the file readable and writable only by root.
+chmod 600 /mnt/swapfile
+mkswap /mnt/swapfile
+swapon /mnt/swapfile
address@hidden example
+
+Note that if you have encrypted the root partition and created a swap
+file in its file system as described above, then the encryption also
+protects the swap file, just like any other file in that file system.
+
address@hidden Proceeding with the Installation
address@hidden Proceeding with the Installation
+
+With the target partitions ready and the target root mounted on
address@hidden/mnt}, we're ready to go. First, run:
+
address@hidden
+herd start cow-store /mnt
address@hidden example
+
+This makes @file{/gnu/store} copy-on-write, such that packages added to it
+during the installation phase are written to the target disk on @file{/mnt}
+rather than kept in memory. This is necessary because the first phase of
+the @command{guix system init} command (see below) entails downloads or
+builds to @file{/gnu/store} which, initially, is an in-memory file system.
+
+Next, you have to edit a file and
+provide the declaration of the operating system to be installed. To
+that end, the installation system comes with three text editors. We
+recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
+supports syntax highlighting and parentheses matching; other editors
+include GNU Zile (an Emacs clone), and
+nvi (a clone of the original BSD @command{vi} editor).
+We strongly recommend storing that file on the target root file system, say,
+as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
+configuration file once you have rebooted into the newly-installed system.
+
address@hidden the Configuration System}, for an overview of the
+configuration file. The example configurations discussed in that
+section are available under @file{/etc/configuration} in the
+installation image. Thus, to get started with a system configuration
+providing a graphical display server (a ``desktop'' system), you can run
+something along these lines:
+
address@hidden
+# mkdir /mnt/etc
+# cp /etc/configuration/desktop.scm /mnt/etc/config.scm
+# nano /mnt/etc/config.scm
address@hidden example
+
+You should pay attention to what your configuration file contains, and
+in particular:
+
address@hidden
address@hidden
+Make sure the @code{bootloader-configuration} form refers to the target
+you want to install GRUB on. It should mention @code{grub-bootloader} if
+you are installing GRUB in the legacy way, or @code{grub-efi-bootloader}
+for newer UEFI systems. For legacy systems, the @code{target} field
+names a device, like @code{/dev/sda}; for UEFI systems it names a path
+to a mounted EFI partition, like @code{/boot/efi}, and do make sure the
+path is actually mounted.
+
address@hidden
+Be sure that your file system labels match the value of their respective
address@hidden fields in your @code{file-system} configuration, assuming
+your @code{file-system} configuration uses the @code{file-system-label}
+procedure in its @code{device} field.
+
address@hidden
+If there are encrypted or RAID partitions, make sure to add a
address@hidden field to describe them (@pxref{Mapped Devices}).
address@hidden itemize
+
+Once you are done preparing the configuration file, the new system must
+be initialized (remember that the target root file system is mounted
+under @file{/mnt}):
+
address@hidden
+guix system init /mnt/etc/config.scm /mnt
address@hidden example
+
address@hidden
+This copies all the necessary files and installs GRUB on
address@hidden/dev/sdX}, unless you pass the @option{--no-bootloader} option.
For
+more information, @pxref{Invoking guix system}. This command may trigger
+downloads or builds of missing packages, which can take some time.
+
+Once that command has completed---and hopefully succeeded!---you can run
address@hidden and boot into the new system. The @code{root} password
+in the new system is initially empty; other users' passwords need to be
+initialized by running the @command{passwd} command as @code{root},
+unless your configuration specifies otherwise
+(@pxref{user-account-password, user account passwords}).
+
address@hidden upgrading GuixSD
+From then on, you can update GuixSD whenever you want by running @command{guix
+pull} as @code{root} (@pxref{Invoking guix pull}), and then running
address@hidden system reconfigure /etc/config.scm}, as @code{root} too, to
+build a new system generation with the latest packages and services
+(@pxref{Invoking guix system}). We recommend doing that regularly so that
+your system includes the latest security updates (@pxref{Security Updates}).
+
+Join us on @code{#guix} on the Freenode IRC network or on
address@hidden@@gnu.org} to share your experience---good or not so
+good.
+
address@hidden Installing GuixSD in a VM
address@hidden Installing GuixSD in a Virtual Machine
+
address@hidden virtual machine, GuixSD installation
address@hidden virtual private server (VPS)
address@hidden VPS (virtual private server)
+If you'd like to install GuixSD in a virtual machine (VM) or on a
+virtual private server (VPS) rather than on your beloved machine, this
+section is for you.
+
+To boot a @uref{http://qemu.org/,QEMU} VM for installing GuixSD in a
+disk image, follow these steps:
+
address@hidden
address@hidden
+First, retrieve and decompress the GuixSD installation image as
+described previously (@pxref{USB Stick and DVD Installation}).
+
address@hidden
+Create a disk image that will hold the installed system. To make a
+qcow2-formatted disk image, use the @command{qemu-img} command:
+
address@hidden
+qemu-img create -f qcow2 guixsd.img 50G
address@hidden example
+
+The resulting file will be much smaller than 50 GB (typically less than
+1 MB), but it will grow as the virtualized storage device is filled up.
+
address@hidden
+Boot the USB installation image in an VM:
+
address@hidden
+qemu-system-x86_64 -m 1024 -smp 1 \
+ -net user -net nic,model=virtio -boot menu=on \
+ -drive address@hidden@var{system}.iso \
+ -drive file=guixsd.img
address@hidden example
+
+The ordering of the drives matters.
+
+In the VM console, quickly press the @kbd{F12} key to enter the boot
+menu. Then press the @kbd{2} key and the @kbd{RET} key to validate your
+selection.
+
address@hidden
+You're now root in the VM, proceed with the installation process.
address@hidden for Installation}, and follow the instructions.
address@hidden enumerate
+
+Once installation is complete, you can boot the system that's on your
address@hidden image. @xref{Running GuixSD in a VM}, for how to do
+that.
+
address@hidden Building the Installation Image
address@hidden Building the Installation Image
+
address@hidden installation image
+The installation image described above was built using the @command{guix
+system} command, specifically:
+
address@hidden
+guix system disk-image gnu/system/install.scm
address@hidden example
+
+Have a look at @file{gnu/system/install.scm} in the source tree,
+and see also @ref{Invoking guix system} for more information
+about the installation image.
+
address@hidden Building the Installation Image for ARM Boards
+
+Many ARM boards require a specific variant of the
address@hidden://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
+
+If you build a disk image and the bootloader is not available otherwise
+(on another boot drive etc), it's advisable to build an image that
+includes the bootloader, specifically:
+
address@hidden
+guix system disk-image --system=armhf-linux -e '((@@ (gnu system install)
os-with-u-boot) (@@ (gnu system install) installation-os)
"A20-OLinuXino-Lime2")'
address@hidden example
+
address@hidden is the name of the board. If you specify an invalid
+board, a list of possible boards will be printed.
+
@c *********************************************************************
@node Package Management
@chapter Package Management
@@ -9091,658 +9744,6 @@ ClientCommand: cuirass --cache-directory
/var/cache/cuirass @dots{}
@end example
address@hidden System Installation
address@hidden System Installation
-
address@hidden installing GuixSD
address@hidden Guix System Distribution
-This section explains how to install the Guix System Distribution (GuixSD)
-on a machine. The Guix package manager can
-also be installed on top of a running GNU/Linux system,
address@hidden
-
address@hidden
address@hidden Note
address@hidden This paragraph is for people reading this from tty2 of the
address@hidden installation image.
-You are reading this documentation with an Info reader. For details on
-how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
-link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU
-Info}. Hit @kbd{l} afterwards to come back here.
-
-Alternately, run @command{info info} in another tty to keep the manual
-available.
address@hidden quotation
address@hidden ifinfo
-
address@hidden
-* Limitations:: What you can expect.
-* Hardware Considerations:: Supported hardware.
-* USB Stick and DVD Installation:: Preparing the installation medium.
-* Preparing for Installation:: Networking, partitioning, etc.
-* Proceeding with the Installation:: The real thing.
-* Installing GuixSD in a VM:: GuixSD playground.
-* Building the Installation Image:: How this comes to be.
address@hidden menu
-
address@hidden Limitations
address@hidden Limitations
-
-As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
-not production-ready. It may contain bugs and lack important
-features. Thus, if you are looking for a stable production system that
-respects your freedom as a computer user, a good solution at this point
-is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
-the more established GNU/Linux distributions}. We hope you can soon switch
-to the GuixSD without fear, of course. In the meantime, you can
-also keep using your distribution and try out the package manager on top
-of it (@pxref{Installation}).
-
-Before you proceed with the installation, be aware of the following
-noteworthy limitations applicable to version @value{VERSION}:
-
address@hidden
address@hidden
-The installation process does not include a graphical user interface and
-requires familiarity with GNU/Linux (see the following subsections to
-get a feel of what that means.)
-
address@hidden
-Support for the Logical Volume Manager (LVM) is missing.
-
address@hidden
-More and more system services are provided (@pxref{Services}), but some
-may be missing.
-
address@hidden
-More than 8,500 packages are available, but you might
-occasionally find that a useful package is missing.
-
address@hidden
-GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
-as well as a number of X11 window managers. However, some graphical
-applications may be missing, as well as KDE.
address@hidden itemize
-
-You have been warned! But more than a disclaimer, this is an invitation
-to report issues (and success stories!), and to join us in improving it.
address@hidden, for more info.
-
-
address@hidden Hardware Considerations
address@hidden Hardware Considerations
-
address@hidden hardware support on GuixSD
address@hidden focuses on respecting the user's computing freedom. It
-builds around the kernel Linux-libre, which means that only hardware for
-which free software drivers and firmware exist is supported. Nowadays,
-a wide range of off-the-shelf hardware is supported on
-GNU/Linux-libre---from keyboards to graphics cards to scanners and
-Ethernet controllers. Unfortunately, there are still areas where
-hardware vendors deny users control over their own computing, and such
-hardware is not supported on GuixSD.
-
address@hidden WiFi, hardware support
-One of the main areas where free drivers or firmware are lacking is WiFi
-devices. WiFi devices known to work include those using Atheros chips
-(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
-driver, and those using Broadcom/AirForce chips (BCM43xx with
-Wireless-Core Revision 5), which corresponds to the @code{b43-open}
-Linux-libre driver. Free firmware exists for both and is available
-out-of-the-box on GuixSD, as part of @var{%base-firmware}
-(@pxref{operating-system Reference, @code{firmware}}).
-
address@hidden RYF, Respects Your Freedom
-The @uref{https://www.fsf.org/, Free Software Foundation} runs
address@hidden://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a
-certification program for hardware products that respect your freedom
-and your privacy and ensure that you have control over your device. We
-encourage you to check the list of RYF-certified devices.
-
-Another useful resource is the @uref{https://www.h-node.org/, H-Node}
-web site. It contains a catalog of hardware devices with information
-about their support in GNU/Linux.
-
-
address@hidden USB Stick and DVD Installation
address@hidden USB Stick and DVD Installation
-
-An ISO-9660 installation image that can be written to a USB stick or
-burnt to a DVD can be downloaded from
address@hidden://alpha.gnu.org/gnu/guix/address@hidden@var{system}.iso.xz},
-where @var{system} is one of:
-
address@hidden @code
address@hidden x86_64-linux
-for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
-
address@hidden i686-linux
-for a 32-bit GNU/Linux system on Intel-compatible CPUs.
address@hidden table
-
address@hidden start duplication of authentication part from ``Binary
Installation''
-Make sure to download the associated @file{.sig} file and to verify the
-authenticity of the image against it, along these lines:
-
address@hidden
-$ wget https://alpha.gnu.org/gnu/guix/address@hidden@var{system}.iso.xz.sig
-$ gpg --verify address@hidden@var{system}.iso.xz.sig
address@hidden example
-
-If that command fails because you do not have the required public key,
-then run this command to import it:
-
address@hidden
-$ gpg --keyserver @value{KEY-SERVER} \
- --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
address@hidden example
-
address@hidden
-and rerun the @code{gpg --verify} command.
address@hidden end duplication
-
-This image contains the tools necessary for an installation.
-It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
-
address@hidden Copying to a USB Stick
-
-To copy the image to a USB stick, follow these steps:
-
address@hidden
address@hidden
-Decompress the image using the @command{xz} command:
-
address@hidden
-xz -d address@hidden@var{system}.iso.xz
address@hidden example
-
address@hidden
-Insert a USB stick of address@hidden or more into your machine, and determine
-its device name. Assuming that the USB stick is known as @file{/dev/sdX},
-copy the image with:
-
address@hidden
-dd address@hidden@var{system}.iso of=/dev/sdX
-sync
address@hidden example
-
-Access to @file{/dev/sdX} usually requires root privileges.
address@hidden enumerate
-
address@hidden Burning on a DVD
-
-To copy the image to a DVD, follow these steps:
-
address@hidden
address@hidden
-Decompress the image using the @command{xz} command:
-
address@hidden
-xz -d address@hidden@var{system}.iso.xz
address@hidden example
-
address@hidden
-Insert a blank DVD into your machine, and determine
-its device name. Assuming that the DVD drive is known as @file{/dev/srX},
-copy the image with:
-
address@hidden
-growisofs -dvd-compat -Z /dev/address@hidden@var{system}.iso
address@hidden example
-
-Access to @file{/dev/srX} usually requires root privileges.
address@hidden enumerate
-
address@hidden Booting
-
-Once this is done, you should be able to reboot the system and boot from
-the USB stick or DVD. The latter usually requires you to get in the
-BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
-
address@hidden GuixSD in a VM}, if, instead, you would like to install
-GuixSD in a virtual machine (VM).
-
-
address@hidden Preparing for Installation
address@hidden Preparing for Installation
-
-Once you have successfully booted your computer using the installation medium,
-you should end up with the welcome page of the graphical installer. The
-graphical installer is a text-based user interface built upon the newt
-library. It shall guide you through all the different steps needed to install
-GNU GuixSD. However, as the graphical installer is still under heavy
-development, you might want to fallback to the original, shell based install
-process, by switching to TTYs 3 to 6 with the shortcuts CTRL-ALT-F[3-6]. The
-following sections describe the installation procedure assuming you're using
-one of those TTYs. They are configured and can be used to run commands as
-root.
-
-TTY2 shows this documentation, browsable using the Info reader commands
-(@pxref{Top,,, info-stnd, Stand-alone GNU Info}). The installation system
-runs the GPM mouse daemon, which allows you to select text with the left mouse
-button and to paste it with the middle button.
-
address@hidden Note
-Installation requires access to the Internet so that any missing
-dependencies of your system configuration can be downloaded. See the
-``Networking'' section below.
address@hidden quotation
-
-The installation system includes many common tools needed for this task.
-But it is also a full-blown GuixSD system, which means that you can
-install additional packages, should you need it, using @command{guix
-package} (@pxref{Invoking guix package}).
-
address@hidden Keyboard Layout
-
address@hidden keyboard layout
-The installation image uses the US qwerty keyboard layout. If you want
-to change it, you can use the @command{loadkeys} command. For example,
-the following command selects the Dvorak keyboard layout:
-
address@hidden
-loadkeys dvorak
address@hidden example
-
-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.
-
address@hidden Networking
-
-Run the following command to see what your network interfaces are called:
-
address@hidden
-ifconfig -a
address@hidden example
-
address@hidden
address@hidden or, using the GNU/Linux-specific @command{ip} command:
-
address@hidden
-ip a
address@hidden example
-
address@hidden
http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
-Wired interfaces have a name starting with @samp{e}; for example, the
-interface corresponding to the first on-board Ethernet controller is
-called @samp{eno1}. Wireless interfaces have a name starting with
address@hidden, like @samp{w1p2s0}.
-
address@hidden @asis
address@hidden Wired connection
-To configure a wired network run the following command, substituting
address@hidden with the name of the wired interface you want to use.
-
address@hidden
-ifconfig @var{interface} up
address@hidden example
-
address@hidden Wireless connection
address@hidden wireless
address@hidden WiFi
-To configure wireless networking, you can create a configuration file
-for the @command{wpa_supplicant} configuration tool (its location is not
-important) using one of the available text editors such as
address@hidden:
-
address@hidden
-nano wpa_supplicant.conf
address@hidden example
-
-As an example, the following stanza can go to this file and will work
-for many wireless networks, provided you give the actual SSID and
-passphrase for the network you are connecting to:
-
address@hidden
address@hidden
- ssid="@var{my-ssid}"
- key_mgmt=WPA-PSK
- psk="the network's secret passphrase"
address@hidden
address@hidden example
-
-Start the wireless service and run it in the background with the
-following command (substitute @var{interface} with the name of the
-network interface you want to use):
-
address@hidden
-wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
address@hidden example
-
-Run @command{man wpa_supplicant} for more information.
address@hidden table
-
address@hidden DHCP
-At this point, you need to acquire an IP address. On a network where IP
-addresses are automatically assigned @i{via} DHCP, you can run:
-
address@hidden
-dhclient -v @var{interface}
address@hidden example
-
-Try to ping a server to see if networking is up and running:
-
address@hidden
-ping -c 3 gnu.org
address@hidden example
-
-Setting up network access is almost always a requirement because the
-image does not contain all the software and tools that may be needed.
-
address@hidden installing over SSH
-If you want to, you can continue the installation remotely by starting
-an SSH server:
-
address@hidden
-herd start ssh-daemon
address@hidden example
-
-Make sure to either set a password with @command{passwd}, or configure
-OpenSSH public key authentication before logging in.
-
address@hidden Disk Partitioning
-
-Unless this has already been done, the next step is to partition, and
-then format the target partition(s).
-
-The installation image includes several partitioning tools, including
-Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
address@hidden, and @command{cfdisk}. Run it and set up your disk with
-the partition layout you want:
-
address@hidden
-cfdisk
address@hidden example
-
-If your disk uses the GUID Partition Table (GPT) format and you plan to
-install BIOS-based GRUB (which is the default), make sure a BIOS Boot
-Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB
-manual}).
-
address@hidden EFI, installation
address@hidden UEFI, installation
address@hidden ESP, EFI system partition
-If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition}
-(ESP) is required. This partition should be mounted at @file{/boot/efi} and
-must have the @code{esp} flag set. E.g., for @command{parted}:
-
address@hidden
-parted /dev/sda set 1 esp on
address@hidden example
-
address@hidden Note
address@hidden grub-bootloader
address@hidden grub-efi-bootloader
-Unsure whether to use EFI- or BIOS-based GRUB? If the directory
address@hidden/sys/firmware/efi} exists in the installation image, then you
should
-probably perform an EFI installation, using @code{grub-efi-bootloader}.
-Otherwise you should use the BIOS-based GRUB, known as
address@hidden @xref{Bootloader Configuration}, for more info on
-bootloaders.
address@hidden quotation
-
-Once you are done partitioning the target hard disk drive, you have to
-create a file system on the relevant partition(s)@footnote{Currently
-GuixSD only supports ext4 and btrfs file systems. In particular, code
-that reads file system UUIDs and labels only works for these file system
-types.}. For the ESP, if you have one and assuming it is
address@hidden/dev/sda1}, run:
-
address@hidden
-mkfs.fat -F32 /dev/sda1
address@hidden example
-
-Preferably, assign file systems a label so that you can easily and
-reliably refer to them in @code{file-system} declarations (@pxref{File
-Systems}). This is typically done using the @code{-L} option of
address@hidden and related commands. So, assuming the target root
-partition lives at @file{/dev/sda2}, a file system with the label
address@hidden can be created with:
-
address@hidden
-mkfs.ext4 -L my-root /dev/sda2
address@hidden example
-
address@hidden encrypted disk
-If you are instead planning to encrypt the root partition, you can use
-the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
address@hidden://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
address@hidden cryptsetup}} for more information.) Assuming you want to
-store the root partition on @file{/dev/sda2}, the command sequence would
-be along these lines:
-
address@hidden
-cryptsetup luksFormat /dev/sda2
-cryptsetup open --type luks /dev/sda2 my-partition
-mkfs.ext4 -L my-root /dev/mapper/my-partition
address@hidden example
-
-Once that is done, mount the target file system under @file{/mnt}
-with a command like (again, assuming @code{my-root} is the label of the
-root file system):
-
address@hidden
-mount LABEL=my-root /mnt
address@hidden example
-
-Also mount any other file systems you would like to use on the target
-system relative to this path. If you have @file{/boot} on a separate
-partition for example, mount it at @file{/mnt/boot} now so it is found
-by @code{guix system init} afterwards.
-
-Finally, if you plan to use one or more swap partitions (@pxref{Memory
-Concepts, swap space,, libc, The GNU C Library Reference Manual}), make
-sure to initialize them with @command{mkswap}. Assuming you have one
-swap partition on @file{/dev/sda3}, you would run:
-
address@hidden
-mkswap /dev/sda3
-swapon /dev/sda3
address@hidden example
-
-Alternatively, you may use a swap file. For example, assuming that in
-the new system you want to use the file @file{/swapfile} as a swap file,
-you would address@hidden example will work for many types of file
-systems (e.g., ext4). However, for copy-on-write file systems (e.g.,
-btrfs), the required steps may be different. For details, see the
-manual pages for @command{mkswap} and @command{swapon}.}:
-
address@hidden
-# This is 10 GiB of swap space. Adjust "count" to change the size.
-dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
-# For security, make the file readable and writable only by root.
-chmod 600 /mnt/swapfile
-mkswap /mnt/swapfile
-swapon /mnt/swapfile
address@hidden example
-
-Note that if you have encrypted the root partition and created a swap
-file in its file system as described above, then the encryption also
-protects the swap file, just like any other file in that file system.
-
address@hidden Proceeding with the Installation
address@hidden Proceeding with the Installation
-
-With the target partitions ready and the target root mounted on
address@hidden/mnt}, we're ready to go. First, run:
-
address@hidden
-herd start cow-store /mnt
address@hidden example
-
-This makes @file{/gnu/store} copy-on-write, such that packages added to it
-during the installation phase are written to the target disk on @file{/mnt}
-rather than kept in memory. This is necessary because the first phase of
-the @command{guix system init} command (see below) entails downloads or
-builds to @file{/gnu/store} which, initially, is an in-memory file system.
-
-Next, you have to edit a file and
-provide the declaration of the operating system to be installed. To
-that end, the installation system comes with three text editors. We
-recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
-supports syntax highlighting and parentheses matching; other editors
-include GNU Zile (an Emacs clone), and
-nvi (a clone of the original BSD @command{vi} editor).
-We strongly recommend storing that file on the target root file system, say,
-as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
-configuration file once you have rebooted into the newly-installed system.
-
address@hidden the Configuration System}, for an overview of the
-configuration file. The example configurations discussed in that
-section are available under @file{/etc/configuration} in the
-installation image. Thus, to get started with a system configuration
-providing a graphical display server (a ``desktop'' system), you can run
-something along these lines:
-
address@hidden
-# mkdir /mnt/etc
-# cp /etc/configuration/desktop.scm /mnt/etc/config.scm
-# nano /mnt/etc/config.scm
address@hidden example
-
-You should pay attention to what your configuration file contains, and
-in particular:
-
address@hidden
address@hidden
-Make sure the @code{bootloader-configuration} form refers to the target
-you want to install GRUB on. It should mention @code{grub-bootloader} if
-you are installing GRUB in the legacy way, or @code{grub-efi-bootloader}
-for newer UEFI systems. For legacy systems, the @code{target} field
-names a device, like @code{/dev/sda}; for UEFI systems it names a path
-to a mounted EFI partition, like @code{/boot/efi}, and do make sure the
-path is actually mounted.
-
address@hidden
-Be sure that your file system labels match the value of their respective
address@hidden fields in your @code{file-system} configuration, assuming
-your @code{file-system} configuration uses the @code{file-system-label}
-procedure in its @code{device} field.
-
address@hidden
-If there are encrypted or RAID partitions, make sure to add a
address@hidden field to describe them (@pxref{Mapped Devices}).
address@hidden itemize
-
-Once you are done preparing the configuration file, the new system must
-be initialized (remember that the target root file system is mounted
-under @file{/mnt}):
-
address@hidden
-guix system init /mnt/etc/config.scm /mnt
address@hidden example
-
address@hidden
-This copies all the necessary files and installs GRUB on
address@hidden/dev/sdX}, unless you pass the @option{--no-bootloader} option.
For
-more information, @pxref{Invoking guix system}. This command may trigger
-downloads or builds of missing packages, which can take some time.
-
-Once that command has completed---and hopefully succeeded!---you can run
address@hidden and boot into the new system. The @code{root} password
-in the new system is initially empty; other users' passwords need to be
-initialized by running the @command{passwd} command as @code{root},
-unless your configuration specifies otherwise
-(@pxref{user-account-password, user account passwords}).
-
address@hidden upgrading GuixSD
-From then on, you can update GuixSD whenever you want by running @command{guix
-pull} as @code{root} (@pxref{Invoking guix pull}), and then running
address@hidden system reconfigure /etc/config.scm}, as @code{root} too, to
-build a new system generation with the latest packages and services
-(@pxref{Invoking guix system}). We recommend doing that regularly so that
-your system includes the latest security updates (@pxref{Security Updates}).
-
-Join us on @code{#guix} on the Freenode IRC network or on
address@hidden@@gnu.org} to share your experience---good or not so
-good.
-
address@hidden Installing GuixSD in a VM
address@hidden Installing GuixSD in a Virtual Machine
-
address@hidden virtual machine, GuixSD installation
address@hidden virtual private server (VPS)
address@hidden VPS (virtual private server)
-If you'd like to install GuixSD in a virtual machine (VM) or on a
-virtual private server (VPS) rather than on your beloved machine, this
-section is for you.
-
-To boot a @uref{http://qemu.org/,QEMU} VM for installing GuixSD in a
-disk image, follow these steps:
-
address@hidden
address@hidden
-First, retrieve and decompress the GuixSD installation image as
-described previously (@pxref{USB Stick and DVD Installation}).
-
address@hidden
-Create a disk image that will hold the installed system. To make a
-qcow2-formatted disk image, use the @command{qemu-img} command:
-
address@hidden
-qemu-img create -f qcow2 guixsd.img 50G
address@hidden example
-
-The resulting file will be much smaller than 50 GB (typically less than
-1 MB), but it will grow as the virtualized storage device is filled up.
-
address@hidden
-Boot the USB installation image in an VM:
-
address@hidden
-qemu-system-x86_64 -m 1024 -smp 1 \
- -net user -net nic,model=virtio -boot menu=on \
- -drive address@hidden@var{system}.iso \
- -drive file=guixsd.img
address@hidden example
-
-The ordering of the drives matters.
-
-In the VM console, quickly press the @kbd{F12} key to enter the boot
-menu. Then press the @kbd{2} key and the @kbd{RET} key to validate your
-selection.
-
address@hidden
-You're now root in the VM, proceed with the installation process.
address@hidden for Installation}, and follow the instructions.
address@hidden enumerate
-
-Once installation is complete, you can boot the system that's on your
address@hidden image. @xref{Running GuixSD in a VM}, for how to do
-that.
-
address@hidden Building the Installation Image
address@hidden Building the Installation Image
-
address@hidden installation image
-The installation image described above was built using the @command{guix
-system} command, specifically:
-
address@hidden
-guix system disk-image gnu/system/install.scm
address@hidden example
-
-Have a look at @file{gnu/system/install.scm} in the source tree,
-and see also @ref{Invoking guix system} for more information
-about the installation image.
-
address@hidden Building the Installation Image for ARM Boards
-
-Many ARM boards require a specific variant of the
address@hidden://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
-
-If you build a disk image and the bootloader is not available otherwise
-(on another boot drive etc), it's advisable to build an image that
-includes the bootloader, specifically:
-
address@hidden
-guix system disk-image --system=armhf-linux -e '((@@ (gnu system install)
os-with-u-boot) (@@ (gnu system install) installation-os)
"A20-OLinuXino-Lime2")'
address@hidden example
-
address@hidden is the name of the board. If you specify an invalid
-board, a list of possible boards will be printed.
-
@node System Configuration
@chapter System Configuration
--
2.20.1