diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 336 |
1 files changed, 222 insertions, 114 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 6770c9d664..0e1e253b02 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -116,7 +116,7 @@ Copyright @copyright{} 2022 Antero Mejr@* Copyright @copyright{} 2023 Karl Hallsby@* Copyright @copyright{} 2023 Nathaniel Nicandro@* Copyright @copyright{} 2023 Tanguy Le Carrour@* -Copyright @copyright{} 2023 Zheng Junjie@* +Copyright @copyright{} 2023, 2024 Zheng Junjie@* Copyright @copyright{} 2023 Brian Cully@* Copyright @copyright{} 2023 Felix Lechner@* Copyright @copyright{} 2023 Foundation Devices, Inc.@* @@ -370,7 +370,7 @@ System Configuration * Keyboard Layout:: How the system interprets key strokes. * Locales:: Language and cultural convention settings. * Services:: Specifying system services. -* Setuid Programs:: Programs running with elevated privileges. +* Privileged Programs:: Programs running with elevated privileges. * X.509 Certificates:: Authenticating HTTPS servers. * Name Service Switch:: Configuring libc's name service switch. * Initial RAM Disk:: Linux-Libre bootstrapping. @@ -860,8 +860,28 @@ files, configuration, and services. @section Setting Up the Daemon @cindex daemon +During installation, the @dfn{build daemon} that must be running +to use Guix has already been set up and you can run @command{guix} +commands in your terminal program, @pxref{Getting Started}: + +@example +guix build hello +@end example + +If this runs through without error, feel free to skip this section. +You should continue with the following section, @ref{Application +Setup}. + +However, now would be a good time to replace outdated daemon versions, +tweak it, perform builds on other machines (@pxref{Daemon Offload +Setup}), or start it manually in special environments like ``chroots'' +(@pxref{Chrooting into an existing system}) or WSL (not needed for WSL +images created with Guix, @pxref{System Images, +@code{wsl2-image-type}}). If you want to know more or optimize your +system, this section is worth reading. + Operations such as building a package or running the garbage collector -are all performed by a specialized process, the @dfn{build daemon}, on +are all performed by a specialized process, the build daemon, on behalf of clients. Only the daemon may access the store and its associated database. Thus, any operation that manipulates the store goes through the daemon. For instance, command-line tools such as @@ -1878,15 +1898,28 @@ running Emacs with the @option{--no-site-file} option (@pxref{Init File,,, emacs, The GNU Emacs Manual}). @quotation Note -Emacs can now compile packages natively. Under the default -configuration, this means that Emacs packages will now be -just-in-time (JIT) compiled as you use them, and the results -stored in a subdirectory of your @code{user-emacs-directory}. - -Furthermore, the build system for Emacs packages transparently -supports native compilation, but note, that -@code{emacs-minimal}---the default Emacs for building -packages---has been configured without native compilation. +Most Emacs variants are now capable of doing native compilation. +The approach taken by Guix Emacs however differs greatly +from the approach taken upstream. + +Upstream Emacs compiles packages just-in-time and typically places +shared object files in a special folder within your +@code{user-emacs-directory}. +These shared objects within said folder are organized in a +flat hierarchy, and their file names contain two hashes to +verify the original file name and contents of the source code. + +Guix Emacs on the other hand prefers to compile packages ahead-of-time. +Shared objects retain much of the original file name and no hashes +are added to verify the original file name or the contents of the file. +Crucially, this allows Guix Emacs and packages built against it +to be grafted (@pxref{Security Updates, grafts}), but at the same time, +Guix Emacs lacks the hash-based verification of source code baked +into upstream Emacs. As this naming schema is trivial to exploit, +we disable just-in-time compilation. + +Further note, that @code{emacs-minimal}---the default Emacs +for building packages---has been configured without native compilation. To natively compile your emacs packages ahead of time, use a transformation like @option{--with-input=emacs-minimal=emacs}. @end quotation @@ -1971,19 +2004,10 @@ We consider Guix System to be ready for a wide range of ``desktop'' and server use cases. The reliability guarantees it provides---transactional upgrades and rollbacks, reproducibility---make it a solid foundation. -Nevertheless, before you proceed with the installation, be aware of the -following noteworthy limitations applicable to version @value{VERSION}: - -@itemize -@item -More and more system services are provided (@pxref{Services}), but some -may be missing. +More and more system services are provided (@pxref{Services}). -@item -GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}), -as well as a number of X11 window managers. However, KDE is currently -missing. -@end itemize +Nevertheless, before you proceed with the installation, be aware that some +services you rely on may still be missing from version @value{VERSION}. More than a disclaimer, this is an invitation to report issues (and success stories!), and to join us in improving it. @xref{Contributing}, for more @@ -5355,7 +5379,8 @@ returns a package for the given channels, and using it as part of your operating system configuration, as in this example: @lisp -(use-modules (guix channels)) +(use-modules (gnu packages package-management) + (guix channels)) (define my-channels ;; Channels that should be available to @@ -16940,7 +16965,7 @@ instance to support new system services. * Keyboard Layout:: How the system interprets key strokes. * Locales:: Language and cultural convention settings. * Services:: Specifying system services. -* Setuid Programs:: Programs running with elevated privileges. +* Privileged Programs:: Programs running with elevated privileges. * X.509 Certificates:: Authenticating HTTPS servers. * Name Service Switch:: Configuring libc's name service switch. * Initial RAM Disk:: Linux-Libre bootstrapping. @@ -17664,9 +17689,9 @@ touch this field. Linux @dfn{pluggable authentication module} (PAM) services. @c FIXME: Add xref to PAM services section. -@item @code{setuid-programs} (default: @code{%setuid-programs}) -List of @code{<setuid-program>}. @xref{Setuid Programs}, for more -information. +@item @code{privileged-programs} (default: @code{%default-privileged-programs}) +List of @code{<privileged-program>}. @xref{Privileged Programs}, for +more information. @item @code{sudoers-file} (default: @code{%sudoers-specification}) @cindex sudoers file @@ -23303,6 +23328,11 @@ The available fields are: @item @code{sddm} (default: @code{sddm}) The SDDM package to use. +@quotation Note +sddm has Qt6 enabled by default. If you want to still use a Qt5 theme, +you need to set it to @code{sddm-qt5}. +@end quotation + @item @code{display-server} (default: "x11") Select display server to use for the greeter. Valid values are @samp{"x11"} or @samp{"wayland"}. @@ -23670,10 +23700,10 @@ environment, you are unlikely to need this procedure. @defvar screen-locker-service-type Type for a service that adds a package for a screen locker or screen -saver to the set of setuid programs and/or add a PAM entry for it. The +saver to the set of privileged programs and/or add a PAM entry for it. The value for this service is a @code{<screen-locker-configuration>} object. -While the default behavior is to setup both a setuid program and PAM +While the default behavior is to setup both a privileged program and PAM entry, these two methods are redundant. Screen locker programs may not execute when PAM is configured and @code{setuid} is set on their executable. In this case, @code{using-setuid?} can be set to @code{#f}. @@ -24588,28 +24618,26 @@ The @code{%desktop-services} variable can be used as the @code{services} field of an @code{operating-system} declaration (@pxref{operating-system Reference, @code{services}}). -Additionally, the @code{gnome-desktop-service-type}, -@code{xfce-desktop-service}, @code{mate-desktop-service-type}, -@code{lxqt-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 utilities are added to the system, extending -@code{polkit} and @code{dbus} appropriately, allowing GNOME to operate with -elevated privileges on a limited number of special-purpose system interfaces. -Additionally, adding a service made by @code{gnome-desktop-service-type} adds -the GNOME metapackage to the system profile. Likewise, adding the Xfce -service not only adds the @code{xfce} metapackage to the system profile, but -it also gives the Thunar file manager the ability to open a ``root-mode'' file -management window, if the user authenticates using the 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 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 -expected. +Additionally, the following procedures add one (or more!) desktop +environments to a system. + +@itemize +@item @code{gnome-desktop-service-type} adds GNOME, +@item @code{plasma-desktop-service-type} adds KDE Plasma, +@item @code{enlightenment-desktop-service-type} adds Enlightenment, +@item @code{lxqt-desktop-service-type} adds LXQt, +@item @code{mate-desktop-service-type} adds MATE, and +@item @code{xfce-desktop-service} adds Xfce. +@end itemize + +These service types add ``metapackages'' such as @code{gnome} or +@code{plasma} to the system profile, but most of them also set up other useful +services that mere packages can't do. + +For example, they may elevate privileges on a limited number of +special-purpose system interfaces and programs. This allows backlight +adjustment helpers, power management utilities, screen lockers, and +other integrated functionality to work as expected. The desktop environments in Guix use the Xorg display server by default. If you'd like to use the newer display server protocol @@ -27849,7 +27877,7 @@ remote servers. Run @command{man smtpd.conf} for more information. Make the following commands setgid to @code{smtpq} so they can be executed: @command{smtpctl}, @command{sendmail}, @command{send-mail}, @command{makemap}, @command{mailq}, and @command{newaliases}. -@xref{Setuid Programs}, for more information on setgid programs. +@xref{Privileged Programs}, for more information on setgid programs. @end table @end deftp @@ -32917,25 +32945,30 @@ This is the type of the agate service, whose value should be an (service agate-service-type (agate-configuration (content "/srv/gemini") - (cert "/srv/cert.pem") - (key "/srv/key.rsa"))) + (certs "/srv/gemini-certs"))) @end lisp The example above represents the minimal tweaking necessary to get Agate -up and running. Specifying the path to the certificate and key is +up and running. Specifying the path to the certificate and key directory is always necessary, as the Gemini protocol requires TLS by default. -To obtain a certificate and a key, you could, for example, use OpenSSL, -running a command similar to the following example: +If specified path is writable by Agate, and contains no valid key +and certificate, the Agate will try to generate them on the first start. +If specified directory is read-only - key and certificate should be pre-generated by user. + +To obtain a certificate and a key in a DER format, you could, for example, +use OpenSSL, running a commands similar to the following example: @example -openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \ - -days 3650 -nodes -subj "/CN=example.com" +openssl genpkey -out key.der -outform DER -algorithm RSA \ + -pkeyopt rsa_keygen_bits:4096 +openssl req -x509 -key key.der -outform DER -days 3650 -out cert.der \ + -subj "/CN=example.com" @end example Of course, you'll have to replace @i{example.com} with your own domain name, and then point the Agate configuration towards the path of the -generated key and certificate. +directory with the generated key and certificate using the @code{certs} option. @end defvar @@ -32949,30 +32982,38 @@ The package object of the Agate server. @item @code{content} (default: @file{"/srv/gemini"}) The directory from which Agate will serve files. -@item @code{cert} (default: @code{#f}) -The path to the TLS certificate PEM file to be used for encrypted -connections. Must be filled in with a value from the user. - -@item @code{key} (default: @code{#f}) -The path to the PKCS8 private key file to be used for encrypted -connections. Must be filled in with a value from the user. +@item @code{certs} (default: @file{"/srv/gemini-certs"}) +Root of the certificate directory. Must be filled in with a value from the user. @item @code{addr} (default: @code{'("0.0.0.0:1965" "[::]:1965")}) A list of the addresses to listen on. -@item @code{hostname} (default: @code{#f}) -The domain name of this Gemini server. Optional. +@item @code{hostnames} (default: @code{'()}) +Virtual hosts for the Gemini server. If multiple values are +specified, corresponding directory names should be present in the @code{content} +directory. Optional. @item @code{lang} (default: @code{#f}) RFC 4646 language code(s) for text/gemini documents. Optional. -@item @code{silent?} (default: @code{#f}) -Set to @code{#t} to disable logging output. +@item @code{only-tls13?} (default: @code{#f}) +Set to @code{#t} to disable support for TLSv1.2. @item @code{serve-secret?} (default: @code{#f}) Set to @code{#t} to serve secret files (files/directories starting with a dot). +@item @code{central-conf?} (default: @code{#f}) +Set to @code{#t} to look for the .meta configuration file in the @code{content} +root directory and will ignore @code{.meta} files in other directories + +@item @code{ed25519?} (default: @code{#f}) +Set to @code{#t} to generate keys using the Ed25519 signature algorithm +instead of the default ECDSA. + +@item @code{skip-port-check?} (default: @code{#f}) +Set to @code{#t} to skip URL port check even when a @code{hostname} is specified. + @item @code{log-ip?} (default: @code{#t}) Whether or not to output IP addresses when logging. @@ -40706,12 +40747,54 @@ The following is an example @code{dicod-service-type} configuration. The @code{(gnu services docker)} module provides the following services. +@cindex containerd, container runtime +@defvar containerd-service-type + +This service type operates containerd +@url{https://containerd.io,containerd}, a daemon responsible for +overseeing the entire container lifecycle on its host system. This +includes image handling, storage management, container execution, +supervision, low-level storage operations, network connections, and +more. + +@end defvar + +@deftp {Data Type} containerd-configuration +This is the data type representing the configuration of containerd. + +@table @asis + +@item @code{containerd} (default: @code{containerd}) +The containerd daemon package to use. + +@item @code{debug?} (default @code{#f}) +Enable or disable debug output. + +@item @code{environment-variables} (default: @code{'()}) +List of environment variables to set for @command{containerd}. + +This must be a list of strings where each string has the form +@samp{@var{key}=@var{value}} as in this example: + +@lisp +(list "HTTP_PROXY=socks5://127.0.0.1:9150" + "HTTPS_PROXY=socks5://127.0.0.1:9150") +@end lisp + +@end table +@end deftp + @defvar docker-service-type This is the type of the service that runs @url{https://www.docker.com,Docker}, a daemon that can execute application bundles (sometimes referred to as ``containers'') in isolated environments. +The @code{containerd-service-type} service need to be added to a system +configuration, otherwise a message about not any service provides +@code{containerd} will be displayed during @code{guix system +reconfigure}. + @end defvar @deftp {Data Type} docker-configuration @@ -40726,7 +40809,7 @@ The Docker daemon package to use. The Docker client package to use. @item @code{containerd} (default: @var{containerd}) -The Containerd package to use. +This field is deprecated in favor of @code{containerd-service-type} service. @item @code{proxy} (default @var{docker-libnetwork-cmd-proxy}) The Docker user-land networking proxy package to use. @@ -40765,8 +40848,8 @@ create and run application bundles (aka. ``containers''). The value for this service is the Singularity package to use. The service does not install a daemon; instead, it installs helper programs as -setuid-root (@pxref{Setuid Programs}) such that unprivileged users can invoke -@command{singularity run} and similar commands. +setuid-root (@pxref{Privileged Programs}) such that unprivileged users can +invoke @command{singularity run} and similar commands. @end defvar @cindex OCI-backed, Shepherd services @@ -40788,6 +40871,7 @@ processes as Shepherd Services. (service oci-container-service-type (list (oci-container-configuration + (network "host") (image (oci-image (repository "guile") @@ -40800,20 +40884,17 @@ processes as Shepherd Services. '("-c" "(display \"hello!\n\")"))) (oci-container-configuration (image "prom/prometheus") - (network "host") (ports '(("9000" . "9000") ("9090" . "9090")))) (oci-container-configuration (image "grafana/grafana:10.0.1") (network "host") - (ports - '(("3000" . "3000"))) (volumes '("/var/lib/grafana:/var/lib/grafana"))))) @end lisp -In this example two different Shepherd services are going be added to the +In this example three different Shepherd services are going be added to the system. Each @code{oci-container-configuration} record translates to a @code{docker run} invocation and its fields directly map to options. You can refer to the @@ -40821,8 +40902,8 @@ refer to the documentation for the semantics of each value. If the images are not found they will be @url{https://docs.docker.com/engine/reference/commandline/pull/,pulled}. The -spawned services are going to be attached to the host network and are supposed -to behave like other processes. +services with @code{(network "host")} are going to be attached to the host network +and are supposed to behave like native processes with regard to networking. @end defvar @@ -40854,8 +40935,8 @@ 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\") +(list '("LANGUAGE\" . "eo:ca:eu") + "JAVA_HOME=/opt/java") @end lisp Pair members can be strings, gexps or file-like objects. Strings are passed @@ -40887,6 +40968,23 @@ Set the name of the provisioned Shepherd service. Set additional Shepherd services dependencies to the provisioned Shepherd service. +@item @code{log-file} (type: maybe-string) +When @code{log-file} is set, it names the file to which the service's +standard output and standard error are redirected. @code{log-file} is created +if it does not exist, otherwise it is appended to. + +@item @code{auto-start?} (default: @code{#t}) (type: boolean) +Whether this service should be started automatically by the Shepherd. If it +is @code{#f} the service has to be started manually with @command{herd start}. + +@item @code{respawn?} (default: @code{#f}) (type: boolean) +Whether to have Shepherd restart the service when it stops, for instance when +the underlying process dies. + +@item @code{shepherd-actions} (default: @code{'()}) (type: list-of-symbols) +This is a list of @code{shepherd-action} records defining actions supported +by the service. + @item @code{network} (default: @code{""}) (type: string) Set a Docker network for the spawned container. @@ -41551,11 +41649,14 @@ invokation. @c %end of fragment -@node Setuid Programs -@section Setuid Programs +@node Privileged Programs +@section Privileged Programs +@cindex privileged programs @cindex setuid programs @cindex setgid programs +@cindex capabilities, POSIX +@cindex setcap Some programs need to run with elevated privileges, even when they are launched by unprivileged users. A notorious example is the @command{passwd} program, which users can run to change their @@ -41566,46 +41667,48 @@ obvious security reasons. To address that, @command{passwd} should be (@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual}, for more info about the setuid mechanism). -The store itself @emph{cannot} contain setuid programs: that would be a -security issue since any user on the system can write derivations that +The store itself @emph{cannot} contain privileged programs: that would be +a security issue since any user on the system can write derivations that populate the store (@pxref{The Store}). Thus, a different mechanism is -used: instead of changing the setuid or setgid bits directly on files that -are in the store, we let the system administrator @emph{declare} which +used: instead of directly granting permissions to files that are in +the store, we let the system administrator @emph{declare} which programs should be entrusted with these additional privileges. -The @code{setuid-programs} field of an @code{operating-system} -declaration contains a list of @code{<setuid-program>} denoting the +The @code{privileged-programs} field of an @code{operating-system} +declaration contains a list of @code{<privileged-program>} denoting the names of programs to have a setuid or setgid bit set (@pxref{Using the Configuration System}). For instance, the @command{mount.nfs} program, which is part of the nfs-utils package, with a setuid root can be designated like this: @lisp -(setuid-program - (program (file-append nfs-utils "/sbin/mount.nfs"))) +(privileged-program + (program (file-append nfs-utils "/sbin/mount.nfs")) + (setuid? #t)) @end lisp And then, to make @command{mount.nfs} setuid on your system, add the previous example to your operating system declaration by appending it to -@code{%setuid-programs} like this: +@code{%default-privileged-programs} like this: @lisp (operating-system ;; Some fields omitted... - (setuid-programs - (append (list (setuid-program - (program (file-append nfs-utils "/sbin/mount.nfs")))) - %setuid-programs))) + (privileged-programs + (append (list (privileged-program + (program (file-append nfs-utils "/sbin/mount.nfs")) + (setuid? #t)) + %default-privileged-programs))) @end lisp -@deftp {Data Type} setuid-program -This data type represents a program with a setuid or setgid bit set. +@deftp {Data Type} privileged-program +This data type represents a program with special privileges, such as setuid @table @asis @item @code{program} -A file-like object having its setuid and/or setgid bit set. +A file-like object to which all given privileges should apply. -@item @code{setuid?} (default: @code{#t}) +@item @code{setuid?} (default: @code{#f}) Whether to set user setuid bit. @item @code{setgid?} (default: @code{#f}) @@ -41619,22 +41722,27 @@ defaults to root. GID (integer) group name (string) for the group owner of the program, defaults to root. +@item @code{capabilities} (default: @code{#f}) +A string representing the program's POSIX capabilities, as described by +the @code{cap_to_text(3)} man page from the libcap package, or @code{#f} +to make no changes. + @end table @end deftp -A default set of setuid programs is defined by the -@code{%setuid-programs} variable of the @code{(gnu system)} module. +A default set of privileged programs is defined by the +@code{%default-privileged-programs} variable of the @code{(gnu system)} module. -@defvar %setuid-programs -A list of @code{<setuid-program>} denoting common programs that are -setuid-root. +@defvar {Scheme Variable} %default-privileged-programs +A list of @code{<privileged-program>} denoting common programs with +elevated privileges. The list includes commands such as @command{passwd}, @command{ping}, @command{su}, and @command{sudo}. @end defvar -Under the hood, the actual setuid programs are created in the -@file{/run/setuid-programs} directory at system activation time. The +Under the hood, the actual privileged programs are created in the +@file{/run/privileged/bin} directory at system activation time. The files in this directory refer to the ``real'' binaries, which are in the store. @@ -42576,7 +42684,7 @@ once @command{reconfigure} has completed. @end quotation This effects all the configuration specified in @var{file}: user -accounts, system services, global package list, setuid programs, etc. +accounts, system services, global package list, privileged programs, etc. The command starts system services specified in @var{file} that are not currently running; if a service is currently running this command will arrange for it to be upgraded the next time it is stopped (e.g.@: by @@ -43949,10 +44057,10 @@ In this example, the effect would be to add an @file{/etc/issue} file pointing to the given file. @end defvar -@defvar setuid-program-service-type -Type for the ``setuid-program service''. This service collects lists of +@defvar privileged-program-service-type +Type for the ``privileged-program service''. This service collects lists of executable file names, passed as gexps, and adds them to the set of -setuid and setgid programs on the system (@pxref{Setuid Programs}). +privileged programs on the system (@pxref{Privileged Programs}). @end defvar @defvar profile-service-type |