diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 279 |
1 files changed, 173 insertions, 106 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 9553a373e8..88fd679f42 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -17,7 +17,7 @@ @set BASE-URL https://ftp.gnu.org/gnu/guix @c The official substitute server used by default. -@set SUBSTITUTE-SERVER ci.guix.info +@set SUBSTITUTE-SERVER ci.guix.gnu.org @set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER} @copying @@ -59,9 +59,11 @@ Copyright @copyright{} 2018 Oleg Pykhalov@* Copyright @copyright{} 2018 Mike Gerwitz@* Copyright @copyright{} 2018 Pierre-Antoine Rouby@* Copyright @copyright{} 2018 Gábor Boskovits@* -Copyright @copyright{} 2018 Florian Pelz@* +Copyright @copyright{} 2018, 2019 Florian Pelz@* Copyright @copyright{} 2018 Laura Lazzati@* Copyright @copyright{} 2018 Alex Vong@* +Copyright @copyright{} 2019 Josh Holland@* +Copyright @copyright{} 2019 Diego Nicola Barbato@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -114,8 +116,9 @@ package management tool written for the GNU system. @c translation. This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN, GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU -Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}), and -Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}). If you +Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}), +Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), and +Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you would like to translate it in your native language, consider joining the @uref{https://translationproject.org/domain/guix-manual.html, Translation Project}. @@ -398,7 +401,7 @@ garbage collection of packages (@pxref{Features}). @cindex Guix System Guix comes with a distribution of the GNU system consisting entirely of free software@footnote{The term ``free'' here refers to the -@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to +@url{https://www.gnu.org/philosophy/free-sw.html,freedom provided to users of that software}.}. The distribution can be installed on its own (@pxref{System Installation}), but it is also possible to install Guix as a package manager on top of @@ -409,7 +412,7 @@ Guix@tie{}System. The distribution provides core GNU packages such as GNU libc, GCC, and Binutils, as well as many GNU and non-GNU applications. The complete list of available packages can be browsed -@url{http://www.gnu.org/software/guix/packages,on-line} or by +@url{https://www.gnu.org/software/guix/packages,on-line} or by running @command{guix package} (@pxref{Invoking guix package}): @example @@ -437,13 +440,13 @@ using the EABI hard-float application binary interface (ABI), and Linux-Libre kernel. @item aarch64-linux -little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is -currently in an experimental stage, with limited support. -@xref{Contributing}, for how to help! +little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. @item mips64el-linux little-endian 64-bit MIPS processors, specifically the Loongson series, -n32 ABI, and Linux-Libre kernel. +n32 ABI, and Linux-Libre kernel. This configuration is no longer fully +supported; in particular, the project's build farms no longer provide +substitutes for this architecture. @end table @@ -620,7 +623,7 @@ with these commands: @c files into place. @c @c See this thread for more information: -@c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html +@c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html @example # cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \ @@ -725,11 +728,11 @@ GNU Guix is available for download from its website at GNU Guix depends on the following packages: @itemize -@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.2.x; +@item @url{https://gnu.org/software/guile/, GNU Guile}, version 2.2.x; @item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version 0.1.0 or later; @item -@uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings +@uref{https://gnutls.org/, GnuTLS}, specifically its Guile bindings (@pxref{Guile Preparations, how to install the GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}); @item @@ -740,8 +743,8 @@ or later; @uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August 2017 or later; @item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}; -@item @url{http://zlib.net, zlib}; -@item @url{http://www.gnu.org/software/make/, GNU Make}. +@item @url{https://zlib.net, zlib}; +@item @url{https://www.gnu.org/software/make/, GNU Make}. @end itemize The following dependencies are optional: @@ -763,9 +766,9 @@ Unless @code{--disable-daemon} was passed to @command{configure}, the following packages are also needed: @itemize -@item @url{http://gnupg.org/, GNU libgcrypt}; -@item @url{http://sqlite.org, SQLite 3}; -@item @url{http://gcc.gnu.org, GCC's g++}, with support for the +@item @url{https://gnupg.org/, GNU libgcrypt}; +@item @url{https://sqlite.org, SQLite 3}; +@item @url{https://gcc.gnu.org, GCC's g++}, with support for the C++11 standard. @end itemize @@ -779,7 +782,7 @@ unintended misconfiguration of @var{localstatedir} so you do not inadvertently corrupt your store (@pxref{The Store}). @cindex Nix, compatibility -When a working installation of @url{http://nixos.org/nix/, the Nix package +When a working installation of @url{https://nixos.org/nix/, the Nix package manager} is available, you can instead configure Guix with @code{--disable-daemon}. In that case, Nix replaces the three dependencies above. @@ -908,7 +911,7 @@ regarded as pure functions (@pxref{Introduction}). On a GNU/Linux system, a build user pool may be created like this (using Bash syntax and the @code{shadow} commands): -@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html +@c See https://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html @c for why `-G' is needed. @example # groupadd --system guixbuild @@ -2074,7 +2077,7 @@ ifconfig -a ip a @end example -@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 +@c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 Wired interfaces have a name starting with @samp{e}; for example, the interface corresponding to the first on-board Ethernet controller is called @samp{eno1}. Wireless interfaces have a name starting with @@ -2398,7 +2401,7 @@ If you'd like to install Guix System in a virtual machine (VM) or on a virtual private server (VPS) rather than on your beloved machine, this section is for you. -To boot a @uref{http://qemu.org/,QEMU} VM for installing Guix System in a +To boot a @uref{https://qemu.org/,QEMU} VM for installing Guix System in a disk image, follow these steps: @enumerate @@ -2461,7 +2464,7 @@ about the installation image. @section Building the Installation Image for ARM Boards Many ARM boards require a specific variant of the -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader. +@uref{https://www.denx.de/wiki/U-Boot/, U-Boot} bootloader. If you build a disk image and the bootloader is not available otherwise (on another boot drive etc), it's advisable to build an image that @@ -4294,9 +4297,9 @@ same format as the @file{signing-key.pub} file. The list of authorized keys is kept in the human-editable file @file{/etc/guix/acl}. The file contains -@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format +@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format s-expressions''} and is structured as an access-control list in the -@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure +@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure (SPKI)}. @item --extract=@var{directory} @@ -4775,7 +4778,7 @@ guix pack -f squashfs guile emacs geiser @noindent The result is a SquashFS file system image that can either be mounted or directly be used as a file system container image with the -@uref{http://singularity.lbl.gov, Singularity container execution +@uref{https://singularity.lbl.gov, Singularity container execution environment}, using commands like @command{singularity shell} or @command{singularity exec}. @@ -4924,6 +4927,12 @@ is an infinity of channel URLs and commit IDs that can lead to the same pack. Recording such ``silent'' metadata in the output thus potentially breaks the source-to-binary bitwise reproducibility property. +@item --root=@var{file} +@itemx -r @var{file} +@cindex garbage collector root, for packs +Make @var{file} a symlink to the resulting pack, and register it as a garbage +collector root. + @item --localstatedir @itemx --profile-name=@var{name} Include the ``local state directory'', @file{/var/guix}, in the resulting @@ -5084,7 +5093,7 @@ package looks like this: (inputs `(("gawk" ,gawk))) (synopsis "Hello, GNU world: An example GNU package") (description "Guess what GNU Hello prints!") - (home-page "http://www.gnu.org/software/hello/") + (home-page "https://www.gnu.org/software/hello/") (license gpl3+))) @end example @@ -5242,8 +5251,7 @@ Return the @code{<derivation>} object of @var{package} cross-built from @var{target} must be a valid GNU triplet denoting the target hardware and operating system, such as @code{"mips64el-linux-gnu"} -(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU -Configure and Build System}). +(@pxref{Specifying Target Triplets,,, autoconf, Autoconf}). @end deffn @cindex package transformations @@ -5674,7 +5682,7 @@ executed. Some of these build systems are listed below. @defvr {Scheme Variable} ant-build-system This variable is exported by @code{(guix build-system ant)}. It implements the build procedure for Java packages that can be built with -@url{http://ant.apache.org/, Ant build tool}. +@url{https://ant.apache.org/, Ant build tool}. It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as provided by the @code{icedtea} package to the set of inputs. Different @@ -5779,7 +5787,7 @@ supports builds of packages using Cargo, the build tool of the @uref{https://www.rust-lang.org, Rust programming language}. In its @code{configure} phase, this build system replaces dependencies -specified in the @file{Carto.toml} file with inputs to the Guix package. +specified in the @file{Cargo.toml} file with inputs to the Guix package. The @code{install} phase installs the binaries, and it also installs the source code and @file{Cargo.toml} file. @end defvr @@ -5844,7 +5852,7 @@ directories specified in @code{#:doc-dirs} are installed as well. @defvr {Scheme Variable} cmake-build-system This variable is exported by @code{(guix build-system cmake)}. It implements the build procedure for packages using the -@url{http://www.cmake.org, CMake build tool}. +@url{https://www.cmake.org, CMake build tool}. It automatically adds the @code{cmake} package to the set of inputs. Which package is used can be specified with the @code{#:cmake} @@ -6060,7 +6068,7 @@ Which Perl package is used can be specified with @code{#:perl}. @defvr {Scheme Variable} r-build-system This variable is exported by @code{(guix build-system r)}. It -implements the build procedure used by @uref{http://r-project.org, R} +implements the build procedure used by @uref{https://r-project.org, R} packages, which essentially is little more than running @code{R CMD INSTALL --library=/gnu/store/@dots{}} in an environment where @code{R_LIBS_SITE} contains the paths to all R package inputs. Tests @@ -6069,7 +6077,7 @@ are run after installation using the R function @end defvr @defvr {Scheme Variable} rakudo-build-system -This variable is exported by @code{(guix build-system rakudo)} It +This variable is exported by @code{(guix build-system rakudo)}. It implements the build procedure used by @uref{https://rakudo.org/, Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the package to @code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and @@ -6201,7 +6209,7 @@ locations in the output directory. @defvr {Scheme Variable} meson-build-system This variable is exported by @code{(guix build-system meson)}. It implements the build procedure for packages that use -@url{http://mesonbuild.com, Meson} as their build system. +@url{https://mesonbuild.com, Meson} as their build system. It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set of inputs, and they can be changed with the parameters @code{#:meson} @@ -8100,7 +8108,7 @@ also be offloaded to a remote machine of the right architecture. @item --target=@var{triplet} @cindex cross-compilation Cross-build for @var{triplet}, which must be a valid GNU triplet, such -as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU +as @code{"mips64el-linux-gnu"} (@pxref{Specifying Target Triplets, GNU configuration triplets,, autoconf, Autoconf}). @anchor{build-check} @@ -8518,7 +8526,7 @@ guix import cpan Acme::Boolean @cindex CRAN @cindex Bioconductor Import metadata from @uref{https://cran.r-project.org/, CRAN}, the -central repository for the @uref{http://r-project.org, GNU@tie{}R +central repository for the @uref{https://r-project.org, GNU@tie{}R statistical and graphical environment}. Information is extracted from the @code{DESCRIPTION} file of the package. @@ -8552,7 +8560,7 @@ guix import cran --archive=bioconductor GenomicRanges @item texlive @cindex TeX Live @cindex CTAN -Import metadata from @uref{http://www.ctan.org/, CTAN}, the +Import metadata from @uref{https://www.ctan.org/, CTAN}, the comprehensive TeX archive network for TeX packages that are part of the @uref{https://www.tug.org/texlive/, TeX Live distribution}. @@ -8631,9 +8639,9 @@ guix import json hello.json @item nix Import metadata from a local copy of the source of the -@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This +@uref{https://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This relies on the @command{nix-instantiate} command of -@uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are +@uref{https://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are typically written in a mixture of Nix-language and Bash code. This command only imports the high-level package structure that is written in the Nix language. It normally includes all the basic fields of a @@ -8755,7 +8763,7 @@ information. Currently the supported repositories and their identifiers are: @itemize - @item -@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu} +@uref{https://elpa.gnu.org/packages, GNU}, selected by the @code{gnu} identifier. This is the default. Packages from @code{elpa.gnu.org} are signed with one of the keys @@ -8765,11 +8773,11 @@ contained in the GnuPG keyring at signatures,, emacs, The GNU Emacs Manual}). @item -@uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the +@uref{https://stable.melpa.org/packages, MELPA-Stable}, selected by the @code{melpa-stable} identifier. @item -@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa} +@uref{https://melpa.org/packages, MELPA}, selected by the @code{melpa} identifier. @end itemize @@ -8935,13 +8943,13 @@ the updater for X.org packages; @item kernel.org the updater for packages hosted on kernel.org; @item elpa -the updater for @uref{http://elpa.gnu.org/, ELPA} packages; +the updater for @uref{https://elpa.gnu.org/, ELPA} packages; @item cran the updater for @uref{https://cran.r-project.org/, CRAN} packages; @item bioconductor the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages; @item cpan -the updater for @uref{http://www.cpan.org/, CPAN} packages; +the updater for @uref{https://www.cpan.org/, CPAN} packages; @item pypi the updater for @uref{https://pypi.python.org, PyPI} packages. @item gem @@ -9179,7 +9187,7 @@ that Guix uses, as in this example: (cpe-version . "2.3"))) @end example -@c See <http://www.openwall.com/lists/oss-security/2017/03/15/3>. +@c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>. Some entries in the CVE database do not specify which version of a package they apply to, and would thus ``stick around'' forever. Package developers who found CVE alerts and verified they can be ignored can @@ -9337,7 +9345,7 @@ For the example above, the map looks like this: produced by @command{guix size}} This option requires that -@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be +@uref{https://wingolog.org/software/guile-charting/, Guile-Charting} be installed and visible in Guile's module search path. When that is not the case, @command{guix size} fails as it tries to load it. @@ -9358,12 +9366,12 @@ directed acyclic graph (DAG). It can quickly become difficult to have a mental model of the package DAG, so the @command{guix graph} command provides a visual representation of the DAG. By default, @command{guix graph} emits a DAG representation in the input format of -@uref{http://www.graphviz.org/, Graphviz}, so its output can be passed +@uref{https://www.graphviz.org/, Graphviz}, so its output can be passed directly to the @command{dot} command of Graphviz. It can also emit an HTML page with embedded JavaScript code to display a ``chord diagram'' in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or emit Cypher queries to construct a graph in a graph database supporting -the @uref{http://www.opencypher.org/, openCypher} query language. +the @uref{https://www.opencypher.org/, openCypher} query language. The general syntax is: @example @@ -10081,8 +10089,17 @@ challenge}, it ignores signatures on those substitutes, which is innocuous since the command only gathers statistics and cannot install those substitutes. -Among other things, it is possible to query specific system types and -specific package sets. The available options are listed below. +The general syntax is: + +@example +guix weather @var{options}@dots{} [@var{packages}@dots{}] +@end example + +When @var{packages} is omitted, @command{guix weather} checks the availability +of substitutes for @emph{all} the packages, or for those specified with +@option{--manifest}; otherwise it only considers the specified packages. It +is also possible to query specific system types with @option{--system}. The +available options are listed below. @table @code @item --substitute-urls=@var{urls} @@ -11320,7 +11337,7 @@ The name of the source for that locale. This is typically the @item @code{charset} (default: @code{"UTF-8"}) The ``character set'' or ``code set'' for that locale, -@uref{http://www.iana.org/assignments/character-sets, as defined by +@uref{https://www.iana.org/assignments/character-sets, as defined by IANA}. @end table @@ -11758,8 +11775,8 @@ interpreted as backspace when the user types their login name. @item @code{kill-characters} (default: @code{#f}) This option accepts a string that should be interpreted to mean "ignore -all previous characters" (also called a "kill" character) when the types -their login name. +all previous characters" (also called a "kill" character) when the user +types their login name. @item @code{chdir} (default: @code{#f}) This option accepts, as a string, a directory path that will be changed @@ -12024,7 +12041,7 @@ A directory path where the @command{guix-daemon} will perform builds. @deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}] Run @var{udev}, which populates the @file{/dev} directory dynamically. udev rules can be provided as a list of files through the @var{rules} -variable. The procedures @var{udev-rule} and @var{file->udev-rule} from +variable. The procedures @code{udev-rule} and @code{file->udev-rule} from @code{(gnu services base)} simplify the creation of such rule files. @end deffn @@ -12498,7 +12515,7 @@ For example: The package that provides the DHCP daemon. This package is expected to provide the daemon at @file{sbin/dhcpd} relative to its output directory. The default package is the -@uref{http://www.isc.org/products/DHCP, ISC's DHCP server}. +@uref{https://www.isc.org/products/DHCP, ISC's DHCP server}. @item @code{config-file} (default: @code{#f}) The configuration file to use. This is required. It will be passed to @code{dhcpd} via its @code{-cf} option. This may be any ``file-like'' @@ -12806,7 +12823,7 @@ A list of local IP addresses or hostnames the ntpd daemon should listen on. A list of local IP address the ntpd daemon should use for outgoing queries. @item @code{sensor} (default: @code{'()}) Specify a list of timedelta sensor devices ntpd should use. @code{ntpd} -will listen to each sensor that acutally exists and ignore non-existant ones. +will listen to each sensor that actually exists and ignore non-existent ones. See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more information. @item @code{server} (default: @var{%ntp-servers}) @@ -12997,7 +13014,8 @@ so anyone (or just yourself) can download existing files or upload new files. @deffn {Scheme Variable} rsync-service-type -This is the type for the @uref{https://rsync.samba.org, rsync} rsync daemon, +This is the service type for the @uref{https://rsync.samba.org, rsync} daemon, +The value for this service type is a @command{rsync-configuration} record as in this example: @example @@ -13347,7 +13365,7 @@ The @code{(gnu services avahi)} provides the following definition. @defvr {Scheme Variable} avahi-service-type This is the service that runs @command{avahi-daemon}, a system-wide mDNS/DNS-SD responder that allows for service discovery and -``zero-configuration'' host name lookups (see @uref{http://avahi.org/}). +``zero-configuration'' host name lookups (see @uref{https://avahi.org/}). Its value must be a @code{zero-configuration} record---see below. This service extends the name service cache daemon (nscd) so that it can @@ -13394,7 +13412,7 @@ This is a list of domains to browse. @end deftp @deffn {Scheme Variable} openvswitch-service-type -This is the type of the @uref{http://www.openvswitch.org, Open vSwitch} +This is the type of the @uref{https://www.openvswitch.org, Open vSwitch} service, whose value should be an @code{openvswitch-configuration} object. @end deffn @@ -13485,6 +13503,33 @@ This is the type for the SLiM graphical login manager for X11. Like GDM, SLiM looks for session types described by @file{.desktop} files and allows users to choose a session from the log-in screen using @kbd{F1}. It also honors @file{~/.xsession} files. + +Unlike GDM, SLiM does not spawn the user session on a different VT after +logging in, which means that you can only start one graphical session. If you +want to be able to run multiple graphical sessions at the same time you have +to add multiple SLiM services to your system services. The following example +shows how to replace the default GDM service with two SLiM services on tty7 +and tty8. + +@lisp +(use-modules (gnu services) + (gnu services desktop) + (gnu services xorg) + (srfi srfi-1)) ;for 'remove' + +(operating-system + ;; ... + (services (cons* (service slim-service-type (slim-configuration + (display ":0") + (vt "vt7"))) + (service slim-service-type (slim-configuration + (display ":1") + (vt "vt8"))) + (remove (lambda (service) + (eq? (service-kind service) gdm-service-type)) + %desktop-services)))) +@end lisp + @end defvr @deftp {Data Type} slim-configuration @@ -13522,6 +13567,12 @@ false, you will be unable to log in. @item @code{xorg-configuration} (default @code{(xorg-configuration)}) Configuration of the Xorg graphical server. +@item @code{display} (default @code{":0"}) +The display on which to start the Xorg graphical server. + +@item @code{vt} (default @code{"vt7"}) +The VT on which to start the Xorg graphical server. + @item @code{xauth} (default: @code{xauth}) The XAuth package to use. @@ -13696,7 +13747,7 @@ default is @code{-nolisten tcp}. @deffn {Scheme Procedure} set-xorg-configuration @var{config} @ [@var{login-manager-service-type}] Tell the log-in manager (of type @var{login-manager-service-type}) to use -@var{config}, an <xorg-configuration> record. +@var{config}, an @code{<xorg-configuration>} record. Since the Xorg configuration is embedded in the log-in manager's configuration---e.g., @code{gdm-configuration}---this procedure provides a @@ -13832,7 +13883,7 @@ Defaults to @samp{"0640"}. @deftypevr {@code{files-configuration} parameter} log-location error-log Defines the error log filename. Specifying a blank filename disables -access log generation. The value @code{stderr} causes log entries to be +error log generation. The value @code{stderr} causes log entries to be sent to the standard error file when the scheduler is running in the foreground, or to the system log daemon when run in the background. The value @code{syslog} causes log entries to be sent to the system log @@ -13897,7 +13948,7 @@ Defaults to @samp{"0644"}. @deftypevr {@code{files-configuration} parameter} log-location page-log Defines the page log filename. Specifying a blank filename disables -access log generation. The value @code{stderr} causes log entries to be +page log generation. The value @code{stderr} causes log entries to be sent to the standard error file when the scheduler is running in the foreground, or to the system log daemon when run in the background. The value @code{syslog} causes log entries to be sent to the system log @@ -14585,13 +14636,14 @@ adds or adjusts services for a typical ``desktop'' setup. In particular, it adds a graphical login manager (@pxref{X Window, @code{gdm-service-type}}), screen lockers, a network management tool -(@pxref{Networking Services, @code{network-manager-service-type}}), energy and color -management services, the @code{elogind} login and seat manager, the -Polkit privilege service, the GeoClue location service, the -AccountsService daemon that allows authorized users change system -passwords, an NTP client (@pxref{Networking Services}), the Avahi -daemon, and has the name service switch service configured to be able to -use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}). +(@pxref{Networking Services, @code{network-manager-service-type}}) with modem +support (@pxref{Networking Services, @code{modem-manager-service-type}}), +energy and color management services, the @code{elogind} login and seat +manager, the Polkit privilege service, the GeoClue location service, the +AccountsService daemon that allows authorized users change system passwords, +an NTP client (@pxref{Networking Services}), the Avahi daemon, and has the +name service switch service configured to be able to use @code{nss-mdns} +(@pxref{Name Service Switch, mDNS}). @end defvr The @var{%desktop-services} variable can be used as the @code{services} @@ -14643,7 +14695,7 @@ polkit with the actions from @code{gnome-settings-daemon}. Configuration record for the GNOME desktop environment. @table @asis -@item @code{gnome} (default @code{gnome}) +@item @code{gnome} (default: @code{gnome}) The GNOME package to use. @end table @end deftp @@ -14653,7 +14705,7 @@ This is the type of a service to run the @uref{Xfce, https://xfce.org/} desktop environment. Its value is an @code{xfce-desktop-configuration} object (see below.) -This service that adds the @code{xfce} package to the system profile, and +This service adds the @code{xfce} package to the system profile, and extends polkit with the ability for @code{thunar} to manipulate the file system as root from within a user session, after the user has authenticated with the administrator's password. @@ -14663,7 +14715,7 @@ with the administrator's password. Configuration record for the Xfce desktop environment. @table @asis -@item @code{xfce} (default @code{xfce}) +@item @code{xfce} (default: @code{xfce}) The Xfce package to use. @end table @end deftp @@ -14682,7 +14734,7 @@ profile, and extends polkit with the actions from Configuration record for the MATE desktop environment. @table @asis -@item @code{mate} (default @code{mate}) +@item @code{mate} (default: @code{mate}) The MATE package to use. @end table @end deftp @@ -14694,7 +14746,7 @@ profile, and extends dbus with actions from @code{efl}. @deftp {Data Type} enlightenment-desktop-service-configuration @table @asis -@item @code{enlightenment} (default @code{enlightenment}) +@item @code{enlightenment} (default: @code{enlightenment}) The enlightenment package to use. @end table @end deftp @@ -14728,7 +14780,7 @@ are described below. Return a service that runs the ``system bus'', using @var{dbus}, with support for @var{services}. -@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication +@uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process communication facility. Its system bus is used to allow system services to communicate and to be notified of system-wide events. @@ -14824,7 +14876,7 @@ package to expose as a service. @deffn {Scheme Procedure} polkit-service @ [#:polkit @var{polkit}] Return a service that runs the -@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege +@uref{https://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege management service}, which allows system administrators to grant access to privileged operations in a structured way. By querying the Polkit service, a privileged system component can know when it should grant additional @@ -14833,7 +14885,7 @@ the capability to suspend the system if the user is logged in locally. @end deffn @defvr {Scheme Variable} upower-service-type -Service that runs @uref{http://upower.freedesktop.org/, @command{upowerd}}, a +Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a system-wide monitor for power consumption and battery levels, with the given configuration settings. @@ -14907,7 +14959,7 @@ Possible values are: @end deftp @deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}] -Return a service for @uref{http://udisks.freedesktop.org/docs/latest/, +Return a service for @uref{https://udisks.freedesktop.org/docs/latest/, UDisks}, a @dfn{disk management} daemon that provides user interfaces with notifications and ways to mount/unmount disks. Programs that talk to UDisks include the @command{udisksctl} command, part of UDisks, and GNOME Disks. @@ -14917,7 +14969,7 @@ include the @command{udisksctl} command, part of UDisks, and GNOME Disks. Return a service that runs @command{colord}, a system service with a D-Bus interface to manage the color profiles of input and output devices such as screens and scanners. It is notably used by the GNOME Color Manager graphical -tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web +tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web site} for more information. @end deffn @@ -15845,13 +15897,13 @@ failed. Defaults to @samp{#f}. @end deftypevr -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords? +@deftypevr {@code{dovecot-configuration} parameter} string auth-verbose-passwords In case of password mismatches, log the attempted password. Valid values are no, plain and sha1. sha1 can be useful for detecting brute force password attempts vs. user simply trying the same password over and over again. You can also truncate the value to n chars by appending ":n" (e.g.@: sha1:6). -Defaults to @samp{#f}. +Defaults to @samp{"no"}. @end deftypevr @deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug? @@ -17139,11 +17191,11 @@ string, you could instantiate a prosody service like this: @cindex IRC (Internet Relay Chat) @cindex IRC gateway -@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC +@url{https://bitlbee.org,BitlBee} is a gateway that provides an IRC interface to a variety of messaging protocols such as XMPP. @defvr {Scheme Variable} bitlbee-service-type -This is the service type for the @url{http://bitlbee.org,BitlBee} IRC +This is the service type for the @url{https://bitlbee.org,BitlBee} IRC gateway daemon. Its value is a @code{bitlbee-configuration} (see below). @@ -17312,7 +17364,7 @@ Maximum size in bytes that a user can send in one text chat message. Maximum size in bytes that a user can send in one image message. @item @code{cert-required?} (default: @code{#f}) -If it is set to @code{#t} clients that use weak password authentification +If it is set to @code{#t} clients that use weak password authentication will not be accepted. Users must have completed the certificate wizard to join. @item @code{remember-channel?} (default: @code{#f}) @@ -17975,7 +18027,7 @@ specified by clients; The @code{krb5-realm} and @code{krb5-configuration} types have many fields. Only the most commonly used ones are described here. For a full list, and more detailed explanation of each, see the MIT -@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf} +@uref{https://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf} documentation. @@ -18034,7 +18086,7 @@ A service type for the Kerberos 5 PAM module. @end defvr @deftp {Data Type} pam-krb5-configuration -Data type representing the configuration of the Kerberos 5 PAM module +Data type representing the configuration of the Kerberos 5 PAM module. This type has the following parameters: @table @asis @item @code{pam-krb5} (default: @code{pam-krb5}) @@ -20120,7 +20172,7 @@ Defaults to @samp{()}. The @code{(gnu services vpn)} module provides services related to @dfn{virtual private networks} (VPNs). It provides a @emph{client} service for -your machine to connect to a VPN, and a @emph{servire} service for your machine +your machine to connect to a VPN, and a @emph{server} service for your machine to host a VPN. Both services use @uref{https://openvpn.net/, OpenVPN}. @deffn {Scheme Procedure} openvpn-client-service @ @@ -20717,7 +20769,7 @@ TLP enables various powersaving modes in userspace and kernel. Contrary to @code{upower-service}, it is not a passive, monitoring tool, as it will apply custom settings each time a new power source is detected. More information can be found at -@uref{http://linrunner.de/en/tlp/tlp.html, TLP home page}. +@uref{https://linrunner.de/en/tlp/tlp.html, TLP home page}. @deffn {Scheme Variable} tlp-service-type The service type for the TLP tool. Its value should be a valid @@ -21717,7 +21769,7 @@ Defaults to @samp{"3:remote 4:event"}. @deftypevr {@code{libvirt-configuration} parameter} string log-outputs Logging outputs. -An output is one of the places to save logging information The format +An output is one of the places to save logging information. The format for an output can be: @table @code @@ -23186,7 +23238,7 @@ could instantiate a cgit service like this: @cindex Gitolite service @cindex Git, hosting -@uref{http://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git +@uref{https://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git repositories on a central server. Gitolite can handle multiple repositories and users, and supports flexible @@ -23412,7 +23464,7 @@ passed to @command{lircd}. The @code{(gnu services spice)} module provides the following service. @deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent] -Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a daemon +Returns a service that runs @url{https://www.spice-space.org,VDAGENT}, a daemon that enables sharing the clipboard with a vm and setting the guest display resolution when the graphical console window resizes. @end deffn @@ -23550,7 +23602,7 @@ The @code{(gnu services docker)} module provides the following service. @defvr {Scheme Variable} docker-service-type -This is the type of the service that runs @url{http://www.docker.com,Docker}, +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. @@ -24036,7 +24088,7 @@ in ``legacy'' BIOS mode. Available bootloaders are described in @code{(gnu bootloader @dots{})} modules. In particular, @code{(gnu bootloader u-boot)} contains definitions of bootloaders for a wide range of ARM and AArch64 systems, using the -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot bootloader}. +@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}. @item @code{target} This is a string denoting the target onto which to install the @@ -24267,7 +24319,7 @@ an older system generation at boot time should you need it. @quotation Note @c The paragraph below refers to the problem discussed at -@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>. +@c <https://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>. It is highly recommended to run @command{guix pull} once before you run @command{guix system reconfigure} for the first time (@pxref{Invoking guix pull}). Failing to do that you would see an older version of Guix @@ -24463,20 +24515,26 @@ system configuration file. You can then load the image and launch a Docker container using commands like the following: @example -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 +image_id="`docker load < guix-system-docker-image.tar.gz`" +container_id="`docker create $image_id`" +docker start $container_id @end example This command starts a new Docker container from the specified image. It will boot the Guix system in the usual manner, which means it will start any services you have defined in the operating system -configuration. Depending on what you run in the Docker container, it +configuration. You can get an interactive shell running in the container +using @command{docker exec}: + +@example +docker exec -ti $container_id /run/current-system/profile/bin/bash --login +@end example + +Depending on what you run in the Docker container, it may be necessary to give the container additional permissions. For example, if you intend to build software using Guix inside of the Docker container, you may need to pass the @option{--privileged} option to -@code{docker run}. +@code{docker create}. @item container Return a script to run the operating system declared in @var{file} @@ -24551,6 +24609,11 @@ When this option is omitted, @command{guix system} computes an estimate of the image size as a function of the size of the system declared in @var{file}. +@item --network +@itemx -N +For the @code{container} action, allow containers to access the host network, +that is, do not create a network namespace. + @item --root=@var{file} @itemx -r @var{file} Make @var{file} a symlink to the result, and register it as a garbage @@ -24649,7 +24712,7 @@ example graph. @cindex virtual machine To run Guix in a virtual machine (VM), one can use the pre-built Guix VM image distributed at -@indicateurl{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.@var{system}.xz} +@url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.xz}. This image is a compressed image in QCOW format. You will first need to decompress with @command{xz -d}, and then you can pass it to an emulator such as QEMU (see below for details). @@ -24663,7 +24726,7 @@ as @file{/etc/config.scm} (@pxref{Using the Configuration System}). Instead of using this pre-built image, one can also 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 efficiently use. +@uref{https://qemu.org/, QEMU emulator} can efficiently use. @cindex QEMU If you built your own image, you must copy it out of the store @@ -25245,7 +25308,7 @@ These are the names that may be passed to @command{herd start}, shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the @code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details. -@item @code{requirements} (default: @code{'()}) +@item @code{requirement} (default: @code{'()}) List of symbols denoting the Shepherd services this one depends on. @cindex one-shot services, for the Shepherd @@ -25277,6 +25340,10 @@ This is a list of @code{shepherd-action} objects (see below) defining herd @var{action} @var{service} [@var{arguments}@dots{}] @end example +@item @code{auto-start?} (default: @code{#t}) +Whether this service should be started automatically by the Shepherd. If it +is @code{#f} the service has to be started manually with @code{herd start}. + @item @code{documentation} A documentation string, as shown when running: @@ -25798,7 +25865,7 @@ approximation, we will consider it final.}, depicted below. @image{images/bootstrap-packages,6in,,Dependency graph of the early packages} -@c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>. +@c See <https://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>. The first tool that gets built with the bootstrap binaries is GNU@tie{}Make---noted @code{make-boot0} above---which is a prerequisite for all the following packages. From there Findutils and Diffutils get @@ -25934,7 +26001,7 @@ reason. @node Acknowledgments @chapter Acknowledgments -Guix is based on the @uref{http://nixos.org/nix/, Nix package manager}, +Guix is based on the @uref{https://nixos.org/nix/, Nix package manager}, which was designed and implemented by Eelco Dolstra, with contributions from other people (see the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package |