Newer
Older
@example
guix graph -t references `readlink -f ~/.guix-profile`
@end example
@item referrers
This is the graph of the @dfn{referrers} of a store item, as returned by
@command{guix gc --referrers} (@pxref{Invoking guix gc}).
This relies exclusively on local information from your store. For
instance, let us suppose that the current Inkscape is available in 10
profiles on your machine; @command{guix graph -t referrers inkscape}
will show a graph rooted at Inkscape and with those 10 profiles linked
to it.
It can help determine what is preventing a store item from being garbage
collected.
The available options are the following:
@table @option
@item --type=@var{type}
@itemx -t @var{type}
Produce a graph output of @var{type}, where @var{type} must be one of
the values listed above.
@item --list-types
List the supported graph types.
@item --backend=@var{backend}
@itemx -b @var{backend}
Produce a graph using the selected @var{backend}.
@item --list-backends
List the supported graph backends.
Currently, the available backends are Graphviz and d3.js.
@item --expression=@var{expr}
@itemx -e @var{expr}
Consider the package @var{expr} evaluates to.
This is useful to precisely refer to a package, as in this example:
@example
guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
@end example
@item --system=@var{system}
@itemx -s @var{system}
Display the graph for @var{system}---e.g., @code{i686-linux}.
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}
@cindex @command{guix publish}
The purpose of @command{guix publish} is to enable users to easily share
their store with others, who can then use it as a substitute server
(@pxref{Substitutes}).
When @command{guix publish} runs, it spawns an HTTP server which allows
anyone with network access to obtain substitutes from it. This means
that any machine running Guix can also act as if it were a build farm,
since the HTTP interface is compatible with Cuirass, the software behind
the @code{@value{SUBSTITUTE-SERVER}} build farm.
For security, each substitute is signed, allowing recipients to check
their authenticity and integrity (@pxref{Substitutes}). Because
@command{guix publish} uses the signing key of the system, which is only
readable by the system administrator, it must be started as root; the
@code{--user} option makes it drop root privileges early on.
The signing key pair must be generated before @command{guix publish} is
launched, using @command{guix archive --generate-key} (@pxref{Invoking
guix archive}).
The general syntax is:
guix publish @var{options}@dots{}
Running @command{guix publish} without any additional arguments will
spawn an HTTP server on port 8080:
guix publish
Once a publishing server has been authorized (@pxref{Invoking guix
archive}), the daemon may download substitutes from it:
@example
guix-daemon --substitute-urls=http://example.org:8080
@end example
By default, @command{guix publish} compresses archives on the fly as it
serves them. This ``on-the-fly'' mode is convenient in that it requires
no setup and is immediately available. However, when serving lots of
clients, we recommend using the @option{--cache} option, which enables
caching of the archives before they are sent to clients---see below for
details. The @command{guix weather} command provides a handy way to
check what a server provides (@pxref{Invoking guix weather}).
As a bonus, @command{guix publish} also serves as a content-addressed
mirror for source files referenced in @code{origin} records
(@pxref{origin Reference}). For instance, assuming @command{guix
publish} is running on @code{example.org}, the following URL returns the
raw @file{hello-2.10.tar.gz} file with the given SHA256 hash
(represented in @code{nix-base32} format, @pxref{Invoking guix hash}):
@example
http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i
@end example
Obviously, these URLs only work for files that are in the store; in
other cases, they return 404 (``Not Found'').
@cindex build logs, publication
Build logs are available from @code{/log} URLs like:
@example
http://example.org/log/gwspk@dots{}-guile-2.2.3
@end example
@noindent
When @command{guix-daemon} is configured to save compressed build logs,
as is the case by default (@pxref{Invoking guix-daemon}), @code{/log}
URLs return the compressed log as-is, with an appropriate
@code{Content-Type} and/or @code{Content-Encoding} header. We recommend
running @command{guix-daemon} with @code{--log-compression=gzip} since
Web browsers can automatically decompress it, which is not the case with
bzip2 compression.
The following options are available:
@table @code
@item --port=@var{port}
@itemx -p @var{port}
Listen for HTTP requests on @var{port}.
@item --listen=@var{host}
Listen on the network interface for @var{host}. The default is to
accept connections from any interface.
@item --user=@var{user}
@itemx -u @var{user}
Change privileges to @var{user} as soon as possible---i.e., once the
server socket is open and the signing key has been read.
@item --compression[=@var{method}[:@var{level}]]
@itemx -C [@var{method}[:@var{level}]]
Compress data using the given @var{method} and @var{level}. @var{method} is
one of @code{lzip} and @code{gzip}; when @var{method} is omitted, @code{gzip}
is used.
When @var{level} is zero, disable compression. The range 1 to 9 corresponds
to different compression levels: 1 is the fastest, and 9 is the best
(CPU-intensive). The default is 3.
Usually, @code{lzip} compresses noticeably better than @code{gzip} for a small
increase in CPU usage; see
@uref{https://nongnu.org/lzip/lzip_benchmark.html,benchmarks on the lzip Web
page}.
Unless @option{--cache} is used, compression occurs on the fly and
the compressed streams are not
cached. Thus, to reduce load on the machine that runs @command{guix
publish}, it may be a good idea to choose a low compression level, to
run @command{guix publish} behind a caching proxy, or to use
@option{--cache}. Using @option{--cache} has the advantage that it
allows @command{guix publish} to add @code{Content-Length} HTTP header
to its responses.
This option can be repeated, in which case every substitute gets compressed
using all the selected methods, and all of them are advertised. This is
useful when users may not support all the compression methods: they can select
the one they support.
@item --cache=@var{directory}
@itemx -c @var{directory}
Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory}
and only serve archives that are in cache.
When this option is omitted, archives and meta-data are created
on-the-fly. This can reduce the available bandwidth, especially when
compression is enabled, since this may become CPU-bound. Another
drawback of the default mode is that the length of archives is not known
in advance, so @command{guix publish} does not add a
@code{Content-Length} HTTP header to its responses, which in turn
prevents clients from knowing the amount of data being downloaded.
Conversely, when @option{--cache} is used, the first request for a store
item (@i{via} a @code{.narinfo} URL) returns 404 and triggers a
background process to @dfn{bake} the archive---computing its
@code{.narinfo} and compressing the archive, if needed. Once the
archive is cached in @var{directory}, subsequent requests succeed and
are served directly from the cache, which guarantees that clients get
the best possible bandwidth.
The ``baking'' process is performed by worker threads. By default, one
thread per CPU core is created, but this can be customized. See
@option{--workers} below.
When @option{--ttl} is used, cached entries are automatically deleted
when they have expired.
@item --workers=@var{N}
When @option{--cache} is used, request the allocation of @var{N} worker
threads to ``bake'' archives.
@item --ttl=@var{ttl}
Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
(TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5
days, @code{1m} means 1 month, and so on.
This allows the user's Guix to keep substitute information in cache for
@var{ttl}. However, note that @code{guix publish} does not itself
guarantee that the store items it provides will indeed remain available
for as long as @var{ttl}.
Additionally, when @option{--cache} is used, cached entries that have
not been accessed for @var{ttl} and that no longer have a corresponding
item in the store, may be deleted.
@item --nar-path=@var{path}
Use @var{path} as the prefix for the URLs of ``nar'' files
(@pxref{Invoking guix archive, normalized archives}).
By default, nars are served at a URL such as
@code{/nar/gzip/@dots{}-coreutils-8.25}. This option allows you to
change the @code{/nar} part to @var{path}.
@item --public-key=@var{file}
@itemx --private-key=@var{file}
Use the specific @var{file}s as the public/private key pair used to sign
the store items being published.
The files must correspond to the same key pair (the private key is used
for signing and the public key is merely advertised in the signature
metadata). They must contain keys in the canonical s-expression format
as produced by @command{guix archive --generate-key} (@pxref{Invoking
guix archive}). By default, @file{/etc/guix/signing-key.pub} and
@file{/etc/guix/signing-key.sec} are used.
@item --repl[=@var{port}]
@itemx -r [@var{port}]
Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
Reference Manual}) on @var{port} (37146 by default). This is used
primarily for debugging a running @command{guix publish} server.
@end table
Enabling @command{guix publish} on Guix System is a one-liner: just
instantiate a @code{guix-publish-service-type} service in the @code{services} field
of the @code{operating-system} declaration (@pxref{guix-publish-service-type,
@code{guix-publish-service-type}}).
If you are instead running Guix on a ``foreign distro'', follow these
@itemize
@item
If your host distro uses the systemd init system:
# ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
/etc/systemd/system/
# systemctl start guix-publish && systemctl enable guix-publish
@end example
@item
If your host distro uses the Upstart init system:
# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
# start guix-publish
@end example
@item
Otherwise, proceed similarly with your distro's init system.
@end itemize
@node Invoking guix challenge
@section Invoking @command{guix challenge}
@cindex reproducible builds
@cindex verifiable builds
@cindex @command{guix challenge}
@cindex challenge
Do the binaries provided by this server really correspond to the source
code it claims to build? Is a package build process deterministic?
These are the questions the @command{guix challenge} command attempts to
answer.
The former is obviously an important question: Before using a substitute
server (@pxref{Substitutes}), one had better @emph{verify} that it
provides the right binaries, and thus @emph{challenge} it. The latter
is what enables the former: If package builds are deterministic, then
independent builds of the package should yield the exact same result,
bit for bit; if a server provides a binary different from the one
obtained locally, it may be either corrupt or malicious.
We know that the hash that shows up in @file{/gnu/store} file names is
the hash of all the inputs of the process that built the file or
directory---compilers, libraries, build scripts,
etc. (@pxref{Introduction}). Assuming deterministic build processes,
one store file name should map to exactly one build output.
@command{guix challenge} checks whether there is, indeed, a single
mapping by comparing the build outputs of several independent builds of
any given store item.
The command output looks like this:
@smallexample
$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org"
updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 100.0%
updating list of substitutes from 'https://guix.example.org'... 100.0%
/gnu/store/@dots{}-openssl-1.0.2d contents differ:
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
6,406 store items were analyzed:
- 4,749 (74.1%) were identical
- 525 (8.2%) differed
- 1,132 (17.7%) were inconclusive
@end smallexample
@noindent
In this example, @command{guix challenge} first scans the store to
determine the set of locally-built derivations---as opposed to store
items that were downloaded from a substitute server---and then queries
all the substitute servers. It then reports those store items for which
the servers obtained a result different from the local build.
@cindex non-determinism, in package builds
As an example, @code{guix.example.org} always gets a different answer.
Conversely, @code{@value{SUBSTITUTE-SERVER}} agrees with local builds, except in the
case of Git. This might indicate that the build process of Git is
non-deterministic, meaning that its output varies as a function of
various things that Guix does not fully control, in spite of building
packages in isolated environments (@pxref{Features}). Most common
sources of non-determinism include the addition of timestamps in build
results, the inclusion of random numbers, and directory listings sorted
by inode number. See @uref{https://reproducible-builds.org/docs/}, for
more information.
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}):
$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \
| guix archive -x /tmp/git
$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
This command shows the difference between the files resulting from the
local build, and the files resulting from the build on
@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging Files,,
diffutils, Comparing and Merging Files}). The @command{diff} command
works great for text files. When binary files differ, a better option
is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
visualize differences for all kinds of files.
Once you have done that work, you can tell whether the differences are due
to a non-deterministic build process or to a malicious server. We try
hard to remove sources of non-determinism in packages to make it easier
to verify substitutes, but of course, this is a process that
involves not just Guix, but a large part of the free software community.
In the meantime, @command{guix challenge} is one tool to help address
the problem.
If you are writing packages for Guix, you are encouraged to check
whether @code{@value{SUBSTITUTE-SERVER}} and other substitute servers obtain the
same build result as you did with:
$ guix challenge @var{package}
@end example
@noindent
where @var{package} is a package specification such as
@code{guile@@2.0} or @code{glibc:debug}.
The general syntax is:
guix challenge @var{options} [@var{packages}@dots{}]
When a difference is found between the hash of a locally-built item and
that of a server-provided substitute, or among substitutes provided by
different servers, the command displays it as in the example above and
its exit code is 2 (other non-zero exit codes denote other kinds of
errors.)
The one option that matters is:
@table @code
@item --substitute-urls=@var{urls}
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
information about mismatches.
@end table
@node Invoking guix copy
@section Invoking @command{guix copy}
@cindex copy, of store items, over SSH
@cindex SSH, copy of store items
@cindex sharing store items across machines
@cindex transferring store items across machines
The @command{guix copy} command copies items from the store of one
machine to that of another machine over a secure shell (SSH)
connection@footnote{This command is available only when Guile-SSH was
found. @xref{Requirements}, for details.}. For example, the following
command copies the @code{coreutils} package, the user's profile, and all
their dependencies over to @var{host}, logged in as @var{user}:
guix copy --to=@var{user}@@@var{host} \
coreutils `readlink -f ~/.guix-profile`
If some of the items to be copied are already present on @var{host},
they are not actually sent.
The command below retrieves @code{libreoffice} and @code{gimp} from
@var{host}, assuming they are available there:
guix copy --from=@var{host} libreoffice gimp
The SSH connection is established using the Guile-SSH client, which is
compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
@file{~/.ssh/config}, and uses the SSH agent for authentication.
The key used to sign items that are sent must be accepted by the remote
machine. Likewise, the key used by the remote machine to sign items you
are retrieving must be in @file{/etc/guix/acl} so it is accepted by your
own daemon. @xref{Invoking guix archive}, for more information about
store item authentication.
The general syntax is:
guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
You must always specify one of the following options:
@table @code
@item --to=@var{spec}
@itemx --from=@var{spec}
Specify the host to send to or receive from. @var{spec} must be an SSH
spec such as @code{example.org}, @code{charlie@@example.org}, or
@code{charlie@@example.org:2222}.
@end table
The @var{items} can be either package names, such as @code{gimp}, or
store items, such as @file{/gnu/store/@dots{}-idutils-4.6}.
When specifying the name of a package to send, it is first built if
needed, unless @option{--dry-run} was specified. Common build options
are supported (@pxref{Common Build Options}).
@node Invoking guix container
@section Invoking @command{guix container}
@cindex container
@cindex @command{guix container}
@quotation Note
As of version @value{VERSION}, this tool is experimental. The interface
is subject to radical change in the future.
@end quotation
The purpose of @command{guix container} is to manipulate processes
running within an isolated environment, commonly known as a
``container'', typically created by the @command{guix environment}
(@pxref{Invoking guix environment}) and @command{guix system container}
(@pxref{Invoking guix system}) commands.
The general syntax is:
guix container @var{action} @var{options}@dots{}
@var{action} specifies the operation to perform with a container, and
@var{options} specifies the context-specific arguments for the action.
The following actions are available:
@table @code
@item exec
Execute a command within the context of a running container.
The syntax is:
guix container exec @var{pid} @var{program} @var{arguments}@dots{}
@end example
@var{pid} specifies the process ID of the running container.
@var{program} specifies an executable file name within the root file
system of the container. @var{arguments} are the additional options that
will be passed to @var{program}.
The following command launches an interactive login shell inside a
Guix system container, started by @command{guix system container}, and whose
process ID is 9001:
guix container exec 9001 /run/current-system/profile/bin/bash --login
Note that the @var{pid} cannot be the parent process of a container. It
must be PID 1 of the container or one of its child processes.
@end table
@node Invoking guix weather
@section Invoking @command{guix weather}
Occasionally you're grumpy because substitutes are lacking and you end
up building packages by yourself (@pxref{Substitutes}). The
@command{guix weather} command reports on substitute availability on the
specified servers so you can have an idea of whether you'll be grumpy
today. It can sometimes be useful info as a user, but it is primarily
useful to people running @command{guix publish} (@pxref{Invoking guix
publish}).
@cindex statistics, for substitutes
@cindex availability of substitutes
@cindex substitute availability
@cindex weather, substitute availability
Here's a sample run:
$ guix weather --substitute-urls=https://guix.example.org
computing 5,872 package derivations for x86_64-linux...
looking for 6,128 store items on https://guix.example.org..
updating list of substitutes from 'https://guix.example.org'... 100.0%
https://guix.example.org
43.4% substitutes available (2,658 out of 6,128)
7,032.5 MiB of nars (compressed)
19,824.2 MiB on disk (uncompressed)
0.030 seconds per request (182.9 seconds in total)
33.5 requests per second
9.8% (342 out of 3,470) of the missing items are queued
867 queued builds
x86_64-linux: 518 (59.7%)
i686-linux: 221 (25.5%)
aarch64-linux: 128 (14.8%)
build rate: 23.41 builds per hour
x86_64-linux: 11.16 builds per hour
i686-linux: 6.03 builds per hour
aarch64-linux: 6.41 builds per hour
@end example
@cindex continuous integration, statistics
As you can see, it reports the fraction of all the packages for which
substitutes are available on the server---regardless of whether
substitutes are enabled, and regardless of whether this server's signing
key is authorized. It also reports the size of the compressed archives
(``nars'') provided by the server, the size the corresponding store
items occupy in the store (assuming deduplication is turned off), and
the server's throughput. The second part gives continuous integration
(CI) statistics, if the server supports it. In addition, using the
@option{--coverage} option, @command{guix weather} can list ``important''
package substitutes missing on the server (see below).
To achieve that, @command{guix weather} queries over HTTP(S) meta-data
(@dfn{narinfos}) for all the relevant store items. Like @command{guix
challenge}, it ignores signatures on those substitutes, which is
innocuous since the command only gathers statistics and cannot install
those substitutes.
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}
@var{urls} is the space-separated list of substitute server URLs to
query. When this option is omitted, the default set of substitute
servers is queried.
@item --system=@var{system}
@itemx -s @var{system}
Query substitutes for @var{system}---e.g., @code{aarch64-linux}. This
option can be repeated, in which case @command{guix weather} will query
substitutes for several system types.
@item --manifest=@var{file}
Instead of querying substitutes for all the packages, only ask for those
specified in @var{file}. @var{file} must contain a @dfn{manifest}, as
with the @code{-m} option of @command{guix package} (@pxref{Invoking
guix package}).
@item --coverage[=@var{count}]
@itemx -c [@var{count}]
Report on substitute coverage for packages: list packages with at least
@var{count} dependents (zero by default) for which substitutes are
unavailable. Dependent packages themselves are not listed: if @var{b} depends
on @var{a} and @var{a} has no substitutes, only @var{a} is listed, even though
@var{b} usually lacks substitutes as well. The result looks like this:
@example
$ guix weather --substitute-urls=@value{SUBSTITUTE-URL} -c 10
computing 8,983 package derivations for x86_64-linux...
looking for 9,343 store items on @value{SUBSTITUTE-URL}...
updating substitutes from '@value{SUBSTITUTE-URL}'... 100.0%
@value{SUBSTITUTE-URL}
64.7% substitutes available (6,047 out of 9,343)
@dots{}
2502 packages are missing from '@value{SUBSTITUTE-URL}' for 'x86_64-linux', among which:
58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0
46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1
37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008
@dots{}
@end example
What this example shows is that @code{kcoreaddons} and presumably the 58
packages that depend on it have no substitutes at @code{ci.guix.info};
likewise for @code{qgpgme} and the 46 packages that depend on it.
If you are a Guix developer, or if you are taking care of this build farm,
you'll probably want to have a closer look at these packages: they may simply
fail to build.
@end table
@node Invoking guix processes
@section Invoking @command{guix processes}
The @command{guix processes} command can be useful to developers and system
administrators, especially on multi-user machines and on build farms: it lists
the current sessions (connections to the daemon), as well as information about
the processes involved@footnote{Remote sessions, when @command{guix-daemon} is
started with @option{--listen} specifying a TCP endpoint, are @emph{not}
listed.}. Here's an example of the information it returns:
$ sudo guix processes
SessionPID: 19002
ClientPID: 19090
ClientCommand: guix environment --ad-hoc python
SessionPID: 19402
ClientPID: 19367
ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{}
SessionPID: 19444
ClientPID: 19419
ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock
LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock
LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock
ChildProcess: 20495: guix offload x86_64-linux 7200 1 28800
ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800
ChildProcess: 27793: guix offload x86_64-linux 7200 1 28800
@end example
In this example we see that @command{guix-daemon} has three clients:
@command{guix environment}, @command{guix publish}, and the Cuirass continuous
integration tool; their process identifier (PID) is given by the
@code{ClientPID} field. The @code{SessionPID} field gives the PID of the
@command{guix-daemon} sub-process of this particular session.
The @code{LockHeld} fields show which store items are currently locked by this
session, which corresponds to store items being built or substituted (the
@code{LockHeld} field is not displayed when @command{guix processes} is not
running as root.) Last, by looking at the @code{ChildProcess} field, we
understand that these three builds are being offloaded (@pxref{Daemon Offload
Setup}).
The output is in Recutils format so we can use the handy @command{recsel}
command to select sessions of interest (@pxref{Selection Expressions,,,
recutils, GNU recutils manual}). As an example, the command shows the command
line and PID of the client that triggered the build of a Perl package:
$ sudo guix processes | \
recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
ClientPID: 19419
ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
@chapter System Configuration
@cindex system configuration
Guix System supports a consistent whole-system configuration
mechanism. By that we mean that all aspects of the global system
configuration---such as the available system services, timezone and
locale settings, user accounts---are declared in a single place. Such
a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
One of the advantages of putting all the system configuration under the
control of Guix is that it supports transactional system upgrades, and
makes it possible to roll back to a previous system instantiation,
should something go wrong with the new one (@pxref{Features}). Another
advantage is that it makes it easy to replicate the exact same configuration
across different machines, or at different points in time, without
having to resort to additional administration tools layered on top of
@c Yes, we're talking of Puppet, Chef, & co. here. ↑
This section describes this mechanism. First we focus on the system
administrator's viewpoint---explaining how the system is configured and
instantiated. Then we show how this mechanism can be extended, for
instance to support new system services.
@menu
* Using the Configuration System:: Customizing your GNU system.
* operating-system Reference:: Detail of operating-system declarations.
* File Systems:: Configuring file system mounts.
* Mapped Devices:: Block device extra processing.
* User Accounts:: Specifying user accounts.
* Keyboard Layout:: How the system interprets key strokes.
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
* X.509 Certificates:: Authenticating HTTPS servers.
* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* Bootloader Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
* Invoking guix deploy:: Deploying a system configuration to a remote host.
* Running Guix in a VM:: How to run Guix System in a virtual machine.
* Defining Services:: Adding new service definitions.
@end menu
@node Using the Configuration System
@section Using the Configuration System
The operating system is configured by providing an
@code{operating-system} declaration in a file that can then be passed to
the @command{guix system} command (@pxref{Invoking guix system}). A
simple setup, with the default system services, the default Linux-Libre
kernel, initial RAM disk, and boot loader looks like this:
@findex operating-system
@lisp
@include os-config-bare-bones.texi
This example should be self-describing. Some of the fields defined
above, such as @code{host-name} and @code{bootloader}, are mandatory.
Others, such as @code{packages} and @code{services}, can be omitted, in
which case they get a default value.
Below we discuss the effect of some of the most important fields
(@pxref{operating-system Reference}, for details about all the available
fields), and how to @dfn{instantiate} the operating system using
@command{guix system}.
@unnumberedsubsec Bootloader
@cindex legacy boot, on Intel machines
@cindex BIOS boot, on Intel machines
@cindex UEFI boot
@cindex EFI boot
The @code{bootloader} field describes the method that will be used to boot
your system. Machines based on Intel processors can boot in ``legacy'' BIOS
mode, as in the example above. However, more recent machines rely instead on
the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that case,
the @code{bootloader} field should contain something along these lines:
(bootloader-configuration
(bootloader grub-efi-bootloader)
(target "/boot/efi"))
@xref{Bootloader Configuration}, for more information on the available
configuration options.
@unnumberedsubsec Globally-Visible Packages
The @code{packages} field lists packages that will be globally visible
on the system, for all user accounts---i.e., in every user's @code{PATH}
environment variable---in addition to the per-user profiles
(@pxref{Invoking guix package}). The @code{%base-packages} variable
provides all the tools one would expect for basic user and administrator
tasks---including the GNU Core Utilities, the GNU Networking Utilities,
the GNU Zile lightweight text editor, @command{find}, @command{grep},
etc. The example above adds GNU@tie{}Screen to those,
taken from the @code{(gnu packages screen)}
module (@pxref{Package Modules}). The
@code{(list package output)} syntax can be used to add a specific output
of a package:
@lisp
(use-modules (gnu packages))
(use-modules (gnu packages dns))
(operating-system
;; ...
(packages (cons (list bind "utils")
%base-packages)))
@end lisp
@findex specification->package
Referring to packages by variable name, like @code{bind} above, has
the advantage of being unambiguous; it also allows typos and such to be
diagnosed right away as ``unbound variables''. The downside is that one
needs to know which module defines which package, and to augment the
@code{use-package-modules} line accordingly. To avoid that, one can use
the @code{specification->package} procedure of the @code{(gnu packages)}
module, which returns the best package for a given name or name and
version:
@lisp
(use-modules (gnu packages))
(operating-system
;; ...
(packages (append (map specification->package
'("tcpdump" "htop" "gnupg@@2.0"))
%base-packages)))
@end lisp
@unnumberedsubsec System Services
@vindex %base-services
The @code{services} field lists @dfn{system services} to be made
available when the system starts (@pxref{Services}).
The @code{operating-system} declaration above specifies that, in
addition to the basic services, we want the OpenSSH secure shell
daemon listening on port 2222 (@pxref{Networking Services,
@code{openssh-service-type}}). Under the hood,
@code{openssh-service-type} arranges so that @command{sshd} is started with the
right command-line options, possibly with supporting configuration files
generated as needed (@pxref{Defining Services}).
@cindex customization, of services
@findex modify-services
Occasionally, instead of using the base services as is, you will want to
customize them. To do this, use @code{modify-services} (@pxref{Service
Reference, @code{modify-services}}) to modify the list.
For example, suppose you want to modify @code{guix-daemon} and Mingetty
(the console log-in) in the @code{%base-services} list (@pxref{Base
Services, @code{%base-services}}). To do that, you can write the
following in your operating system declaration:
(define %my-services
;; My very own list of services.
(modify-services %base-services
(guix-service-type config =>
(guix-configuration
(inherit config)
(use-substitutes? #f)
(extra-options '("--gc-keep-derivations"))))
(mingetty-service-type config =>
(mingetty-configuration
(operating-system
;; @dots{}
(services %my-services))
This changes the configuration---i.e., the service parameters---of the
@code{guix-service-type} instance, and that of all the
@code{mingetty-service-type} instances in the @code{%base-services} list.
Observe how this is accomplished: first, we arrange for the original
configuration to be bound to the identifier @code{config} in the
@var{body}, and then we write the @var{body} so that it evaluates to the
desired configuration. In particular, notice how we use @code{inherit}
to create a new configuration which has the same values as the old
configuration, but with a few modifications.
@cindex encrypted disk
The configuration for a typical ``desktop'' usage, with an encrypted
root partition, the X11 display
server, GNOME and Xfce (users can choose which of these desktop
environments to use at the log-in screen by pressing @kbd{F1}), network
management, power management, and more, would look like this:
@lisp
@include os-config-desktop.texi
@end lisp
A graphical system with a choice of lightweight window managers
instead of full-blown desktop environments would look like this:
@lisp
@include os-config-lightweight-desktop.texi
@end lisp
This example refers to the @file{/boot/efi} file system by its UUID,
@code{1234-ABCD}. Replace this UUID with the right UUID on your system,
as returned by the @command{blkid} command.
@xref{Desktop Services}, for the exact list of services provided by
@code{%desktop-services}. @xref{X.509 Certificates}, for background
information about the @code{nss-certs} package that is used here.
Again, @code{%desktop-services} is just a list of service objects. If