Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari@*
-Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ricardo Wurmus@*
+Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@*
Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022 Efraim Flashner@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
Copyright @copyright{} 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke@*
-Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
+Copyright @copyright{} 2017, 2019, 2020, 2022 Hartmut Goebel@*
Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@*
Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2021 Hui Lu@*
Copyright @copyright{} 2021 pukkamustard@*
Copyright @copyright{} 2021 Alice Brenon@*
-Copyright @copyright{} 2021 Josselin Poiret@*
+Copyright @copyright{} 2021, 2022 Josselin Poiret@*
+Copyright @copyright{} 2021 muradm@*
Copyright @copyright{} 2021 Andrew Tropin@*
Copyright @copyright{} 2021 Sarah Morgensen@*
-Copyright @copyright{} 2021 Josselin Poiret@*
Copyright @copyright{} 2022 Remco van 't Veer@*
Copyright @copyright{} 2022 Aleksandr Vityazev@*
Copyright @copyright{} 2022 Philip M@sup{c}Grath@*
Copyright @copyright{} 2022 Karl Hallsby@*
+Copyright @copyright{} 2022 Justin Veilleux@*
+Copyright @copyright{} 2022 Reily Siegel@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
* System Installation:: Installing the whole operating system.
+* System Troubleshooting Tips:: When things don't go as planned.
* Getting Started:: Your first steps.
* Package Management:: Package installation, upgrade, etc.
* Channels:: Customizing the package collection.
* Installing Guix in a VM:: Guix System playground.
* Building the Installation Image:: How this comes to be.
+System Troubleshooting Tips
+
+* Chrooting into an existing system:: Fixing things from a chroot
+
Manual Installation
* Keyboard Layout and Networking and Partitioning:: Initial setup.
* The Store Monad:: Purely functional interface to the store.
* G-Expressions:: Manipulating build expressions.
* Invoking guix repl:: Programming Guix in Guile.
+* Using Guix Interactively:: Fine-grain interaction at the REPL.
Defining Packages
./guix-install.sh
@end example
+If you're running Debian or a derivative such as Ubuntu, you can instead
+install the package (it might be a version older than @value{VERSION}
+but you can update it afterwards by running @samp{guix pull}):
+
+@example
+sudo apt install guix
+@end example
+
+Likewise on openSUSE:
+
+@example
+sudo zypper install guix
+@end example
+
When you're done, @pxref{Application Setup} for extra configuration you
might need, and @ref{Getting Started} for your first steps!
@end quotation
The @code{guix-daemon} program may then be run as @code{root} with the
following command@footnote{If your machine uses the systemd init system,
-dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
-file in @file{/etc/systemd/system} will ensure that
+copying the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
+file to @file{/etc/systemd/system} will ensure that
@command{guix-daemon} is automatically started. Similarly, if your
-machine uses the Upstart init system, drop the
+machine uses the Upstart init system, copy the
@file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
-file in @file{/etc/init}.}:
+file to @file{/etc/init}.}:
@example
# guix-daemon --build-users-group=guixbuild
a list of available keyboard layouts. Run @command{man loadkeys} for
more information.
+@anchor{manual-installation-networking}
@subsubsection Networking
Run the following command to see what your network interfaces are called:
@code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid
board, a list of possible boards will be printed.
+@c *********************************************************************
+@cindex troubleshooting, guix system
+@cindex guix system troubleshooting
+@node System Troubleshooting Tips
+@chapter System Troubleshooting Tips
+
+Guix System allows rebooting into a previous generation should the last
+one be malfunctioning, which makes it quite robust against being broken
+irreversibly. This feature depends on GRUB being correctly functioning
+though, which means that if for whatever reasons your GRUB installation
+becomes corrupted during a system reconfiguration, you may not be able
+to easily boot into a previous generation. A technique that can be used
+in this case is to @i{chroot} into your broken system and reconfigure it
+from there. Such technique is explained below.
+
+@cindex chroot, guix system
+@cindex chrooting, guix system
+@cindex repairing GRUB, via chroot
+@node Chrooting into an existing system
+@section Chrooting into an existing system
+
+This section details how to @i{chroot} to an already installed Guix
+System with the aim of reconfiguring it, for example to fix a broken
+GRUB installation. The process is similar to how it would be done on
+other GNU/Linux systems, but there are some Guix System particularities
+such as the daemon and profiles that make it worthy of explaining here.
+
+@enumerate
+@item
+Obtain a bootable image of Guix System. It is recommended the latest
+development snapshot so the kernel and the tools used are at least as as
+new as those of your installed system; it can be retrieved from the
+@url{https://ci.guix.gnu.org/search/latest/ISO-9660?query=spec:images+status:success+system:x86_64-linux+image.iso,
+https://ci.guix.gnu.org} URL. Follow the @pxref{USB Stick and DVD
+Installation} section for copying it to a bootable media.
+
+@item
+Boot the image, and proceed with the graphical text-based installer
+until your network is configured. Alternatively, you could configure
+the network manually by following the
+@ref{manual-installation-networking} section. If you get the error
+@samp{RTNETLINK answers: Operation not possible due to RF-kill}, try
+@samp{rfkill list} followed by @samp{rfkill unblock 0}, where @samp{0}
+is your device identifier (ID).
+
+@item
+Switch to a virtual console (tty) if you haven't already by pressing
+simultaneously the @kbd{Control + Alt + F4} keys. Mount your file
+system at @file{/mnt}. Assuming your root partition is
+@file{/dev/sda2}, you would do:
+
+@example sh
+mount /dev/sda2 /mnt
+@end example
+
+@item
+Mount special block devices and Linux-specific directories:
+
+@example sh
+mount --bind /proc /mnt/proc
+mount --bind /sys /mnt/sys
+mount --bind /dev /mnt/dev
+@end example
+
+If your system is EFI-based, you must also mount the ESP partition.
+Assuming it is @file{/dev/sda1}, you can do so with:
+
+@example sh
+mount /dev/sda1 /mnt/boot/efi
+@end example
+
+@item
+Enter your system via chroot:
+
+@example sh
+chroot /mnt /bin/sh
+@end example
+
+@item
+Source your @var{user} profile to setup the environment, where
+@var{user} is the user name used for the Guix System you are attempting
+to repair:
+
+@example sh
+source /home/@var{user}/.guix-profile/etc/profile
+@end example
+
+To ensure you are working with the Guix revision you normally would as
+your normal user, also source your current Guix profile:
+
+@example sh
+source /home/@var{user}/.config/guix/current/etc/profile
+@end example
+
+@item
+Start a minimal @command{guix-daemon} in the background:
+
+@example sh
+guix-daemon --build-users-group=guixbuild --disable-chroot &
+@end example
+
+@item
+Edit your Guix System configuration if needed, then reconfigure with:
+
+@example sh
+guix system reconfigure your-config.scm
+@end example
+
+@item
+Finally, you should be good to reboot the system to test your fix.
+
+@end enumerate
+
@c *********************************************************************
@node Getting Started
@chapter Getting Started
@item --delete-generations[=@var{duration}]
@itemx -d [@var{duration}]
Before starting the garbage collection process, delete all the generations
-older than @var{duration}, for all the user profiles; when run as root, this
+older than @var{duration}, for all the user profiles and home environment
+generations; when run as root, this
applies to all the profiles @emph{of all the users}.
For example, this command deletes all the generations of all your profiles
modules:
@example
-$ guix pull --list-generations
-@dots{}
+$ guix describe
Generation 19 Aug 27 2018 16:20:48
guix d894ab8
repository URL: https://git.savannah.gnu.org/git/guix.git
repository URL: https://example.org/variant-packages.git
branch: master
commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
- 11 new packages: variant-gimp, variant-emacs-with-cool-features, @dots{}
- 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
@end example
@noindent
-The output of @command{guix pull} above shows that Generation@tie{}19 includes
-both Guix and packages from the @code{variant-personal-packages} channel. Among
-the new and upgraded packages that are listed, some like @code{variant-gimp} and
-@code{variant-emacs-with-cool-features} might come from
-@code{variant-packages}, while others come from the Guix default channel.
+The output of @command{guix describe} above shows that we're now running
+Generation@tie{}19 and that it includes
+both Guix and packages from the @code{variant-personal-packages} channel
+(@pxref{Invoking guix describe}).
@node Using a Custom Guix Channel
@section Using a Custom Guix Channel
@cindex pinning, channels
@cindex replicating Guix
@cindex reproducibility, of Guix
-The @command{guix pull --list-generations} output above shows precisely which
-commits were used to build this instance of Guix. We can thus replicate it,
-say, on another machine, by providing a channel specification in
-@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
+The @command{guix describe} command shows precisely which commits were
+used to build the instance of Guix we're using (@pxref{Invoking guix
+describe}). We can replicate this instance on another machine or at a
+different point in time by providing a channel specification ``pinned''
+to these commits that looks like this:
@lisp
;; Deploy specific commits of my channels of interest.
(commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
@end lisp
-The @command{guix describe --format=channels} command can even generate this
-list of channels directly (@pxref{Invoking guix describe}). The resulting
-file can be used with the @option{-C} option of @command{guix pull}
-(@pxref{Invoking guix pull}) or @command{guix time-machine}
-(@pxref{Invoking guix time-machine}).
+To obtain this pinned channel specification, the easiest way is to run
+@command{guix describe} and to save its output in the @code{channels}
+format in a file, like so:
-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
-one machine will be exactly the same, bit for bit, as the output of the same
-command on the other machine. It also means both machines have access to all
-the source code of Guix and, transitively, to all the source code of every
-package it defines.
+@example
+guix describe -f channels > channels.scm
+@end example
+
+The resulting @file{channels.scm} file can be passed to the @option{-C}
+option of @command{guix pull} (@pxref{Invoking guix pull}) or
+@command{guix time-machine} (@pxref{Invoking guix time-machine}), as in
+this example:
+
+@example
+guix time-machine -C channels.scm -- shell python -- python3
+@end example
+
+Given the @file{channels.scm} file, the command above will always fetch
+the @emph{exact same Guix instance}, then use that instance to run the
+exact same Python (@pxref{Invoking guix shell}). On any machine, at any
+time, it ends up running the exact same binaries, bit for bit.
+
+@cindex lock files
+Pinned channels address a problem similar to ``lock files'' as
+implemented by some deployment tools---they let you pin and reproduce a
+set of packages. In the case of Guix though, you are effectively
+pinning the entire package set as defined at the given channel commits;
+in fact, you are pinning all of Guix, including its core modules and
+command-line tools. You're also getting strong guarantees that you are,
+indeed, obtaining the exact same software.
This gives you super powers, allowing you to track the provenance of binary
artifacts with very fine grain, and to reproduce software environments at
* The Store Monad:: Purely functional interface to the store.
* G-Expressions:: Manipulating build expressions.
* Invoking guix repl:: Programming Guix in Guile
+* Using Guix Interactively:: Fine-grain interaction at the REPL.
@end menu
@node Package Modules
Systems}).
@item @code{arguments} (default: @code{'()})
-The arguments that should be passed to the build system. This is a
-list, typically containing sequential keyword-value pairs.
+The arguments that should be passed to the build system (@pxref{Build
+Systems}). This is a list, typically containing sequential
+keyword-value pairs, as in this example:
+
+@lisp
+(package
+ (name "example")
+ ;; several fields omitted
+ (arguments
+ (list #:tests? #f ;skip tests
+ #:make-flags #~'("VERBOSE=1") ;pass flags to 'make'
+ #:configure-flags #~'("--enable-frobbing"))))
+@end lisp
+
+The exact set of supported keywords depends on the build system
+(@pxref{Build Systems}), but you will find that almost all of them honor
+@code{#:configure-flags}, @code{#:make-flags}, @code{#:tests?}, and
+@code{#:phases}. The @code{#:phases} keyword in particular lets you
+modify the set of build phases for your package (@pxref{Build Phases}).
@item @code{inputs} (default: @code{'()})
@itemx @code{native-inputs} (default: @code{'()})
options, and so on. Some of these custom packages can be defined
straight from the command line (@pxref{Package Transformation Options}).
This section describes how to define package variants in code. This can
-be useful in ``manifests'' (@pxref{profile-manifest,
-@option{--manifest}}) and in your own package collection
+be useful in ``manifests'' (@pxref{Writing Manifests})
+and in your own package collection
(@pxref{Creating a Channel}), among others!
@cindex inherit, for package definitions
This Boolean, @code{#t} by default, determines whether to ``validate''
the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well
as executables) previously installed by the @code{install} phase.
-
-This validation step consists in making sure that all the shared
-libraries needed by an ELF binary, which are listed as
-@code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the
-@code{DT_RUNPATH} entry of that binary. In other words, it ensures that
-running or using those binaries will not result in a ``file not found''
-error at run time. @xref{Options, @option{-rpath},, ld, The GNU
-Linker}, for more information on @code{RUNPATH}.
+@xref{phase-validate-runpath, the @code{validate-runpath} phase}, for
+details.
@item #:substitutable?
This Boolean, @code{#t} by default, tells whether the package outputs
@code{with-zef?} parameter.
@end defvr
+@defvr {Scheme Variable} rebar-build-system
+This variable is exported by @code{(guix build-system rebar)}. It
+implements a build procedure around @uref{https://rebar3.org,rebar3},
+a build system for programs written in the Erlang language.
+
+It adds both @code{rebar3} and the @code{erlang} to the set of inputs.
+Different packages can be specified with the @code{#:rebar} and
+@code{#:erlang} parameters, respectively.
+
+This build system is based on @code{gnu-build-system}, but with the
+following phases changed:
+
+@table @code
+
+@item unpack
+This phase, after unpacking the source like the @code{gnu-build-system}
+does, checks for a file @code{contents.tar.gz} at the top-level of the
+source. If this file exists, it will be unpacked, too. This eases
+handling of package hosted at @uref{https://hex.pm/},
+the Erlang and Elixir package repository.
+
+@item bootstrap
+@item configure
+There are no @code{bootstrap} and @code{configure} phase because erlang
+packages typically don’t need to be configured.
+
+@item build
+This phase runs @code{rebar3 compile}
+with the flags listed in @code{#:rebar-flags}.
+
+@item check
+Unless @code{#:tests? #f} is passed,
+this phase runs @code{rebar3 eunit},
+or some other target specified with @code{#:test-target},
+with the flags listed in @code{#:rebar-flags},
+
+@item install
+This installs the files created in the @i{default} profile, or some
+other profile specified with @code{#:install-profile}.
+
+@end table
+@end defvr
+
@defvr {Scheme Variable} texlive-build-system
This variable is exported by @code{(guix build-system texlive)}. It is
used to build TeX packages in batch mode with a specified engine. The
@code{build-expression->derivation}}).
@end defvr
+@defvr {Scheme Variable} channel-build-system
+This variable is exported by @code{(guix build-system channel)}.
+
+This build system is meant primarily for internal use. A package using
+this build system must have a channel specification as its @code{source}
+field (@pxref{Channels}); alternatively, its source can be a directory
+name, in which case an additional @code{#:commit} argument must be
+supplied to specify the commit being built (a hexadecimal string).
+
+The resulting package is a Guix instance of the given channel, similar
+to how @command{guix time-machine} would build it.
+@end defvr
+
@node Build Phases
@section Build Phases
Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
is false), copying them to the @code{debug} output when available
(@pxref{Installing Debugging Files}).
+
+@cindex RUNPATH, validation
+@anchor{phase-validate-runpath}
+@item validate-runpath
+Validate the @code{RUNPATH} of ELF binaries, unless
+@code{#:validate-runpath?} is false (@pxref{Build Systems}).
+
+This validation step consists in making sure that all the shared
+libraries needed by an ELF binary, which are listed as @code{DT_NEEDED}
+entries in its @code{PT_DYNAMIC} segment, appear in the
+@code{DT_RUNPATH} entry of that binary. In other words, it ensures that
+running or using those binaries will not result in a ``file not found''
+error at run time. @xref{Options, @option{-rpath},, ld, The GNU
+Linker}, for more information on @code{RUNPATH}.
+
@end table
Other build systems have similar phases, with some variations. For
(substitute* "Makefile"
(("PREFIX =.*")
(string-append "PREFIX = "
- out "\n")))
- #true))))))))
+ out "\n")))))))))))
@end lisp
The new phase that is inserted is written as an anonymous procedure,
@end lisp
Note that the @code{(guix monad-repl)} module extends the Guile REPL with
-new ``meta-commands'' to make it easier to deal with monadic procedures:
-@code{run-in-store}, and @code{enter-store-monad}. The former is used
+new ``commands'' to make it easier to deal with monadic procedures:
+@code{run-in-store}, and @code{enter-store-monad} (@pxref{Using Guix
+Interactively}). The former is used
to ``run'' a single monadic value through the store:
@example
Note that non-monadic values cannot be returned in the
@code{store-monad} REPL.
+Other meta-commands are available at the REPL, such as @code{,build} to
+build a file-like object (@pxref{Using Guix Interactively}).
+
The main syntactic forms to deal with monads in general are provided by
the @code{(guix monads)} module and are described below.
@code{!#}
@end example
-Without a file name argument, a Guile REPL is started:
+Without a file name argument, a Guile REPL is started, allowing for
+interactive use (@pxref{Using Guix Interactively}):
@example
$ guix repl
configuration file is loaded when spawning a @code{guile} REPL.
@end table
+@node Using Guix Interactively
+@section Using Guix Interactively
+
+@cindex interactive use
+@cindex REPL, read-eval-print loop
+The @command{guix repl} command gives you access to a warm and friendly
+@dfn{read-eval-print loop} (REPL) (@pxref{Invoking guix repl}). If
+you're getting into Guix programming---defining your own packages,
+writing manifests, defining services for Guix System or Guix Home,
+etc.---you will surely find it convenient to toy with ideas at the REPL.
+
+If you use Emacs, the most convenient way to do that is with Geiser
+(@pxref{The Perfect Setup}), but you do not have to use Emacs to enjoy
+the REPL@. When using @command{guix repl} or @command{guile} in the
+terminal, we recommend using Readline for completion and Colorized to
+get colorful output. To do that, you can run:
+
+@example
+guix install guile guile-readline guile-colorized
+@end example
+
+@noindent
+... and then create a @file{.guile} file in your home directory containing
+this:
+
+@lisp
+(use-modules (ice-9 readline) (ice-9 colorized))
+
+(activate-readline)
+(activate-colorized)
+@end lisp
+
+The REPL lets you evaluate Scheme code; you type a Scheme expression at
+the prompt, and the REPL prints what it evaluates to:
+
+@example
+$ guix repl
+scheme@@(guix-user)> (+ 2 3)
+$1 = 5
+scheme@@(guix-user)> (string-append "a" "b")
+$2 = "ab"
+@end example
+
+It becomes interesting when you start fiddling with Guix at the REPL.
+The first thing you'll want to do is to ``import'' the @code{(guix)}
+module, which gives access to the main part of the programming
+interface, and perhaps a bunch of useful Guix modules. You could type
+@code{(use-modules (guix))}, which is valid Scheme code to import a
+module (@pxref{Using Guile Modules,,, guile, GNU Guile Reference
+Manual}), but the REPL provides the @code{use} @dfn{command} as a
+shorthand notation (@pxref{REPL Commands,,, guile, GNU Guile Reference
+Manual}):
+
+@example
+scheme@@(guix-user)> ,use (guix)
+scheme@@(guix-user)> ,use (gnu packages base)
+@end example
+
+Notice that REPL commands are introduced by a leading comma. A REPL
+command like @code{use} is not valid Scheme code; it's interpreted
+specially by the REPL.
+
+Guix extends the Guile REPL with additional commands for convenience.
+Among those, the @code{build} command comes in handy: it ensures that
+the given file-like object is built, building it if needed, and returns
+its output file name(s). In the example below, we build the
+@code{coreutils} and @code{grep} packages, as well as a ``computed
+file'' (@pxref{G-Expressions, @code{computed-file}}), and we use the
+@code{scandir} procedure to list the files in Grep's @code{/bin}
+directory:
+
+@example
+scheme@@(guix-user)> ,build coreutils
+$1 = "/gnu/store/@dots{}-coreutils-8.32-debug"
+$2 = "/gnu/store/@dots{}-coreutils-8.32"
+scheme@@(guix-user)> ,build grep
+$3 = "/gnu/store/@dots{}-grep-3.6"
+scheme@@(guix-user)> ,build (computed-file "x" #~(mkdir #$output))
+building /gnu/store/@dots{}-x.drv...
+$4 = "/gnu/store/@dots{}-x"
+scheme@@(guix-user)> ,use(ice-9 ftw)
+scheme@@(guix-user)> (scandir (string-append $3 "/bin"))
+$5 = ("." ".." "egrep" "fgrep" "grep")
+@end example
+
+At a lower-level, a useful command is @code{lower}: it takes a file-like
+object and ``lowers'' it into a derivation (@pxref{Derivations}) or a
+store file:
+
+@example
+scheme@@(guix-user)> ,lower grep
+$6 = #<derivation /gnu/store/@dots{}-grep-3.6.drv => /gnu/store/@dots{}-grep-3.6 7f0e639115f0>
+scheme@@(guix-user)> ,lower (plain-file "x" "Hello!")
+$7 = "/gnu/store/@dots{}-x"
+@end example
+
+The full list of REPL commands can be seen by typing @code{,help guix}
+and is given below for reference.
+
+@deffn {REPL command} build @var{object}
+Lower @var{object} and build it if it's not already built, returning its
+output file name(s).
+@end deffn
+
+@deffn {REPL command} lower @var{object}
+Lower @var{object} into a derivation or store file name and return it.
+@end deffn
+
+@deffn {REPL command} verbosity @var{level}
+Change build verbosity to @var{level}.
+
+This is similar to the @option{--verbosity} command-line option
+(@pxref{Common Build Options}): level 0 means total silence, level 1
+shows build events only, and higher levels print build logs.
+@end deffn
+
+@deffn {REPL command} run-in-store @var{exp}
+Run @var{exp}, a monadic expresssion, through the store monad.
+@xref{The Store Monad}, for more information.
+@end deffn
+
+@deffn {REPL command} enter-store-monad
+Enter a new REPL to evaluate monadic expressions (@pxref{The Store
+Monad}). You can quit this ``inner'' REPL by typing @code{,q}.
+@end deffn
+
@c *********************************************************************
@node Utilities
@chapter Utilities
@end example
Additional options include:
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@end table
+
+@item hexpm
+@cindex hexpm
+Import metadata from the hex.pm Erlang and Elixir package repository
+@uref{https://hex.pm, hex.pm}, as in this example:
+
+@example
+guix import hexpm stun
+@end example
+
+The importer tries to determine the build system used by the package.
+
+The hexpm importer also allows you to specify a version string:
+
+@example
+guix import hexpm cf@@0.3.0
+@end example
+
+Additional options include:
+
@table @code
@item --recursive
@itemx -r
@end example
@item --list-updaters
-@itemx -L
List available updaters and exit (see @option{--type} above).
For each updater, display the fraction of packages it covers; at the
Use @var{host} as the OpenPGP key server when importing a public key.
@item --load-path=@var{directory}
+@itemx -L @var{directory}
Add @var{directory} to the front of the package module search path
(@pxref{Package Modules}).
@node Invoking guix style
@section Invoking @command{guix style}
-The @command{guix style} command helps packagers style their package
-definitions according to the latest fashionable trends. The command
-currently provides the following styling rules:
+The @command{guix style} command helps users and packagers alike style
+their package definitions and configuration files according to the
+latest fashionable trends. It can either reformat whole files, with the
+@option{--whole-file} option, or apply specific @dfn{styling rules} to
+individual package definitions. The command currently provides the
+following styling rules:
@itemize
@item
to select the style rule, the default rule being @code{format}---see
below.
+To reformat entire source files, the syntax is:
+
+@example
+guix style --whole-file @var{file}@dots{}
+@end example
+
The available options are listed below.
@table @code
@itemx -n
Show source file locations that would be edited but do not modify them.
+@item --whole-file
+@itemx -f
+Reformat the given files in their entirety. In that case, subsequent
+arguments are interpreted as file names (rather than package names), and
+the @option{--styling} option has no effect.
+
+As an example, here is how you might reformat your operating system
+configuration (you need write permissions for the file):
+
+@example
+guix style -f /etc/config.scm
+@end example
+
@item --styling=@var{rule}
@itemx -S @var{rule}
Apply @var{rule}, one of the following styling rules:
fine-grain control over when inputs should be simplified.
@end table
+@item --list-stylings
+@itemx -l
+List and describe the available styling rules and exit.
+
@item --load-path=@var{directory}
@itemx -L @var{directory}
Add @var{directory} to the front of the package module search path
Only disable the checkers specified in a comma-separated list using the
names returned by @option{--list-checkers}.
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Consider the package @var{expr} evaluates to.
+
+This is useful to unambiguously designate packages, as in this example:
+
+@example
+guix lint -c archival -e '(@@ (gnu packages guile) guile-3.0)'
+@end example
+
@item --no-network
@itemx -n
Only enable the checkers that do not depend on Internet access.
The command output looks like this:
@smallexample
-$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
-updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
-updating list of substitutes from 'https://guix.example.org'... 100.0%
+$ guix challenge \
+ --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org" \
+ openssl git pius coreutils grep
+updating substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
+updating substitutes from 'https://guix.example.org'... 100.0%
/gnu/store/@dots{}-openssl-1.0.2d contents differ:
local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
@dots{}
-6,406 store items were analyzed:
- - 4,749 (74.1%) were identical
- - 525 (8.2%) differed
- - 1,132 (17.7%) were inconclusive
+5 store items were analyzed:
+ - 2 (40.0%) were identical
+ - 3 (60.0%) differed
+ - 0 (0.0%) 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.
+In this example, @command{guix challenge} queries all the substitute
+servers for each of the fives packages specified on the command line.
+It then reports those store items for which the servers obtained a
+result different from the local build (if it exists) and/or different
+from one another; here, the @samp{local hash} lines indicate that a
+local build result was available for each of these packages and shows
+its hash.
@cindex non-determinism, in package builds
As an example, @code{guix.example.org} always gets a different answer.
same build result as you did with:
@example
-$ guix challenge @var{package}
+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:
@example
-guix challenge @var{options} [@var{packages}@dots{}]
+guix challenge @var{options} @var{argument}@dots{}
@end example
+@noindent
+where @var{argument} is a package specification such as
+@code{guile@@2.0} or @code{glibc:debug} or, alternatively, a store file
+name as returned, for example, by @command{guix build} or @command{guix
+gc --list-live}.
+
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
$ 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%
+updating 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)
instantiates that configuration, and makes it the default GRUB boot
entry (@pxref{Invoking guix system}).
+@quotation Note
+We recommend that you keep this @file{my-system-config.scm} file safe
+and under version control to easily track changes to your configuration.
+@end quotation
+
The normal way to change the system configuration is by updating this
file and re-running @command{guix system reconfigure}. One should never
have to touch files in @file{/etc} or to run commands that modify the
@end table
@end deftp
+@deftp {Data Type} guix-extension
+
+This data type represents the parameters of the Guix build daemon that
+are extendable. This is the type of the object that must be used within
+a guix service extension.
+@xref{Service Composition}, for more information.
+
+@table @asis
+@item @code{authorized-keys} (default: @code{'()})
+A list of file-like objects where each element contains a public key.
+
+@item @code{substitute-urls} (default: @code{'()})
+A list of strings where each element is a substitute URL.
+
+@item @code{chroot-directories} (default: @code{'()})
+A list of file-like objects or strings pointing to additional directories the build daemon can use.
+@end table
+@end deftp
+
@deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
Run @var{udev}, which populates the @file{/dev} directory dynamically.
udev rules can be provided as a list of files through the @var{rules}
@samp{pam_limits} man page from the @code{linux-pam} package.
@end deffn
+@defvr {Scheme Variable} greetd-service-type
+@uref{https://git.sr.ht/~kennylevinsen/greetd, @code{greetd}} is a minimal and
+flexible login manager daemon, that makes no assumptions about what you
+want to launch.
+
+If you can run it from your shell in a TTY, greetd can start it. If it
+can be taught to speak a simple JSON-based IPC protocol, then it can be
+a geeter.
+
+@code{greetd-service-type} provides necessary infrastructure for logging
+in users, including:
+
+@itemize @bullet
+@item
+@code{greetd} PAM service
+
+@item
+Special variation of @code{pam-mount} to mount @code{XDG_RUNTIME_DIR}
+@end itemize
+
+Here is example of switching from @code{mingetty-service-type} to
+@code{greetd-service-type}, and how different terminals could be:
+
+@lisp
+ (append
+ (modify-services %base-services
+ ;; greetd-service-type provides "greetd" PAM service
+ (delete login-service-type)
+ ;; and can be used in place of mingetty-service-type
+ (delete mingetty-service-type))
+ (list
+ (service greetd-service-type
+ (greetd-configuration
+ (terminals
+ (list
+ ;; we can make any terminal active by default
+ (greetd-terminal-configuration (terminal-vt "1") (terminal-switch #t))
+ ;; we can make environment without XDG_RUNTIME_DIR set
+ ;; even provide our own environment variables
+ (greetd-terminal-configuration
+ (terminal-vt "2")
+ (default-session-command
+ (greetd-agreety-session
+ (extra-env '(("MY_VAR" . "1")))
+ (xdg-env? #f))))
+ ;; we can use different shell instead of default bash
+ (greetd-terminal-configuration
+ (terminal-vt "3")
+ (default-session-command
+ (greetd-agreety-session (command (file-append zsh "/bin/zsh")))))
+ ;; we can use any other executable command as greeter
+ (greetd-terminal-configuration
+ (terminal-vt "4")
+ (default-session-command (program-file "my-noop-greeter" #~(exit))))
+ (greetd-terminal-configuration (terminal-vt "5"))
+ (greetd-terminal-configuration (terminal-vt "6"))))))
+ ;; mingetty-service-type can be used in parallel
+ ;; if needed to do so, do not (delete login-service-type)
+ ;; as illustrated above
+ #| (service mingetty-service-type (mingetty-configuration (tty "tty8"))) |#))
+@end lisp
+@end defvr
+
+@deftp {Data Type} greetd-configuration
+Configuration record for the @code{greetd-service-type}.
+@table @asis
+
+@item @code{motd}
+A file-like object containing the ``message of the day''.
+
+@item @code{allow-empty-passwords?} (default: @code{#t})
+Allow empty passwords by default so that first-time users can log in when
+the 'root' account has just been created.
+
+@item @code{terminals} (default: @code{'()})
+List of @code{greetd-terminal-configuration} per terminal for which
+@code{greetd} should be started.
+@end table
+@end deftp
+
+@deftp {Data Type} greetd-terminal-configuration
+Configuration record for per terminal greetd daemon service.
+
+@table @asis
+@item @code{greetd} (default: @code{greetd})
+The greetd package to use.
+
+@item @code{config-file-name}
+Configuration file name to use for greetd daemon. Generally, autogenerated
+derivation based on @code{terminal-vt} value.
+
+@item @code{log-file-name}
+Log file name to use for greetd daemon. Generally, autogenerated
+name based on @code{terminal-vt} value.
+
+@item @code{terminal-vt} (default: @samp{"7"})
+The VT to run on. Use of a specific VT with appropriate conflict avoidance
+is recommended.
+
+@item @code{terminal-switch} (default: @code{#f})
+Make this terminal active on start of @code{greetd}.
+
+@item @code{default-session-user} (default: @samp{"greeter"})
+The user to use for running the greeter.
+
+@item @code{default-session-command} (default: @code{(greetd-agreety-session)})
+Can be either instance of @code{greetd-agreety-session} configuration or
+@code{gexp->script} like object to use as greeter.
+
+@end table
+@end deftp
+
+@deftp {Data Type} greetd-agreety-session
+Configuration record for the agreety greetd greeter.
+
+@table @asis
+@item @code{agreety} (default: @code{greetd})
+The package with @command{/bin/agreety} command.
+
+@item @code{command} (default: @code{(file-append bash "/bin/bash")})
+Command to be started by @command{/bin/agreety} on successful login.
+
+@item @code{command-args} (default: @code{'("-l")})
+Command arguments to pass to command.
+
+@item @code{extra-env} (default: @code{'()})
+Extra environment variables to set on login.
+
+@item @code{xdg-env?} (default: @code{#t})
+If true @code{XDG_RUNTIME_DIR} and @code{XDG_SESSION_TYPE} will be set
+before starting command. One should note that, @code{extra-env} variables
+are set right after mentioned variables, so that they can be overriden.
+
+@end table
+@end deftp
+
@node Scheduled Job Execution
@subsection Scheduled Job Execution
@item @code{files}
The list of files or file glob patterns to rotate.
-@item @code{options} (default: @code{'()})
+@vindex %default-log-rotation-options
+@item @code{options} (default: @code{%default-log-rotation-options})
The list of rottlog options for this rotation (@pxref{Configuration
-parameters,,, rottlog, GNU Rot[t]lg Manual}).
+parameters,,, rottlog, GNU Rot[t]log Manual}).
@item @code{post-rotate} (default: @code{#f})
Either @code{#f} or a gexp to execute once the rotation has completed.
@end table
@end deftp
+@cindex logging, anonymization
+@subheading Anonip Service
+
+Anonip is a privacy filter that removes IP address from web server logs.
+This service creates a FIFO and filters any written lines with anonip
+before writing the filtered log to a target file.
+
+The following example sets up the FIFO
+@file{/var/run/anonip/https.access.log} and writes the filtered log file
+@file{/var/log/anonip/https.access.log}.
+
+@lisp
+(service anonip-service-type
+ (anonip-configuration
+ (input "/var/run/anonip/https.access.log")
+ (output "/var/log/anonip/https.access.log")))
+@end lisp
+
+Configure your web server to write its logs to the FIFO at
+@file{/var/run/anonip/https.access.log} and collect the anonymized log
+file at @file{/var/web-logs/https.access.log}.
+
+@deftp {Data Type} anonip-configuration
+This data type represents the configuration of anonip.
+It has the following parameters:
+
+@table @asis
+@item @code{anonip} (default: @code{anonip})
+The anonip package to use.
+
+@item @code{input}
+The file name of the input log file to process. The service creates a
+FIFO of this name. The web server should write its logs to this FIFO.
+
+@item @code{output}
+The file name of the processed log file.
+@end table
+
+The following optional settings may be provided:
+
+@table @asis
+@item @code{skip-private?}
+When @code{#true} do not mask addresses in private ranges.
+
+@item @code{column}
+A 1-based indexed column number. Assume IP address is in the specified
+column (default is 1).
+
+@item @code{replacement}
+Replacement string in case address parsing fails, e.g. @code{"0.0.0.0"}.
+
+@item @code{ipv4mask}
+Number of bits to mask in IPv4 addresses.
+
+@item @code{ipv6mask}
+Number of bits to mask in IPv6 addresses.
+
+@item @code{increment}
+Increment the IP address by the given number. By default this is zero.
+
+@item @code{delimiter}
+Log delimiter string.
+
+@item @code{regex}
+Regular expression for detecting IP addresses. Use this instead of @code{column}.
+@end table
+@end deftp
+
+
@node Networking Setup
@subsection Networking Setup
This is the type for statically-configured network interfaces. Its
value must be a list of @code{static-networking} records. Each of them
declares a set of @dfn{addresses}, @dfn{routes}, and @dfn{links}, as
-show below.
+shown below.
@cindex network interface controller (NIC)
@cindex NIC, networking interface controller
described below.
@end defvr
-@deftp {Data Type} opendht-configuration
-This is the data type for the OpenDHT service configuration.
-
@c The fields documentation has been auto-generated using the
@c configuration->documentation procedure from
@c (gnu services configuration).
+@deftp {Data Type} opendht-configuration
Available @code{opendht-configuration} fields are:
-@deftypevr {@code{opendht-configuration} parameter} package opendht
+@table @asis
+@item @code{opendht} (default: @code{opendht}) (type: file-like)
The @code{opendht} package to use.
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} boolean peer-discovery?
+@item @code{peer-discovery?} (default: @code{#f}) (type: boolean)
Whether to enable the multicast local peer discovery mechanism.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} boolean enable-logging?
+@item @code{enable-logging?} (default: @code{#f}) (type: boolean)
Whether to enable logging messages to syslog. It is disabled by default
as it is rather verbose.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} boolean debug?
+@item @code{debug?} (default: @code{#f}) (type: boolean)
Whether to enable debug-level logging messages. This has no effect if
logging is disabled.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} maybe-string bootstrap-host
+@item @code{bootstrap-host} (default: @code{"bootstrap.jami.net:4222"}) (type: maybe-string)
The node host name that is used to make the first connection to the
network. A specific port value can be provided by appending the
@code{:PORT} suffix. By default, it uses the Jami bootstrap nodes, but
any host can be specified here. It's also possible to disable
-bootsrapping by setting this to the @code{'disabled} symbol.
+bootstrapping by explicitly setting this field to the
+@code{'unset} value.
-Defaults to @samp{"bootstrap.jami.net:4222"}.
+@item @code{port} (default: @code{4222}) (type: maybe-number)
+The UDP port to bind to. When left unspecified, an available port is
+automatically selected.
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} maybe-number port
-The UDP port to bind to. When set to @code{'disabled}, an available
-port is automatically selected.
-
-Defaults to @samp{4222}.
-
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port
+@item @code{proxy-server-port} (type: maybe-number)
Spawn a proxy server listening on the specified port.
-Defaults to @samp{disabled}.
-
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port-tls
+@item @code{proxy-server-port-tls} (type: maybe-number)
Spawn a proxy server listening to TLS connections on the specified port.
-Defaults to @samp{disabled}.
-
-@end deftypevr
+@end table
@end deftp
@cindex Tor
@item @code{xorg-configuration} (default: @code{(xorg-configuration)})
Configuration of the Xorg graphical server.
-@item @code{xsession} (default: @code{(xinitrc)})
+@item @code{x-session} (default: @code{(xinitrc)})
Script to run before starting a X session.
@item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper})
@item @code{numlock} (default: "on")
Valid values are @samp{"on"}, @samp{"off"} or @samp{"none"}.
-@item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")})
+@item @code{halt-command} (default @code{#~(string-append #$shepherd "/sbin/halt")})
Command to run when halting.
@item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")})
(list cups-filters epson-inkjet-printer-escpr hplip-minimal))))
@end lisp
-Note: If you wish to use the Qt5 based GUI which comes with the hplip
+@quotation Note
+If you wish to use the Qt5 based GUI which comes with the hplip
package then it is suggested that you install the @code{hplip} package,
either in your OS configuration file or as your user.
+@end quotation
The available configuration parameters follow. Each parameter
definition is preceded by its type; for example, @samp{string-list foo}
provided by @code{(gnu services dbus)} and @code{(gnu services desktop)}
are described below.
-@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
+@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()] @
+ [#:verbose?]
Return a service that runs the ``system bus'', using @var{dbus}, with
-support for @var{services}.
+support for @var{services}. When @var{verbose?} is true, it causes the
+@samp{DBUS_VERBOSE} environment variable to be set to @samp{1}; a
+verbose-enabled D-Bus package such as @code{dbus-verbose} should be
+provided as @var{dbus} in this scenario. The verbose output is logged
+to @file{/var/log/dbus-daemon.log}.
@uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process communication
facility. Its system bus is used to allow system services to communicate
@end table
@end deftp
+@defvr {Scheme Variable} seatd-service-type
+@uref{https://sr.ht/~kennylevinsen/seatd/, seatd} is a minimal seat
+management daemon.
+
+Seat management takes care of mediating access to shared devices (graphics,
+input), without requiring the applications needing access to be root.
+
+@lisp
+(append
+ (list
+ ;; make sure seatd is running
+ (service seatd-service-type))
+
+ ;; normally one would want %base-services
+ %base-services)
+
+@end lisp
+@end defvr
+
+@deftp {Data Type} seatd-configuration
+Configuration record for the seatd daemon service.
+
+@table @asis
+@item @code{seatd} (default: @code{seatd})
+The seatd package to use.
+
+@item @code{user} (default: @samp{"root"})
+User to own the seatd socket.
+
+@item @code{group} (default: @samp{"users"})
+Group to own the seatd socket.
+
+@item @code{socket} (default: @samp{"/run/seatd.sock"})
+Where to create the seatd socket.
+
+@item @code{logfile} (default: @samp{"/var/log/seatd.log"})
+Log file to write to.
+
+@item @code{loglevel} (default: @samp{"error"})
+Log level to output logs. Possible values: @samp{"silent"}, @samp{"error"},
+@samp{"info"} and @samp{"debug"}.
+
+@end table
+@end deftp
+
+
@node Sound Services
@subsection Sound Services
users and daemons on the local machine, as well as permitting email to
remote servers. Run @command{man smtpd.conf} for more information.
+@item @code{setgid-commands?} (default: @code{#t})
+Make the following commands setgid to @code{smtpq} so they can be
+executed: @command{smtpctl}, @command{sendmail}, @command{send-mail},
+@command{makemap}, @command{mailq}, and @command{newaliases}.
+@xref{Setuid Programs}, for more information on setgid programs.
@end table
@end deftp
definition is preceded by its type; for example, @samp{string-list foo}
indicates that the @code{foo} parameter should be specified as a list of
strings. Types starting with @code{maybe-} denote parameters that won't
-show up in @code{prosody.cfg.lua} when their value is @code{'disabled}.
+show up in @code{prosody.cfg.lua} when their value is left unspecified.
There is also a way to specify the configuration as a string, if you
have an old @code{prosody.cfg.lua} file that you want to port over from
@samp{"john.smith@@example.com"} then you need to add a host
@samp{"example.com"}. All options in this list will apply only to this host.
-Note: the name @emph{virtual} host is used in configuration to avoid confusion with
+@quotation Note
+The name @emph{virtual} host is used in configuration to avoid confusion with
the actual physical host that Prosody is installed on. A single Prosody
instance can serve many domains, each one defined as a VirtualHost entry in
Prosody's configuration. Conversely a server that hosts a single domain would
have just one VirtualHost entry.
See @url{https://prosody.im/doc/configure#virtual_host_settings}.
+@end quotation
Available @code{virtualhost-configuration} fields are:
Available @code{jami-configuration} fields are:
@table @asis
-@item @code{jamid} (default: @code{libjami}) (type: package)
+@item @code{libjami} (default: @code{libjami}) (type: package)
The Jami daemon package to use.
-@item @code{dbus} (default: @code{dbus}) (type: package)
+@item @code{dbus} (default: @code{dbus-for-jami}) (type: package)
The D-Bus package to use to start the required D-Bus session.
@item @code{nss-certs} (default: @code{nss-certs}) (type: package)
@item @code{auto-answer?} (default: @code{#f}) (type: boolean)
Whether to force automatic answer to incoming calls.
-@item @code{accounts} (default: @code{disabled}) (type: maybe-jami-account-list)
+@item @code{accounts} (type: maybe-jami-account-list)
A list of Jami accounts to be (re-)provisioned every time the Jami
daemon service starts. When providing this field, the account
directories under @file{/var/lib/jami/} are recreated every time the
readable only to the @samp{root} user (i.e., not in the store), to guard
against leaking the secret key material of the Jami account it contains.
-@item @code{allowed-contacts} (default: @code{disabled}) (type: maybe-account-fingerprint-list)
+@item @code{allowed-contacts} (type: maybe-account-fingerprint-list)
The list of allowed contacts for the account, entered as their 40
characters long fingerprint. Messages or calls from accounts not in
-that list will be rejected. When unspecified, the configuration of the
-account archive is used as-is with respect to contacts and public
+that list will be rejected. When left specified, the configuration of
+the account archive is used as-is with respect to contacts and public
inbound calls/messaging allowance, which typically defaults to allow any
contact to communicate with the account.
-@item @code{moderators} (default: @code{disabled}) (type: maybe-account-fingerprint-list)
+@item @code{moderators} (type: maybe-account-fingerprint-list)
The list of contacts that should have moderation privileges (to ban,
mute, etc. other users) in rendezvous conferences, entered as their 40
-characters long fingerprint. When unspecified, the configuration of the
-account archive is used as-is with respect to moderation, which
+characters long fingerprint. When left unspecified, the configuration
+of the account archive is used as-is with respect to moderation, which
typically defaults to allow anyone to moderate.
-@item @code{rendezvous-point?} (default: @code{disabled}) (type: maybe-boolean)
+@item @code{rendezvous-point?} (type: maybe-boolean)
Whether the account should operate in the rendezvous mode. In this
mode, all the incoming audio/video calls are mixed into a conference.
When left unspecified, the value from the account archive prevails.
-@item @code{peer-discovery?} (default: @code{disabled}) (type: maybe-boolean)
+@item @code{peer-discovery?} (type: maybe-boolean)
Whether peer discovery should be enabled. Peer discovery is used to
discover other OpenDHT nodes on the local network, which can be useful
to maintain communication between devices on such network even when the
connection to the the Internet has been lost. When left unspecified,
the value from the account archive prevails.
-@item @code{bootstrap-hostnames} (default: @code{disabled}) (type: maybe-string-list)
+@item @code{bootstrap-hostnames} (type: maybe-string-list)
A list of hostnames or IPs pointing to OpenDHT nodes, that should be
used to initially join the OpenDHT network. When left unspecified, the
value from the account archive prevails.
-@item @code{name-server-uri} (default: @code{disabled}) (type: maybe-string)
+@item @code{name-server-uri} (type: maybe-string)
The URI of the name server to use, that can be used to retrieve the
account fingerprint for a registered username.
server log to ensure that Mumble is using the cipher suites that you
expected it to.
-Note: Changing this option may impact the backwards compatibility of your
+@quotation Note
+Changing this option may impact the backwards compatibility of your
Mumble-Server server, and can remove the ability for older Mumble clients to be able to connect to it.
+@end quotation
@item @code{public-registration} (default: @code{#f})
Must be a @code{<mumble-server-public-registration-configuration>}
@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm
The TCP congestion-control algorithm to use for peer connections,
specified using a string recognized by the operating system in calls to
-@code{setsockopt} (or set to @code{disabled}, in which case the
-operating-system default is used).
+@code{setsockopt}. When left unspecified, the operating-system default
+is used.
Note that on GNU/Linux systems, the kernel must be configured to allow
processes to use a congestion-control algorithm not in the default set;
the default port is 80, and a different port can be specified
explicitly.
+@item @code{extra-content}
+A string or list of strings to add to the upstream block.
+
@end table
@end deftp
@c %automatically generated documentation
+@deftp {Data Type} openvpn-client-configuration
Available @code{openvpn-client-configuration} fields are:
-@deftypevr {@code{openvpn-client-configuration} parameter} package openvpn
+@table @asis
+@item @code{openvpn} (default: @code{openvpn}) (type: file-like)
The OpenVPN package.
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} string pid-file
+@item @code{pid-file} (default: @code{"/var/run/openvpn/openvpn.pid"}) (type: string)
The OpenVPN pid file.
-Defaults to @samp{"/var/run/openvpn/openvpn.pid"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} proto proto
+@item @code{proto} (default: @code{udp}) (type: proto)
The protocol (UDP or TCP) used to open a channel between clients and
servers.
-Defaults to @samp{udp}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} dev dev
+@item @code{dev} (default: @code{tun}) (type: dev)
The device type used to represent the VPN connection.
-Defaults to @samp{tun}.
-
-@end deftypevr
-
-If you do not have some of these files (eg.@: you use a username and
-password), you can disable any of the following three fields by setting
-it to @code{'disabled}.
-
-@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string ca
+@item @code{ca} (default: @code{"/etc/openvpn/ca.crt"}) (type: maybe-string)
The certificate authority to check connections against.
-Defaults to @samp{"/etc/openvpn/ca.crt"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string cert
+@item @code{cert} (default: @code{"/etc/openvpn/client.crt"}) (type: maybe-string)
The certificate of the machine the daemon is running on. It should be
signed by the authority given in @code{ca}.
-Defaults to @samp{"/etc/openvpn/client.crt"}.
-
-@end deftypevr
+@item @code{key} (default: @code{"/etc/openvpn/client.key"}) (type: maybe-string)
+The key of the machine the daemon is running on. It must be the key
+whose certificate is @code{cert}.
-@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string key
-The key of the machine the daemon is running on. It must be the key whose
-certificate is @code{cert}.
-
-Defaults to @samp{"/etc/openvpn/client.key"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} boolean comp-lzo?
+@item @code{comp-lzo?} (default: @code{#t}) (type: boolean)
Whether to use the lzo compression algorithm.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-key?
+@item @code{persist-key?} (default: @code{#t}) (type: boolean)
Don't re-read key files across SIGUSR1 or --ping-restart.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-tun?
+@item @code{persist-tun?} (default: @code{#t}) (type: boolean)
Don't close and reopen TUN/TAP device or run up/down scripts across
SIGUSR1 or --ping-restart restarts.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} boolean fast-io?
+@item @code{fast-io?} (default: @code{#f}) (type: boolean)
(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
poll/epoll/select prior to the write operation.
-Defaults to @samp{#f}.
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} number verbosity
+@item @code{verbosity} (default: @code{3}) (type: number)
Verbosity level.
-Defaults to @samp{3}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} tls-auth-client tls-auth
+@item @code{tls-auth} (default: @code{#f}) (type: tls-auth-client)
Add an additional layer of HMAC authentication on top of the TLS control
channel to protect against DoS attacks.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string auth-user-pass
+@item @code{auth-user-pass} (type: maybe-string)
Authenticate with server using username/password. The option is a file
-containing username/password on 2 lines. Do not use a file-like object as it
-would be added to the store and readable by any user.
-
-Defaults to @samp{'disabled}.
-@end deftypevr
+containing username/password on 2 lines. Do not use a file-like object
+as it would be added to the store and readable by any user.
-@deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage?
+@item @code{verify-key-usage?} (default: @code{#t}) (type: key-usage)
Whether to check the server certificate has server usage extension.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} bind bind?
+@item @code{bind?} (default: @code{#f}) (type: bind)
Bind to a specific local port number.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} resolv-retry resolv-retry?
+@item @code{resolv-retry?} (default: @code{#t}) (type: resolv-retry)
Retry resolving server address.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} openvpn-remote-list remote
+@item @code{remote} (default: @code{()}) (type: openvpn-remote-list)
A list of remote servers to connect to.
-Defaults to @samp{()}.
-
+@deftp {Data Type} openvpn-remote-configuration
Available @code{openvpn-remote-configuration} fields are:
-@deftypevr {@code{openvpn-remote-configuration} parameter} string name
+@table @asis
+@item @code{name} (default: @code{"my-server"}) (type: string)
Server name.
-Defaults to @samp{"my-server"}.
+@item @code{port} (default: @code{1194}) (type: number)
+Port number the server listens to.
-@end deftypevr
+@end table
-@deftypevr {@code{openvpn-remote-configuration} parameter} number port
-Port number the server listens to.
+@end deftp
-Defaults to @samp{1194}.
+@end table
-@end deftypevr
+@end deftp
-@end deftypevr
@c %end of automatic openvpn-client documentation
@c %automatically generated documentation
+@deftp {Data Type} openvpn-server-configuration
Available @code{openvpn-server-configuration} fields are:
-@deftypevr {@code{openvpn-server-configuration} parameter} package openvpn
+@table @asis
+@item @code{openvpn} (default: @code{openvpn}) (type: file-like)
The OpenVPN package.
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} string pid-file
+@item @code{pid-file} (default: @code{"/var/run/openvpn/openvpn.pid"}) (type: string)
The OpenVPN pid file.
-Defaults to @samp{"/var/run/openvpn/openvpn.pid"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} proto proto
+@item @code{proto} (default: @code{udp}) (type: proto)
The protocol (UDP or TCP) used to open a channel between clients and
servers.
-Defaults to @samp{udp}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} dev dev
+@item @code{dev} (default: @code{tun}) (type: dev)
The device type used to represent the VPN connection.
-Defaults to @samp{tun}.
-
-@end deftypevr
-
-If you do not have some of these files (eg.@: you use a username and
-password), you can disable any of the following three fields by setting
-it to @code{'disabled}.
-
-@deftypevr {@code{openvpn-server-configuration} parameter} maybe-string ca
+@item @code{ca} (default: @code{"/etc/openvpn/ca.crt"}) (type: maybe-string)
The certificate authority to check connections against.
-Defaults to @samp{"/etc/openvpn/ca.crt"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} maybe-string cert
+@item @code{cert} (default: @code{"/etc/openvpn/client.crt"}) (type: maybe-string)
The certificate of the machine the daemon is running on. It should be
signed by the authority given in @code{ca}.
-Defaults to @samp{"/etc/openvpn/client.crt"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} maybe-string key
-The key of the machine the daemon is running on. It must be the key whose
-certificate is @code{cert}.
-
-Defaults to @samp{"/etc/openvpn/client.key"}.
+@item @code{key} (default: @code{"/etc/openvpn/client.key"}) (type: maybe-string)
+The key of the machine the daemon is running on. It must be the key
+whose certificate is @code{cert}.
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} boolean comp-lzo?
+@item @code{comp-lzo?} (default: @code{#t}) (type: boolean)
Whether to use the lzo compression algorithm.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-key?
+@item @code{persist-key?} (default: @code{#t}) (type: boolean)
Don't re-read key files across SIGUSR1 or --ping-restart.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-tun?
+@item @code{persist-tun?} (default: @code{#t}) (type: boolean)
Don't close and reopen TUN/TAP device or run up/down scripts across
SIGUSR1 or --ping-restart restarts.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} boolean fast-io?
+@item @code{fast-io?} (default: @code{#f}) (type: boolean)
(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
poll/epoll/select prior to the write operation.
-Defaults to @samp{#f}.
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} number verbosity
+@item @code{verbosity} (default: @code{3}) (type: number)
Verbosity level.
-Defaults to @samp{3}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} tls-auth-server tls-auth
+@item @code{tls-auth} (default: @code{#f}) (type: tls-auth-server)
Add an additional layer of HMAC authentication on top of the TLS control
channel to protect against DoS attacks.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} number port
+@item @code{port} (default: @code{1194}) (type: number)
Specifies the port number on which the server listens.
-Defaults to @samp{1194}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} ip-mask server
+@item @code{server} (default: @code{"10.8.0.0 255.255.255.0"}) (type: ip-mask)
An ip and mask specifying the subnet inside the virtual network.
-Defaults to @samp{"10.8.0.0 255.255.255.0"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} cidr6 server-ipv6
+@item @code{server-ipv6} (default: @code{#f}) (type: cidr6)
A CIDR notation specifying the IPv6 subnet inside the virtual network.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} string dh
+@item @code{dh} (default: @code{"/etc/openvpn/dh2048.pem"}) (type: string)
The Diffie-Hellman parameters file.
-Defaults to @samp{"/etc/openvpn/dh2048.pem"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} string ifconfig-pool-persist
+@item @code{ifconfig-pool-persist} (default: @code{"/etc/openvpn/ipp.txt"}) (type: string)
The file that records client IPs.
-Defaults to @samp{"/etc/openvpn/ipp.txt"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} gateway redirect-gateway?
+@item @code{redirect-gateway?} (default: @code{#f}) (type: gateway)
When true, the server will act as a gateway for its clients.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} boolean client-to-client?
+@item @code{client-to-client?} (default: @code{#f}) (type: boolean)
When true, clients are allowed to talk to each other inside the VPN.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} keepalive keepalive
+@item @code{keepalive} (default: @code{(10 120)}) (type: keepalive)
Causes ping-like messages to be sent back and forth over the link so
that each side knows when the other side has gone down. @code{keepalive}
requires a pair. The first element is the period of the ping sending,
and the second element is the timeout before considering the other side
down.
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} number max-clients
+@item @code{max-clients} (default: @code{100}) (type: number)
The maximum number of clients.
-Defaults to @samp{100}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} string status
+@item @code{status} (default: @code{"/var/run/openvpn/status"}) (type: string)
The status file. This file shows a small report on current connection.
It is truncated and rewritten every minute.
-Defaults to @samp{"/var/run/openvpn/status"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} openvpn-ccd-list client-config-dir
+@item @code{client-config-dir} (default: @code{()}) (type: openvpn-ccd-list)
The list of configuration for some clients.
-Defaults to @samp{()}.
-
-Available @code{openvpn-ccd-configuration} fields are:
-
-@deftypevr {@code{openvpn-ccd-configuration} parameter} string name
-Client name.
-
-Defaults to @samp{"client"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask iroute
-Client own network
-
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask ifconfig-push
-Client VPN IP.
-
-Defaults to @samp{#f}.
-
-@end deftypevr
+@end table
-@end deftypevr
+@end deftp
@c %end of automatic openvpn-server documentation
@end deffn
Each parameter definition is preceded by its type; for example,
-@samp{boolean foo} indicates that the @code{foo} parameter
-should be specified as a boolean. Types starting with
-@code{maybe-} denote parameters that won't show up in TLP config file
-when their value is @code{'disabled}.
+@samp{boolean foo} indicates that the @code{foo} parameter should be
+specified as a boolean. Types starting with @code{maybe-} denote
+parameters that won't show up in TLP config file when their value is
+left unset, or is explicitly set to the @code{'unset} value.
@c The following documentation was initially generated by
@c (generate-tlp-documentation) in (gnu services pm). Manually maintained
An association list of hooks. These provide a way to execute arbitrary
code upon certain events, like a build result being processed.
+@item @code{parallel-hooks} (default: @var{'()})
+Hooks can be configured to run in parallel. This parameter is an
+association list of hooks to do in parallel, where the key is the symbol
+for the hook and the value is the number of threads to run.
+
@item @code{guile} (default: @code{guile-3.0-latest})
The Guile package with which to run the Guix Build Coordinator.
can be written to swap and this is a method to limit how much memory can
be used. It accepts a string and can be a number of bytes or use a
suffix, eg.: @code{"2G"}.
-@item @code{priority} (default @code{-1})
+@item @code{priority} (default @code{#f})
This is the priority of the swap device created from the zram device.
-@code{swapon} accepts values between -1 and 32767, with higher values
-indicating higher priority. Higher priority swap will generally be used
-first.
+@xref{Swap Space} for a description of swap priorities. You might want
+to set a specific priority for the zram device, otherwise it could end
+up not being used much for the reasons described there.
@end table
@end deftp
--expose=$HOME --share=$HOME/tmp=/exchange
@end example
+The @option{--share} and @option{--expose} options can also be passed to
+the generated script to bind-mount additional directories into the
+container.
+
@quotation Note
This option requires Linux-libre 3.19 or newer.
@end quotation
Describe the running system generation: its file name, the kernel and
bootloader used, etc., as well as provenance information when available.
+The @code{--list-installed} flag is available, with the same
+syntax that is used in @command{guix package --list-installed}
+(@pxref{Invoking guix package}). When the flag is used,
+the description will include a list of packages that are currently
+installed in the system profile, with optional filtering based on a
+regular expression.
+
@quotation Note
The @emph{running} system generation---referred to by
@file{/run/current-system}---is not necessarily the @emph{current}
$ guix system list-generations 10d
@end example
+The @code{--list-installed} flag may also be specified, with the same
+syntax that is used in @command{guix package --list-installed}. This
+may be helpful if trying to determine when a package was added to the
+system.
+
@end table
The @command{guix system} command has even more to offer! The following
shows the extension relations among services.
+@quotation Note
+The @command{dot} program is provided by the @code{graphviz} package.
+@end quotation
+
@anchor{system-shepherd-graph}
@item shepherd-graph
Emit to standard output the @dfn{dependency
@deffn {Scheme Syntax} define-maybe @var{type}
Sometimes a field should not be serialized if the user doesn’t specify a
value. To achieve this, you can use the @code{define-maybe} macro to
-define a ``maybe type''; if the value of a maybe type is set to the
-@code{disabled}, it will not be serialized.
+define a ``maybe type''; if the value of a maybe type is left unset, or
+is set to the @code{'unset} value, then it will not be
+serialized.
When defining a ``maybe type'', the corresponding serializer for the
regular type will be used by default. For example, a field of type
@code{maybe-string} will be serialized using the @code{serialize-string}
procedure by default, you can of course change this by specifying a
custom serializer procedure. Likewise, the type of the value would have
-to be a string, unless it is set to the @code{disabled} symbol.
+to be a string, or left unspecified.
@lisp
(define-maybe string)
(define-configuration baz-configuration
(name
- ;; Nothing will be serialized by default. If set to a string, the
- ;; `serialize-string' procedure will be used to serialize the string.
- (maybe-string 'disabled)
+ ;; If set to a string, the `serialize-string' procedure will be used
+ ;; to serialize the string. Otherwise this field is not serialized.
+ maybe-string ; equivalent to (maybe-string *unspecified*)
"The name of this module."))
@end lisp
There is also the @code{no-serialization} literal, which when set means
that no serializer will be defined for the ``maybe type'', regardless of
-its value is @code{disabled} or not.
+whether its value is set or not.
@code{define-maybe/no-serialization} is a shorthand for specifying the
@code{no-serialization} literal.
(define-configuration/no-serialization test-configuration
(mode
- (maybe-symbol 'disabled)
+ maybe-symbol
"Docstring."))
@end lisp
@end deffn
disk by using something like @code{mixed-text-file}.
@end deffn
-@deffn {Scheme Procedure} validate-configuration @var{configuration}
-@var{fields}
-Type-check @var{fields}, a list of field names of @var{configuration}, a
-configuration record created by @code{define-configuration}.
-@end deffn
-
@deffn {Scheme Procedure} empty-serializer @var{field-name} @var{value}
A serializer that just returns an empty string. The
@code{serialize-package} procedure is an alias for this.
"The name of the contact."
serialize-contact-name)
(phone-number
- (maybe-integer 'disabled)
+ maybe-integer
"The person's phone number.")
(email
- (maybe-string 'disabled)
+ maybe-string
"The person's email address.")
(married?
(boolean)
* Shells: Shells Home Services. POSIX shells, Bash, Zsh.
* Mcron: Mcron Home Service. Scheduled User's Job Execution.
* Shepherd: Shepherd Home Service. Managing User's Daemons.
+* SSH: Secure Shell. Setting up the secure shell client.
* Desktop: Desktop Home Services. Services for graphical environments.
+* Guix: Guix Home Services. Services for Guix.
@end menu
@c In addition to that Home Services can provide
Bash configuration files (@pxref{Bash Startup Files,,, bash, The GNU
Bash Reference Manual}.
+For example, here is how you would define a service that extends the
+Bash service such that @file{~/.bash_profile} defines an additional
+environment variable, @env{PS1}:
+
+@lisp
+(define bash-fancy-prompt-service
+ (simple-service 'bash-fancy-prompt
+ home-bash-service-type
+ (home-bash-extension
+ (environment-variables
+ '(("PS1" . "\\u \\wλ "))))))
+@end lisp
+
+You would then add @code{bash-fancy-prompt-service} to the list in the
+@code{services} field of your @code{home-environment}. The reference of
+@code{home-bash-extension} follows.
+
@deftp {Data Type} home-bash-extension
Available @code{home-bash-extension} fields are:
mcron, GNU@tie{}mcron}). The information about system's mcron is
applicable here (@pxref{Scheduled Job Execution}), the only difference
for home services is that they have to be declared in a
-@code{home-envirnoment} record instead of an @code{operating-system}
+@code{home-environment} record instead of an @code{operating-system}
record.
@defvr {Scheme Variable} home-mcron-service-type
@end table
@end deftp
+@node Secure Shell
+@subsection Secure Shell
+
+@cindex secure shell client, configuration
+@cindex SSH client, configuration
+The @uref{https://www.openssh.com, OpenSSH package} includes a client,
+the @command{ssh} command, that allows you to connect to remote machines
+using the @acronym{SSH, secure shell} protocol. With the @code{(gnu
+home services ssh)} module, you can set up OpenSSH so that it works in a
+predictable fashion, almost independently of state on the local machine.
+To do that, you instantiate @code{home-openssh-service-type} in your
+Home configuration, as explained below.
+
+@defvr {Scheme Variable} home-openssh-service-type
+This is the type of the service to set up the OpenSSH client. It takes
+care of several things:
+
+@itemize
+@item
+providing a @file{~/.ssh/config} file based on your configuration so
+that @command{ssh} knows about hosts you regularly connect to and their
+associated parameters;
+
+@item
+providing a @file{~/.ssh/authorized_keys}, which lists public keys that
+the local SSH server, @command{sshd}, may accept to connect to this user
+account;
+
+@item
+optionally providing a @file{~/.ssh/known_hosts} file so that @file{ssh}
+can authenticate hosts you connect to.
+@end itemize
+
+Here is an example of a service and its configuration that you could add
+to the @code{services} field of your @code{home-environment}:
+
+@lisp
+(service home-openssh-service-type
+ (home-openssh-configuration
+ (hosts
+ (list (openssh-host (name "ci.guix.gnu.org")
+ (user "charlie"))
+ (openssh-host (name "chbouib")
+ (host-name "chbouib.example.org")
+ (user "supercharlie")
+ (port 10022))))
+ (authorized-keys (list (local-file "alice.pub")))))
+@end lisp
+
+The example above lists two hosts and their parameters. For instance,
+running @command{ssh chbouib} will automatically connect to
+@code{chbouib.example.org} on port 10022, logging in as user
+@samp{supercharlie}. Further, it marks the public key in
+@file{alice.pub} as authorized for incoming connections.
+
+The value associated with a @code{home-openssh-service-type} instance
+must be a @code{home-openssh-configuration} record, as describe below.
+@end defvr
+
+@deftp {Data Type} home-openssh-configuration
+This is the datatype representing the OpenSSH client and server
+configuration in one's home environment. It contains the following
+fields:
+
+@table @asis
+@item @code{hosts} (default: @code{'()})
+A list of @code{openssh-host} records specifying host names and
+associated connection parameters (see below). This host list goes into
+@file{~/.ssh/config}, which @command{ssh} reads at startup.
+
+@item @code{known-hosts} (default: @code{*unspecified*})
+This must be either:
+
+@itemize
+@item
+@code{*unspecified*}, in which case @code{home-openssh-service-type}
+leaves it up to @command{ssh} and to the user to maintain the list of
+known hosts at @file{~/.ssh/known_hosts}, or
+
+@item
+a list of file-like objects, in which case those are concatenated and
+emitted as @file{~/.ssh/known_hosts}.
+@end itemize
+
+The @file{~/.ssh/known_hosts} contains a list of host name/host key
+pairs that allow @command{ssh} to authenticate hosts you connect to and
+to detect possible impersonation attacks. By default, @command{ssh}
+updates it in a @dfn{TOFU, trust-on-first-use} fashion, meaning that it
+records the host's key in that file the first time you connect to it.
+This behavior is preserved when @code{known-hosts} is set to
+@code{*unspecified*}.
+
+If you instead provide a list of host keys upfront in the
+@code{known-hosts} field, your configuration becomes self-contained and
+stateless: it can be replicated elsewhere or at another point in time.
+Preparing this list can be relatively tedious though, which is why
+@code{*unspecified*} is kept as a default.
+
+@item @code{authorized-keys} (default: @code{'()})
+This must be a list of file-like objects, each of which containing an
+SSH public key that should be authorized to connect to this machine.
+
+Concretely, these files are concatenated and made available as
+@file{~/.ssh/authorized_keys}. If an OpenSSH server, @command{sshd}, is
+running on this machine, then it @emph{may} take this file into account:
+this is what @command{sshd} does by default, but be aware that it can
+also be configured to ignore it.
+@end table
+@end deftp
+
+@c %start of fragment
+
+@deftp {Data Type} openssh-host
+Available @code{openssh-host} fields are:
+
+@table @asis
+@item @code{name} (type: string)
+Name of this host declaration.
+
+@item @code{host-name} (type: maybe-string)
+Host name---e.g., @code{"foo.example.org"} or @code{"192.168.1.2"}.
+
+@item @code{address-family} (type: address-family)
+Address family to use when connecting to this host: one of
+@code{AF_INET} (for IPv4 only), @code{AF_INET6} (for IPv6 only), or
+@code{*unspecified*} (allowing any address family).
+
+@item @code{identity-file} (type: maybe-string)
+The identity file to use---e.g., @code{"/home/charlie/.ssh/id_ed25519"}.
+
+@item @code{port} (type: maybe-natural-number)
+TCP port number to connect to.
+
+@item @code{user} (type: maybe-string)
+User name on the remote host.
+
+@item @code{forward-x11?} (default: @code{#f}) (type: boolean)
+Whether to forward remote client connections to the local X11 graphical
+display.
+
+@item @code{forward-x11-trusted?} (default: @code{#f}) (type: boolean)
+Whether remote X11 clients have full access to the original X11
+graphical display.
+
+@item @code{forward-agent?} (default: @code{#f}) (type: boolean)
+Whether the authentication agent (if any) is forwarded to the remote
+machine.
+
+@item @code{compression?} (default: @code{#f}) (type: boolean)
+Whether to compress data in transit.
+
+@item @code{proxy-command} (type: maybe-string)
+The command to use to connect to the server. As an example, a command
+to connect via an HTTP proxy at 192.0.2.0 would be: @code{"nc -X connect
+-x 192.0.2.0:8080 %h %p"}.
+
+@item @code{host-key-algorithms} (type: maybe-string-list)
+The list of accepted host key algorithms---e.g.,
+@code{'("ssh-ed25519")}.
+
+@item @code{accepted-key-types} (type: maybe-string-list)
+The list of accepted user public key types.
+
+@item @code{extra-content} (default: @code{""}) (type: raw-configuration-string)
+Extra content appended as-is to this @code{Host} block in
+@file{~/.ssh/config}.
+
+@end table
+
+@end deftp
+
+
+@c %end of fragment
+
+
@node Desktop Home Services
@subsection Desktop Home Services
@item @code{nighttime-temperature} (default: @code{4500}) (type: integer)
Nighttime color temperature (kelvins).
-@item @code{daytime-brightness} (default: @code{disabled}) (type: maybe-inexact-number)
-Daytime screen brightness, between 0.1 and 1.0.
+@item @code{daytime-brightness} (type: maybe-inexact-number)
+Daytime screen brightness, between 0.1 and 1.0, or left unspecified.
-@item @code{nighttime-brightness} (default: @code{disabled}) (type: maybe-inexact-number)
-Nighttime screen brightness, between 0.1 and 1.0.
+@item @code{nighttime-brightness} (type: maybe-inexact-number)
+Nighttime screen brightness, between 0.1 and 1.0, or left unspecified.
-@item @code{latitude} (default: @code{disabled}) (type: maybe-inexact-number)
+@item @code{latitude} (type: maybe-inexact-number)
Latitude, when @code{location-provider} is @code{'manual}.
-@item @code{longitude} (default: @code{disabled}) (type: maybe-inexact-number)
+@item @code{longitude} (type: maybe-inexact-number)
Longitude, when @code{location-provider} is @code{'manual}.
-@item @code{dawn-time} (default: @code{disabled}) (type: maybe-string)
+@item @code{dawn-time} (type: maybe-string)
Custom time for the transition from night to day in the
morning---@code{"HH:MM"} format. When specified, solar elevation is not
used to determine the daytime/nighttime period.
-@item @code{dusk-time} (default: @code{disabled}) (type: maybe-string)
+@item @code{dusk-time} (type: maybe-string)
Likewise, custom time for the transition from day to night in the
evening.
@end deftp
+@node Guix Home Services
+@subsection Guix Home Services
+
+The @code{(gnu home services guix)} module provides services for
+user-specific Guix configuration.
+
+@defvr {Scheme Variable} home-channels-service-type
+This is the service type for managing
+@file{$XDG_CONFIG_HOME/guix/channels.scm}, the file that controls the
+channels received on @command{guix pull} (@pxref{Channels}). Its
+associated value is a list of @code{channel} records, defined in the
+@code{(guix channels)} module.
+
+Generally, it is better to extend this service than to directly
+configure it, as its default value is the default guix channel(s)
+defined by @code{%default-channels}. If you configure this service
+directly, be sure to include a guix channel. @xref{Specifying
+Additional Channels} and @ref{Using a Custom Guix Channel} for more
+details.
+
+A typical extension for adding a channel might look like this:
+
+@lisp
+(simple-service 'variant-packages-service
+ home-channels-service-type
+ (list
+ (channel
+ (name 'variant-packages)
+ (url "https://example.org/variant-packages.git")))
+@end lisp
+@end defvr
@node Invoking guix home
@section Invoking @code{guix home}
Describe the current home generation: its file name, as well as
provenance information when available.
+To show installed packages in the current home generation's profile, the
+@code{--list-installed} flag is provided, with the same syntax that is
+used in @command{guix package --list-installed} (@pxref{Invoking guix
+package}). For instance, the following command shows a table of all the
+packages with ``emacs'' in their name that are installed in the current
+home generation's profile:
+
+@example
+guix home describe --list-installed=emacs
+@end example
+
@item list-generations
List a summary of each generation of the home environment available on
disk, in a human-readable way. This is similar to the
generations that are up to 10 days old:
@example
-$ guix home list-generations 10d
+guix home list-generations 10d
@end example
+The @code{--list-installed} flag may also be specified, with the same
+syntax that is used in @command{guix home describe}. This may be
+helpful if trying to determine when a package was added to the home
+profile.
+
@item import
Generate a @dfn{home environment} from the packages in the default
profile and configuration files found in the user's home directory. The
guix import texlive @var{package}
@end example
+Additional options include:
+
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@end table
+
@quotation Note
@TeX{} Live packaging is still very much work in progress, but you can
help! @xref{Contributing}, for more information.
HCoop / jackhill / guix / guix.git / blobdiff