Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
-Copyright @copyright{} 2017, 2021 Christopher Lemmer Webber@*
-Copyright @copyright{} 2017, 2018, 2019, 2020 Marius Bakke@*
+Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
+Copyright @copyright{} 2017, 2018, 2019, 2020, 2021 Marius Bakke@*
Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@*
Copyright @copyright{} 2017, 2018, 2019, 2020, 2021 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2019 Kyle Andrews@*
Copyright @copyright{} 2019 Alex Griffin@*
Copyright @copyright{} 2019, 2020, 2021 Guillaume Le Vaillant@*
-Copyright @copyright{} 2020 Leo Prikler@*
+Copyright @copyright{} 2020 Liliana Marie Prikler@*
Copyright @copyright{} 2019, 2020 Simon Tournier@*
Copyright @copyright{} 2020 Wiktor Żelazny@*
Copyright @copyright{} 2020 Damien Cassou@*
Copyright @copyright{} 2021 Raghav Gururajan@*
Copyright @copyright{} 2021 Domagoj Stolfa@*
Copyright @copyright{} 2021 Hui Lu@*
+Copyright @copyright{} 2021 pukkamustard@*
+Copyright @copyright{} 2021 Alice Brenon@*
+Copyright @copyright{} 2021 Andrew Tropin@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
* System Configuration:: Configuring the operating system.
+* Home Configuration:: Configuring the home environment.
* Documentation:: Browsing software user manuals.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
* Running Guix in a VM:: How to run Guix System in a virtual machine.
* Defining Services:: Adding new service definitions.
+Home Environment Configuration
+
+* Invoking guix home:: Instantiating a home environment configuration.
+
Services
* Base Services:: Essential system services.
# systemctl enable --now gnu-store.mount guix-daemon
@end example
+You may also want to arrange for @command{guix gc} to run periodically:
+
+@example
+# cp ~root/.config/guix/current/lib/systemd/system/guix-gc.service \
+ ~root/.config/guix/current/lib/systemd/system/guix-gc.timer \
+ /etc/systemd/system/
+# systemctl enable --now guix-gc.timer
+@end example
+
+You may want to edit @file{guix-gc.service} to adjust the command line
+options to fit your needs (@pxref{Invoking guix gc}).
+
If your host distro uses the Upstart init system:
@example
Once you are done partitioning the target hard disk drive, you have to
create a file system on the relevant partition(s)@footnote{Currently
-Guix System only supports ext4, btrfs, JFS, and F2FS file systems. In
+Guix System only supports ext4, btrfs, JFS, F2FS, and XFS file systems. In
particular, code that reads file system UUIDs and labels only works for these
file system types.}. For the ESP, if you have one and assuming it is
@file{/dev/sda1}, run:
that end, the installation system comes with three text editors. We
recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
supports syntax highlighting and parentheses matching; other editors
-include GNU Zile (an Emacs clone), and
+include mg (an Emacs clone), and
nvi (a clone of the original BSD @command{vi} editor).
We strongly recommend storing that file on the target root file system, say,
as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
@itemize
@item
-Make sure the @code{bootloader-configuration} form refers to the target
-you want to install GRUB on. It should mention @code{grub-bootloader} if
-you are installing GRUB in the legacy way, or @code{grub-efi-bootloader}
-for newer UEFI systems. For legacy systems, the @code{target} field
-names a device, like @code{/dev/sda}; for UEFI systems it names a path
-to a mounted EFI partition, like @code{/boot/efi}; do make sure the path is
-currently mounted and a @code{file-system} entry is specified in your
-configuration.
+Make sure the @code{bootloader-configuration} form refers to the targets
+you want to install GRUB on. It should mention @code{grub-bootloader}
+if you are installing GRUB in the legacy way, or
+@code{grub-efi-bootloader} for newer UEFI systems. For legacy systems,
+the @code{targets} field contain the names of the devices, like
+@code{(list "/dev/sda")}; for UEFI systems it names the paths to mounted
+EFI partitions, like @code{(list "/boot/efi")}; do make sure the paths
+are currently mounted and a @code{file-system} entry is specified in
+your configuration.
@item
Be sure that your file system labels match the value of their respective
symlinks, as well as empty mount points for virtual file systems like
procfs.
-@item deb
-This produces a Debian archive (a package with the @samp{.deb} file
-extension) containing all the specified binaries and symbolic links,
-that can be installed on top of any dpkg-based GNU/Linux distribution.
-
@quotation Note
Singularity @emph{requires} you to provide @file{/bin/sh} in the image.
For that reason, @command{guix pack -f squashfs} always implies @code{-S
run} and @command{singularity exec} will fail with an unhelpful ``no
such file or directory'' message.
@end quotation
+
+@item deb
+This produces a Debian archive (a package with the @samp{.deb} file
+extension) containing all the specified binaries and symbolic links,
+that can be installed on top of any dpkg-based GNU(/Linux) distribution.
+Advanced options can be revealed via the @option{--help-deb-format}
+option. They allow embedding control files for more fine-grained
+control, such as activating specific triggers or providing a maintainer
+configure script to run arbitrary setup code upon installation.
+
+@example
+guix pack -f deb -C xz -S /usr/bin/hello=bin/hello hello
+@end example
+
+@quotation Note
+Because archives produced with @command{guix pack} contain a collection
+of store items and because each @command{dpkg} package must not have
+conflicting files, in practice that means you likely won't be able to
+install more than one such archive on a given system.
+@end quotation
+
+@quotation Warning
+@command{dpkg} will assume ownership of any files contained in the pack
+that it does @emph{not} know about. It is unwise to install
+Guix-produced @samp{.deb} files on a system where @file{/gnu/store} is
+shared by other software, such as a Guix installation or other, non-deb
+packs.
+@end quotation
+
@end table
@cindex relocatable binaries
The URL of the Git repository to clone.
@item @code{commit}
-This string denotes either the commit to fetch (a hexadecimal string,
-either the full SHA1 commit or a ``short'' commit string; the latter is
-not recommended) or the tag to fetch.
+This string denotes either the commit to fetch (a hexadecimal string),
+or the tag to fetch. You can also use a ``short'' commit ID or a
+@command{git describe} style identifier such as
+@code{v1.0.1-10-g58d7909c97}.
@item @code{recursive?} (default: @code{#f})
This Boolean indicates whether to recursively fetch Git sub-modules.
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 binaries, which are listed as
+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''
is useful when a package contains multiple packages and you want to build
only one of them. This is equivalent to passing the @code{-p} argument to
@code{dune}.
+
@end defvr
@defvr {Scheme Variable} go-build-system
the built output. The key @code{#:install-source?}, which defaults to
@code{#t}, controls whether or not the source code is installed. It can
be set to @code{#f} for packages that only provide executable files.
+
+Packages can be cross-built, and if a specific architecture or operating
+system is desired then the keywords @code{#:goarch} and @code{#:goos}
+can be used to force the package to be built for that architecture and
+operating system. The combinations known to Go can be found
+@url{"https://golang.org/doc/install/source#environment", in their
+documentation}.
@end defvr
@defvr {Scheme Variable} glib-or-gtk-build-system
also exported.
@end defvr
+@defvr {Scheme Variable} minetest-mod-build-system
+This variable is exported by @code{(guix build-system minetest)}. It
+implements a build procedure for @uref{https://www.minetest.net, Minetest}
+mods, which consists of copying Lua code, images and other resources to
+the location Minetest searches for mods. The build system also minimises
+PNG images and verifies that Minetest can load the mod without errors.
+@end defvr
+
@defvr {Scheme Variable} minify-build-system
This variable is exported by @code{(guix build-system minify)}. It
implements a minification procedure for simple JavaScript packages.
@example
guix build --quiet --keep-going \
- $(guix package -A | cut -f1,2 --output-delimiter=@@)
+ $(guix package -A | awk '@{ print $1 "@@" $2 @}')
@end example
@var{package-or-derivation} may be either the name of a package found in
@item --with-commit=@var{package}=@var{commit}
This is similar to @option{--with-branch}, except that it builds from
@var{commit} rather than the tip of a branch. @var{commit} must be a valid
-Git commit SHA1 identifier or a tag.
+Git commit SHA1 identifier, a tag, or a @command{git describe} style
+identifier such as @code{1.0-3-gabc123}.
@item --with-patch=@var{package}=@var{file}
Add @var{file} to the list of patches applied to @var{package}, where
in Guix.
@end table
+@item minetest
+@cindex minetest
+@cindex ContentDB
+Import metadata from @uref{https://content.minetest.net, ContentDB}.
+Information is taken from the JSON-formatted metadata provided through
+@uref{https://content.minetest.net/help/api/, ContentDB's API} and
+includes most relevant information, including dependencies. There are
+some caveats, however. The license information is often incomplete.
+The commit hash is sometimes missing. The descriptions are in the
+Markdown format, but Guix uses Texinfo instead. Texture packs and
+subgames are unsupported.
+
+The command below imports metadata for the Mesecons mod by Jeija:
+
+@example
+guix import minetest Jeija/mesecons
+@end example
+
+The author name can also be left out:
+
+@example
+guix import minetest mesecons
+@end example
+
+@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 cpan
@cindex CPAN
Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
@code{emacs} package (@pxref{Package Installation, ELPA package
signatures,, emacs, The GNU Emacs Manual}).
+@item
+@uref{https://elpa.nongnu.org/nongnu/, NonGNU}, selected by the
+@code{nongnu} identifier.
+
@item
@uref{https://stable.melpa.org/packages, MELPA-Stable}, selected by the
@code{melpa-stable} identifier.
and generate package expressions for all those packages that are not yet
in Guix.
@item --repo
-Select the given repository (a repository name). Possible values include:
+By default, packages are searched in the official OPAM repository. This
+option, which can be used more than once, lets you add other repositories
+which will be searched for packages. It accepts as valid arguments:
+
@itemize
-@item @code{opam}, the default opam repository,
-@item @code{coq} or @code{coq-released}, the stable repository for coq packages,
-@item @code{coq-core-dev}, the repository that contains development versions of coq,
-@item @code{coq-extra-dev}, the repository that contains development versions
- of coq packages.
+@item the name of a known repository - can be one of @code{opam},
+ @code{coq} (equivalent to @code{coq-released}),
+ @code{coq-core-dev}, @code{coq-extra-dev} or @code{grew}.
+@item the URL of a repository as expected by the
+ @code{opam repository add} command (for instance, the URL equivalent
+ of the above @code{opam} name would be
+ @uref{https://opam.ocaml.org}).
+@item the path to a local copy of a repository (a directory containing a
+ @file{packages/} sub-directory).
@end itemize
+
+Repositories are assumed to be passed to this option by order of
+preference. The additional repositories will not replace the default
+@code{opam} repository, which is always kept as a fallback.
+
+Also, please note that versions are not compared accross repositories.
+The first repository (from left to right) that has at least one version
+of a given package will prevail over any others, and the version
+imported will be the latest one found @emph{in this repository only}.
+
@end table
@item go
@item generic-html
a generic updater that crawls the HTML page where the source tarball of
the package is hosted, when applicable.
+
+@item generic-git
+a generic updater for packages hosted on Git repositories. It tries to
+be smart about parsing Git tag names, but if it is not able to parse the
+tag name and compare tags correctly, users can define the following
+properties for a package.
+
+@itemize
+@item @code{release-tag-prefix}: a regular expression for matching a prefix of
+the tag name.
+
+@item @code{release-tag-suffix}: a regular expression for matching a suffix of
+the tag name.
+
+@item @code{release-tag-version-delimiter}: a string used as the delimiter in
+the tag name for separating the numbers of the version.
+
+@item @code{accept-pre-releases}: by default, the updater will ignore
+pre-releases; to make it also look for pre-releases, set the this
+property to @code{#t}.
+
+@end itemize
+
+@lisp
+(package
+ (name "foo")
+ ;; ...
+ (properties
+ '((release-tag-prefix . "^release0-")
+ (release-tag-suffix . "[a-z]?$")
+ (release-tag-version-delimiter . ":"))))
+@end lisp
+
+
@end table
For instance, the following command only checks for updates of Emacs
/gnu/store/@dots{}-libunistring-0.9.10
@end example
+Sometimes you still want to visualize the graph but would like to trim
+it so it can actually be displayed. One way to do it is via the
+@option{--max-depth} (or @option{-M}) option, which lets you specify the
+maximum depth of the graph. In the example below, we visualize only
+@code{libreoffice} and the nodes whose distance to @code{libreoffice} is
+at most 2:
+
+@example
+guix graph -M 2 libreoffice | xdot -f fdp -
+@end example
+
+Mind you, that's still a big ball of spaghetti, but at least
+@command{dot} can render it quickly and it can be browsed somewhat.
+
The available options are the following:
@table @option
@lisp
(bootloader-configuration
(bootloader grub-efi-bootloader)
- (target "/boot/efi"))
+ (targets '("/boot/efi")))
@end lisp
@xref{Bootloader Configuration}, for more information on the available
(@pxref{Invoking guix package}). The @code{%base-packages} variable
provides all the tools one would expect for basic user and administrator
tasks---including the GNU Core Utilities, the GNU Networking Utilities,
-the GNU Zile lightweight text editor, @command{find}, @command{grep},
+the @command{mg} lightweight text editor, @command{find}, @command{grep},
etc. The example above adds GNU@tie{}Screen to those,
taken from the @code{(gnu packages screen)}
module (@pxref{Package Modules}). The
customize them. To do this, use @code{modify-services} (@pxref{Service
Reference, @code{modify-services}}) to modify the list.
-For example, suppose you want to modify @code{guix-daemon} and Mingetty
-(the console log-in) in the @code{%base-services} list (@pxref{Base
-Services, @code{%base-services}}). To do that, you can write the
-following in your operating system declaration:
+@anchor{auto-login to TTY} For example, suppose you want to modify
+@code{guix-daemon} and Mingetty (the console log-in) in the
+@code{%base-services} list (@pxref{Base Services,
+@code{%base-services}}). To do that, you can write the following in
+your operating system declaration:
@lisp
(define %my-services
This changes the configuration---i.e., the service parameters---of the
@code{guix-service-type} instance, and that of all the
-@code{mingetty-service-type} instances in the @code{%base-services} list.
+@code{mingetty-service-type} instances in the @code{%base-services} list
+(@pxref{Auto-Login to a Specific TTY, see the cookbook for how to
+auto-login one user to a specific TTY,, guix-cookbook, GNU Guix Cookbook})).
Observe how this is accomplished: first, we arrange for the original
configuration to be bound to the identifier @code{config} in the
@var{body}, and then we write the @var{body} so that it evaluates to the
@c FIXME: Add xref to PAM services section.
@item @code{setuid-programs} (default: @code{%setuid-programs})
-List of string-valued G-expressions denoting setuid programs.
-@xref{Setuid Programs}.
+List of @code{<setuid-program>}. @xref{Setuid Programs}, for more
+information.
@item @code{sudoers-file} (default: @code{%sudoers-specification})
@cindex sudoers file
instance, for the root file system.
@item @code{check?} (default: @code{#t})
-This Boolean indicates whether the file system needs to be checked for
-errors before being mounted.
+This Boolean indicates whether the file system should be checked for
+errors before being mounted. How and when this happens can be further
+adjusted with the following options.
+
+@item @code{skip-check-if-clean?} (default: @code{#t})
+When true, this Boolean indicates that a file system check triggered
+by @code{check?} may exit early if the file system is marked as
+``clean'', meaning that it was previously correctly unmounted and
+should not contain errors.
+
+Setting this to false will always force a full consistency check when
+@code{check?} is true. This may take a very long time and is not
+recommended on healthy systems---in fact, it may reduce reliability!
+
+Conversely, some primitive file systems like @code{fat} do not keep
+track of clean shutdowns and will perform a full scan regardless of the
+value of this option.
+
+@item @code{repair} (default: @code{'preen})
+When @code{check?} finds errors, it can (try to) repair them and
+continue booting. This option controls when and how to do so.
+
+If false, try not to modify the file system at all. Checking certain
+file systems like @code{jfs} may still write to the device to replay
+the journal. No repairs will be attempted.
+
+If @code{#t}, try to repair any errors found and assume ``yes'' to
+all questions. This will fix the most errors, but may be risky.
+
+If @code{'preen}, repair only errors that are safe to fix without
+human interaction. What that means is left up to the developers of
+each file system and may be equivalent to ``none'' or ``all''.
@item @code{create-mount-point?} (default: @code{#f})
When true, the mount point is created if it does not exist yet.
(keyboard-layout (keyboard-layout "tr")) ;for the console
(bootloader (bootloader-configuration
(bootloader grub-efi-bootloader)
- (target "/boot/efi")
+ (targets '("/boot/efi"))
(keyboard-layout keyboard-layout))) ;for GRUB
(services (cons (set-xorg-configuration
(xorg-configuration ;for Xorg
(lambda ()
(execl (string-append #$findutils "/bin/updatedb")
"updatedb"
- "--prunepaths=/tmp /var/tmp /gnu/store"))))
+ "--prunepaths=/tmp /var/tmp /gnu/store"))
+ "updatedb"))
(define garbage-collector-job
;; Collect garbage 5 minutes after midnight every day.
%base-services)))
@end lisp
+@quotation Tip
+When providing the action of a job specification as a procedure, you
+should provide an explicit name for the job via the optional 3rd
+argument as done in the @code{updatedb-job} example above. Otherwise,
+the job would appear as ``Lambda function'' in the output of
+@command{herd schedule mcron}, which is not nearly descriptive enough!
+@end quotation
+
For more complex jobs defined in Scheme where you need control over the top
level, for instance to introduce a @code{use-modules} form, you can move your
code to a separate program using the @code{program-file} procedure of the
@code{mcron-configuration} object.
This service type can be the target of a service extension that provides
-it additional job specifications (@pxref{Service Composition}). In
-other words, it is possible to define services that provide additional
-mcron jobs to run.
+additional job specifications (@pxref{Service Composition}). In other
+words, it is possible to define services that provide additional mcron
+jobs to run.
@end defvr
@deftp {Data Type} mcron-configuration
@item @code{allow-empty-passwords?} (default: @code{#t})
Whether to allow logins with empty passwords.
+@item @code{gnupg?} (default: @code{#f})
+If enabled, @code{pam-gnupg} will attempt to automatically unlock the
+user's GPG keys with the login password via @code{gpg-agent}. The
+keygrips of all keys to be unlocked should be written to
+@file{~/.pam-gnupg}, and can be queried with @code{gpg -K
+--with-keygrip}. Presetting passphrases must be enabled by adding
+@code{allow-preset-passphrase} in @file{~/.gnupg/gpg-agent.conf}.
+
@item @code{auto-login?} (default: @code{#f})
@itemx @code{default-user} (default: @code{""})
When @code{auto-login?} is false, SLiM presents a log-in screen.
@node Telephony Services
@subsection Telephony Services
+@cindex telephony, services
+The @code{(gnu services telephony)} module contains Guix service
+definitions for telephony services. Currently it provides the following
+services:
+
+@subsubheading Jami
+
+@cindex jami, service
+
+This section describes how to configure a Jami server that can be used
+to host video (or audio) conferences, among other uses. The following
+example demonstrates how to specify Jami account archives (backups) to
+be provisioned automatically:
+
+@lisp
+(service jami-service-type
+ (jami-configuration
+ (accounts
+ (list (jami-account
+ (archive "/etc/jami/unencrypted-account-1.gz"))
+ (jami-account
+ (archive "/etc/jami/unencrypted-account-2.gz"))))))
+@end lisp
+
+When the accounts field is specified, the Jami account files of the
+service found under @file{/var/lib/jami} are recreated every time the
+service starts.
+
+Jami accounts and their corresponding backup archives can be generated
+using either the @code{jami-qt} or @code{jami-gnome} Jami clients. The
+accounts should not be password-protected, but it is wise to ensure
+their files are only readable by @samp{root}.
+
+The next example shows how to declare that only some contacts should be
+allowed to communicate with a given account:
+
+@lisp
+(service jami-service-type
+ (jami-configuration
+ (accounts
+ (list (jami-account
+ (archive "/etc/jami/unencrypted-account-1.gz")
+ (peer-discovery? #t)
+ (rendezvous-point? #t)
+ (allowed-contacts
+ '("1dbcb0f5f37324228235564b79f2b9737e9a008f"
+ "2dbcb0f5f37324228235564b79f2b9737e9a008f")))))))
+@end lisp
+
+In this mode, only the declared @code{allowed-contacts} can initiate
+communication with the Jami account. This can be used, for example,
+with rendezvous point accounts to create a private video conferencing
+space.
+
+To put the system administrator in full control of the conferences
+hosted on their system, the Jami service supports the following actions:
+
+@example sh
+# herd doc jami list-actions
+(list-accounts
+ list-account-details
+ list-banned-contacts
+ list-contacts
+ list-moderators
+ add-moderator
+ ban-contact
+ enable-account
+ disable-account)
+@end example
+
+The above actions aim to provide the most valuable actions for
+moderation purposes, not to cover the whole Jami API. Users wanting to
+interact with the Jami daemon from Guile may be interested in
+experimenting with the @code{(gnu build jami-service)} module, which
+powers the above Shepherd actions.
+
+@c TODO: This should be auto-generated from the doc already defined on
+@c the shepherd-actions themselves in (gnu services telephony).
+The @code{add-moderator} and @code{ban-contact} actions accept a contact
+@emph{fingerprint} (40 characters long hash) as first argument and an
+account fingerprint or username as second argument:
+
+@example sh
+# herd add-moderator jami 1dbcb0f5f37324228235564b79f2b9737e9a008f \
+ f3345f2775ddfe07a4b0d95daea111d15fbc1199
+
+# herd list-moderators jami
+Moderators for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
+ - 1dbcb0f5f37324228235564b79f2b9737e9a008f
+
+@end example
+
+In the case of @code{ban-contact}, the second username argument is
+optional; when omitted, the account is banned from all Jami accounts:
+
+@example sh
+# herd ban-contact jami 1dbcb0f5f37324228235564b79f2b9737e9a008f
+
+# herd list-banned-contacts jami
+Banned contacts for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
+ - 1dbcb0f5f37324228235564b79f2b9737e9a008f
+
+@end example
+
+Banned contacts are also stripped from their moderation privileges.
+
+The @code{disable-account} action allows to completely disconnect an
+account from the network, making it unreachable, while
+@code{enable-account} does the inverse. They accept a single account
+username or fingerprint as first argument:
+
+@example sh
+# herd disable-account jami f3345f2775ddfe07a4b0d95daea111d15fbc1199
+
+# herd list-accounts jami
+The following Jami accounts are available:
+ - f3345f2775ddfe07a4b0d95daea111d15fbc1199 (dummy) [disabled]
+
+@end example
+
+The @code{list-account-details} action prints the detailed parameters of
+each accounts in the Recutils format, which means the @command{recsel}
+command can be used to select accounts of interest (@pxref{Selection
+Expressions,,,recutils, GNU recutils manual}). Note that period
+characters (@samp{.}) found in the account parameter keys are mapped to
+underscores (@samp{_}) in the output, to meet the requirements of the
+Recutils format. The following example shows how to print the account
+fingerprints for all accounts operating in the rendezvous point mode:
+
+@example sh
+# herd list-account-details jami | \
+ recsel -p Account.username -e 'Account.rendezVous ~ "true"'
+Account_username: f3345f2775ddfe07a4b0d95daea111d15fbc1199
+@end example
+
+The remaining actions should be self-explanatory.
+
+The complete set of available configuration options is detailed below.
+
+@c TODO: Ideally, the following fragments would be auto-generated at
+@c build time, so that they needn't be manually duplicated.
+@c Auto-generated via (configuration->documentation 'jami-configuration)
+@deftp {Data Type} jami-configuration
+Available @code{jami-configuration} fields are:
+
+@table @asis
+@item @code{jamid} (default: @code{libring}) (type: package)
+The Jami daemon package to use.
+
+@item @code{dbus} (default: @code{dbus}) (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)
+The nss-certs package to use to provide TLS certificates.
+
+@item @code{enable-logging?} (default: @code{#t}) (type: boolean)
+Whether to enable logging to syslog.
+
+@item @code{debug?} (default: @code{#f}) (type: boolean)
+Whether to enable debug level messages.
+
+@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)
+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
+service starts, ensuring a consistent state.
+
+@end table
+
+@end deftp
+
+@c Auto-generated via (configuration->documentation 'jami-account)
+@deftp {Data Type} jami-account
+Available @code{jami-account} fields are:
+
+@table @asis
+@item @code{archive} (type: string-or-computed-file)
+The account archive (backup) file name of the account. This is used to
+provision the account when the service starts. The account archive
+should @emph{not} be encrypted. It is highly recommended to make it
+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)
+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
+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)
+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
+typically defaults to allow anyone to moderate.
+
+@item @code{rendezvous-point?} (default: @code{disabled}) (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)
+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)
+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)
+The URI of the name server to use, that can be used to retrieve the
+account fingerprint for a registered username.
+
+@end table
+
+@end deftp
+
+@subsubheading Murmur (VoIP server)
+
@cindex Murmur (VoIP server)
@cindex VoIP server
This section describes how to set up and run a Murmur server. Murmur is
@end table
@end deffn
+@anchor{NGINX}
@subsubheading NGINX
@deffn {Scheme Variable} nginx-service-type
The @code{(gnu services vpn)} module provides services related to
@dfn{virtual private networks} (VPNs).
+@subsubheading Bitmask
+
+@defvr {Scheme Variable} bitmask-service-type
+A service type for the @uref{https://bitmask.net, Bitmask} VPN client. It makes
+the client available in the system and loads its polkit policy. Please note that
+the client expects an active polkit-agent, which is either run by your
+desktop-environment or should be run manually.
+@end defvr
+
@subsubheading OpenVPN
It provides a @emph{client} service for your machine to connect to a
Once a substitute is successfully fetched, trigger substitute baking at
@var{trigger-url}.
+@item @code{publish?} (default: @code{#t})
+If set to false, do not start a publish server and ignore the
+@code{publish-port} argument. This can be useful if there is already a
+standalone publish server standing next to the remote server.
+
@item @code{public-key}
@item @code{private-key}
Use the specific @var{file}s as the public/private key pair used to sign
@item @code{publish-port} (default: @code{5558})
The TCP port of the publish server. It defaults to @code{5558}.
+@item @code{substitute-urls} (default: @code{%default-substitute-urls})
+The list of URLs where to look for substitutes by default.
+
@item @code{public-key}
@item @code{private-key}
Use the specific @var{file}s as the public/private key pair used to sign
(by default: @code{git}). This is necessary when using Gitolite with software
like cgit or gitweb.
+@item @code{unsafe-pattern} (default: @code{#f})
+An optional Perl regular expression for catching unsafe configurations in
+the configuration file. See
+@uref{https://gitolite.com/gitolite/git-config.html#compensating-for-unsafe_patt,
+Gitolite's documentation} for more information.
+
+When the value is not @code{#f}, it should be a string containing a Perl
+regular expression, such as @samp{"[`~#\$\&()|;<>]"}, which is the default
+value used by gitolite. It rejects any special character in configuration
+that might be interpreted by a shell, which is useful when sharing the
+administration burden with other people that do not otherwise have shell
+access on the server.
+
@item @code{git-config-keys} (default: @code{""})
Gitolite allows you to set git config values using the @samp{config}
keyword. This setting allows control over the config keys to accept.
@end deftp
+@subsubheading Gitile Service
+
+@cindex Gitile service
+@cindex Git, forge
+@uref{https://git.lepiller.eu/gitile, Gitile} is a Git forge for viewing
+public git repository contents from a web browser.
+
+Gitile works best in collaboration with Gitolite, and will serve the public
+repositories from Gitolite by default. The service should listen only on
+a local port, and a webserver should be configured to serve static resources.
+The gitile service provides an easy way to extend the Nginx service for
+that purpose (@pxref{NGINX}).
+
+The following example will configure Gitile to serve repositories from a
+custom location, with some default messages for the home page and the
+footers.
+
+@lisp
+(service gitile-service-type
+ (gitile-configuration
+ (repositories "/srv/git")
+ (base-git-url "https://myweb.site/git")
+ (index-title "My git repositories")
+ (intro '((p "This is all my public work!")))
+ (footer '((p "This is the end")))
+ (nginx-server-block
+ (nginx-server-configuration
+ (ssl-certificate
+ "/etc/letsencrypt/live/myweb.site/fullchain.pem")
+ (ssl-certificate-key
+ "/etc/letsencrypt/live/myweb.site/privkey.pem")
+ (listen '("443 ssl http2" "[::]:443 ssl http2"))
+ (locations
+ (list
+ ;; Allow for https anonymous fetch on /git/ urls.
+ (git-http-nginx-location-configuration
+ (git-http-configuration
+ (uri-path "/git/")
+ (git-root "/var/lib/gitolite/repositories")))))))))
+@end lisp
+
+In addition to the configuration record, you should configure your git
+repositories to contain some optional information. First, your public
+repositories need to contain the @file{git-daemon-export-ok} magic file
+that allows Git to export the repository. Gitile uses the presence of this
+file to detect public repositories it should make accessible. To do so with
+Gitolite for instance, modify your @file{conf/gitolite.conf} to include
+this in the repositories you want to make public:
+
+@example
+repo foo
+ R = daemon
+@end example
+
+In addition, Gitile can read the repository configuration to display more
+infomation on the repository. Gitile uses the gitweb namespace for its
+configuration. As an example, you can use the following in your
+@file{conf/gitolite.conf}:
+
+@example
+repo foo
+ R = daemon
+ desc = A long description, optionally with <i>HTML</i>, shown on the index page
+ config gitweb.name = The Foo Project
+ config gitweb.synopsis = A short description, shown on the main page of the project
+@end example
+
+Do not forget to commit and push these changes once you are satisfied. You
+may need to change your gitolite configuration to allow the previous
+configuration options to be set. One way to do that is to add the
+following service definition:
+
+@lisp
+(service gitolite-service-type
+ (gitolite-configuration
+ (admin-pubkey (local-file "key.pub"))
+ (rc-file
+ (gitolite-rc-file
+ (umask #o0027)
+ ;; Allow to set any configuration key
+ (git-config-keys ".*")
+ ;; Allow any text as a valid configuration value
+ (unsafe-patt "^$")))))
+@end lisp
+
+@deftp {Data Type} gitile-configuration
+Data type representing the configuration for @code{gitile-service-type}.
+
+@table @asis
+@item @code{package} (default: @var{gitile})
+Gitile package to use.
+
+@item @code{host} (default: @code{"localhost"})
+The host on which gitile is listening.
+
+@item @code{port} (default: @code{8080})
+The port on which gitile is listening.
+
+@item @code{database} (default: @code{"/var/lib/gitile/gitile-db.sql"})
+The location of the database.
+
+@item @code{repositories} (default: @code{"/var/lib/gitolite/repositories"})
+The location of the repositories. Note that only public repositories will
+be shown by Gitile. To make a repository public, add an empty
+@file{git-daemon-export-ok} file at the root of that repository.
+
+@item @code{base-git-url}
+The base git url that will be used to show clone commands.
+
+@item @code{index-title} (default: @code{"Index"})
+The page title for the index page that lists all the available repositories.
+
+@item @code{intro} (default: @code{'()})
+The intro content, as a list of sxml expressions. This is shown above the list
+of repositories, on the index page.
+
+@item @code{footer} (default: @code{'()})
+The footer content, as a list of sxml expressions. This is shown on every
+page served by Gitile.
+
+@item @code{nginx-server-block}
+An nginx server block that will be extended and used as a reverse proxy by
+Gitile to serve its pages, and as a normal web server to serve its assets.
+
+You can use this block to add more custom URLs to your domain, such as a
+@code{/git/} URL for anonymous clones, or serving any other files you would
+like to serve.
+@end table
+@end deftp
+
+
@node Game Services
@subsection Game Services
@table @asis
-@item @code{package} (default: @code{docker})
+@item @code{docker} (default: @code{docker})
The Docker daemon package to use.
-@item @code{package} (default: @code{docker-cli})
+@item @code{docker-cli} (default: @code{docker-cli})
The Docker client package to use.
@item @code{containerd} (default: @var{containerd})
should be setuid root.
The @code{setuid-programs} field of an @code{operating-system}
-declaration contains a list of G-expressions denoting the names of
-programs to be setuid-root (@pxref{Using the Configuration System}).
-For instance, the @command{passwd} program, which is part of the Shadow
-package, can be designated by this G-expression (@pxref{G-Expressions}):
+declaration contains a list of @code{<setuid-program>} denoting the
+names of programs to have a setuid or setgid bit set (@pxref{Using the
+Configuration System}). For instance, the @command{passwd} program,
+which is part of the Shadow package, with a setuid root can be
+designated like this:
@example
-#~(string-append #$shadow "/bin/passwd")
+(setuid-program
+ (program (file-append #$shadow "/bin/passwd")))
@end example
+@deftp {Data Type} setuid-program
+This data type represents a program with a setuid or setgid bit set.
+
+@table @asis
+@item @code{program}
+A file-like object having its setuid and/or setgid bit set.
+
+@item @code{setuid?} (default: @code{#t})
+Whether to set user setuid bit.
+
+@item @code{setgid?} (default: @code{#f})
+Whether to set group setgid bit.
+
+@item @code{user} (default: @code{0})
+UID (integer) or user name (string) for the user owner of the program,
+defaults to root.
+
+@item @code{group} (default: @code{0})
+GID (integer) goup name (string) for the group owner of the program,
+defaults to root.
+
+@end table
+@end deftp
+
A default set of setuid programs is defined by the
@code{%setuid-programs} variable of the @code{(gnu system)} module.
@defvr {Scheme Variable} %setuid-programs
-A list of G-expressions denoting common programs that are setuid-root.
+A list of @code{<setuid-program>} denoting common programs that are
+setuid-root.
The list includes commands such as @command{passwd}, @command{ping},
@command{su}, and @command{sudo}.
When unspecified, the device name from the root file system of the
operating system declaration is used.
+@item fsck.mode=@var{mode}
+Whether to check the @var{root} file system for errors before mounting
+it. @var{mode} is one of @code{skip} (never check), @code{force} (always
+check), or @code{auto} to respect the root file-system object's 'check?'
+setting (@pxref{File Systems}) and run a full scan only if the file system
+was not cleanly shut down.
+
+@code{auto} is the default if this option is not present or if @var{mode}
+is not one of the above.
+
+@item fsck.repair=@var{level}
+The level of repairs to perform automatically if errors are found in the
+@var{root} file system. @var{level} is one of @code{no} (do not write to
+@var{root} at all if possible), @code{yes} (repair as much as possible),
+or @code{preen} to repair problems considered safe to repair automatically.
+
+@code{preen} is the default if this option is not present or if @var{level}
+is not one of the above.
+
@item --system=@var{system}
Have @file{/run/booted-system} and @file{/run/current-system} point to
@var{system}.
program to run in that initrd.
@deffn {Scheme Procedure} expression->initrd @var{exp} @
- [#:guile %guile-3.0-static-stripped] [#:name "guile-initrd"]
+ [#:guile %guile-static-stripped] [#:name "guile-initrd"]
Return as a file-like object a Linux initrd (a gzipped cpio archive)
containing @var{guile} and that evaluates @var{exp}, a G-expression,
upon booting. All the derivations referenced by @var{exp} are
through TFTP@. In combination with an NFS root file system this allows you to
build a diskless Guix system.
-The installation of the @code{grub-efi-netboot-bootloader} generates the content
-of the TFTP root directory at @code{target}
-(@pxref{Bootloader Configuration, @code{target}}), to be served by a TFTP server.
- You may want to mount your TFTP server directory onto @code{target} to move the
-required files to the TFTP server automatically.
+The installation of the @code{grub-efi-netboot-bootloader} generates the
+content of the TFTP root directory at @code{targets} (@pxref{Bootloader
+Configuration, @code{targets}}), to be served by a TFTP server. You may
+want to mount your TFTP server directories onto the @code{targets} to
+move the required files to the TFTP server automatically.
If you plan to use an NFS root file system as well (actually if you mount the
store from an NFS share), then the TFTP server needs to serve the file
store path, for example as
@file{tftp://tftp-server/gnu/store/…-initrd/initrd.cpio.gz}.
-Two symlinks are created to make this possible. The first symlink is
-@code{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to
-@file{../../../boot/grub/grub.cfg},
-where @code{target} may be @file{/boot}. In this case the link is not leaving
-the served TFTP root directory, but otherwise it does. The second link is
-@code{target}@file{/gnu/store} and points to @file{../gnu/store}. This link
-is leaving the served TFTP root directory.
-
-The assumption behind all this is that you have an NFS server exporting the root
-file system for your Guix system, and additionally a TFTP server exporting your
-@code{target} directory—usually @file{/boot}—from that same root file system for
-your Guix system. In this constellation the symlinks will work.
-
-For other constellations you will have to program your own bootloader installer,
-which then takes care to make necessary files from the store accessible through
-TFTP, for example by copying them into the TFTP root directory at @code{target}.
+Two symlinks are created to make this possible. For each target in the
+@code{targets} field, the first symlink is
+@samp{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to
+@file{../../../boot/grub/grub.cfg}, where @samp{target} may be
+@file{/boot}. In this case the link is not leaving the served TFTP root
+directory, but otherwise it does. The second link is
+@samp{target}@file{/gnu/store} and points to @file{../gnu/store}. This
+link is leaving the served TFTP root directory.
+
+The assumption behind all this is that you have an NFS server exporting
+the root file system for your Guix system, and additionally a TFTP
+server exporting your @code{targets} directories—usually a single
+@file{/boot}—from that same root file system for your Guix system. In
+this constellation the symlinks will work.
+
+For other constellations you will have to program your own bootloader
+installer, which then takes care to make necessary files from the store
+accessible through TFTP, for example by copying them into the TFTP root
+directory to your @code{targets}.
It is important to note that symlinks pointing outside the TFTP root directory
may need to be allowed in the configuration of your TFTP server. Further the
over netboot possible. For all this we can currently only recommend you to look
for instructions about @acronym{PXE, Preboot eXecution Environment}.
-@item @code{target}
-This is a string denoting the target onto which to install the
+@item @code{targets}
+This is a list of strings denoting the targets onto which to install the
bootloader.
-The interpretation depends on the bootloader in question. For
-@code{grub-bootloader}, for example, it should be a device name understood by
-the bootloader @command{installer} command, such as @code{/dev/sda} or
-@code{(hd0)} (@pxref{Invoking grub-install,,, grub, GNU GRUB Manual}). For
-@code{grub-efi-bootloader}, it should be the mount point of the EFI file
-system, usually @file{/boot/efi}. For @code{grub-efi-netboot-bootloader},
-@code{target} should be the mount point corresponding to the TFTP root
-directory of your TFTP server.
+The interpretation of targets depends on the bootloader in question.
+For @code{grub-bootloader}, for example, they should be device names
+understood by the bootloader @command{installer} command, such as
+@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
+GNU GRUB Manual}). For @code{grub-efi-bootloader}, they should be mount
+points of the EFI file system, usually @file{/boot/efi}. For
+@code{grub-efi-netboot-bootloader}, @code{targets} should be the mount
+points corresponding to TFTP root directories served by your TFTP
+server.
@item @code{menu-entries} (default: @code{()})
A possibly empty list of @code{menu-entry} objects (see below), denoting
needed for the system to operate correctly---e.g., the @file{/etc},
@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
-This command also installs bootloader on the target specified in
+This command also installs bootloader on the targets specified in
@file{my-os-config}, unless the @option{--no-bootloader} option was
passed.
(timezone "Etc/UTC")
(bootloader (bootloader-configuration
(bootloader grub-bootloader)
- (target "/dev/vda")
+ (targets '("/dev/vda"))
(terminal-outputs '(console))))
(file-systems (cons (file-system
(mount-point "/")
This service represents PID@tie{}1.
@end defvr
+@node Home Configuration
+@chapter Home Configuration
+@cindex home configuration
+Guix supports declarative configuration of @dfn{home environments} by
+utilizing the configuration mechanism described in the previous chapter
+(@pxref{Defining Services}), but for user's dotfiles and packages. It
+works both on Guix System and foreign distros and allows users to
+declare all the packages and services that should be installed and
+configured for the user. Once a user has written a file containing
+@code{home-environment} record, such a configuration can be
+@dfn{instantiated} by an unprivileged user with the @command{guix home}
+command (@pxref{Invoking guix home}).
+@c Maybe later, it will be possible to make home configuration a part of
+@c system configuration to make everything managed by guix system.
+
+@quotation Note
+The functionality described in this section is still under development
+and is subject to change. Get in touch with us on
+@email{guix-devel@@gnu.org}!
+@end quotation
+
+The user's home environment usually consists of three basic parts:
+software, configuration, and state. Software in mainstream distros are
+usually installed system-wide, but with GNU Guix most software packages
+can be installed on a per-user basis without needing root privileges,
+and are thus considered part of the user’s @dfn{home environment}.
+Packages on their own not very useful in many cases, because often they
+require some additional configuration, usually config files that reside
+in @env{XDG_CONFIG_HOME} (@file{~/.config} by default) or other
+directories. Everything else can be considered state, like media files,
+application databases, and logs.
+
+Using Guix for managing home environments provides a number of
+advantages:
+
+@itemize
+
+@item All software can be configured in one language (Guile Scheme),
+this gives users the ability to share values between configurations of
+different programs.
+
+@item A well-defined home environment is self-contained and can be
+created in a declarative and reproducible way---there is no need to grab
+external binaries or manually edit some configuration file.
+
+@item After every @command{guix home reconfigure} invocation, a new home
+environment generation will be created. This means that users can
+rollback to a previous home environment generation so they don’t have to
+worry about breaking their configuration.
+
+@item It is possible to manage stateful data with Guix Home, this
+includes the ability to automatically clone Git repositories on the
+initial setup of the machine, and periodically running commands like
+@command{rsync} to sync data with another host. This functionality is
+still in an experimental stage, though.
+
+@end itemize
+
+@menu
+* Declaring the Home Environment:: Customizing your Home.
+* Configuring the Shell:: Enabling home environment.
+* Home Services:: Specifying home services.
+* Invoking guix home:: Instantiating a home configuration.
+@end menu
+
+@node Declaring the Home Environment
+@section Declaring the Home Environment
+The home environment is configured by providing a
+@code{home-environment} declaration in a file that can be passed to the
+@command{guix home} command (@pxref{Invoking guix home}). A simple
+setup can include Bash and a custom text configuration, like in the
+example below. Don't be afraid to declare home environment parts, which
+overlaps with your current dotfiles, before installing any configuration
+files, Guix Home will back up existing config files to a separate place
+in the home folder.
+
+@quotation Note
+It is highly recommended that you manage your shell or shells with Guix
+Home, because it will make sure that all the necessary scripts are
+sourced by the shell configuration file. Otherwise you will need to do
+it manually. (@pxref{Configuring the Shell}).
+@end quotation
+
+@findex home-environment
+@lisp
+@include he-config-bare-bones.scm
+@end lisp
+
+The @code{packages} field should be self-explanatory, it will install
+the list of packages into the user's profile. The most important field
+is @code{services}, it contains a list of @dfn{home services}, which are
+the basic building blocks of a home environment.
+
+There is no daemon (at least not necessarily) related to a home service,
+a home service is just an element that is used to declare part of home
+environment and extend other parts of it. The extension mechanism
+discussed in the previous chapter (@pxref{Defining Services}) should not
+be confused with @ref{Shepherd Services}. Using this extension
+mechanism and some Scheme code that glues things together gives the user
+the freedom to declare their own, very custom, home environments.
+
+@node Configuring the Shell
+@section Configuring the Shell
+This section is safe to skip if your shell or shells are managed by
+Guix Home. Otherwise, read it carefully.
+
+There are a few scripts that must be evaluated by a login shell to
+activate the home environment. The shell startup files only read by
+login shells often have @code{profile} suffix. For more information
+about login shells see @ref{Invoking Bash,,, bash, The GNU Bash
+Reference Manual} and see @ref{Bash Startup Files,,, bash, The GNU Bash
+Reference Manual}.
+
+The first script that needs to be sourced is @file{setup-environment},
+which sets all the necessary environment variables (including variables
+declared by the user) and the second one is @file{on-first-login}, which
+starts Shepherd for the current user and performs actions declared by
+other home services that extends
+@code{home-run-on-first-login-service-type}.
+
+Guix Home will always create @file{~/.profile}, which contains the
+following lines:
+
+@example
+HOME_ENVIRONMENT=$HOME/.guix-home
+. $HOME_ENVIRONMENT/setup-environment
+$HOME_ENVIRONMENT/on-first-login
+@end example
+
+This makes POSIX compliant login shells activate the home environment.
+However, in most cases this file won't be read by most modern shells,
+because they are run in non POSIX mode by default and have their own
+@file{*profile} startup files. For example Bash will prefer
+@file{~/.bash_profile} in case it exists and only if it doesn't will it
+fallback to @file{~/.profile}. Zsh (if no additional options are
+specified) will ignore @file{~/.profile}, even if @file{~/.zprofile}
+doesn't exist.
+
+To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or
+@code{source ~/profile} to the startup file for the login shell. In
+case of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is
+@file{~/.zprofile}.
+
+@quotation Note
+This step is only required if your shell is NOT managed by Guix Home.
+Otherwise, everything will be done automatically.
+@end quotation
+
+@node Home Services
+@section Home Services
+@cindex home services
+
+A @dfn{home service} is not necessarily something that has a daemon and
+is managed by Shepherd (@pxref{Jump Start,,, shepherd, The GNU Shepherd
+Manual}), in most cases it doesn't. It's a simple building block of the
+home environment, often declaring a set of packages to be installed in
+the home environment profile, a set of config files to be symlinked into
+@env{XDG_CONFIG_HOME} (@file{~/.config} by default), and environment
+variables to be set by a login shell.
+
+There is a service extension mechanism (@pxref{Service Composition})
+which allows home services to extend other home services and utilize
+capabilities they provide; for example: declare mcron jobs
+(@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home
+Service}; declare daemons by extending @ref{Shepherd Home Service}; add
+commands, which will be invoked on by the Bash by extending
+@ref{Shells Home Services, @code{home-bash-service-type}}.
+
+A good way to discover avaliable home services is using the
+@command{guix home search} command (@pxref{Invoking guix home}). After
+the required home services are found, include its module with the
+@code{use-modules} form (@pxref{use-modules,, Using Guile Modules,
+guile, The GNU Guile Reference Manual}), or the @code{#:use-modules}
+directive (@pxref{define-module,, Creating Guile Modules, guile, The GNU
+Guile Reference Manual}) and declare a home service using the
+@code{service} function, or extend a service type by declaring a new
+service with the @code{simple-service} procedure from @code{(gnu
+services)}.
+
+@menu
+* Essential Home Services:: Environment variables, packages, on-* scripts.
+* 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.
+@end menu
+@c In addition to that Home Services can provide
+
+@node Essential Home Services
+@subsection Essential Home Services
+There are a few essential services defined in @code{(gnu
+home-services)}, they are mostly for internal use and are required to
+build a home environment, but some of them will be useful for the end
+user.
+
+@cindex environment variables
+
+@defvr {Scheme Variable} home-environment-variables-service-type
+The service of this type will be instantiated by every home environment
+automatically by default, there is no need to define it, but someone may
+want to extend it with a list of pairs to set some environment
+variables.
+
+@lisp
+(list ("ENV_VAR1" . "value1")
+ ("ENV_VAR2" . "value2"))
+@end lisp
+
+The easiest way to extend a service type, without defining new service
+type is to use the @code{simple-service} helper from @code{(gnu
+services)}.
+
+@lisp
+(simple-service 'some-useful-env-vars-service
+ home-environment-variables-service-type
+ `(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst")
+ ("SHELL" . ,(file-append zsh "/bin/zsh"))
+ ("USELESS_VAR" . #f)
+ ("_JAVA_AWT_WM_NONREPARENTING" . #t)))
+@end lisp
+
+If you include such a service in you home environment definition, it
+will add the following content to the @file{setup-environment} script
+(which is expected to be sourced by the login shell):
+
+@example
+export LESSHISTFILE=$XDG_CACHE_HOME/.lesshst
+export SHELL=/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh
+export _JAVA_AWT_WM_NONREPARENTING
+@end example
+
+@quotation Note
+Make sure that module @code{(gnu packages shells)} is imported with
+@code{use-modules} or any other way, this namespace contains the
+definition of the @code{zsh} packages, which is used in the example
+above.
+@end quotation
+
+The association list (@pxref{Association Lists, alists, Association
+Lists, guile, The GNU Guile Reference manual}) is a data structure
+containing key-value pairs, for
+@code{home-environment-variables-service-type} the key is always a
+string, the value can be a string, string-valued gexp
+(@pxref{G-Expressions}), file-like object (@pxref{G-Expressions,
+file-like object}) or boolean. For gexps, the variable will be set to
+the value of the gexp; for file-like objects, it will be set to the path
+of the file in the store (@pxref{The Store}); for @code{#t}, it will
+export the variable without any value; and for @code{#f}, it will omit
+variable.
+
+@end defvr
+
+@defvr {Scheme Variable} home-profile-service-type
+The service of this type will be instantiated by every home environment
+automatically, there is no need to define it, but you may want to extend
+it with a list of packages if you want to install additional packages
+into your profile. Other services, which need to make some programs
+avaliable to the user will also extend this service type.
+
+The extension value is just a list of packages:
+
+@lisp
+(list htop vim emacs)
+@end lisp
+
+The same approach as @code{simple-service} (@pxref{Service Reference,
+simple-service}) for @code{home-environment-variables-service-type} can
+be used here, too. Make sure that modules containing the specified
+packages are imported with @code{use-modules}. To find a package or
+information about its module use @command{guix search} (@pxref{Invoking
+guix package}). Alternatively, @code{specification->package} can be
+used to get the package record from string without importing related
+module.
+@end defvr
+
+There are few more essential services, but users are not expected to
+extend them.
+
+@defvr {Scheme Variable} home-service-type
+The root of home services DAG, it generates a folder, which later will be
+symlinked to @file{~/.guix-home}, it contains configurations,
+profile with binaries and libraries, and some necessary scripts to glue
+things together.
+@end defvr
+
+@defvr {Scheme Variable} home-run-on-first-login-service-type
+The service of this type generates a Guile script, which is expected to
+be executed by the login shell. It is only executed if the special flag
+file inside @env{XDG_RUNTIME_DIR} hasn't been created, this prevents
+redundant executions of the script if multiple login shells are spawned.
+
+It can be extended with a gexp. However, to autostart an application,
+users @emph{should not} use this service, in most cases it's better to extend
+@code{home-shpeherd-service-type} with a Shepherd service
+(@pxref{Shepherd Services}), or extend the shell's startup file with
+required command using the appropriate service type.
+@end defvr
+
+@defvr {Scheme Variable} home-activation-service-type
+The service of this type generates a guile script, which runs on every
+@command{guix home reconfigure} invocation or any other action, which
+leads to the activation of the home environment.
+@end defvr
+
+@node Shells Home Services
+@subsection Shells
+
+@cindex shell
+@cindex login shell
+@cindex interactive shell
+@cindex bash
+@cindex zsh
+
+Shells play a quite important role in the environment initialization
+process, you can configure them manually as described in section
+@ref{Configuring the Shell}, but the recommended way is to use home services
+listed below. It's both easier and more reliable.
+
+Each home environment instantiates
+@code{home-shell-profile-service-type}, which creates a
+@file{~/.profile} startup file for all POSIX-compatible shells. This
+file contains all the necessary steps to properly initialize the
+environment, but many modern shells like Bash or Zsh prefer their own
+startup files, that's why the respective home services
+(@code{home-bash-service-type} and @code{home-zsh-service-type}) ensure
+that @file{~/.profile} is sourced by @file{~/.bash_profile} and
+@file{~/.zprofile}, respectively.
+
+@subsubheading Shell Profile Service
+
+@deftp {Data Type} home-shell-profile-configuration
+Available @code{home-shell-profile-configuration} fields are:
+
+@table @asis
+@item @code{profile} (default: @code{()}) (type: text-config)
+@code{home-shell-profile} is instantiated automatically by
+@code{home-environment}, DO NOT create this service manually, it can
+only be extended. @code{profile} is a list of strings or gexps, which
+will go to @file{~/.profile}. By default @file{~/.profile} contains the
+initialization code, which have to be evaluated by login shell to make
+home-environment's profile avaliable to the user, but other commands can
+be added to the file if it is really necessary. In most cases shell's
+configuration files are preferred places for user's customizations.
+Extend home-shell-profile service only if you really know what you do.
+
+@end table
+
+@end deftp
+
+@subsubheading Bash Home Service
+
+@deftp {Data Type} home-bash-configuration
+Available @code{home-bash-configuration} fields are:
+
+@table @asis
+@item @code{package} (default: @code{bash}) (type: package)
+The Bash package to use.
+
+@item @code{guix-defaults?} (default: @code{#t}) (type: boolean)
+Add sane defaults like reading @file{/etc/bashrc}, coloring output for
+@code{ls} provided by guix to @file{.bashrc}.
+
+@item @code{environment-variables} (default: @code{()}) (type: alist)
+Association list of environment variables to set for the Bash session.
+
+@item @code{bash-profile} (default: @code{()}) (type: text-config)
+List of strings or gexps, which will be added to @file{.bash_profile}.
+Used for executing user's commands at start of login shell (In most
+cases the shell started on tty just after login). @file{.bash_login}
+won't be ever read, because @file{.bash_profile} always present.
+
+@item @code{bashrc} (default: @code{()}) (type: text-config)
+List of strings or gexps, which will be added to @file{.bashrc}. Used
+for executing user's commands at start of interactive shell (The shell
+for interactive usage started by typing @code{bash} or by terminal app
+or any other program).
+
+@item @code{bash-logout} (default: @code{()}) (type: text-config)
+List of strings or gexps, which will be added to @file{.bash_logout}.
+Used for executing user's commands at the exit of login shell. It won't
+be read in some cases (if the shell terminates by exec'ing another
+process for example).
+
+@end table
+
+@end deftp
+
+@subsubheading Zsh Home Service
+
+@deftp {Data Type} home-zsh-configuration
+Available @code{home-zsh-configuration} fields are:
+
+@table @asis
+@item @code{package} (default: @code{zsh}) (type: package)
+The Zsh package to use.
+
+@item @code{xdg-flavor?} (default: @code{#t}) (type: boolean)
+Place all the configs to @file{$XDG_CONFIG_HOME/zsh}. Makes
+@file{~/.zshenv} to set @env{ZDOTDIR} to @file{$XDG_CONFIG_HOME/zsh}.
+Shell startup process will continue with
+@file{$XDG_CONFIG_HOME/zsh/.zshenv}.
+
+@item @code{environment-variables} (default: @code{()}) (type: alist)
+Association list of environment variables to set for the Zsh session.
+
+@item @code{zshenv} (default: @code{()}) (type: text-config)
+List of strings or gexps, which will be added to @file{.zshenv}. Used
+for setting user's shell environment variables. Must not contain
+commands assuming the presence of tty or producing output. Will be read
+always. Will be read before any other file in @env{ZDOTDIR}.
+
+@item @code{zprofile} (default: @code{()}) (type: text-config)
+List of strings or gexps, which will be added to @file{.zprofile}. Used
+for executing user's commands at start of login shell (In most cases the
+shell started on tty just after login). Will be read before
+@file{.zlogin}.
+
+@item @code{zshrc} (default: @code{()}) (type: text-config)
+List of strings or gexps, which will be added to @file{.zshrc}. Used
+for executing user's commands at start of interactive shell (The shell
+for interactive usage started by typing @code{zsh} or by terminal app or
+any other program).
+
+@item @code{zlogin} (default: @code{()}) (type: text-config)
+List of strings or gexps, which will be added to @file{.zlogin}. Used
+for executing user's commands at the end of starting process of login
+shell.
+
+@item @code{zlogout} (default: @code{()}) (type: text-config)
+List of strings or gexps, which will be added to @file{.zlogout}. Used
+for executing user's commands at the exit of login shell. It won't be
+read in some cases (if the shell terminates by exec'ing another process
+for example).
+
+@end table
+
+@end deftp
+
+@node Mcron Home Service
+@subsection Scheduled User's Job Execution
+
+@cindex cron
+@cindex mcron
+@cindex scheduling jobs
+
+The @code{(gnu home-services mcron)} module provides an interface to
+GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
+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}
+record.
+
+@defvr {Scheme Variable} home-mcron-service-type
+This is the type of the @code{mcron} home service, whose value is an
+@code{home-mcron-configuration} object. It allows to manage scheduled
+tasks.
+
+This service type can be the target of a service extension that provides
+additional job specifications (@pxref{Service Composition}). In other
+words, it is possible to define services that provide additional mcron
+jobs to run.
+@end defvr
+
+@deftp {Data Type} home-mcron-configuration
+Data type representing the configuration of mcron.
+
+@table @asis
+@item @code{mcron} (default: @var{mcron})
+The mcron package to use.
+
+@item @code{jobs}
+This is a list of gexps (@pxref{G-Expressions}), where each gexp
+corresponds to an mcron job specification (@pxref{Syntax, mcron job
+specifications,, mcron, GNU@tie{}mcron}).
+@end table
+@end deftp
+
+@node Shepherd Home Service
+@subsection Managing User's Daemons
+
+@cindex shepherd services
+
+@defvr {Scheme Variable} home-shepherd-service-type
+The service type for the userland Shepherd, which allows one to manage
+long-running processes or one-shot tasks. User's Shepherd is not an
+init process (PID 1), but almost all other information described in
+(@pxref{Shepherd Services}) is applicable here too.
+
+This is the service type that extensions target when they want to create
+shepherd services (@pxref{Service Types and Services}, for an example).
+Each extension must pass a list of @code{<shepherd-service>}. Its
+value must be a @code{shepherd-configuration}, as described below.
+@end defvr
+
+@deftp {Data Type} shepherd-configuration
+This data type represents the Shepherd's configuration.
+
+@table @code
+@item shepherd (default: @code{shepherd})
+The Shepherd package to use.
+
+@item auto-start? (default: @code{#t})
+Whether or not to start Shepherd on first login.
+
+@item services (default: @code{'()})
+A list of @code{<shepherd-service>} to start.
+You should probably use the service extension
+mechanism instead (@pxref{Shepherd Services}).
+@end table
+@end deftp
+
+@node Invoking guix home
+@section Invoking @code{guix home}
+
+Once you have written a home environment declaration (@pxref{Declaring
+the Home Environment,,,,}, it can be @dfn{instantiated} using the
+@command{guix home} command. The synopsis is:
+
+@example
+guix home @var{options}@dots{} @var{action} @var{file}
+@end example
+
+@var{file} must be the name of a file containing a
+@code{home-environment} declaration. @var{action} specifies how the
+home environment is instantiated, but there are few auxuliary actions
+which don't instantiate it. Currently the following values are
+supported:
+
+@table @code
+@item search
+Display available home service type definitions that match the given
+regular expressions, sorted by relevance:
+
+@cindex shell
+@cindex shell-profile
+@cindex bash
+@cindex zsh
+@example
+$ guix home search shell
+name: home-shell-profile
+location: gnu/home-services/shells.scm:73:2
+extends: home-files
+description: Create `~/.profile', which is used for environment initialization
++ of POSIX compatible login shells. Can be extended with a list of strings or
++ gexps.
+relevance: 6
+
+name: home-zsh-plugin-manager
+location: gnu/home-services/shellutils.scm:28:2
+extends: home-zsh home-profile
+description: Install plugins in profile and configure Zsh to load them.
+relevance: 1
+
+name: home-zsh-direnv
+location: gnu/home-services/shellutils.scm:69:2
+extends: home-profile home-zsh
+description: Enables `direnv' for `zsh'. Adds hook to `.zshrc' and installs a
++ package in the profile.
+relevance: 1
+
+name: home-zsh-autosuggestions
+location: gnu/home-services/shellutils.scm:43:2
+extends: home-zsh-plugin-manager home-zsh
+description: Enables Fish-like fast/unobtrusive autosuggestions for `zsh' and
++ sets reasonable default values for some plugin's variables to improve perfomance
++ and adjust behavior: `(history completion)' is set for strategy, manual rebind
++ and async are enabled.
+relevance: 1
+
+name: home-zsh
+location: gnu/home-services/shells.scm:236:2
+extends: home-files home-profile
+description: Install and configure Zsh.
+relevance: 1
+
+name: home-bash
+location: gnu/home-services/shells.scm:388:2
+extends: home-files home-profile
+description: Install and configure Bash.
+relevance: 1
+
+@dots{}
+@end example
+
+As for @command{guix package --search}, the result is written in
+@code{recutils} format, which makes it easy to filter the output
+(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
+
+@item reconfigure
+Build the home environment described in @var{file}, and switch to it.
+Switching means that the activation script will be evaluated and (in
+basic scenario) symlinks to configuration files generated from
+@code{home-environment} declaration will be created in @file{~}. If the
+file with the same path already exists in home folder it will be moved
+to @file{~/TIMESTAMP-guix-home-legacy-configs-backup}, where TIMESTAMP
+is a current UNIX epoch time.
+
+@quotation Note
+It is highly recommended to run @command{guix pull} once before you run
+@command{guix home reconfigure} for the first time (@pxref{Invoking guix
+pull}).
+@end quotation
+
+This effects all the configuration specified in @var{file}. The command
+starts Shepherd services specified in @var{file} that are not currently
+running; if a service is currently running, this command will arrange
+for it to be upgraded the next time it is stopped (e.g.@: by @code{herd
+stop X} or @code{herd restart X}).
+
+This command creates a new generation whose number is one greater than
+the current generation (as reported by @command{guix home
+list-generations}). If that generation already exists, it will be
+overwritten. This behavior mirrors that of @command{guix package}
+(@pxref{Invoking guix package}).
+
+@cindex provenance tracking, of the home environment
+Upon completion, the new home is deployed under @file{~/.guix-home}.
+This directory contains @dfn{provenance meta-data}: the list of channels
+in use (@pxref{Channels}) and @var{file} itself, when available. You
+can view the provenance information by running:
+
+@example
+guix home describe
+@end example
+
+This information is useful should you later want to inspect how this
+particular generation was built. In fact, assuming @var{file} is
+self-contained, you can later rebuild generation @var{n} of your
+home environment with:
+
+@example
+guix time-machine \
+ -C /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/channels.scm -- \
+ home reconfigure \
+ /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/configuration.scm
+
+@end example
+
+You can think of it as some sort of built-in version control! Your
+home is not just a binary artifact: @emph{it carries its own source}.
+@c @xref{Service Reference, @code{provenance-service-type}}, for more
+@c information on provenance tracking.
+
+@c @footnote{This action (and the related actions
+@c @code{switch-generation} and @code{roll-back}) are usable after the
+@c home environment is initialized.}.
+
+@item switch-generation
+@cindex home generations
+Switch to an existing home generation. This action atomically switches
+the home profile to the specified home generation.
+
+The target generation can be specified explicitly by its generation
+number. For example, the following invocation would switch to home
+generation 7:
+
+@example
+guix home switch-generation 7
+@end example
+
+The target generation can also be specified relative to the current
+generation with the form @code{+N} or @code{-N}, where @code{+3} means
+``3 generations ahead of the current generation,'' and @code{-1} means
+``1 generation prior to the current generation.'' When specifying a
+negative value such as @code{-1}, you must precede it with @code{--} to
+prevent it from being parsed as an option. For example:
+
+@example
+guix home switch-generation -- -1
+@end example
+
+This action will fail if the specified generation does not exist.
+
+@item roll-back
+@cindex rolling back
+Switch to the preceding home generation. This is the inverse
+of @command{reconfigure}, and it is exactly the same as invoking
+@command{switch-generation} with an argument of @code{-1}.
+
+@item delete-generations
+@cindex deleting home generations
+@cindex saving space
+Delete home generations, making them candidates for garbage collection
+(@pxref{Invoking guix gc}, for information on how to run the ``garbage
+collector'').
+
+This works in the same way as @samp{guix package --delete-generations}
+(@pxref{Invoking guix package, @option{--delete-generations}}). With no
+arguments, all home generations but the current one are deleted:
+
+@example
+guix home delete-generations
+@end example
+
+You can also select the generations you want to delete. The example below
+deletes all the home generations that are more than two month old:
+
+@example
+guix home delete-generations 2m
+@end example
+
+@item build
+Build the derivation of the home environment, which includes all the
+configuration files and programs needed. This action does not actually
+install anything.
+
+@item describe
+Describe the current home generation: its file name, as well as
+provenance information when available.
+
+@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
+@option{--list-generations} option of @command{guix package}
+(@pxref{Invoking guix package}).
+
+Optionally, one can specify a pattern, with the same syntax that is used
+in @command{guix package --list-generations}, to restrict the list of
+generations displayed. For instance, the following command displays
+generations that are up to 10 days old:
+
+@example
+$ guix home list-generations 10d
+@end example
+
+@end table
@node Documentation
@chapter Documentation
HCoop / jackhill / guix / guix.git / blobdiff