diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 439 |
1 files changed, 416 insertions, 23 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 1c1e0164e7..769ca1399f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -123,10 +123,12 @@ Copyright @copyright{} 2023 Foundation Devices, Inc.@* Copyright @copyright{} 2023 Thomas Ieong@* Copyright @copyright{} 2023 Saku Laesvuori@* Copyright @copyright{} 2023 Graham James Addis@* -Copyright @copyright{} 2023 Tomas Volf@* +Copyright @copyright{} 2023, 2024 Tomas Volf@* Copyright @copyright{} 2024 Herman Rimm@* Copyright @copyright{} 2024 Matthew Trzcinski@* Copyright @copyright{} 2024 Richard Sent@* +Copyright @copyright{} 2024 Dariqq@* +Copyright @copyright{} 2024 Denis 'GNUtoo' Carikli@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -742,7 +744,12 @@ provide Guix through their own package managers. The version of Guix may be older than @value{VERSION} but you can update it afterwards by running @samp{guix pull}. -For Debian or a derivative such as Ubuntu, call: +We advise system administrators who install Guix, both from the +installation script or @i{via} the native package manager of their +foreign distribution, to also regularly read and follow security +notices, as shown by @command{guix pull}. + +For Debian or derivatives such as Ubuntu or Trisquel, call: @example sudo apt install guix @@ -754,6 +761,12 @@ Likewise, on openSUSE: sudo zypper install guix @end example +If you are running Parabola, after enabling the pcr (Parabola +Community Repo) repository, you can install Guix with: +@example +sudo pacman -S guix +@end example + The Guix project also provides a shell script, @file{guix-install.sh}, which automates the binary installation process without use of a foreign distro package @@ -779,6 +792,13 @@ As root, run: # ./guix-install.sh @end example +The script to install Guix is also packaged in Parabola (in the pcr +repository). You can install and run it with: +@example +sudo pacman -S guix-installer +sudo guix-install.sh +@end example + @quotation Note By default, @file{guix-install.sh} will configure Guix to download pre-built package binaries, called @dfn{substitutes} @@ -8238,8 +8258,8 @@ retrieve. @item @code{url} The URL of the Mercurial repository to clone. -@item @code{revision} -This string denotes revision to fetch specified as a number. +@item @code{changeset} +This string denotes changeset to fetch. @end table @end deftp @@ -8302,6 +8322,43 @@ This string denotes revision to fetch specified as a number. @end table @end deftp +For CVS repositories, the module @code{(guix cvs-download)} defines the +@code{cvs-fetch} origin method and @code{cvs-reference} data type for +support of the Concurrent Versions System (CVS). + +@deffn {Procedure} cvs-fetch ref hash-algo hash [name] +Return a fixed-output derivation that fetches @var{ref}, a +@code{<cvs-reference>} object. The output is expected to have recursive +hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as +the file name, or a generic name if @code{#f}. +@end deffn + +@deftp {Data Type} cvs-reference +This data type represents a CVS reference for @code{cvs-fetch} to +retrieve. + +@table @asis +@item @code{root-directory} +The CVS root directory. + +@item @code{module} +Module to fetch. + +@item @code{revision} +Revision to fetch. +@end table + +The example below denotes a version of gnu-standards to fetch: + +@lisp +(cvs-reference + (root-directory ":pserver:anonymous@@cvs.savannah.gnu.org:/sources/gnustandards") + (module "gnustandards") + (revision "2020-11-25")) +@end lisp + +@end deftp + @node Defining Package Variants @section Defining Package Variants @@ -12154,6 +12211,18 @@ When @var{recursive?} is true, call @code{(@var{select?} @var{file} absolute file name and @var{stat} is the result of @code{lstat}; exclude entries for which @var{select?} does not return true. +@var{file} can be wrapped in the @code{assume-valid-file-name} syntactic +keyword. When this is done, there will not be a warning when +@code{local-file} is used with a non-literal path. The path is still +looked up relative to the current working directory at run time. +Wrapping is done like this: + +@lisp +(define alice-key-file-path "alice.pub") +;; ... +(local-file (assume-valid-file-name alice-key-file-path)) +@end lisp + This is the declarative counterpart of the @code{interned-file} monadic procedure (@pxref{The Store Monad, @code{interned-file}}). @end deffn @@ -14395,6 +14464,39 @@ and generate package expressions for all those packages that are not yet in Guix. @end table +@item npm-binary +@cindex npm +@cindex Node.js +Import metadata from the @uref{https://registry.npmjs.org, npm +Registry}, as in this example: + +@example +guix import npm-binary buffer-crc32 +@end example + +The npm-binary importer also allows you to specify a version string: + +@example +guix import npm-binary buffer-crc32@@1.0.0 +@end example + +@quotation Note +Generated package expressions skip the build step of the +@code{node-build-system}. As such, generated package expressions often +refer to transpiled or generated files, instead of being built from +source. +@end quotation + +Additional options include: + +@table @code +@item --recursive +@itemx -r +Traverse the dependency graph of the given upstream package recursively +and generate package expressions for all those packages that are not yet +in Guix. +@end table + @item opam @cindex OPAM @cindex OCaml @@ -17175,10 +17277,10 @@ version: %base-packages))) @end lisp -@findex specification->package+output +@findex specifications->packages When a package has more than one output it can be a challenge to refer to a specific output instead of just to the standard @code{out} output. For these -situations one can use the @code{specification->package+output} procedure from +situations one can use the @code{specifications->packages} procedure from the @code{(gnu packages)} module. For example: @lisp @@ -17186,8 +17288,8 @@ the @code{(gnu packages)} module. For example: (operating-system ;; ... - (packages (append (map specification->package+output - '("git" "git:send-email")) + (packages (append (specifications->packages + '("git" "git:send-email")) %base-packages))) @end lisp @@ -17779,6 +17881,20 @@ a dependency of @file{/sys/fs/cgroup/cpu} and Another example is a file system that depends on a mapped device, for example for an encrypted partition (@pxref{Mapped Devices}). + +@item @code{shepherd-requirements} (default: @code{'()}) +This is a list of symbols denoting Shepherd requirements that must be +met before mounting the file system. + +As an example, an NFS file system would typically have a requirement for +@code{networking}. + +Typically, file systems are mounted before most other Shepherd services +are started. However, file systems with a non-empty +shepherd-requirements field are mounted after Shepherd services have +begun. Any Shepherd service that depends on a file system with a +non-empty shepherd-requirements field must depend on it directly and not +on the generic symbol @code{file-systems}. @end table @end deftp @@ -19375,9 +19491,11 @@ the nscd---e.g., @code{(list @var{nss-mdns})}. Package object denoting the GNU C Library providing the @command{nscd} command. -@item @code{log-file} (default: @code{"/var/log/nscd.log"}) -Name of the nscd log file. This is where debugging output goes when -@code{debug-level} is strictly positive. +@item @code{log-file} (default: @code{#f}) +Name of the nscd log file. Debugging output goes to that file when +@code{debug-level} is strictly positive, or to standard error if it is +@code{#f}. Regular messages are written to syslog when +@code{debug-level} is zero, regardless of the value of @code{log-file}. @item @code{debug-level} (default: @code{0}) Integer denoting the debugging levels. Higher numbers mean that more @@ -23540,6 +23658,17 @@ in @var{config}, are available. The result should be used in place of Usually the X server is started by a login manager. @end deffn +@deffn {Procedure} xorg-start-command-xinit [config] +Return a @code{startx} script in which the modules, fonts, +etc. specified in @var{config} are available. The result should be used +in place of @code{startx} and should be invoked by the user from a tty +after login. Unlike @code{xorg-start-command}, this script calls xinit. +Therefore it works well when executed from a tty. This script can be +set up as @code{startx} using @code{startx-command-service-type} or +@code{home-startx-command-service-type}. If you are using a desktop +environment, you are unlikely to need this procedure. +@end deffn + @defvar screen-locker-service-type Type for a service that adds a package for a screen locker or screen @@ -23599,6 +23728,14 @@ Whether to setup program as setuid binary. @end deftp +@defvar startx-command-service-type +Add @command{startx} to the system profile putting it onto @env{PATH}. + +The value for this service is a @code{<xorg-configuration>} object which +is passed to the @code{xorg-start-command-xinit} procedure producing the +@command{startx} used. Default value is @code{(xorg-configuration)}. +@end defvar + @node Printing Services @subsection Printing Services @@ -34674,6 +34811,45 @@ Base URL to use for links to laminar itself. @node Power Management Services @subsection Power Management Services +@cindex power-profiles-daemon +@subsubheading Power Profiles Daemon + +The @code{(gnu services pm)} module provides a Guix service definition for +the Linux Power Profiles Daemon, which makes power profiles handling +available over D-Bus. + +The available profiles consist of the default @samp{balanced} mode, a @samp{power-saver} mode +and on supported systems a @samp{performance} mode. + +@quotation Important +The @code{power-profiles-daemon} conflicts with other power management tools +like @code{tlp}. Using both together is not recommended. +@end quotation + +@defvar power-profiles-daemon-service-type +This is the service type for the +@uref{https://gitlab.freedesktop.org/upower/power-profiles-daemon/, Power Profiles Daemon}. +The value for this service is a @code{power-profiles-daemon-configuration}. + +To enable the Power Profiles Daemon with default configuration +add this line to your services: + +@lisp +(service power-profiles-daemon-service-type) +@end lisp +@end defvar + +@deftp {Data Type} power-profiles-daemon-configuration +Data type representing the configuration of @code{power-profiles-daemon-service-type}. + +@table @asis +@item @code{power-profiles-daemon} (default: @code{power-profiles-daemon}) (type: file-like) +Package object of power-profiles-daemon. + +@end table +@end deftp + + @cindex tlp @cindex power management with TLP @subsubheading TLP daemon @@ -40425,6 +40601,17 @@ processes as Shepherd Services. (service oci-container-service-type (list (oci-container-configuration + (image + (oci-image + (repository "guile") + (tag "3") + (value (specifications->manifest '("guile"))) + (pack-options '(#:symlinks (("/bin/guile" -> "bin/guile")) + #:max-layers 2)))) + (entrypoint "/bin/guile") + (command + '("-c" "(display \"hello!\n\")"))) + (oci-container-configuration (image "prom/prometheus") (network "host") (ports @@ -40464,13 +40651,30 @@ The user under whose authority docker commands will be run. @item @code{group} (default: @code{"docker"}) (type: string) The group under whose authority docker commands will be run. -@item @code{command} (default: @code{()}) (type: list-of-strings) +@item @code{command} (default: @code{'()}) (type: list-of-strings) Overwrite the default command (@code{CMD}) of the image. @item @code{entrypoint} (default: @code{""}) (type: string) Overwrite the default entrypoint (@code{ENTRYPOINT}) of the image. -@item @code{environment} (default: @code{()}) (type: list) +@item @code{host-environment} (default: @code{'()}) (type: list) +Set environment variables in the host environment where @command{docker +run} is invoked. This is especially useful to pass secrets from the +host to the container without having them on the @command{docker run}'s +command line: by setting the @code{MYSQL_PASSWORD} on the host and by passing +@code{--env MYSQL_PASSWORD} through the @code{extra-arguments} field, it is +possible to securely set values in the container environment. This field's +value can be a list of pairs or strings, even mixed: + +@lisp +(list '(\"LANGUAGE\" . \"eo:ca:eu\") + \"JAVA_HOME=/opt/java\") +@end lisp + +Pair members can be strings, gexps or file-like objects. Strings are passed +directly to @code{make-forkexec-constructor}. + +@item @code{environment} (default: @code{'()}) (type: list) Set environment variables. This can be a list of pairs or strings, even mixed: @lisp @@ -40478,22 +40682,28 @@ Set environment variables. This can be a list of pairs or strings, even mixed: "JAVA_HOME=/opt/java") @end lisp -String are passed directly to the Docker CLI. You can refer to the +Pair members can be strings, gexps or file-like objects. +Strings are passed directly to the Docker CLI. You can refer to the @uref{https://docs.docker.com/engine/reference/commandline/run/#env,upstream} documentation for semantics. -@item @code{image} (type: string) -The image used to build the container. Images are resolved by the -Docker Engine, and follow the usual format +@item @code{image} (type: string-or-oci-image) +The image used to build the container. It can be a string or an +@code{oci-image} record. Strings are resolved by the Docker Engine, and +follow the usual format @code{myregistry.local:5000/testing/test-image:tag}. @item @code{provision} (default: @code{""}) (type: string) Set the name of the provisioned Shepherd service. +@item @code{requirement} (default: @code{'()}) (type: list-of-symbols) +Set additional Shepherd services dependencies to the provisioned +Shepherd service. + @item @code{network} (default: @code{""}) (type: string) Set a Docker network for the spawned container. -@item @code{ports} (default: @code{()}) (type: list) +@item @code{ports} (default: @code{'()}) (type: list) Set the port or port ranges to expose from the spawned container. This can be a list of pairs or strings, even mixed: @@ -40502,11 +40712,12 @@ list of pairs or strings, even mixed: "10443:443") @end lisp -String are passed directly to the Docker CLI. You can refer to the +Pair members can be strings, gexps or file-like objects. +Strings are passed directly to the Docker CLI. You can refer to the @uref{https://docs.docker.com/engine/reference/commandline/run/#publish,upstream} documentation for semantics. -@item @code{volumes} (default: @code{()}) (type: list) +@item @code{volumes} (default: @code{'()}) (type: list) Set volume mappings for the spawned container. This can be a list of pairs or strings, even mixed: @@ -40515,7 +40726,8 @@ list of pairs or strings, even mixed: "/gnu/store:/gnu/store") @end lisp -String are passed directly to the Docker CLI. You can refer to the +Pair members can be strings, gexps or file-like objects. +Strings are passed directly to the Docker CLI. You can refer to the @uref{https://docs.docker.com/engine/reference/commandline/run/#volume,upstream} documentation for semantics. @@ -40530,6 +40742,62 @@ You can refer to the @url{https://docs.docker.com/engine/reference/run/#workdir,upstream} documentation for semantics. +@item @code{extra-arguments} (default: @code{'()}) (type: list) +A list of strings, gexps or file-like objects that will be directly +passed to the @command{docker run} invokation. + +@end table + +@end deftp + + +@c %end of fragment + +@c %start of fragment + +@deftp {Data Type} oci-image +Available @code{oci-image} fields are: + +@table @asis +@item @code{repository} (type: string) +A string like @code{myregistry.local:5000/testing/test-image} that names +the OCI image. + +@item @code{tag} (default: @code{"latest"}) (type: string) +A string representing the OCI image tag. Defaults to @code{latest}. + +@item @code{value} (type: oci-lowerable-image) +A @code{manifest} or @code{operating-system} record that will be lowered +into an OCI compatible tarball. Otherwise this field's value can be a +gexp or a file-like object that evaluates to an OCI compatible tarball. + +@item @code{pack-options} (default: @code{'()}) (type: list) +An optional set of keyword arguments that will be passed to the +@code{docker-image} procedure from @code{guix scripts pack}. They can +be used to replicate @command{guix pack} behavior: + +@lisp +(oci-image + (repository "guile") + (tag "3") + (value + (specifications->manifest '("guile"))) + (pack-options '(#:symlinks (("/bin/guile" -> "bin/guile")) + #:max-layers 2))) +@end lisp + +If the @code{value} field is an @code{operating-system} record, this field's +value will be ignored. + +@item @code{system} (default: @code{""}) (type: string) +Attempt to build for a given system, e.g. "i686-linux" + +@item @code{target} (default: @code{""}) (type: string) +Attempt to cross-build for a given triple, e.g. "aarch64-linux-gnu" + +@item @code{grafts?} (default: @code{#f}) (type: boolean) +Whether to allow grafting or not in the pack build. + @end table @end deftp @@ -40669,7 +40937,7 @@ After @command{guix system reconfigure} configure Nix for your user: @itemize @item Add a Nix channel and update it. See -@url{https://nixos.wiki/wiki/Nix_channels, Nix channels} for more +@url{https://wiki.nixos.org/wiki/Nix_channels, Nix channels} for more information about the available channels. If you would like to use the unstable Nix channel you can do this by running: @@ -40980,6 +41248,122 @@ Mode for filter. @c End of auto-generated fail2ban documentation. +@cindex Backup +@subsubheading Backup Services + +The @code{(gnu services backup)} module offers services for backing up +file system trees. For now, it provides the @code{restic-backup-service-type}. + +With @code{restic-backup-service-type}, you can periodically back up +directories and files with @uref{https://restic.net/, Restic}, which +supports end-to-end encryption and deduplication. Consider the +following configuration: + +@lisp +(use-service-modules backup @dots{}) ;for 'restic-backup-service-type' +(use-package-modules sync @dots{}) ;for 'rclone' + +(operating-system + ;; @dots{} + (packages (append (list rclone) ;for use by restic + %base-packages)) + (services + (list + (service restic-backup-service-type + (restic-backup-configuration + (jobs + (list (restic-backup-job + (name "remote-ftp") + (repository "rclone:remote-ftp:backup/restic") + (password-file "/root/.restic") + ;; Every day at 23. + (schedule "0 23 * * *") + (files '("/root/.restic" + "/root/.config/rclone" + "/etc/ssh/ssh_host_rsa_key" + "/etc/ssh/ssh_host_rsa_key.pub" + "/etc/guix/signing-key.pub" + "/etc/guix/signing-key.sec")))))))))) +@end lisp + +Each @code{restic-backup-job} translates to an mcron job which sets the +@env{RESTIC_PASSWORD} environment variable by reading the first line of +@code{password-file} and runs @command{restic backup}, creating backups +using rclone of all the files listed in the @code{files} field. + +The @code{restic-backup-service-type} installs as well @code{restic-guix} +to the system profile, a @code{restic} utility wrapper that allows for easier +interaction with the Guix configured backup jobs. For example the following +could be used to instantaneusly trigger a backup for the above shown +configuration, without waiting for the scheduled job: + +@example +restic-guix backup remote-ftp +@end example + +@c %start of fragment + +@deftp {Data Type} restic-backup-configuration +Available @code{restic-backup-configuration} fields are: + +@table @asis +@item @code{jobs} (default: @code{'()}) (type: list-of-restic-backup-jobs) +The list of backup jobs for the current system. + +@end table + +@end deftp + + +@c %end of fragment + +@c %start of fragment + +@deftp {Data Type} restic-backup-job +Available @code{restic-backup-job} fields are: + +@table @asis +@item @code{restic} (default: @code{restic}) (type: package) +The restic package to be used for the current job. + +@item @code{user} (default: @code{"root"}) (type: string) +The user used for running the current job. + +@item @code{repository} (type: string) +The restic repository target of this job. + +@item @code{name} (type: string) +A string denoting a name for this job. + +@item @code{password-file} (type: string) +Name of the password file, readable by the configured @code{user}, +that will be used to set the @env{RESTIC_PASSWORD} environment variable +for the current job. + +@item @code{schedule} (type: gexp-or-string) +A string or a gexp that will be passed as time specification in the +mcron job specification (@pxref{Syntax, mcron job specifications,, +mcron,GNU@tie{}mcron}). + +@item @code{files} (default: @code{'()}) (type: list-of-lowerables) +The list of files or directories to be backed up. It must be a list of +values that can be lowered to strings. + +@item @code{verbose?} (default: @code{#f}) (type: boolean) +Whether to enable verbose output for the current backup job. + +@item @code{extra-flags} (default: @code{'()}) (type: list-of-lowerables) +A list of values that are lowered to strings. These will be passed as +command-line arguments to the current job @command{restic backup} +invokation. + +@end table + +@end deftp + + +@c %end of fragment + @node Setuid Programs @section Setuid Programs @@ -42250,7 +42634,7 @@ image=$(guix system image --image-type=qcow2 \ cp $image /tmp/my-image.qcow2 chmod +w /tmp/my-image.qcow2 qemu-system-x86_64 -enable-kvm -hda /tmp/my-image.qcow2 -m 1000 \ - -bios $(guix build ovmf)/share/firmware/ovmf_x64.bin + -bios $(guix build ovmf-x86-64)/share/firmware/ovmf_x64.bin @end example When using the @code{mbr-hybrid-raw} image type, a raw disk image is @@ -45915,6 +46299,15 @@ The list of expressions to be read by @code{xmodmap} on service startup. @end table @end deftp +@defvar home-startx-command-service-type +Add @command{startx} to the home profile putting it onto @env{PATH}. + +The value for this service is a @code{<xorg-configuration>} object which +is passed to the @code{xorg-start-command-xinit} procedure producing the +@command{startx} used. Default value is @code{(xorg-configuration)}. +@end defvar + + @node Guix Home Services @subsection Guix Home Services |