diff options
Diffstat (limited to 'doc/guix-cookbook.texi')
| -rw-r--r-- | doc/guix-cookbook.texi | 214 |
1 files changed, 175 insertions, 39 deletions
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index 3bc63cba7a..57e39f12d9 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -23,7 +23,8 @@ Copyright @copyright{} 2020 Christine Lemmer-Webber@* Copyright @copyright{} 2021 Joshua Branson@* Copyright @copyright{} 2022, 2023 Maxim Cournoyer@* Copyright @copyright{} 2023-2024 Ludovic Courtès@* -Copyright @copyright{} 2023 Thomas Ieong +Copyright @copyright{} 2023 Thomas Ieong@* +Copyright @copyright{} 2024 Florian Pelz@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -67,8 +68,9 @@ This manual is also available in French (@pxref{Top,,, guix-cookbook.fr, Livre de recettes de GNU Guix}), German (@pxref{Top,,, guix-cookbook.de, GNU-Guix-Kochbuch}), Korean (@pxref{Top,,, guix-cookbook.ko, GNU Guix 쿡북}), Brazilian Portuguese (@pxref{Top,,, guix-cookbook.pt_BR, -Livro de Receitas do GNU Guix}) and Slovak (@pxref{Top,,, guix-cookbook.sk, -Receptár GNU Guix}). If you would like to translate +Livro de receitas do GNU Guix}), Slovak (@pxref{Top,,, guix-cookbook.sk, +Receptár GNU Guix}), and Swedish (@pxref{Top,,, guix-cookbook.sv, +Kokbok för GNU Guix}). 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 @@ -84,6 +86,7 @@ manual}). * Software Development:: Environments, continuous integration, etc. * Environment management:: Control environment * Installing Guix on a Cluster:: High-performance computing. +* Guix System Management:: System Management specifics. * Acknowledgments:: Thanks! * GNU Free Documentation License:: The license of this document. @@ -197,6 +200,10 @@ Installing Guix on a Cluster * Cluster Disk Usage:: Disk usage considerations. * Cluster Security Considerations:: Keeping the cluster secure. +Guix System Management + +* Upgrade Postgres for Cuirass:: How to handle deprecation of the default postgres package. + @end detailmenu @end menu @@ -747,7 +754,7 @@ my-hello 2.10 out We've gone as far as we could without any knowledge of Scheme. Before moving on to more complex packages, now is the right time to brush up on your Scheme -knowledge. @pxref{A Scheme Crash Course} to get up to speed. +knowledge. @xref{A Scheme Crash Course} to get up to speed. @node Setup @subsection Setup @@ -1606,8 +1613,8 @@ reference. @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 +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 @@ -1681,7 +1688,7 @@ creates a package. ;; See kernel-config for an example. (configuration-file #f) (defconfig "defconfig") - (extra-options %default-extra-linux-options)) + (extra-options (default-extra-linux-options version))) ...) @end lisp @@ -1693,7 +1700,8 @@ declared like this: (make-linux-libre* linux-libre-5.15-version linux-libre-5.15-gnu-revision linux-libre-5.15-source - '("x86_64-linux" "i686-linux" "armhf-linux" "aarch64-linux" "riscv64-linux") + '("x86_64-linux" "i686-linux" "armhf-linux" + "aarch64-linux" "riscv64-linux") #:configuration-file kernel-config)) @end lisp @@ -1748,7 +1756,7 @@ The second way to create a custom kernel is to pass a new value to the it: @lisp -(define %default-extra-linux-options +(define (default-extra-linux-options version) `(;; https://lists.gnu.org/archive/html/guix-devel/2014-04/msg00039.html ("CONFIG_DEVPTS_MULTIPLE_INSTANCES" . #true) ;; Modules required for initrd: @@ -1798,7 +1806,7 @@ custom kernel: %file-systems %efi-support %emulation - (@@@@ (gnu packages linux) %default-extra-linux-options))) + ((@@@@ (gnu packages linux) default-extra-linux-options) version))) (define-public linux-libre-macbook41 ;; XXX: Access the internal 'make-linux-libre*' procedure, which is @@ -1812,11 +1820,12 @@ custom kernel: #:extra-options %macbook41-config-options)) @end lisp -In the above example @code{%file-systems} is a collection of flags enabling -different file system support, @code{%efi-support} enables EFI support and -@code{%emulation} enables a x86_64-linux machine to act in 32-bit mode also. -@code{%default-extra-linux-options} are the ones quoted above, which had to be -added in since they were replaced in the @code{extra-options} keyword. +In the above example @code{%file-systems} is a collection of flags +enabling different file system support, @code{%efi-support} enables EFI +support and @code{%emulation} enables a x86_64-linux machine to act in +32-bit mode also. The @code{default-extra-linux-options} procedure is +the one defined above, which had to be used to avoid loosing the default +configuration options of the @code{extra-options} keyword. This all sounds like it should be doable, but how does one even know which modules are required for a particular system? Two places that can be helpful @@ -2405,9 +2414,11 @@ Then you need to add the following code to a StumpWM configuration file @lisp (require :ttf-fonts) (setf xft:*font-dirs* '("/run/current-system/profile/share/fonts/")) -(setf clx-truetype:+font-cache-filename+ (concat (getenv "HOME") "/.fonts/font-cache.sexp")) +(setf clx-truetype:+font-cache-filename+ (concat (getenv "HOME") + "/.fonts/font-cache.sexp")) (xft:cache-fonts) -(set-font (make-instance 'xft:font :family "DejaVu Sans Mono" :subfamily "Book" :size 11)) +(set-font (make-instance 'xft:font :family "DejaVu Sans Mono" + :subfamily "Book" :size 11)) @end lisp @node Session lock @@ -2447,7 +2458,7 @@ be made setuid-root so it can authenticate users, and it needs a PAM service. Th can be achieved by adding the following service to your @file{config.scm}: @lisp -(service screen-locker-services-type +(service screen-locker-service-type (screen-locker-configuration (name "slock") (program (file-append slock "/bin/slock")))) @@ -2963,13 +2974,14 @@ should be defined, so that the bind mount can depend on it. (file-system (device (uuid "UUID goes here")) (mount-point "/path-to-spinning-disk-goes-here") - (type "ext4"))) ;; Make sure to set this to the appropriate type for your drive. + (type "ext4"))) ;Make sure to set this to the appropriate type for your drive. @end lisp The source folder must also be defined, so that guix will know it's not a regular block device, but a folder. @lisp -(define (%source-directory) "/path-to-spinning-disk-goes-here/tmp") ;; "source-directory" can be named any valid variable name. +;; "source-directory" can be named any valid variable name. +(define (%source-directory) "/path-to-spinning-disk-goes-here/tmp") @end lisp Finally, inside the @code{file-systems} definition, we must add the @@ -2980,14 +2992,18 @@ mount itself. ...<other drives omitted for clarity>... - source-drive ;; Must match the name you gave the source drive in the earlier definition. + ;; Must match the name you gave the source drive in the earlier definition. + source-drive (file-system - (device (%source-directory)) ;; Make sure "source-directory" matches your earlier definition. + ;; Make sure "source-directory" matches your earlier definition. + (device (%source-directory)) (mount-point "/tmp") - (type "none") ;; We are mounting a folder, not a partition, so this type needs to be "none" + ;; We are mounting a folder, not a partition, so this type needs to be "none" + (type "none") (flags '(bind-mount)) - (dependencies (list source-drive)) ;; Ensure "source-drive" matches what you've named the variable for the drive. + ;; Ensure "source-drive" matches what you've named the variable for the drive. + (dependencies (list source-drive)) ) ...<other drives omitted for clarity>... @@ -3036,8 +3052,8 @@ follow: config => (guix-configuration (inherit config) ;; ci.guix.gnu.org's Onion service - (substitute-urls - "@value{SUBSTITUTE-TOR-URL}") + (substitute-urls "\ +@value{SUBSTITUTE-TOR-URL}") (http-proxy "http://localhost:9250"))))))) @end lisp @@ -3279,12 +3295,14 @@ that should accomplish the above-mentioned tasks: #~(string-append "\ # Declare Bluetooth audio device type \"bluealsa\" from bluealsa module pcm_type.bluealsa @{ - lib \"" #$(file-append bluez-alsa "/lib/alsa-lib/libasound_module_pcm_bluealsa.so") "\" + lib \"" +#$(file-append bluez-alsa "/lib/alsa-lib/libasound_module_pcm_bluealsa.so") "\" @} # Declare control device type \"bluealsa\" from the same module ctl_type.bluealsa @{ - lib \"" #$(file-append bluez-alsa "/lib/alsa-lib/libasound_module_ctl_bluealsa.so") "\" + lib \"" +#$(file-append bluez-alsa "/lib/alsa-lib/libasound_module_ctl_bluealsa.so") "\" @} # Define the actual Bluetooth audio device. @@ -3778,13 +3796,15 @@ QEMU comes with a helper program to conveniently make use of a network bridge interface as an unprivileged user @pxref{Network options,,, QEMU, QEMU Documentation}. The binary must be made setuid root for proper operation; this can be achieved by adding it to the -@code{setuid-programs} field of your (host) @code{operating-system} +@code{privileged-programs} field of your (host) @code{operating-system} definition, as shown below: @example lisp -(setuid-programs - (cons (file-append qemu "/libexec/qemu-bridge-helper") - %setuid-programs)) +(privileged-programs + (cons (privileged-program + (program (file-append qemu "/libexec/qemu-bridge-helper")) + (setuid? #t)) + %default-privileged-programs)) @end example The file @file{/etc/qemu/bridge.conf} must also be made to allow the @@ -4076,7 +4096,8 @@ We can create a manifest specification per profile and install them this way: @example GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles mkdir -p "$GUIX_EXTRA_PROFILES"/my-project # if it does not exist yet -guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project +guix package --manifest=/path/to/guix-my-project-manifest.scm \ + --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project @end example Here we set an arbitrary variable @samp{GUIX_EXTRA_PROFILES} to point to the directory @@ -4143,13 +4164,14 @@ It contains the same variables you would get if you ran: guix package --search-paths=prefix --profile=$my_profile" @end example -Once again, see (@pxref{Invoking guix package,,, guix, GNU Guix Reference Manual}) +Once again, see @ref{Invoking guix package,,, guix, GNU Guix Reference Manual} for the command line options. To upgrade a profile, simply install the manifest again: @example -guix package -m /path/to/guix-my-project-manifest.scm -p "$GUIX_EXTRA_PROFILES"/my-project/my-project +guix package -m /path/to/guix-my-project-manifest.scm \ + -p "$GUIX_EXTRA_PROFILES"/my-project/my-project @end example To upgrade all profiles, it's easy enough to loop over them. For instance, @@ -4159,7 +4181,8 @@ of the profile (e.g.@: "project1"), you could do the following in Bourne shell: @example for profile in "$GUIX_EXTRA_PROFILES"/*; do - guix package --profile="$profile" --manifest="$HOME/.guix-manifests/guix-$profile-manifest.scm" + guix package --profile="$profile" \ + --manifest="$HOME/.guix-manifests/guix-$profile-manifest.scm" done @end example @@ -4337,7 +4360,9 @@ mkdir -p "$GUIX_EXTRA"/my-project guix pull --channels=channel-specs.scm --profile="$GUIX_EXTRA/my-project/guix" mkdir -p "$GUIX_EXTRA_PROFILES/my-project" -"$GUIX_EXTRA"/my-project/guix/bin/guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project +"$GUIX_EXTRA"/my-project/guix/bin/guix package \ + --manifest=/path/to/guix-my-project-manifest.scm \ + --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project @end example It's safe to delete the Guix channel profile you've just installed with the @@ -5071,12 +5096,13 @@ use_guix() PACKAGES=(help2man guile-sqlite3 guile-gcrypt) # Thanks <https://lists.gnu.org/archive/html/guix-devel/2016-09/msg00859.html> - eval "$(guix environment --search-paths --root="$gcroot" --pure guix --ad-hoc $@{PACKAGES[@@]@} $@{PACKAGES_MAINTENANCE[@@]@} "$@@")" + eval "$(guix shell --search-paths --root="$gcroot" --pure \ + --development guix $@{PACKAGES[@@]@} $@{PACKAGES_MAINTENANCE[@@]@} "$@@")" # Predefine configure flags. configure() @{ - ./configure --localstatedir=/var --prefix= + ./configure @} export_function configure @@ -5178,9 +5204,21 @@ startup file for @command{guix-daemon}, @code{--listen} argument to the @code{ExecStart} line so that it looks something like this: +@c Since Debian Buster, \ is documented to split lines. +@c https://manpages.debian.org/buster/systemd/systemd.exec.5.en.html +@c Use it in PDF and Info versions to avoid cut-off at the page border. +@ifnothtml +@example +ExecStart=/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon \ + --build-users-group=guixbuild \ + --listen=/var/guix/daemon-socket/socket --listen=0.0.0.0 +@end example +@end ifnothtml +@ifhtml @example ExecStart=/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon --build-users-group=guixbuild --listen=/var/guix/daemon-socket/socket --listen=0.0.0.0 @end example +@end ifhtml For these changes to take effect, the service needs to be restarted: @@ -5491,6 +5529,104 @@ guix gc --referrers /gnu/store/…-glibc-2.25 This will report whether profiles exist that refer to this specific glibc variant. +@c ********************************************************************* +@node Guix System Management +@chapter Guix System Management +@cindex system management +@cindex sysadmin + +Since Guix does not handle packaging, system configuration and services +the way other (more ``classical'') distributions do, some workflows tend +to unfold slightly different as we are used to and need slight +adjustment. This chapter intends to help with such manners. + +@menu +* Upgrade Postgres for Cuirass:: Upgrading from the default postgres. +@end menu + +@node Upgrade Postgres for Cuirass +@section Upgrade Postgres for Cuirass + +With the deprecation of the default value for the postgres package in +postgresql-configuration (see b93434e656eba4260df82158a96c295000d3ff44), +system upgrades need some manual action before they can take place. +Here's a handy guide on how to. + +Please note that this is a straight-forward way for smaller datasets. +For larger databases +@url{https://www.postgresql.org/docs/current/pgupgrade.html, +@code{pg_upgrade}} may be the better choice. Handling the service and +system upgrade as described in this guide still applies, though. + +@enumerate +@item +Stop and disable cuirass. + +Prevent the service from starting and failing after a reconfiguration: + + @code{sudo herd stop cuirass && sudo herd disable cuirass} + +@item +Dump the database contents. + + @code{sudo su - postgres -s /bin/sh -c pg_dumpall > /tmp/pg.dump} + +@item +Add or alter the postgres service. + +Depending on whether your postgres service is defined implicitly +(through the dependency from the cuirass service) or its own entry in +your operating system's @code{(services)} property, you need to either +add or alter the already existing configuration to reflect your intended +version upgrade. + +Be careful not to upgrade directly to postgres-16 -- cuirass service for +some reason doesn't like that. I had to find and purge the relevant +files and then re-initialize after a failed upgrade to postgres 16. + +@lisp +(service postgresql-service-type + (postgresql-configuration + (postgresql (@ (gnu packages databases) postgresql-15)))) +@end lisp + +Note: If you for some reason didn't read the text here but somewhat +blindly followed the examples and @emph{did upgrade to 16}, here's how +you reset the state: + +@enumerate +@item +Delete the database instance files. + +They default to live under @file{/var/lib/postgres/data}. + +@item +Re-initialize postgres. + +@code{sudo su - postgres -s /bin/sh -c 'pg_ctl init -D +/var/lib/postgres/data'} +@end enumerate + +@item +Reconfigure your system. + +@code{sudo guix system reconfigure path/to/your/altered/config.scm} + +@item +Restore database contents. + +@code{sudo su - postgres -s /bin/sh -c 'psql -d postgres -f /tmp/pg.dump'} + +@item +Enable and start the service. + +@example +sudo herd enable cuirass +sudo herd start cuirass +@end example + +@end enumerate + @c ********************************************************************* @node Acknowledgments |