diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 168 |
1 files changed, 123 insertions, 45 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 11ce9d6f62..043aad1b65 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -165,10 +165,17 @@ System Installation * 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. +* Guided Graphical Installation:: Easy graphical installation. +* Manual Installation:: Manual installation for wizards. +* After System Installation:: When installation succeeded. * Installing Guix in a VM:: Guix System playground. * Building the Installation Image:: How this comes to be. +Manual Installation + +* Keyboard Layout and Networking and Partitioning:: Initial setup. +* Proceeding with the Installation:: Installing. + Package Management * Features:: How Guix will make your life brighter. @@ -1777,7 +1784,9 @@ available. * 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. +* Guided Graphical Installation:: Easy graphical installation. +* Manual Installation:: Manual installation for wizards. +* After System Installation:: When installation succeeded. * Installing Guix in a VM:: Guix System playground. * Building the Installation Image:: How this comes to be. @end menu @@ -1866,7 +1875,7 @@ about their support in GNU/Linux. An ISO-9660 installation image that can be written to a USB stick or burnt to a DVD can be downloaded from -@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz}, +@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz}, where @var{system} is one of: @table @code @@ -1882,8 +1891,8 @@ Make sure to download the associated @file{.sig} file and to verify the authenticity of the image against it, along these lines: @example -$ wget https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig -$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig +$ wget https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig +$ gpg --verify guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig @end example If that command fails because you do not have the required public key, @@ -1910,7 +1919,7 @@ To copy the image to a USB stick, follow these steps: Decompress the image using the @command{xz} command: @example -xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz +xz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz @end example @item @@ -1919,7 +1928,7 @@ its device name. Assuming that the USB stick is known as @file{/dev/sdX}, copy the image with: @example -dd if=guixsd-install-@value{VERSION}.@var{system}.iso of=/dev/sdX +dd if=guix-system-install-@value{VERSION}.@var{system}.iso of=/dev/sdX sync @end example @@ -1935,7 +1944,7 @@ To copy the image to a DVD, follow these steps: Decompress the image using the @command{xz} command: @example -xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz +xz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz @end example @item @@ -1944,7 +1953,7 @@ its device name. Assuming that the DVD drive is known as @file{/dev/srX}, copy the image with: @example -growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.@var{system}.iso +growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.@var{system}.iso @end example Access to @file{/dev/srX} usually requires root privileges. @@ -1963,21 +1972,19 @@ Guix System in a virtual machine (VM). @node Preparing for Installation @section 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@tie{}Guix System. 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. +Once you have booted, you can use the guided graphical installer, which makes +it easy to get started (@pxref{Guided Graphical Installation}). Alternately, +if you are already familiar with GNU/Linux and if you want more control than +what the graphical installer provides, you can choose the ``manual'' +installation process (@pxref{Manual Installation}). -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. +The graphical installer is available on TTY1. You can obtain root shells on +TTYs 3 to 6 by hitting @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, etc. TTY2 shows +this documentation and you can reach it with @kbd{ctrl-alt-f2}. Documentation +is 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. @quotation Note Installation requires access to the Internet so that any missing @@ -1985,12 +1992,65 @@ dependencies of your system configuration can be downloaded. See the ``Networking'' section below. @end quotation -The installation system includes many common tools needed for this task. -But it is also a full-blown Guix System, which means that you can -install additional packages, should you need it, using @command{guix -package} (@pxref{Invoking guix package}). +@node Guided Graphical Installation +@section Guided Graphical Installation + +The graphical installer is a text-based user interface. It will guide you, +with dialog boxes, through the steps needed to install GNU@tie{}Guix System. + +The first dialog boxes allow you to set up the system as you use it during the +installation: you can choose the language, keyboard layout, and set up +networking, which will be used during the installation. The image below shows +the networking dialog. + +@image{images/installer-network,5in,, networking setup with the graphical installer} + +Later steps allow you to partition your hard disk, as shown in the image +below, to choose whether or not to use encrypted file systems, to enter the +host name and root password, and to create an additional account, among other +things. + +@image{images/installer-partitions,5in,, partitioning with the graphical installer} -@subsection Keyboard Layout +Note that, at any time, the installer allows you to exit the current +installation step and resume at a previous step, as show in the image below. + +@image{images/installer-resume,5in,, resuming the installation process} + +Once you're done, the installer produces an operating system configuration and +displays it (@pxref{Using the Configuration System}). At that point you can +hit ``OK'' and installation will proceed. On success, you can reboot into the +new system and enjoy. @xref{After System Installation}, for what's next! + + +@node Manual Installation +@section Manual Installation + +This section describes how you would ``manually'' install GNU@tie{}Guix System +on your machine. This option requires familiarity with GNU/Linux, with the +shell, and with common administration tools. If you think this is not for +you, consider using the guided graphical installer (@pxref{Guided Graphical +Installation}). + +The installation system provides root shells on TTYs 3 to 6; press +@kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, and so on to reach them. It includes +many common tools needed to install the system. But it is also a full-blown +Guix System, which means that you can install additional packages, should you +need it, using @command{guix package} (@pxref{Invoking guix package}). + +@menu +* Keyboard Layout and Networking and Partitioning:: Initial setup. +* Proceeding with the Installation:: Installing. +@end menu + +@node Keyboard Layout and Networking and Partitioning +@subsection Keyboard Layout, Networking, and Partitioning + +Before you can install the system, you may want to adjust the keyboard layout, +set up networking, and partition your target hard disk. This section will +guide you through this. + +@subsubsection Keyboard Layout @cindex keyboard layout The installation image uses the US qwerty keyboard layout. If you want @@ -2005,7 +2065,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. -@subsection Networking +@subsubsection Networking Run the following command to see what your network interfaces are called: @@ -2098,7 +2158,7 @@ herd start ssh-daemon Make sure to either set a password with @command{passwd}, or configure OpenSSH public key authentication before logging in. -@subsection Disk Partitioning +@subsubsection Disk Partitioning Unless this has already been done, the next step is to partition, and then format the target partition(s). @@ -2219,7 +2279,7 @@ 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. @node Proceeding with the Installation -@section Proceeding with the Installation +@subsection Proceeding with the Installation With the target partitions ready and the target root mounted on @file{/mnt}, we're ready to go. First, run: @@ -2303,9 +2363,14 @@ 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}). +@xref{After System Installation}, for what's next! + + +@node After System Installation +@section After System Installation -@cindex upgrading Guix System -From then on, you can update the system whenever you want by running, say: +Success, you've now booted into Guix System! From then on, you can update the +system whenever you want by running, say: @example guix pull @@ -2326,8 +2391,8 @@ explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}. @end quotation Join us on @code{#guix} on the Freenode IRC network or on -@email{guix-devel@@gnu.org} to share your experience---good or not so -good. +@email{guix-devel@@gnu.org} to share your experience! + @node Installing Guix in a VM @section Installing Guix in a Virtual Machine @@ -2364,7 +2429,7 @@ Boot the USB installation image in an VM: @example qemu-system-x86_64 -m 1024 -smp 1 \ -net user -net nic,model=virtio -boot menu=on \ - -drive file=guixsd-install-@value{VERSION}.@var{system}.iso \ + -drive file=guix-system-install-@value{VERSION}.@var{system}.iso \ -drive file=guixsd.img @end example @@ -14165,7 +14230,7 @@ field of an @code{operating-system} declaration (@pxref{operating-system Reference, @code{services}}). Additionally, the @code{gnome-desktop-service}, -@code{xfce-desktop-service}, @code{mate-desktop-service} and +@code{xfce-desktop-service}, @code{mate-desktop-service-type} and @code{enlightenment-desktop-service-type} procedures can add GNOME, XFCE, MATE and/or Enlightenment to a system. To ``add GNOME'' means that system-level services like the backlight adjustment helpers and the power management @@ -14181,8 +14246,8 @@ administrator's password via the standard polkit graphical interface. To ``add MATE'' means that @code{polkit} and @code{dbus} are extended appropriately, allowing MATE to operate with elevated privileges on a limited number of special-purpose system interfaces. Additionally, -adding a service made by @code{mate-desktop-service} adds the MATE -metapackage to the system profile. ``Adding ENLIGHTENMENT'' means that +adding a service of type @code{mate-desktop-service-type} adds the MATE +metapackage to the system profile. ``Adding Enlightenment'' means that @code{dbus} is extended appropriately, and several of Enlightenment's binaries are set as setuid, allowing Enlightenment's screen locker and other functionality to work as expetected. @@ -14209,13 +14274,26 @@ file system as root from within a user session, after the user has authenticated with the administrator's password. @end deffn -@deffn {Scheme Procedure} mate-desktop-service -Return a service that adds the @code{mate} package to the system +@deffn {Scheme Variable} mate-desktop-service-type +This is the type of the service that runs the @uref{https://mate-desktop.org/, +MATE desktop environment}. Its value is a @code{mate-desktop-configuration} +object (see below.) + +This service adds the @code{mate} package to the system profile, and extends polkit with the actions from @code{mate-settings-daemon}. @end deffn -@deffn {Scheme Procedure} enlightenment-desktop-service-type +@deftp {Data Type} mate-desktop-configuration +Configuration record for the MATE desktop environment. + +@table @asis +@item @code{mate} (default @code{mate}) +The MATE package to use. +@end table +@end deftp + +@deffn {Scheme Variable} enlightenment-desktop-service-type Return a service that adds the @code{enlightenment} package to the system profile, and extends dbus with actions from @code{efl}. @end deffn @@ -16471,7 +16549,7 @@ Defaults to @samp{"internal_plain"}. @deftypevr {@code{prosody-configuration} parameter} maybe-string log Set logging options. Advanced logging configuration is not yet supported -by the Guix Prosody Service. See @url{https://prosody.im/doc/logging}. +by the Prosody service. See @url{https://prosody.im/doc/logging}. Defaults to @samp{"*syslog"}. @end deftypevr @@ -23347,7 +23425,7 @@ system configuration file. You can then load the image and launch a Docker container using commands like the following: @example -image_id="$(docker load < guixsd-docker-image.tar.gz)" +image_id="$(docker load < guix-system-docker-image.tar.gz)" docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\ --entrypoint /var/guix/profiles/system/profile/bin/guile \\ $image_id /var/guix/profiles/system/boot @@ -23533,7 +23611,7 @@ example graph. @cindex virtual machine To run Guix in a virtual machine (VM), one can either use the pre-built Guix VM image distributed at -@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-vm-image-@value{VERSION}.@var{system}.xz} +@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-vm-image-@value{VERSION}.@var{system}.xz} , or build their own virtual machine image using @command{guix system vm-image} (@pxref{Invoking guix system}). The returned image is in qcow2 format, which the @uref{http://qemu.org/, QEMU emulator} can |