diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 167 |
1 files changed, 154 insertions, 13 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index b7f1bc1f00..cca57140d6 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -82,6 +82,8 @@ Copyright @copyright{} 2020 Pierre Langlois@* Copyright @copyright{} 2020 pinoaffe@* Copyright @copyright{} 2020 André Batista@* Copyright @copyright{} 2020 Alexandru-Sergiu Marton@* +Copyright @copyright{} 2020 raingloom@* +Copyright @copyright{} 2020 Daniel Brooks@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -404,7 +406,7 @@ using a different distro underneath!}. @xref{GNU Distribution}. @cindex user interfaces Guix provides a command-line package management interface (@pxref{Package Management}), tools to help with software development -(@pxref{Development}), command-line utilities for more advanced usage, +(@pxref{Development}), command-line utilities for more advanced usage (@pxref{Utilities}), as well as Scheme programming interfaces (@pxref{Programming Interface}). @cindex build daemon @@ -1397,6 +1399,11 @@ install and run it, which lifts it into the @code{guix_daemon_t} domain. At that point SELinux could not prevent it from accessing files that are allowed for processes in that domain. +You will need to relabel the store directory after all upgrades to +@file{guix-daemon}, such as after running @code{guix pull}. Assuming the +store is in @file{/gnu}, you can do this with @code{restorecon -vR /gnu}, +or by other means provided by your operating system. + We could generate a much more restrictive policy at installation time, so that only the @emph{exact} file name of the currently installed @code{guix-daemon} executable would be labelled with @@ -6834,6 +6841,18 @@ commit: @end lisp @end deftp +For Mercurial repositories, the module @code{(guix hg-download)} defines +the @code{hg-fetch} origin method and @code{hg-reference} data type for +support of the Mercurial version control system. + +@deffn {Scheme Procedure} hg-fetch @var{ref} @var{hash-algo} @var{hash} @ + [name] +Return a fixed-output derivation that fetches @var{ref}, a +@code{<hg-reference>} object. The output is expected to have recursive +hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as +the file name, or a generic name if @code{#false}. +@end deffn + @node Defining Package Variants @section Defining Package Variants @@ -14527,6 +14546,9 @@ the name of the log-in program. When set to @code{#t} in conjunction with @var{auto-login}, the user will have to press a key before the log-in shell is launched. +@item @code{clear-on-logout?} (default: @code{#t}) +When set to @code{#t}, the screen will be cleared after logout. + @item @code{mingetty} (default: @var{mingetty}) The Mingetty package to use. @@ -16848,6 +16870,101 @@ Use this to add additional options and manage shared secrets out-of-band. @end table @end deftp +@defvr {Scheme Variable} yggdrasil-service-type +The service type for connecting to the @uref{https://yggdrasil-network.github.io/, +Yggdrasil network}, an early-stage implementation of a fully end-to-end +encrypted IPv6 network. + +@quotation +Yggdrasil provides name-independent routing with cryptographically generated +addresses. Static addressing means you can keep the same address as long as +you want, even if you move to a new location, or generate a new address (by +generating new keys) whenever you want. +@uref{https://yggdrasil-network.github.io/2018/07/28/addressing.html} +@end quotation + +Pass it a value of @code{yggdrasil-configuration} to connect it to public +peers and/or local peers. + +Here is an example using public peers and a static address. The static +signing and encryption keys are defined in @file{/etc/yggdrasil-private.conf} +(the default value for @code{config-file}). + +@lisp +;; part of the operating-system declaration +(service yggdrasil-service-type + (yggdrasil-configuration + (autoconf? #f) ;; use only the public peers + (json-config + ;; choose one from + ;; https://github.com/yggdrasil-network/public-peers + '((peers . #("tcp://1.2.3.4:1337")))) + ;; /etc/yggdrasil-private.conf is the default value for config-file + )) +@end lisp +@example +# sample content for /etc/yggdrasil-private.conf +@{ + # Your public encryption key. Your peers may ask you for this to put + # into their AllowedEncryptionPublicKeys configuration. + EncryptionPublicKey: 378dc5... + + # Your private encryption key. DO NOT share this with anyone! + EncryptionPrivateKey: 0777... + + # Your public signing key. You should not ordinarily need to share + # this with anyone. + SigningPublicKey: e1664... + + # Your private signing key. DO NOT share this with anyone! + SigningPrivateKey: 0589d... +@} +@end example +@end defvr + +@deftp {Data Type} yggdrasil-configuration +Data type representing the configuration of Yggdrasil. + +@table @asis +@item @code{package} (default: @code{yggdrasil}) +Package object of Yggdrasil. + +@item @code{json-config} (default: @code{'()}) +Contents of @file{/etc/yggdrasil.conf}. Will be merged with +@file{/etc/yggdrasil-private.conf}. Note that these settings are stored in +the Guix store, which is readable to all users. @strong{Do not store your +private keys in it}. See the output of @code{yggdrasil -genconf} for a +quick overview of valid keys and their default values. + +@item @code{autoconf?} (default: @code{#f}) +Whether to use automatic mode. Enabling it makes Yggdrasil use adynamic IP +and peer with IPv6 neighbors. + +@item @code{log-level} (default: @code{'info}) +How much detail to include in logs. Use @code{'debug} for more detail. + +@item @code{log-to} (default: @code{'stdout}) +Where to send logs. By default, the service logs standard output to +@file{/var/log/yggdrasil.log}. The alternative is @code{'syslog}, which +sends output to the running syslog service. + +@item @code{config-file} (default: @code{"/etc/yggdrasil-private.conf"}) +What HJSON file to load sensitive data from. This is where private keys +should be stored, which are necessary to specify if you don't want a +randomized address after each restart. Use @code{#f} to disable. Options +defined in this file take precedence over @code{json-config}. Use the output +of @code{yggdrasil -genconf} as a starting point. To configure a static +address, delete everything except these options: + +@itemize +@item @code{EncryptionPublicKey} +@item @code{EncryptionPrivateKey} +@item @code{SigningPublicKey} +@item @code{SigningPrivateKey} +@end itemize +@end table +@end deftp + @node Unattended Upgrades @subsection Unattended Upgrades @@ -22072,9 +22189,10 @@ Defaults to @samp{""}. @end deftypevr @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-secret-file -Secret file which will be appended to @file{zabbix.conf.php} file. This -file contains credentials for use by Zabbix front-end. You are expected -to create it manually. +Secret file containing the credentials for the Zabbix front-end. The value +must be a local file name, not a G-expression. You are expected to create +this file manually. Its contents will be copied into @file{zabbix.conf.php} +as the value of @code{$DB['PASSWORD']}. Defaults to @samp{""}. @@ -29126,18 +29244,18 @@ the password from can also be specified, and this is more secure. A file containing the password to use when connecting to the coordinator. -@item @code{systems} (default: @var{#f}) +@item @code{systems} (default: @code{#f}) The systems for which this agent should fetch builds. The agent process will use the current system it's running on as the default. @item @code{max-parallel-builds} (default: @code{1}) The number of builds to perform in parallel. -@item @code{derivation-substitute-urls} (default: @code{1}) +@item @code{derivation-substitute-urls} (default: @code{#f}) URLs from which to attempt to fetch substitutes for derivations, if the derivations aren't already available. -@item @code{non-derivation-substitute-urls} (default: @code{1}) +@item @code{non-derivation-substitute-urls} (default: @code{#f}) URLs from which to attempt to fetch substitutes for build inputs, if the input store items aren't already available. @@ -30909,11 +31027,27 @@ a value. Docker images are built to contain exactly what they need, so the @option{--image-size} option is ignored in the case of @code{docker-image}. +@cindex disk-image, creating disk images The @code{disk-image} command can produce various image types. The -image type can be selected using the @command{--image-type} option. It -defaults to @code{raw}. When its value is @code{iso9660}, the +image type can be selected using the @option{--image-type} option. It +defaults to @code{raw}. When its value is @code{iso9660}, the @option{--label} option can be used to specify a volume ID with -@code{disk-image}. +@code{disk-image}. By default, the root file system of a disk image is +mounted non-volatile; the @option{--volatile} option can be provided to +make it volatile instead. When using @code{disk-image}, the bootloader +installed on the generated image is taken from the provided +@code{operating-system} definition. The following example demonstrates +how to generate an image that uses the @code{grub-efi-bootloader} +bootloader and boot it with QEMU: + +@example +image=$(guix system disk-image --image-type=qcow2 \ + gnu/system/examples/lightweight-desktop.tmpl) +cp $image /tmp/my-image.qcow2 +chmod +w /tmp/my-image.qcow2 +qemu-system-x86_64 -enable-kvm -hda /tmp/my-image.qcow2 -m 1000 + -bios $(guix build ovmf)/share/firmware/ovmf_x64.bin +@end example When using the @code{raw} image type, a raw disk image is produced; it can be copied as is to a USB stick, for instance. Assuming @@ -30927,10 +31061,17 @@ the image to it using the following command: The @code{--list-image-types} command lists all the available image types. +@cindex vm-image, creating virtual machine images When using @code{vm-image}, the returned image is in qcow2 format, which -the QEMU emulator can efficiently use. @xref{Running Guix in a VM}, -for more information on how to run the image in a virtual machine. - +the QEMU emulator can efficiently use. @xref{Running Guix in a VM}, for +more information on how to run the image in a virtual machine. The +@code{grub-bootloader} bootloader is always used independently of what +is declared in the @code{operating-system} file passed as argument. +This is to make it easier to work with QEMU, which uses the SeaBIOS BIOS +by default, expecting a bootloader to be installed in the Master Boot +Record (MBR). + +@cindex docker-image, creating docker images When using @code{docker-image}, a Docker image is produced. Guix builds the image from scratch, not from a pre-existing Docker base image. As a result, it contains @emph{exactly} what you define in the operating |