@c Identifier of the OpenPGP key used to sign tarballs and such.
@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
-@set KEY-SERVER pool.sks-keyservers.net
+@set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=15145
@c Base URL for downloads.
@set BASE-URL https://ftp.gnu.org/gnu/guix
Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
-Copyright @copyright{} 2015, 2016, 2017 Leo Famulari@*
+Copyright @copyright{} 2015, 2016, 2017, 2019 Leo Famulari@*
Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
Copyright @copyright{} 2017, 2018 Marius Bakke@*
Copyright @copyright{} 2017 Hartmut Goebel@*
Copyright @copyright{} 2017 Maxim Cournoyer@*
-Copyright @copyright{} 2017, 2018 Tobias Geerinckx-Rice@*
+Copyright @copyright{} 2017, 2018, 2019 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
Copyright @copyright{} 2017, 2018, 2019 Arun Isaac@*
Copyright @copyright{} 2019 Josh Holland@*
Copyright @copyright{} 2019 Diego Nicola Barbato@*
Copyright @copyright{} 2019 Ivan Petkov@*
+Copyright @copyright{} 2019 Jakob L. Kreuze@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* guix gc: (guix)Invoking guix gc. Reclaiming unused disk space.
* guix pull: (guix)Invoking guix pull. Update the list of available packages.
* guix system: (guix)Invoking guix system. Manage the operating system configuration.
+* guix deploy: (guix)Invoking guix deploy. Manage operating system configurations for remote hosts.
@end direntry
@dircategory Software development
* 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.
then run this command to import it:
@example
-$ gpg --keyserver @value{KEY-SERVER} \
- --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+$ wget @value{OPENPGP-SIGNING-KEY-URL} \
+ -qO - | gpg --import -
@end example
@noindent
and rerun the @code{gpg --verify} command.
+
+Take note that a warning like ``This key is not certified with a trusted
+signature!'' is normal.
+
@c end authentication part
@item
@c FIXME: Specify a version number once a release has been made.
@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 @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON} 3.x;
@item @url{https://zlib.net, zlib};
@item @url{https://www.gnu.org/software/make/, GNU Make}.
@end itemize
then run this command to import it:
@example
-$ gpg --keyserver @value{KEY-SERVER} \
- --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+$ wget @value{OPENPGP-SIGNING-KEY-URL} \
+ -qO - | gpg --import -
@end example
@noindent
and rerun the @code{gpg --verify} command.
+
+Take note that a warning like ``This key is not certified with a trusted
+signature!'' is normal.
+
@c end duplication
This image contains the tools necessary for an installation.
Boot the USB installation image in an VM:
@example
-qemu-system-x86_64 -m 1024 -smp 1 \
+qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
-net user -net nic,model=virtio -boot menu=on \
-drive file=guix-system-install-@value{VERSION}.@var{system}.iso \
-drive file=guixsd.img
@end example
-The ordering of the drives matters.
+The ordering of the drives matters. @code{-enable-kvm} is optional, but
+significantly improves performance, @pxref{Running Guix in a VM}.
In the VM console, quickly press the @kbd{F12} key to enter the boot
menu. Then press the @kbd{2} key and the @kbd{RET} key to validate your
@node Official Substitute Server
@subsection Official Substitute Server
-@cindex hydra
@cindex build farm
The @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an official build farm
that builds packages from Guix continuously for some
# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub
@end example
-@quotation Note
-Similarly, the @file{hydra.gnu.org.pub} file contains the public key
-of an independent build farm also run by the project, reachable at
-@indicateurl{https://mirror.hydra.gnu.org}.
-@end quotation
-
Once this is in place, the output of a command like @code{guix build}
should change from something like:
on channels that you don't control, and you should aim to keep the number of
dependencies to a minimum.
+@cindex subdirectory, channels
+@subsection Package Modules in a Sub-directory
+
+As a channel author, you may want to keep your channel modules in a
+sub-directory. If your modules are in the sub-directory @file{guix}, you must
+add a meta-data file @file{.guix-channel} that contains:
+
+@lisp
+(channel
+ (version 0)
+ (directory "guix"))
+@end lisp
+
@subsection Replicating Guix
@cindex pinning, channels
and each of the user fields, this is only one useful component of a
broader privacy/anonymity solution---not one in and of itself.
+@item --no-cwd
+For containers, the default behavior is to share the current working
+directory with the isolated container and immediately change to that
+directory within the container. If this is undesirable, @code{--no-cwd}
+will cause the current working directory to @emph{not} be automatically
+shared and will change to the user's home directory within the container
+instead. See also @code{--user}.
+
@item --expose=@var{source}[=@var{target}]
For containers, expose the file system @var{source} from the host system
as the read-only file system @var{target} within the container. If
In its @code{configure} phase, this build system will make any source inputs
specified in the @code{#:cargo-inputs} and @code{#:cargo-development-inputs}
-parameters available to cargo. The @code{install} phase installs any crate
-the binaries if they are defined by the crate.
+parameters available to cargo. It will also remove an included
+@code{Cargo.lock} file to be recreated by @code{cargo} during the
+@code{build} phase. The @code{install} phase installs any crate the binaries
+if they are defined by the crate.
@end defvr
@cindex Clojure (programming language)
By default guix calls @code{setup.py} under control of
@code{setuptools}, much like @command{pip} does. Some packages are not
compatible with setuptools (and pip), thus you can disable this by
-setting the @code{#:use-setuptools} parameter to @code{#f}.
+setting the @code{#:use-setuptools?} parameter to @code{#f}.
@end defvr
@defvr {Scheme Variable} perl-build-system
linux-module-build-system, use the key #:linux to specify it).
@end defvr
+@defvr {Scheme Variable} node-build-system
+This variable is exported by @code{(guix build-system node)}. It
+implements the build procedure used by @uref{http://nodejs.org,
+Node.js}, which implements an approximation of the @code{npm install}
+command, followed by an @code{npm test} command.
+
+Which Node.js package is used to interpret the @code{npm} commands can
+be specified with the @code{#:node} parameter which defaults to
+@code{node}.
+@end defvr
+
Lastly, for packages that do not need anything as sophisticated, a
``trivial'' build system is provided. It is trivial in the sense that
it provides basically no support: it does not pull any implicit inputs,
@end deffn
@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
- [#:guile (default-guile)] [#:module-path %load-path]
+ [#:guile (default-guile)] [#:module-path %load-path] @
+ [#:system (%current-system)] [#:target #f]
Return an executable script @var{name} that runs @var{exp} using
@var{guile}, with @var{exp}'s imported modules in its search path.
Look up @var{exp}'s modules in @var{module-path}.
@item --with-commit=@var{package}=@var{commit}
This is similar to @code{--with-branch}, except that it builds from
@var{commit} rather than the tip of a branch. @var{commit} must be a valid
-Git commit SHA1 identifier.
+Git commit SHA1 identifier or a tag.
@end table
@node Additional Build Options
"synopsis": "Hello, GNU world: An example GNU package",
"description": "GNU Hello prints a greeting.",
"license": "GPL-3.0+",
- "native-inputs": ["gcc@@6"]
+ "native-inputs": ["gettext"]
@}
@end example
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 Hydra, the software behind
+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
* 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
%base-services)))
@end lisp
+For more complex jobs defined in Scheme where you need control over the top
+level, for instance to introduce a @code{use-modules} form, you can move your
+code to a separate program using the @code{program-file} procedure of the
+@code{(guix gexp)} module (@pxref{G-Expressions}). The example below
+illustrates that.
+
+@lisp
+(define %battery-alert-job
+ ;; Beep when the battery percentage falls below %MIN-LEVEL.
+ #~(job
+ '(next-minute (range 0 60 1))
+ #$(program-file
+ "battery-alert.scm"
+ (with-imported-modules (source-module-closure
+ '((guix build utils)))
+ #~(begin
+ (define %min-level 20)
+ (use-modules (guix build utils)
+ (ice-9 popen)
+ (ice-9 regex)
+ (ice-9 textual-ports)
+ (srfi srfi-2))
+ (setenv "LC_ALL" "C") ;ensure English output
+ (and-let* ((input-pipe (open-pipe*
+ OPEN_READ
+ #$(file-append acpi "/bin/acpi")))
+ (output (get-string-all input-pipe))
+ (m (string-match "Discharging, ([0-9]+)%" output))
+ (level (string->number (match:substring m 1)))
+ ((< level %min-level)))
+ (format #t "warning: Battery level is low (~a%)~%" level)
+ (invoke #$(file-append beep "/bin/beep") "-r5")))))))
+@end lisp
+
@xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron},
for more information on mcron job specifications. Below is the
reference of the mcron service.
provided by currently active connections.
@item dnsmasq
-NetworkManager will run @code{dnsmasq} as a local caching nameserver,
-using a "split DNS" configuration if you are connected to a VPN, and
+NetworkManager will run @code{dnsmasq} as a local caching nameserver, using a
+@dfn{conditional forwarding} configuration if you are connected to a VPN, and
then update @code{resolv.conf} to point to the local nameserver.
+With this setting, you can share your network connection. For example when
+you want to share your network connection to another laptop @i{via} an
+Ethernet cable, you can open @command{nm-connection-editor} and configure the
+Wired connection's method for IPv4 and IPv6 to be ``Shared to other computers''
+and reestablish the connection (or reboot).
+
+You can also set up a @dfn{host-to-guest connection} to QEMU VMs
+(@pxref{Installing Guix in a VM}). With a host-to-guest connection, you can
+e.g.@: access a Web server running on the VM (@pxref{Web Services}) from a Web
+browser on your host system, or connect to the VM @i{via} SSH
+(@pxref{Networking Services, @code{openssh-service-type}}). To set up a
+host-to-guest connection, run this command once:
+
+@example
+nmcli connection add type tun \
+ connection.interface-name tap0 \
+ tun.mode tap tun.owner $(id -u) \
+ ipv4.method shared \
+ ipv4.addresses 172.28.112.1/24
+@end example
+
+Then each time you launch your QEMU VM (@pxref{Running Guix in a VM}), pass
+@option{-nic tap,ifname=tap0,script=no,downscript=no} to
+@command{qemu-system-...}.
+
@item none
NetworkManager will not modify @code{resolv.conf}.
@end table
@deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
Sets encryption options. By default, CUPS only supports encryption
-using TLS v1.0 or higher using known secure cipher suites. The
-@code{AllowRC4} option enables the 128-bit RC4 cipher suites, which are
-required for some older clients that do not implement newer ones. The
-@code{AllowSSL3} option enables SSL v3.0, which is required for some
-older clients that do not support TLS v1.0.
+using TLS v1.0 or higher using known secure cipher suites. Security is
+reduced when @code{Allow} options are used, and enhanced when @code{Deny}
+options are used. The @code{AllowRC4} option enables the 128-bit RC4 cipher
+suites, which are required for some older clients. The @code{AllowSSL3} option
+enables SSL v3.0, which is required for some older clients that do not support
+TLS v1.0. The @code{DenyCBC} option disables all CBC cipher suites. The
+@code{DenyTLS1.0} option disables TLS v1.0 support - this sets the minimum
+protocol version to TLS v1.1.
Defaults to @samp{()}.
@end deftypevr
key configuration in @file{/etc/knot/secrets.conf} and add this file
to the @code{includes} list.
+One can generate a secret tsig key (for nsupdate and zone transfers with the
+keymgr command from the knot package. Note that the package is not automatically
+installed by the service. The following example shows how to generate a new
+tsig key:
+
+@example
+keymgr -t mysecret > /etc/knot/secrets.conf
+chmod 600 /etc/knot/secrets.conf
+@end example
+
+Also note that the generated key will be named @var{mysecret}, so it is the
+name that needs to be used in the @var{key} field of the
+@code{knot-acl-configuration} record and in other places that need to refer
+to that key.
+
It can also be used to add configuration not supported by this interface.
@item @code{listen-v4} (default: @code{"0.0.0.0"})
@item @code{port} (default: @code{8081})
Port number used by the HTTP server.
-@item --listen=@var{host}
+@item @code{host} (default: @code{"localhost"})
Listen on the network interface for @var{host}. The default is to
accept connections from localhost.
@end table
+@node Invoking guix deploy
+@section Invoking @code{guix deploy}
+
+We've already seen @code{operating-system} declarations used to manage a
+machine's configuration locally. Suppose you need to configure multiple
+machines, though---perhaps you're managing a service on the web that's
+comprised of several servers. @command{guix deploy} enables you to use those
+same @code{operating-system} declarations to manage multiple remote hosts at
+once as a logical ``deployment''.
+
+@quotation Note
+The functionality described in this section is still under development
+and is subject to change. Get in touch with us on
+@email{guix-devel@@gnu.org}!
+@end quotation
+
+@example
+guix deploy @var{file}
+@end example
+
+Such an invocation will deploy the machines that the code within @var{file}
+evaluates to. As an example, @var{file} might contain a definition like this:
+
+@example
+;; This is a Guix deployment of a "bare bones" setup, with
+;; no X11 display server, to a machine with an SSH daemon
+;; listening on localhost:2222. A configuration such as this
+;; may be appropriate for virtual machine with ports
+;; forwarded to the host's loopback interface.
+
+(use-service-modules networking ssh)
+(use-package-modules bootloaders)
+
+(define %system
+ (operating-system
+ (host-name "gnu-deployed")
+ (timezone "Etc/UTC")
+ (bootloader (bootloader-configuration
+ (bootloader grub-bootloader)
+ (target "/dev/vda")
+ (terminal-outputs '(console))))
+ (file-systems (cons (file-system
+ (mount-point "/")
+ (device "/dev/vda1")
+ (type "ext4"))
+ %base-file-systems))
+ (services
+ (append (list (service dhcp-client-service-type)
+ (service openssh-service-type
+ (openssh-configuration
+ (permit-root-login #t)
+ (allow-empty-passwords? #t))))
+ %base-services))))
+
+(list (machine
+ (operating-system %system)
+ (environment managed-host-environment-type)
+ (configuration (machine-ssh-configuration
+ (host-name "localhost")
+ (user "alice")
+ (identity "./id_rsa")
+ (port 2222)))))
+@end example
+
+The file should evaluate to a list of @var{machine} objects. This example,
+upon being deployed, will create a new generation on the remote system
+realizing the @code{operating-system} declaration @var{%system}.
+@var{environment} and @var{configuration} specify how the machine should be
+provisioned---that is, how the computing resources should be created and
+managed. The above example does not create any resources, as a
+@code{'managed-host} is a machine that is already running the Guix system and
+available over the network. This is a particularly simple case; a more
+complex deployment may involve, for example, starting virtual machines through
+a Virtual Private Server (VPS) provider. In such a case, a different
+@var{environment} type would be used.
+
+Do note that you first need to generate a key pair on the coordinator machine
+to allow the daemon to export signed archives of files from the store
+(@pxref{Invoking guix archive}).
+
+@example
+# guix archive --generate-key
+@end example
+
+@noindent
+Each target machine must authorize the key of the master machine so that it
+accepts store items it receives from the coordinator:
+
+@example
+# guix archive --authorize < coordinator-public-key.txt
+@end example
+
+@code{user}, in this example, specifies the name of the user account to log in
+as to perform the deployment. Its default value is @code{root}, but root
+login over SSH may be forbidden in some cases. To work around this,
+@command{guix deploy} can log in as an unprivileged user and employ
+@code{sudo} to escalate privileges. This will only work if @code{sudo} is
+currently installed on the remote and can be invoked non-interactively as
+@code{user}. That is: the line in @code{sudoers} granting @code{user} the
+ability to use @code{sudo} must contain the @code{NOPASSWD} tag.
+
+@deftp {Data Type} machine
+This is the data type representing a single machine in a heterogeneous Guix
+deployment.
+
+@table @asis
+@item @code{operating-system}
+The object of the operating system configuration to deploy.
+
+@item @code{environment}
+An @code{environment-type} describing how the machine should be provisioned.
+At the moment, the only supported value is
+@code{managed-host-environment-type}.
+
+@item @code{configuration} (default: @code{#f})
+An object describing the configuration for the machine's @code{environment}.
+If the @code{environment} has a default configuration, @code{#f} maybe used.
+If @code{#f} is used for an environment with no default configuration,
+however, an error will be thrown.
+@end table
+@end deftp
+
+@deftp {Data Type} machine-ssh-configuration
+This is the data type representing the SSH client parameters for a machine
+with an @code{environment} of @code{managed-host-environment-type}.
+
+@table @asis
+@item @code{host-name}
+@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''.
+@item @code{authorize?} (default: @code{#t})
+If true, the coordinator's signing key will be added to the remote's ACL
+keyring.
+@item @code{port} (default: @code{22})
+@item @code{user} (default: @code{"root"})
+@item @code{identity} (default: @code{#f})
+If specified, the path to the SSH private key to use to authenticate with the
+remote host.
+@end table
+@end deftp
+
@node Running Guix in a VM
@section Running Guix in a Virtual Machine
@example
$ qemu-system-x86_64 \
-net user -net nic,model=virtio \
- -enable-kvm -m 512 \
+ -enable-kvm -m 1024 \
-device virtio-blk,drive=myhd \
-drive if=none,file=/tmp/qemu-image,id=myhd
@end example
@xref{Invoking guix lint}, for more information.
-@quotation Note
-As of version @value{VERSION}, the feature described below is considered
-``beta''.
-@end quotation
-
Guix follows a functional
package management discipline (@pxref{Introduction}), which implies
that, when a package is changed, @emph{every package that depends on it}
HCoop / jackhill / guix / guix.git / blobdiff