X-Git-Url: http://git.hcoop.net/jackhill/guix/guix.git/blobdiff_plain/1a8f7a0f584e5dd6e8f1a379b92f689b71902295..1c94392a13cbdf87e03a644633eb775bf45694a1:/doc/guix-cookbook.texi diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index 581b8c3595..88d3b98394 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -16,7 +16,8 @@ Copyright @copyright{} 2020 Matthew Brooks@* Copyright @copyright{} 2020 Marcin Karpezo@* Copyright @copyright{} 2020 Brice Waegeneire@* Copyright @copyright{} 2020 André Batista@* -Copyright @copyright{} 2020 Christopher Lemmer Webber +Copyright @copyright{} 2020 Christine Lemmer-Webber@* +Copyright @copyright{} 2021 Joshua Branson@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -56,9 +57,12 @@ its API, and related concepts. @c TRANSLATORS: You can replace the following paragraph with information on @c how to join your own translation team and how to report issues with the @c translation. -If you would like to translate this document in your native language, consider -joining the @uref{https://translationproject.org/domain/guix-cookbook.html, -Translation Project}. +This manual is also available in French (@pxref{Top,,, guix-cookbook.fr, +Livre de recettes de GNU Guix}) and German (@pxref{Top,,, +guix-cookbook.de, GNU-Guix-Kochbuch}). If you would like to translate +this document in your native language, consider joining +@uref{https://translate.fedoraproject.org/projects/guix/documentation-cookbook, +Weblate} (@pxref{Translating Guix,,, guix, GNU Guix reference manual}). @menu * Scheme tutorials:: Meet your new favorite language! @@ -84,8 +88,8 @@ Packaging System Configuration -* Customizing the Kernel:: Creating and using a custom Linux kernel - +* Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY +* Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. @end detailmenu @end menu @@ -589,7 +593,7 @@ packages. Guix makes it possible to streamline the process by adding as many ``package declaration directories'' as you want. -Create a directory, say @file{~./guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH} +Create a directory, say @file{~/guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH} environment variable: @example @@ -791,10 +795,8 @@ another, more sophisticated package (slightly modified from the source): "17pjvprmdrx4h6bb1hhc98w9qi6ki7yl57f090n9kbhswxqfs7s3")) (patches (search-patches "libgit2-mtime-0.patch")) (modules '((guix build utils))) - (snippet '(begin - ;; Remove bundled software. - (delete-file-recursively "deps") - #true)))) + ;; Remove bundled software. + (snippet '(delete-file-recursively "deps")))) (build-system cmake-build-system) (outputs '("out" "debug")) (arguments @@ -808,23 +810,19 @@ another, more sophisticated package (slightly modified from the source): (("#!/bin/sh") (string-append "#!" (which "sh")))) (substitute* "tests/clar/fs.h" (("/bin/cp") (which "cp")) - (("/bin/rm") (which "rm"))) - #true)) + (("/bin/rm") (which "rm"))))) ;; Run checks more verbosely. (replace 'check (lambda _ (invoke "./libgit2_clar" "-v" "-Q"))) (add-after 'unpack 'make-files-writable-for-tests (lambda _ (for-each make-file-writable (find-files "." ".*"))))))) (inputs - `(("libssh2" ,libssh2) - ("http-parser" ,http-parser) - ("python" ,python-wrapper))) + (list libssh2 http-parser python-wrapper)) (native-inputs - `(("pkg-config" ,pkg-config))) + (list pkg-config)) (propagated-inputs ;; These two libraries are in 'Requires.private' in libgit2.pc. - `(("openssl" ,openssl) - ("zlib" ,zlib))) + (list openssl zlib)) (home-page "https://libgit2.github.com/") (synopsis "Library providing Git core methods") (description @@ -888,22 +886,6 @@ Snippets might need additional Guile modules which can be imported from the @subsubsection Inputs -First, a syntactic comment: See the quasi-quote / comma syntax? - -@lisp - (native-inputs - `(("pkg-config" ,pkg-config))) -@end lisp - -is equivalent to - -@lisp - (native-inputs - (list (list "pkg-config" pkg-config))) -@end lisp - -You'll mostly see the former because it's shorter. - There are 3 different input types. In short: @table @asis @@ -937,6 +919,24 @@ It also matters when a substitute is available, in which case only the @emph{inp and @emph{propagated inputs} will be fetched: the @emph{native inputs} are not required to install a package from a substitute. +@quotation Note +You may see here and there snippets where package inputs are written +quite differently, like so: + +@lisp +;; The "old style" for inputs. +(inputs + `(("libssh2" ,libssh2) + ("http-parser" ,http-parser) + ("python" ,python-wrapper))) +@end lisp + +This is the ``old style'', where each input in the list is explicitly +given a label (a string). It is still supported but we recommend using +the style above instead. @xref{package Reference,,, guix, GNU Guix +Reference Manual}, for more info. +@end quotation + @subsubsection Outputs Just like how a package can have multiple inputs, it can also produce multiple @@ -1352,7 +1352,9 @@ chapter is to demonstrate some advanced configuration concepts. reference. @menu +* Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. +* Guix System Image API:: Customizing images to target specific platforms. * Connecting to Wireguard VPN:: Connecting to a Wireguard VPN. * Customizing a Window Manager:: Handle customization of a Window manager on Guix System. * Running Guix on a Linode Server:: Running Guix on a Linode Server @@ -1361,6 +1363,51 @@ reference. * Setting up NGINX with Lua:: Configuring NGINX web-server to load Lua modules. @end menu +@node Auto-Login to a Specific TTY +@section Auto-Login to a Specific TTY + +While the Guix manual explains auto-login one user to @emph{all} TTYs ( +@pxref{auto-login to TTY,,, guix, GNU Guix Reference Manual}), some +might prefer a situation, in which one user is logged into one TTY with +the other TTYs either configured to login different users or no one at +all. Note that one can auto-login one user to any TTY, but it is +usually advisable to avoid @code{tty1}, which, by default, is used to +log warnings and errors. + +Here is how one might set up auto login for one user to one tty: + +@lisp +(define (auto-login-to-tty config tty user) + (if (string=? tty (mingetty-configuration-tty config)) + (mingetty-configuration + (inherit config) + (auto-login user)) + config)) + +(define %my-services + (modify-services %base-services + ;; @dots{} + (mingetty-service-type config => + (auto-login-to-tty + config "tty3" "alice")))) + +(operating-system + ;; @dots{} + (services %my-services)) +@end lisp + +One could also @code{compose} (@pxref{Higher-Order Functions,,, guile, +The Guile Reference Manual}) @code{auto-login-to-tty} to login multiple +users to multiple ttys. + +Finally, here is a note of caution. Setting up auto login to a TTY, +means that anyone can turn on your computer and run commands as your +regular user. +However, if you have an encrypted root partition, and thus already need +to enter a passphrase when the system boots, auto-login might be a +convenient option. + + @node Customizing the Kernel @section Customizing the Kernel @@ -1601,6 +1648,217 @@ likely that you'll need to modify the initrd on a machine using a custom kernel, since certain modules which are expected to be built may not be available for inclusion into the initrd. +@node Guix System Image API +@section Guix System Image API + +Historically, Guix System is centered around an @code{operating-system} +structure. This structure contains various fields ranging from the +bootloader and kernel declaration to the services to install. + +Depending on the target machine, that can go from a standard +@code{x86_64} machine to a small ARM single board computer such as the +Pine64, the image constraints can vary a lot. The hardware +manufacturers will impose different image formats with various partition +sizes and offsets. + +To create images suitable for all those machines, a new abstraction is +necessary: that's the goal of the @code{image} record. This record +contains all the required information to be transformed into a +standalone image, that can be directly booted on any target machine. + +@lisp +(define-record-type* + image make-image + image? + (name image-name ;symbol + (default #f)) + (format image-format) ;symbol + (target image-target + (default #f)) + (size image-size ;size in bytes as integer + (default 'guess)) + (operating-system image-operating-system ; + (default #f)) + (partitions image-partitions ;list of + (default '())) + (compression? image-compression? ;boolean + (default #t)) + (volatile-root? image-volatile-root? ;boolean + (default #t)) + (substitutable? image-substitutable? ;boolean + (default #t))) +@end lisp + +This record contains the operating-system to instantiate. The +@code{format} field defines the image type and can be @code{efi-raw}, +@code{qcow2} or @code{iso9660} for instance. In the future, it could be +extended to @code{docker} or other image types. + +A new directory in the Guix sources is dedicated to images definition. For now +there are four files: + +@itemize @bullet +@item @file{gnu/system/images/hurd.scm} +@item @file{gnu/system/images/pine64.scm} +@item @file{gnu/system/images/novena.scm} +@item @file{gnu/system/images/pinebook-pro.scm} +@end itemize + +Let's have a look to @file{pine64.scm}. It contains the +@code{pine64-barebones-os} variable which is a minimal definition of an +operating-system dedicated to the @b{Pine A64 LTS} board. + +@lisp +(define pine64-barebones-os + (operating-system + (host-name "vignemale") + (timezone "Europe/Paris") + (locale "en_US.utf8") + (bootloader (bootloader-configuration + (bootloader u-boot-pine64-lts-bootloader) + (targets '("/dev/vda")))) + (initrd-modules '()) + (kernel linux-libre-arm64-generic) + (file-systems (cons (file-system + (device (file-system-label "my-root")) + (mount-point "/") + (type "ext4")) + %base-file-systems)) + (services (cons (service agetty-service-type + (agetty-configuration + (extra-options '("-L")) ; no carrier detect + (baud-rate "115200") + (term "vt100") + (tty "ttyS0"))) + %base-services)))) +@end lisp + +The @code{kernel} and @code{bootloader} fields are pointing to packages +dedicated to this board. + +Right below, the @code{pine64-image-type} variable is also defined. + +@lisp +(define pine64-image-type + (image-type + (name 'pine64-raw) + (constructor (cut image-with-os arm64-disk-image <>)))) +@end lisp + +It's using a record we haven't talked about yet, the @code{image-type} record, +defined this way: + +@lisp +(define-record-type* + image-type make-image-type + image-type? + (name image-type-name) ;symbol + (constructor image-type-constructor)) ; -> +@end lisp + +The main purpose of this record is to associate a name to a procedure +transforming an @code{operating-system} to an image. To understand why +it is necessary, let's have a look to the command producing an image +from an @code{operating-system} configuration file: + +@example +guix system image my-os.scm +@end example + +This command expects an @code{operating-system} configuration but how +should we indicate that we want an image targeting a Pine64 board? We +need to provide an extra information, the @code{image-type}, by passing +the @code{--image-type} or @code{-t} flag, this way: + +@example +guix system image --image-type=pine64-raw my-os.scm +@end example + +This @code{image-type} parameter points to the @code{pine64-image-type} +defined above. Hence, the @code{operating-system} declared in +@code{my-os.scm} will be applied the @code{(cut image-with-os +arm64-disk-image <>)} procedure to turn it into an image. + +The resulting image looks like: + +@lisp +(image + (format 'disk-image) + (target "aarch64-linux-gnu") + (operating-system my-os) + (partitions + (list (partition + (inherit root-partition) + (offset root-offset))))) +@end lisp + +which is the aggregation of the @code{operating-system} defined in + @code{my-os.scm} to the @code{arm64-disk-image} record. + +But enough Scheme madness. What does this image API bring to the Guix user? + +One can run: + +@example +mathieu@@cervin:~$ guix system --list-image-types +The available image types are: + + - pinebook-pro-raw + - pine64-raw + - novena-raw + - hurd-raw + - hurd-qcow2 + - qcow2 + - uncompressed-iso9660 + - efi-raw + - arm64-raw + - arm32-raw + - iso9660 +@end example + +and by writing an @code{operating-system} file based on +@code{pine64-barebones-os}, you can customize your image to your +preferences in a file (@file{my-pine-os.scm}) like this: + +@lisp +(use-modules (gnu services linux) + (gnu system images pine64)) + +(let ((base-os pine64-barebones-os)) + (operating-system + (inherit base-os) + (timezone "America/Indiana/Indianapolis") + (services + (cons + (service earlyoom-service-type + (earlyoom-configuration + (prefer-regexp "icecat|chromium"))) + (operating-system-user-services base-os))))) +@end lisp + +run: + +@example +guix system image --image-type=pine64-raw my-pine-os.scm +@end example + +or, + +@example +guix system image --image-type=hurd-raw my-hurd-os.scm +@end example + +to get an image that can be written directly to a hard drive and booted +from. + +Without changing anything to @code{my-hurd-os.scm}, calling: + +@example +guix system image --image-type=hurd-qcow2 my-hurd-os.scm +@end example + +will instead produce a Hurd QEMU image. + @node Connecting to Wireguard VPN @section Connecting to Wireguard VPN @@ -1790,10 +2048,12 @@ Copy into it the output of: cat ~/.ssh/_rsa.pub @end example -Power the Linode down. In the Linode's Disks/Configurations tab, resize -the Debian disk to be smaller. 30 GB is recommended. +Power the Linode down. + +In the Linode's Storage tab, resize the Debian disk to be smaller. +30 GB free space is recommended. Then click "Add a disk", and fill +out the form with the following: -In the Linode settings, "Add a disk", with the following: @itemize @bullet @item Label: "Guix" @@ -1805,9 +2065,9 @@ Filesystem: ext4 Set it to the remaining size @end itemize -On the "configuration" field that comes with the default image, press -"..." and select "Edit", then on that menu add to @file{/dev/sdc} the "Guix" -label. +In the Configurations tab, press "Edit" on the default Debian profile. +Under "Block Device Assignment" click "Add a Device". It should be +@file{/dev/sdc} and you can select the "Guix" disk. Save Changes. Now "Add a Configuration", with the following: @itemize @bullet @@ -1833,8 +2093,8 @@ Root device: @file{/dev/sda} Turn off all the filesystem/boot helpers @end itemize -Now power it back up, picking the Debian configuration. Once it's -booted up, ssh in your server via @code{ssh +Now power it back up, booting with the Debian configuration. Once it's +running, ssh to your server via @code{ssh root@@@var{}}. (You can find your server IP address in your Linode Summary section.) Now you can run the "install guix from @pxref{Binary Installation,,, guix, GNU Guix}" steps: @@ -1923,19 +2183,20 @@ Replace the following fields in the above configuration: @end lisp The last line in the above example lets you log into the server as root -and set the initial root password. After you have done this, you may +and set the initial root password (see the note at the end of this +recipe about root login). After you have done this, you may delete that line from your configuration and reconfigure to prevent root login. -Save your ssh public key (eg: @file{~/.ssh/id_rsa.pub}) as -@file{@var{}_rsa.pub} and your +Copy your ssh public key (eg: @file{~/.ssh/id_rsa.pub}) as +@file{@var{}_rsa.pub} and put @file{guix-config.scm} in the same directory. In a new terminal run these commands. @example sftp root@@ -put /home//ssh/id_rsa.pub . -put /path/to/linode/guix-config.scm . +put /path/to/files/_rsa.pub . +put /path/to/files/guix-config.scm . @end example In your first terminal, mount the guix drive: @@ -1945,9 +2206,9 @@ mkdir /mnt/guix mount /dev/sdc /mnt/guix @end example -Due to the way we set things up above, we do not install GRUB -completely. Instead we install only our grub configuration file. So we -need to copy over some of the other GRUB stuff that is already there: +Due to the way we set up the bootloader section of the guix-config.scm, +only the grub configuration file will be installed. So, we need to copy +over some of the other GRUB stuff already installed on the Debian system: @example mkdir -p /mnt/guix/boot/grub @@ -2000,7 +2261,7 @@ still need to set your root and user password initially by clicking on the ``Launch Console'' option in your linode. Choose the ``Glish'' instead of ``Weblish''. Now you should be able to ssh into the machine. -Horray! At this point you can shut down the server, delete the +Hooray! At this point you can shut down the server, delete the Debian disk, and resize the Guix to the rest of the size. Congratulations! @@ -2245,7 +2506,7 @@ section on @ref{Reproducible profiles}. @item Easier upgrades and maintenance: Multiple profiles make it easy to keep -package listings at hand and make upgrades completely friction-less. +package listings at hand and make upgrades completely frictionless. @end itemize Concretely, here follows some typical profiles: