@set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER}
@copying
-Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès@*
+Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
Copyright @copyright{} 2013 Nikita Karetnikov@*
Copyright @copyright{} 2014, 2015, 2016 Alex Kost@*
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
Copyright @copyright{} 2015, 2016, 2017, 2019 Leo Famulari@*
-Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo Wurmus@*
+Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
Copyright @copyright{} 2016, 2017, 2018, 2019 Efraim Flashner@*
Copyright @copyright{} 2016 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2016, 2017, 2018, 2019 Christopher Baines@*
-Copyright @copyright{} 2017, 2018 Clément Lassieur@*
+Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@*
Copyright @copyright{} 2017, 2018 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017 Christopher Allan Webber@*
-Copyright @copyright{} 2017, 2018 Marius Bakke@*
-Copyright @copyright{} 2017 Hartmut Goebel@*
+Copyright @copyright{} 2017, 2018, 2019 Marius Bakke@*
+Copyright @copyright{} 2017, 2019 Hartmut Goebel@*
Copyright @copyright{} 2017, 2019 Maxim Cournoyer@*
-Copyright @copyright{} 2017, 2018, 2019 Tobias Geerinckx-Rice@*
+Copyright @copyright{} 2017, 2018, 2019, 2020 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
Copyright @copyright{} 2017, 2018, 2019 Arun Isaac@*
Copyright @copyright{} 2019 Diego Nicola Barbato@*
Copyright @copyright{} 2019 Ivan Petkov@*
Copyright @copyright{} 2019 Jakob L. Kreuze@*
+Copyright @copyright{} 2019 Kyle Andrews@*
+Copyright @copyright{} 2019 Alex Griffin@*
+Copyright @copyright{} 2019 Guillaume Le Vaillant@*
+Copyright @copyright{} 2020 Leo Prikler@*
+Copyright @copyright{} 2019, 2020 Simon Tournier@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
* Channels:: Customizing the package collection.
+* Invoking guix time-machine:: Running an older revision of Guix.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
* Invoking guix archive:: Exporting and importing store files.
* Virtualization Services:: Virtualization services.
* Version Control Services:: Providing remote access to Git repositories.
* Game Services:: Game servers.
+* PAM Mount Service:: Service to mount volumes when logging in.
* Miscellaneous Services:: Other services.
Defining Services
be sure to specify the same state directory as the existing installation
using the @code{--localstatedir} option of the @command{configure}
script (@pxref{Directory Variables, @code{localstatedir},, standards,
-GNU Coding Standards}). The @command{configure} script protects against
-unintended misconfiguration of @var{localstatedir} so you do not
+GNU Coding Standards}). Usually, this @var{localstatedir} option is
+set to the value @file{/var}. The @command{configure} script protects
+against unintended misconfiguration of @var{localstatedir} so you do not
inadvertently corrupt your store (@pxref{The Store}).
@node Running the Test Suite
@command{lsh-export-key} (@pxref{Converting keys,,, lsh, LSH Manual}):
@example
-$ lsh-export-key --openssh < /etc/lsh/host-key.pub
+$ lsh-export-key --openssh < /etc/lsh/host-key.pub
ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{}
@end example
This means that substitutes may be downloaded from @var{urls}, as long
as they are signed by a trusted signature (@pxref{Substitutes}).
-@cindex build hook
-@item --no-build-hook
-Do not use the @dfn{build hook}.
-
-The build hook is a helper program that the daemon can start and to
-which it submits build requests. This mechanism is used to offload
-builds to other machines (@pxref{Daemon Offload Setup}).
+@cindex offloading
+@item --no-offload
+Do not use offload builds to other machines (@pxref{Daemon Offload
+Setup}). That is, always build things locally instead of offloading
+builds to remote machines.
@item --cache-failures
Cache build failures. By default, only successful builds are cached.
@dots{} or, using the GNU/Linux-specific @command{ip} command:
@example
-ip a
+ip address
@end example
@c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
ifconfig @var{interface} up
@end example
+@noindent
+@dots{} or, using the GNU/Linux-specific @command{ip} command:
+
+@example
+ip link set @var{interface} up
+@end example
+
@item Wireless connection
@cindex wireless
@cindex WiFi
Once you are done partitioning the target hard disk drive, you have to
create a file system on the relevant partition(s)@footnote{Currently
-Guix System only supports ext4 and btrfs file systems. In particular, code
-that reads file system UUIDs and labels only works for these file system
+Guix System only supports ext4, btrfs, and JFS file systems. In particular,
+code that reads file system UUIDs and labels only works for these file system
types.}. For the ESP, if you have one and assuming it is
@file{/dev/sda1}, run:
@example
qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
- -net user -net nic,model=virtio -boot menu=on,order=d \
+ -nic user,model=virtio-net-pci -boot menu=on,order=d \
-drive file=guix-system.img \
-drive media=cdrom,file=guix-system-install-@value{VERSION}.@var{system}.iso
@end example
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
* Channels:: Customizing the package collection.
+* Invoking guix time-machine:: Running an older revision of Guix.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
* Invoking guix archive:: Exporting and importing store files.
@cindex profile declaration
@cindex profile manifest
Create a new generation of the profile from the manifest object
-returned by the Scheme code in @var{file}.
+returned by the Scheme code in @var{file}. This option can be repeated
+several times, in which case the manifests are concatenated.
This allows you to @emph{declare} the profile's contents rather than
constructing it through a sequence of @code{--install} and similar
@uref{https://git-scm.com, Git} repository, by default the official
GNU@tie{}Guix repository, though this can be customized.
+Specifically, @command{guix pull} downloads code from the @dfn{channels}
+(@pxref{Channels}) specified by one of the followings, in this order:
+
+@enumerate
+@item
+the @option{--channels} option;
+@item
+the user's @file{~/.config/guix/channels.scm} file;
+@item
+the system-wide @file{/etc/guix/channels.scm} file;
+@item
+the built-in default channels specified in the @code{%default-channels}
+variable.
+@end enumerate
+
On completion, @command{guix package} will use packages and package
versions from this just-retrieved copy of Guix. Not only that, but all
the Guix commands and Scheme modules will also be taken from that latest
@item --channels=@var{file}
@itemx -C @var{file}
Read the list of channels from @var{file} instead of
-@file{~/.config/guix/channels.scm}. @var{file} must contain Scheme code that
+@file{~/.config/guix/channels.scm} or @file{/etc/guix/channels.scm}.
+@var{file} must contain Scheme code that
evaluates to a list of channel objects. @xref{Channels}, for more
information.
@end lisp
The @command{guix describe --format=channels} command can even generate this
-list of channels directly (@pxref{Invoking guix describe}).
+list of channels directly (@pxref{Invoking guix describe}). The resulting
+file can be used with the -C options of @command{guix pull}
+(@pxref{Invoking guix pull}) or @command{guix time-machine}
+(@pxref{Invoking guix time-machine}).
At this point the two machines run the @emph{exact same Guix}, with access to
the @emph{exact same packages}. The output of @command{guix build gimp} on
will---some sort of ``meta reproducibility'' capabilities, if you will.
@xref{Inferiors}, for another way to take advantage of these super powers.
+@node Invoking guix time-machine
+@section Invoking @command{guix time-machine}
+
+@cindex @command{guix time-machine}
+@cindex pinning, channels
+@cindex replicating Guix
+@cindex reproducibility, of Guix
+
+The @command{guix time-machine} command provides access to other
+revisions of Guix, for example to install older versions of packages,
+or to reproduce a computation in an identical environment. The revision
+of Guix to be used is defined by a commit or by a channel
+description file created by @command{guix describe}
+(@pxref{Invoking guix describe}).
+
+The general syntax is:
+
+@example
+guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
+@end example
+
+where @var{command} and @var{arg}@dots{} are passed unmodified to the
+@command{guix} command if the specified revision. The @var{options} that define
+this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
+
+@table @code
+@item --url=@var{url}
+@itemx --commit=@var{commit}
+@itemx --branch=@var{branch}
+Use the @code{guix} channel from the specified @var{url}, at the
+given @var{commit} (a valid Git commit ID represented as a hexadecimal
+string), or @var{branch}.
+
+@item --channels=@var{file}
+@itemx -C @var{file}
+Read the list of channels from @var{file}. @var{file} must contain
+Scheme code that evaluates to a list of channel objects.
+@xref{Channels} for more information.
+@end table
+
+As for @command{guix pull}, the absence of any options means that the
+the latest commit on the master branch will be used. The command
+
+@example
+guix time-machine -- build hello
+@end example
+
+will thus build the package @code{hello} as defined in the master branch,
+which is in general a newer revison of Guix than you have installed.
+Time travel works in both directions!
+
+Note that @command{guix time-machine} can trigger builds of channels and
+their dependencies, and these are controlled by the standard build
+options (@pxref{Common Build Options}).
+
@node Inferiors
@section Inferiors
The primary purpose of this operation is to facilitate inspection of
archive contents coming from possibly untrusted substitute servers.
+@item --list
+@itemx -t
+Read a single-item archive as served by substitute servers
+(@pxref{Substitutes}) and print the list of files it contains, as in
+this example:
+
+@example
+$ wget -O - \
+ https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \
+ | lzip -d | guix archive -t
+@end example
+
@end table
@item --manifest=@var{file}
@itemx -m @var{file}
Create an environment for the packages contained in the manifest object
-returned by the Scheme code in @var{file}.
+returned by the Scheme code in @var{file}. This option can be repeated
+several times, in which case the manifests are concatenated.
This is similar to the same-named option in @command{guix package}
(@pxref{profile-manifest, @option{--manifest}}) and uses the same
command:
@example
-guix pack -f squashfs guile emacs geiser
+guix pack -f squashfs bash guile emacs geiser
@end example
@noindent
This produces a SquashFS image containing all the specified binaries and
symlinks, as well as empty mount points for virtual file systems like
procfs.
+
+@quotation Note
+Singularity @emph{requires} you to provide @file{/bin/sh} in the image.
+For that reason, @command{guix pack -f squashfs} always implies @code{-S
+/bin=bin}. Thus, your @command{guix pack} invocation must always start
+with something like:
+
+@example
+guix pack -f squashfs bash @dots{}
+@end example
+
+If you forget the @code{bash} (or similar) package, @command{singularity
+run} and @command{singularity exec} will fail with an unhelpful ``no
+such file or directory'' message.
+@end quotation
@end table
@cindex relocatable binaries
@item --manifest=@var{file}
@itemx -m @var{file}
Use the packages contained in the manifest object returned by the Scheme
-code in @var{file}.
+code in @var{file}. This option can be repeated several times, in which
+case the manifests are concatenated.
This has a similar purpose as the same-named option in @command{guix
package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
One use case for this is the Guix self-contained binary tarball
(@pxref{Binary Installation}).
+@item --derivation
+@itemx -d
+Print the name of the derivation that builds the pack.
+
@item --bootstrap
Use the bootstrap binaries to build the pack. This option is only
useful to Guix developers.
archive. In this case the parameter @code{#:source-dir} can be used to
specify the source sub-directory, defaulting to ``src''.
-The @code{#:main-class} parameter can be used with the minimal ant
-buildfile to specify the main class of the resulting jar. This makes the
-jar file executable. The @code{#:test-include} parameter can be used to
+The @code{#:main-class} parameter can be used with the minimal ant
+buildfile to specify the main class of the resulting jar. This makes the
+jar file executable. The @code{#:test-include} parameter can be used to
specify the list of junit tests to run. It defaults to
@code{(list "**/*Test.java")}. The @code{#:test-exclude} can be used to
disable some tests. It defaults to @code{(list "**/Abstract*.java")},
Which Perl package is used can be specified with @code{#:perl}.
@end defvr
+@defvr {Scheme Variable} qt-build-system
+This variable is exported by @code{(guix build-system qt)}. It
+is intended for use with applications using Qt or KDE.
+
+This build system adds the phase @code{qt-wrap} to the ones defined by
+@var{cmake-build-system}, after the @code{install} phase.
+
+This phase searches for Qt5 plugin paths, QML paths and some XDG in the inputs
+and output. In case some path is found, all programs in the output's
+@file{bin/}, @file{sbin/}, @file{libexec/} and @file{lib/libexec/} directories
+are wrapped in scripts defining the necessary environment variables.
+
+It is possible to exclude specific package outputs from that wrapping process
+by listing their names in the @code{#:qt-wrap-excluded-outputs} parameter.
+This is useful when an output is known not to contain any Qt binaries, and
+where wrapping would gratuitously add a dependency of that output on Qt, KDE,
+or such.
+@end defvr
+
@defvr {Scheme Variable} r-build-system
This variable is exported by @code{(guix build-system r)}. It
implements the build procedure used by @uref{https://r-project.org, R}
(gexp->derivation "vi"
#~(begin
(mkdir #$output)
+ (mkdir (string-append #$output "/bin"))
(system* (string-append #+coreutils "/bin/ln")
"-s"
(string-append #$emacs "/bin/emacs")
@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
[#:recursive? #f] [#:select? (const #t)]
-Return an object representing local file @var{file} to add to the store; this
-object can be used in a gexp. If @var{file} is a relative file name, it is looked
-up relative to the source file where this form appears. @var{file} will be added to
-the store under @var{name}--by default the base name of @var{file}.
+Return an object representing local file @var{file} to add to the store;
+this object can be used in a gexp. If @var{file} is a literal string
+denoting a relative file name, it is looked up relative to the source
+file where it appears; if @var{file} is not a literal string, it is
+looked up relative to the current working directory at run time.
+@var{file} will be added to the store under @var{name}--by default the
+base name of @var{file}.
When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
designates a flat file and @var{recursive?} is true, its contents are added, and its
@xref{Debugging Build Failures}, for tips and tricks on how to debug
build issues.
-This option has no effect when connecting to a remote daemon with a
-@code{guix://} URI (@pxref{The Store, the @code{GUIX_DAEMON_SOCKET}
-variable}).
+This option implies @option{--no-offload}, and it has no effect when
+connecting to a remote daemon with a @code{guix://} URI (@pxref{The
+Store, the @code{GUIX_DAEMON_SOCKET} variable}).
@item --keep-going
@itemx -k
(@pxref{Invoking guix archive}), then rebuilding, and finally comparing
the two results.
-@item --no-build-hook
-Do not attempt to offload builds @i{via} the ``build hook'' of the daemon
-(@pxref{Daemon Offload Setup}). That is, always build things locally
-instead of offloading builds to remote machines.
+@item --no-offload
+Do not use offload builds to other machines (@pxref{Daemon Offload
+Setup}). That is, always build things locally instead of offloading
+builds to remote machines.
@item --max-silent-time=@var{seconds}
When the build or substitution process remains silent for more than
code snippets specified in the package @code{origin} (@pxref{Defining
Packages}).
+Note that @command{guix build -S} compiles the sources only of the
+specified packages. They do not include the sources of statically
+linked dependencies and by themselves are insufficient for reproducing
+the packages.
+
@item --sources
Fetch and return the source of @var{package-or-derivation} and all their
dependencies, recursively. This is a handy way to obtain a local copy
recipes. In other cases, you will be able to examine the read-only recipes
for packages currently in the store.
+Instead of @code{GUIX_PACKAGE_PATH}, the command-line option
+@code{--load-path=@var{directory}} (or in short @code{-L
+@var{directory}}) allows you to add @var{directory} to the front of the
+package module search path and so make your own packages visible.
@node Invoking guix download
@section Invoking @command{guix download}
@item --key-server=@var{host}
Use @var{host} as the OpenPGP key server when importing a public key.
+@item --load-path=@var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tools.
+
@end table
The @code{github} updater uses the
Only enable the checkers specified in a comma-separated list using the
names returned by @code{--list-checkers}.
+@item --load-path=@var{directory}
+@itemx -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tools.
+
@end table
@node Invoking guix size
@itemx -s @var{system}
Consider packages for @var{system}---e.g., @code{x86_64-linux}.
+@item --load-path=@var{directory}
+@itemx -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tools.
@end table
@node Invoking guix graph
The package dependency graph is largely architecture-independent, but there
are some architecture-dependent bits that this option allows you to visualize.
+
+@item --load-path=@var{directory}
+@itemx -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tools.
@end table
+On top of that, @command{guix graph} supports all the usual package
+transformation options (@pxref{Package Transformation Options}). This
+makes it easy to view the effect of a graph-rewriting transformation
+such as @option{--with-input}. For example, the command below outputs
+the graph of @code{git} once @code{openssl} has been replaced by
+@code{libressl} everywhere in the graph:
+
+@example
+guix graph git --with-input=openssl=libressl
+@end example
+So many possibilities, so much fun!
@node Invoking guix publish
@section Invoking @command{guix publish}
@code{guix-publish-service-type}}).
If you are instead running Guix on a ``foreign distro'', follow these
-instructions:”
+instructions:
@itemize
@item
local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
+ differing files:
+ /lib/libcrypto.so.1.1
+ /lib/libssl.so.1.1
+
/gnu/store/@dots{}-git-2.5.0 contents differ:
local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
+ differing file:
+ /libexec/git-core/git-fsck
+
/gnu/store/@dots{}-pius-2.1.1 contents differ:
local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
+ differing file:
+ /share/man/man1/pius.1.gz
@dots{}
by inode number. See @uref{https://reproducible-builds.org/docs/}, for
more information.
-To find out what is wrong with this Git binary, we can do something along
-these lines (@pxref{Invoking guix archive}):
+To find out what is wrong with this Git binary, the easiest approach is
+to run:
+
+@example
+guix challenge git \
+ --diff=diffoscope \
+ --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org"
+@end example
+
+This automatically invokes @command{diffoscope}, which displays detailed
+information about files that differ.
+
+Alternately, we can do something along these lines (@pxref{Invoking guix
+archive}):
@example
$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \
Consider @var{urls} the whitespace-separated list of substitute source
URLs to compare to.
+@item --diff=@var{mode}
+Upon mismatches, show differences according to @var{mode}, one of:
+
+@table @asis
+@item @code{simple} (the default)
+Show the list of files that differ.
+
+@item @code{diffoscope}
+@itemx @var{command}
+Invoke @uref{https://diffoscope.org/, Diffoscope}, passing it
+two directories whose contents do not match.
+
+When @var{command} is an absolute file name, run @var{command} instead
+of Diffoscope.
+
+@item @code{none}
+Do not show further details about the differences.
+@end table
+
+Thus, unless @code{--diff=none} is passed, @command{guix challenge}
+downloads the store items from the given substitute servers so that it
+can compare them.
+
@item --verbose
@itemx -v
Show details about matches (identical contents) in addition to
ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
@end example
-
@node System Configuration
@chapter System Configuration
This is a list of symbols denoting mount flags. Recognized flags
include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
access to special files), @code{no-suid} (ignore setuid and setgid
-bits), @code{no-atime} (do not update file access times), and @code{no-exec}
-(disallow program execution). @xref{Mount-Unmount-Remount,,, libc, The GNU C
-Library Reference Manual}, for more information on these flags.
+bits), @code{no-atime} (do not update file access times),
+@code{strict-atime} (update file access time), @code{lazy-time} (only
+update time on the in-memory version of the file inode), and
+@code{no-exec} (disallow program execution).
+@xref{Mount-Unmount-Remount,,, libc, The GNU C Library Reference
+Manual}, for more information on these flags.
@item @code{options} (default: @code{#f})
This is either @code{#f}, or a string denoting mount options passed to the
* Virtualization Services:: Virtualization services.
* Version Control Services:: Providing remote access to Git repositories.
* Game Services:: Game servers.
+* PAM Mount Service:: Service to mount volumes when logging in.
* Guix Services:: Services relating specifically to Guix.
* Miscellaneous Services:: Other services.
@end menu
@end table
@end deftp
+@defvr {Scheme Variable} pagekite-service-type
+This is the service type for the @uref{https://pagekite.net, PageKite} service,
+a tunneling solution for making localhost servers publicly visible, even from
+behind restrictive firewalls or NAT without forwarded ports. The value for
+this service type is a @code{pagekite-configuration} record.
+
+Here's an example exposing the local HTTP and SSH daemons:
+
+@lisp
+(service pagekite-service-type
+ (pagekite-configuration
+ (kites '("http:@@kitename:localhost:80:@@kitesecret"
+ "raw/22:@@kitename:localhost:22:@@kitesecret"))
+ (extra-file "/etc/pagekite.rc")))
+@end lisp
+@end defvr
+
+@deftp {Data Type} pagekite-configuration
+Data type representing the configuration of PageKite.
+
+@table @asis
+@item @code{package} (default: @var{pagekite})
+Package object of PageKite.
+
+@item @code{kitename} (default: @code{#f})
+PageKite name for authenticating to the frontend server.
+
+@item @code{kitesecret} (default: @code{#f})
+Shared secret for authenticating to the frontend server. You should probably
+put this inside @code{extra-file} instead.
+
+@item @code{frontend} (default: @code{#f})
+Connect to the named PageKite frontend server instead of the
+@uref{https://pagekite.net,,pagekite.net} service.
+
+@item @code{kites} (default: @code{'("http:@@kitename:localhost:80:@@kitesecret")})
+List of service kites to use. Exposes HTTP on port 80 by default. The format
+is @code{proto:kitename:host:port:secret}.
+
+@item @code{extra-file} (default: @code{#f})
+Extra configuration file to read, which you are expected to create manually.
+Use this to add additional options and manage shared secrets out-of-band.
+
+@end table
+@end deftp
+
@node X Window
@subsection X Window
When @code{auto-login?} is true, GDM logs in directly as
@code{default-user}.
+@item @code{debug?} (default: @code{#f})
+When true, GDM writes debug messages to its log.
+
@item @code{gnome-shell-assets} (default: ...)
List of GNOME Shell assets needed by GDM: icon theme, fonts, etc.
the capability to suspend the system if the user is logged in locally.
@end deffn
+@defvr {Scheme Variable} polkit-wheel-service
+Service that adds the @code{wheel} group as admins to the Polkit
+service. This makes it so that users in the @code{wheel} group are queried
+for their own passwords when performing administrative actions instead of
+@code{root}'s, similar to the behaviour used by @code{sudo}.
+@end defvr
+
@defvr {Scheme Variable} upower-service-type
Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a
system-wide monitor for power consumption and battery levels, with the given
include the @command{udisksctl} command, part of UDisks, and GNOME Disks.
@end deffn
-@deffn {Scheme Procedure} colord-service [#:colord @var{colord}]
-Return a service that runs @command{colord}, a system service with a D-Bus
+@deffn {Scheme Variable} colord-service-type
+This is the type of the 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{https://www.freedesktop.org/software/colord/, the colord web
Users need to be in the @code{lp} group to access the D-Bus service.
@end deffn
+@defvr {Scheme Variable} gnome-keyring-service-type
+This is the type of the service that adds the
+@uref{https://wiki.gnome.org/Projects/GnomeKeyring, GNOME Keyring}. Its
+value is a @code{gnome-keyring-configuration} object (see below.)
+
+This service adds the @code{gnome-keyring} package to the system profile
+and extends PAM with entries using @code{pam_gnome_keyring.so}, unlocking
+a user's login keyring when they log in or setting its password with passwd.
+@end defvr
+
+@deftp {Data Type} gnome-keyring-configuration
+Configuration record for the GNOME Keyring service.
+
+@table @asis
+@item @code{keyring} (default: @code{gnome-keyring})
+The GNOME keyring package to use.
+
+@item @code{pam-services}
+A list of @code{(@var{service} . @var{kind})} pairs denoting PAM
+services to extend, where @var{service} is the name of an existing
+service to extend and @var{kind} is one of @code{login} or
+@code{passwd}.
+
+If @code{login} is given, it adds an optional
+@code{pam_gnome_keyring.so} to the auth block without arguments and to
+the session block with @code{auto_start}. If @code{passwd} is given, it
+adds an optional @code{pam_gnome_keyring.so} to the password block
+without arguments.
+
+By default, this field contains ``gdm-password'' with the value @code{login}
+and ``passwd'' is with the value @code{passwd}.
+@end table
+@end deftp
+
+
@node Sound Services
@subsection Sound Services
See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the
details.
+@deffn {Scheme Variable} pulseaudio-service-type
+This is the type for the @uref{http://www.pulseaudio.org/, PulseAudio}
+sound server. It exists to allow system overrides of the default settings
+via @code{pulseaudio-configuration}, see below.
+
+@quotation Warning
+This service on its own does not ensure, that the @code{pulseaudio} package
+exists on your machine. It merely adds configuration files for it, as
+detailed below. In the (admittedly unlikely) case, that you find yourself
+without a @code{pulseaudio} package, consider enabling it through the
+@code{alsa-service-type} above.
+@end quotation
+@end deffn
+
+@deftp {Data Type} pulseaudio-configuration
+Data type representing the configuration for @code{pulseaudio-service}.
+
+@table @asis
+@item @var{client-conf} (default: @code{'()})
+List of settings to set in @file{client.conf}.
+Accepts a list of strings or a symbol-value pairs. A string will be
+inserted as-is with a newline added. A pair will be formatted as
+``key = value'', again with a newline added.
+
+@item @var{daemon-conf} (default: @code{'((flat-volumes . no))})
+List of settings to set in @file{daemon.conf}, formatted just like
+@var{client-conf}.
+
+@item @var{script-file} (default: @code{(file-append pulseaudio "/etc/pulse/default.pa")})
+Script file to use as as @file{default.pa}.
+
+@item @var{system-script-file} (default: @code{(file-append pulseaudio "/etc/pulse/system.pa")})
+Script file to use as as @file{system.pa}.
+@end table
+@end deftp
+
+@deffn {Scheme Variable} ladspa-service-type
+This service sets the @var{LADSPA_PATH} variable, so that programs, which
+respect it, e.g. PulseAudio, can load LADSPA plugins.
+
+The following example will setup the service to enable modules from the
+@code{swh-plugins} package:
+
+@lisp
+(service ladspa-service-type
+ (ladspa-configuration (plugins (list swh-plugins))))
+@end lisp
+
+See @uref{http://plugin.org.uk/ladspa-swh/docs/ladspa-swh.html} for the
+details.
+
+@end deffn
@node Database Services
@subsection Database Services
connect; when it is @code{0.0.0.0}, connections can come from any
networking interface.
-@item @code{package} (default: @code{bitlbee})
+@item @code{bitlbee} (default: @code{bitlbee})
The BitlBee package to use.
@item @code{plugins} (default: @code{'()})
@item @code{server-names-hash-bucket-max-size} (default: @code{#f})
Maximum bucket size for the server names hash tables.
+@item @code{modules} (default: @code{'()})
+List of nginx dynamic modules to load. This should be a list of file
+names of loadable modules, as in this example:
+
+@lisp
+(modules
+ (list
+ (file-append nginx-accept-language-module "\
+/etc/nginx/modules/ngx_http_accept_language_module.so")))
+@end lisp
+
@item @code{extra-content} (default: @code{""})
Extra content for the @code{http} block. Should be string or a string
valued G-expression.
@end table
@end deftp
+@subsubheading Mumi
+
+@cindex Mumi, Debbugs Web interface
+@cindex Debbugs, Mumi Web interface
+@uref{https://git.elephly.net/gitweb.cgi?p=software/mumi.git, Mumi} is a
+Web interface to the Debbugs bug tracker, by default for
+@uref{https://bugs.gnu.org, the GNU instance}. Mumi is a Web server,
+but it also fetches and indexes mail retrieved from Debbugs.
+
+@defvr {Scheme Variable} mumi-service-type
+This is the service type for Mumi.
+@end defvr
+
@subsubheading FastCGI
@cindex fastcgi
@cindex fcgiwrap
It is possible to configure a FastCGI-backed web service to pass HTTP
authentication information from the front-end to the back-end, and to
allow @code{fcgiwrap} to run the back-end process as a corresponding
-local user. To enable this capability on the back-end., run
+local user. To enable this capability on the back-end, run
@code{fcgiwrap} as the @code{root} user and group. Note that this
capability also has to be configured on the front-end as well.
@end table
Group of the worker processes.
@item @code{socket-user} (default: @code{php-fpm})
User who can speak to the php-fpm socket.
-@item @code{socket-group} (default: @code{php-fpm})
+@item @code{socket-group} (default: @code{nginx})
Group that can speak to the php-fpm socket.
@item @code{pid-file} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")})
The process id of the php-fpm process is written to this file
Log for the php-fpm master process.
@item @code{process-manager} (default: @code{(php-fpm-dynamic-process-manager-configuration)})
Detailed settings for the php-fpm process manager.
-Must be either:
+Must be one of:
@table @asis
@item @code{<php-fpm-dynamic-process-manager-configuration>}
@item @code{<php-fpm-static-process-manager-configuration>}
@end table
@end deftp
+@subsubheading Knot Resolver Service
+
+@deffn {Scheme Variable} knot-resolver-service-type
+This this the type of the knot resolver service, whose value should be
+an @code{knot-resolver-configuration} object as in this example:
+
+@lisp
+(service knot-resolver-service-type
+ (knot-resolver-configuration
+ (kresd-config-file (plain-file "kresd.conf" "
+net.listen('192.168.0.1', 5353)
+user('knot-resolver', 'knot-resolver')
+modules = @{ 'hints > iterate', 'stats', 'predict' @}
+cache.size = 100 * MB
+"))))
+@end lisp
+
+For more information, refer its @url{https://knot-resolver.readthedocs.org/en/stable/daemon.html#configuration, manual}.
+@end deffn
+
+@deftp {Data Type} knot-resolver-configuration
+Data type representing the configuration of knot-resolver.
+
+@table @asis
+@item @code{package} (default: @var{knot-resolver})
+Package object of the knot DNS resolver.
+
+@item @code{kresd-config-file} (default: %kresd.conf)
+File-like object of the kresd configuration file to use, by default it
+will listen on @code{127.0.0.1} and @code{::1}.
+
+@item @code{garbage-collection-interval} (default: 1000)
+Number of milliseconds for @code{kres-cache-gc} to periodically trim the cache.
+
+@end table
+@end deftp
+
+
@subsubheading Dnsmasq Service
@deffn {Scheme Variable} dnsmasq-service-type
which are most commonly used in relation to mounting or exporting
directory trees as @dfn{network file systems} (NFS).
+While it is possible to use the individual components that together make
+up a Network File System service, we recommended to configure an NFS
+server with the @code{nfs-service-type}.
+
+@subsubheading NFS Service
+@cindex NFS, server
+
+The NFS service takes care of setting up all NFS component services,
+kernel configuration file systems, and installs configuration files in
+the locations that NFS expects.
+
+@defvr {Scheme Variable} nfs-service-type
+A service type for a complete NFS server.
+@end defvr
+
+@deftp {Data Type} nfs-configuration
+This data type represents the configuration of the NFS service and all
+of its subsystems.
+
+It has the following parameters:
+@table @asis
+@item @code{nfs-utils} (default: @code{nfs-utils})
+The nfs-utils package to use.
+
+@item @code{nfs-version} (default: @code{#f})
+If a string value is provided, the @command{rpc.nfsd} daemon will be
+limited to supporting the given version of the NFS protocol.
+
+@item @code{exports} (default: @code{'()})
+This is a list of directories the NFS server should export. Each entry
+is a list consisting of two elements: a directory name and a string
+containing all options. This is an example in which the directory
+@file{/export} is served to all NFS clients as a read-only share:
+
+@lisp
+(nfs-configuration
+ (exports
+ '(("/export"
+ "*(ro,insecure,no_subtree_check,crossmnt,fsid=0)"))))
+@end lisp
+
+@item @code{rpcmountd-port} (default: @code{#f})
+The network port that the @command{rpc.mountd} daemon should use.
+
+@item @code{rpcstatd-port} (default: @code{#f})
+The network port that the @command{rpc.statd} daemon should use.
+
+@item @code{rpcbind} (default: @code{rpcbind})
+The rpcbind package to use.
+
+@item @code{idmap-domain} (default: @code{"localdomain"})
+The local NFSv4 domain name.
+
+@item @code{nfsd-port} (default: @code{2049})
+The network port that the @command{nfsd} daemon should use.
+
+@item @code{nfsd-threads} (default: @code{8})
+The number of threads used by the @command{nfsd} daemon.
+
+@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
+The directory where the pipefs file system is mounted.
+
+@item @code{debug} (default: @code{'()"})
+A list of subsystems for which debugging output should be enabled. This
+is a list of symbols. Any of these symbols are valid: @code{nfsd},
+@code{nfs}, @code{rpc}, @code{idmap}, @code{statd}, or @code{mountd}.
+@end table
+@end deftp
+
+If you don't need a complete NFS service or prefer to build it yourself
+you can use the individual component services that are documented below.
+
@subsubheading RPC Bind Service
@cindex rpcbind
This must be a string or @code{#f}.
If it is @code{#f} then the daemon will use the host's fully qualified domain name.
+@item @code{verbosity} (default: @code{0})
+The verbosity level of the daemon.
+
@end table
@end deftp
The address that mpd will bind to. To use a Unix domain socket,
an absolute path can be specified here.
+@item @code{outputs} (default: @code{"(list (mpd-output))"})
+The audio outputs that MPD can use. By default this is a single output using pulseaudio.
+
+@end table
+@end deftp
+
+@deftp {Data Type} mpd-output
+Data type representing an @command{mpd} audio output.
+
+@table @asis
+@item @code{name} (default: @code{"MPD"})
+The name of the audio output.
+
+@item @code{type} (default: @code{"pulse"})
+The type of audio output.
+
+@item @code{enabled?} (default: @code{#t})
+Specifies whether this audio output is enabled when MPD is started. By
+default, all audio outputs are enabled. This is just the default
+setting when there is no state file; with a state file, the previous
+state is restored.
+
+@item @code{tags?} (default: @code{#t})
+If set to @code{#f}, then MPD will not send tags to this output. This
+is only useful for output plugins that can receive tags, for example the
+@code{httpd} output plugin.
+
+@item @code{always-on?} (default: @code{#f})
+If set to @code{#t}, then MPD attempts to keep this audio output always
+open. This may be useful for streaming servers, when you don’t want to
+disconnect all listeners even when playback is accidentally stopped.
+
+@item @code{mixer-type}
+This field accepts a symbol that specifies which mixer should be used
+for this audio output: the @code{hardware} mixer, the @code{software}
+mixer, the @code{null} mixer (allows setting the volume, but with no
+effect; this can be used as a trick to implement an external mixer
+External Mixer) or no mixer (@code{none}).
+
+@item @code{extra-options} (default: @code{'()"})
+An association list of option symbols to string values to be appended to
+the audio output configuration.
+
@end table
@end deftp
+The following example shows a configuration of @code{mpd} that provides
+an HTTP audio streaming output.
+
+@lisp
+(service mpd-service-type
+ (mpd-configuration
+ (outputs
+ (list (mpd-output
+ (name "streaming")
+ (type "httpd")
+ (mixer-type 'null)
+ (extra-options
+ `((encoder . "vorbis")
+ (port . "8080"))))))))
+@end lisp
+
+
@node Virtualization Services
@subsection Virtualization services
@end deftp
+@node PAM Mount Service
+@subsection PAM Mount Service
+@cindex pam-mount
+
+The @code{(gnu services pam-mount)} module provides a service allowing
+users to mount volumes when they log in. It should be able to mount any
+volume format supported by the system.
+
+@defvar {Scheme Variable} pam-mount-service-type
+Service type for PAM Mount support.
+@end defvar
+
+@deftp {Data Type} pam-mount-configuration
+Data type representing the configuration of PAM Mount.
+
+It takes the following parameters:
+
+@table @asis
+@item @code{rules}
+The configuration rules that will be used to generate
+@file{/etc/security/pam_mount.conf.xml}.
+
+The configuration rules are SXML elements (@pxref{SXML,,, guile, GNU
+Guile Reference Manual}), and the the default ones don't mount anything
+for anyone at login:
+
+@lisp
+`((debug (@@ (enable "0")))
+ (mntoptions (@@ (allow ,(string-join
+ '("nosuid" "nodev" "loop"
+ "encryption" "fsck" "nonempty"
+ "allow_root" "allow_other")
+ ","))))
+ (mntoptions (@@ (require "nosuid,nodev")))
+ (logout (@@ (wait "0")
+ (hup "0")
+ (term "no")
+ (kill "no")))
+ (mkmountpoint (@@ (enable "1")
+ (remove "true"))))
+@end lisp
+
+Some @code{volume} elements must be added to automatically mount volumes
+at login. Here's an example allowing the user @code{alice} to mount her
+encrypted @code{HOME} directory and allowing the user @code{bob} to mount
+the partition where he stores his data:
+
+@lisp
+(define pam-mount-rules
+`((debug (@@ (enable "0")))
+ (volume (@@ (user "alice")
+ (fstype "crypt")
+ (path "/dev/sda2")
+ (mountpoint "/home/alice")))
+ (volume (@@ (user "bob")
+ (fstype "auto")
+ (path "/dev/sdb3")
+ (mountpoint "/home/bob/data")
+ (options "defaults,autodefrag,compress")))
+ (mntoptions (@@ (allow ,(string-join
+ '("nosuid" "nodev" "loop"
+ "encryption" "fsck" "nonempty"
+ "allow_root" "allow_other")
+ ","))))
+ (mntoptions (@@ (require "nosuid,nodev")))
+ (logout (@@ (wait "0")
+ (hup "0")
+ (term "no")
+ (kill "no")))
+ (mkmountpoint (@@ (enable "1")
+ (remove "true")))))
+
+(service pam-mount-service-type
+ (pam-mount-configuration
+ (rules pam-mount-rules)))
+@end lisp
+
+The complete list of possible options can be found in the man page for
+@uref{http://pam-mount.sourceforge.net/pam_mount.conf.5.html, pam_mount.conf}.
+@end table
+@end deftp
+
+
@node Guix Services
@subsection Guix Services
Display available service type definitions that match the given regular
expressions, sorted by relevance:
+@cindex HDPI
+@cindex HiDPI
+@cindex resolution
@example
-$ guix system search console font
+$ guix system search console
name: console-fonts
-location: gnu/services/base.scm:729:2
+location: gnu/services/base.scm:806:2
extends: shepherd-root
-description: Install the given fonts on the specified ttys (fonts are
-+ per virtual console on GNU/Linux). The value of this service is a list
-+ of tty/font pairs like:
-+
-+ '(("tty1" . "LatGrkCyr-8x16"))
-relevance: 20
+description: Install the given fonts on the specified ttys (fonts are per
++ virtual console on GNU/Linux). The value of this service is a list of
++ tty/font pairs. The font can be the name of a font provided by the `kbd'
++ package or any valid argument to `setfont', as in this example:
++
++ '(("tty1" . "LatGrkCyr-8x16")
++ ("tty2" . (file-append
++ font-tamzen
++ "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
++ ("tty3" . (file-append
++ font-terminus
++ "/share/consolefonts/ter-132n"))) ; for HDPI
+relevance: 9
name: mingetty
-location: gnu/services/base.scm:1048:2
+location: gnu/services/base.scm:1190:2
extends: shepherd-root
description: Provide console login using the `mingetty' program.
relevance: 2
name: login
-location: gnu/services/base.scm:775:2
+location: gnu/services/base.scm:860:2
extends: pam
description: Provide a console log-in service as specified by its
+ configuration value, a `login-configuration' object.
@code{switch-generation} and @code{roll-back}) are usable only on
systems already running Guix System.}.
+@quotation Note
+@c The paragraph below refers to the problem discussed at
+@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
+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.
The command starts system services specified in @var{file} that are not
entries for older configurations to a submenu, allowing you to choose
an older system generation at boot time should you need it.
-@quotation Note
-@c The paragraph below refers to the problem discussed at
-@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
-once @command{reconfigure} has completed.
-@end quotation
+@cindex provenance tracking, of the operating system
+Upon completion, the new system is deployed under
+@file{/run/current-system}. This directory contains @dfn{provenance
+meta-data}: the list of channels in use (@pxref{Channels}) and
+@var{file} itself, when available. This information is useful should
+you later want to inspect how this particular generation was built.
+
+In fact, assuming @var{file} is self-contained, you can later rebuild
+generation @var{n} of your operating system with:
+
+@example
+guix time-machine \
+ -C /var/guix/profiles/system-@var{n}-link/channels.scm -- \
+ system reconfigure \
+ /var/guix/profiles/system-@var{n}-link/configuration.scm
+@end example
+
+You can think of it as some sort of built-in version control! Your
+system is not just a binary artifact: @emph{it carries its own source}.
+@xref{Service Reference, @code{provenance-service-type}}, for more
+information on provenance tracking.
@item switch-generation
@cindex generations
emulated machine:
@example
-$ /gnu/store/@dots{}-run-vm.sh -m 1024 -net user
+$ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -net user,model=virtio-net-pci
@end example
The VM shares its store with the host system.
Return the derivation file name of the given operating system without
building anything.
+@cindex provenance tracking, of the operating system
+@item --save-provenance
+As discussed above, @command{guix system init} and @command{guix system
+reconfigure} always save provenance information @i{via} a dedicated
+service (@pxref{Service Reference, @code{provenance-service-type}}).
+However, other commands don't do that by default. If you wish to, say,
+create a virtual machine image that contains provenance information, you
+can run:
+
+@example
+guix system vm-image --save-provenance config.scm
+@end example
+
+That way, the resulting image will effectively ``embed its own source''
+in the form of meta-data in @file{/run/current-system}. With that
+information, one can rebuild the image to make sure it really contains
+what it pretends to contain; or they could use that to derive a variant
+of the image.
+
@item --file-system-type=@var{type}
@itemx -t @var{type}
For the @code{disk-image} action, create a file system of the given
@table @code
+@item describe
+Describe the current system generation: its file name, the kernel and
+bootloader used, etc., as well as provenance information when available.
+
@item list-generations
List a summary of each generation of the operating system available on
disk, in a human-readable way. This is similar to the
@item @code{build-locally?} (default: @code{#t})
If false, system derivations will be built on the machine being deployed to.
@item @code{system}
-The Nix system type describing the architecture of the machine being deployed
-to. This should look something like ``x86_64-linux''.
+The system type describing the architecture of the machine being deployed
+to---e.g., @code{"x86_64-linux"}.
@item @code{authorize?} (default: @code{#t})
If true, the coordinator's signing key will be added to the remote's ACL
keyring.
@item @code{identity} (default: @code{#f})
If specified, the path to the SSH private key to use to authenticate with the
remote host.
+
+@item @code{host-key} (default: @code{#f})
+This should be the SSH host key of the machine, which looks like this:
+
+@example
+ssh-ed25519 AAAAC3Nz@dots{} root@@example.org
+@end example
+
+When @code{host-key} is @code{#f}, the server is authenticated against
+the @file{~/.ssh/known_hosts} file, just like the OpenSSH @command{ssh}
+client does.
+
@end table
@end deftp
@example
$ qemu-system-x86_64 \
- -net user -net nic,model=virtio \
+ -nic user,model=virtio-net-pci \
-enable-kvm -m 1024 \
-device virtio-blk,drive=myhd \
-drive if=none,file=/tmp/qemu-image,id=myhd
This specifies the hardware platform to emulate. This should match the
host.
-@item -net user
+@item -nic user,model=virtio-net-pci
Enable the unprivileged user-mode network stack. The guest OS can
access the host but not vice versa. This is the simplest way to get the
-guest OS online.
-
-@item -net nic,model=virtio
-You must create a network interface of a given model. If you do not
-create a NIC, the boot will fail. Assuming your hardware platform is
+guest OS online. @code{model} specifies which network device to emulate:
+@code{virtio-net-pci} is a special device made for virtualized operating
+systems and recommended for most uses. Assuming your hardware platform is
x86_64, you can get a list of available NIC models by running
-@command{qemu-system-x86_64 -net nic,model=help}.
+@command{qemu-system-x86_64 -nic model=help}.
@item -enable-kvm
If your system has hardware virtualization extensions, enabling the
@end table
The default @command{run-vm.sh} script that is returned by an invocation of
-@command{guix system vm} does not add a @command{-net user} flag by default.
+@command{guix system vm} does not add a @command{-nic user} flag by default.
To get network access from within the vm add the @code{(dhcp-client-service)}
to your system definition and start the VM using
-@command{`guix system vm config.scm` -net user}. An important caveat of using
-@command{-net user} for networking is that @command{ping} will not work, because
+@command{`guix system vm config.scm` -nic user}. An important caveat of using
+@command{-nic user} for networking is that @command{ping} will not work, because
it uses the ICMP protocol. You'll have to use a different command to check for
network connectivity, for example @command{guix download}.
22 by default, to the host. You can do this with
@example
-`guix system vm config.scm` -net user,hostfwd=tcp::10022-:22
+`guix system vm config.scm` -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
@end example
To connect to the VM you can run
extend it by passing it lists of packages to add to the system profile.
@end defvr
+@cindex provenance tracking, of the operating system
+@defvr {Scheme Variable} provenance-service-type
+This is the type of the service that records @dfn{provenance meta-data}
+in the system itself. It creates several files under
+@file{/run/current-system}:
+
+@table @file
+@item channels.scm
+This is a ``channel file'' that can be passed to @command{guix pull -C}
+or @command{guix time-machine -C}, and which describes the channels used
+to build the system, if that information was available
+(@pxref{Channels}).
+
+@item configuration.scm
+This is the file that was passed as the value for this
+@code{provenance-service-type} service. By default, @command{guix
+system reconfigure} automatically passes the OS configuration file it
+received on the command line.
+
+@item provenance
+This contains the same information as the two other files but in a
+format that is more readily processable.
+@end table
+
+In general, these two pieces of information (channels and configuration
+file) are enough to reproduce the operating system ``from source''.
+
+@quotation Caveats
+This information is necessary to rebuild your operating system, but it
+is not always sufficient. In particular, @file{configuration.scm}
+itself is insufficient if it is not self-contained---if it refers to
+external Guile modules or to extra files. If you want
+@file{configuration.scm} to be self-contained, we recommend that modules
+or files it refers to be part of a channel.
+
+Besides, provenance meta-data is ``silent'' in the sense that it does
+not change the bits contained in your system, @emph{except for the
+meta-data bits themselves}. Two different OS configurations or sets of
+channels can lead to the same system, bit-for-bit; when
+@code{provenance-service-type} is used, these two systems will have
+different meta-data and thus different store file names, which makes
+comparison less trivial.
+@end quotation
+
+This service is automatically added to your operating system
+configuration when you use @command{guix system reconfigure},
+@command{guix system init}, or @command{guix deploy}.
+@end defvr
@node Shepherd Services
@subsection Shepherd Services
HCoop / jackhill / guix / guix.git / blobdiff