diff options
| author | Efraim Flashner <efraim@flashner.co.il> | 2023-01-30 11:33:18 +0200 |
|---|---|---|
| committer | Efraim Flashner <efraim@flashner.co.il> | 2023-01-30 12:39:40 +0200 |
| commit | 4cf1acc7f3033b50b0bf19e02c9f522d522d338c (patch) | |
| tree | 9fd64956ee60304c15387eb394cd649e49f01467 /doc | |
| parent | edb8c09addd186d9538d43b12af74d6c7aeea082 (diff) | |
| parent | 595b53b74e3ef57a1c0c96108ba86d38a170a241 (diff) | |
| download | guix-4cf1acc7f3033b50b0bf19e02c9f522d522d338c.tar guix-4cf1acc7f3033b50b0bf19e02c9f522d522d338c.tar.gz | |
Merge remote-tracking branch 'origin/master' into core-updates
Conflicts:
doc/guix.texi
gnu/local.mk
gnu/packages/admin.scm
gnu/packages/base.scm
gnu/packages/chromium.scm
gnu/packages/compression.scm
gnu/packages/databases.scm
gnu/packages/diffoscope.scm
gnu/packages/freedesktop.scm
gnu/packages/gnome.scm
gnu/packages/gnupg.scm
gnu/packages/guile.scm
gnu/packages/inkscape.scm
gnu/packages/llvm.scm
gnu/packages/openldap.scm
gnu/packages/pciutils.scm
gnu/packages/ruby.scm
gnu/packages/samba.scm
gnu/packages/sqlite.scm
gnu/packages/statistics.scm
gnu/packages/syndication.scm
gnu/packages/tex.scm
gnu/packages/tls.scm
gnu/packages/version-control.scm
gnu/packages/xml.scm
guix/build-system/copy.scm
guix/scripts/home.scm
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build.scm | 2 | ||||
| -rw-r--r-- | doc/contributing.texi | 277 | ||||
| -rw-r--r-- | doc/guix-cookbook.texi | 1083 | ||||
| -rw-r--r-- | doc/guix.texi | 2573 | ||||
| -rw-r--r-- | doc/htmlxref.cnf | 12 | ||||
| -rw-r--r-- | doc/local.mk | 12 |
6 files changed, 3144 insertions, 815 deletions
diff --git a/doc/build.scm b/doc/build.scm index 7d0db8621f..8b8eed639f 100644 --- a/doc/build.scm +++ b/doc/build.scm @@ -66,7 +66,7 @@ (define %manual-languages ;; Available translations for the 'guix-manual' text domain. - '("de" "en" "es" "fr" "ru" "zh_CN")) + '("de" "en" "es" "fr" "pt_BR" "ru" "zh_CN")) (define %cookbook-languages ;; Available translations for the 'guix-cookbook' text domain. diff --git a/doc/contributing.texi b/doc/contributing.texi index 7712f63d67..c436bc4a31 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -786,12 +786,29 @@ for instance, the module python-dateutil is packaged under the names starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as described above. +@quotation Note +Currently there are two different build systems for Python packages in Guix: +@var{python-build-system} and @var{pyproject-build-system}. For the +longest time, Python packages were built from an informally specified +@file{setup.py} file. That worked amazingly well, considering Python's +success, but was difficult to build tooling around. As a result, a host +of alternative build systems emerged and the community eventually settled on a +@url{https://peps.python.org/pep-0517/, formal standard} for specifying build +requirements. @var{pyproject-build-system} is Guix's implementation of this +standard. It is considered ``experimental'' in that it does not yet support +all the various PEP-517 @emph{build backends}, but you are encouraged to try +it for new Python packages and report any problems. It will eventually be +deprecated and merged into @var{python-build-system}. +@end quotation + @subsubsection Specifying Dependencies @cindex inputs, for Python packages Dependency information for Python packages is usually available in the package source tree, with varying degrees of accuracy: in the -@file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}. +@file{pyproject.toml} file, the @file{setup.py} file, in +@file{requirements.txt}, or in @file{tox.ini} (the latter mostly for +test dependencies). Your mission, when writing a recipe for a Python package, is to map these dependencies to the appropriate type of ``input'' (@pxref{package @@ -802,10 +819,12 @@ following check list to determine which dependency goes where. @itemize @item -We currently package Python 2 with @code{setuptools} and @code{pip} -installed like Python 3.4 has per default. Thus you don't need to -specify either of these as an input. @command{guix lint} will warn you -if you do. +We currently package Python with @code{setuptools} and @code{pip} +installed per default. This is about to change, and users are encouraged +to use @code{python-toolchain} if they want a build environment for Python. + +@command{guix lint} will warn if @code{setuptools} or @code{pip} are +added as native-inputs because they are generally not necessary. @item Python dependencies required at run time go into @@ -814,9 +833,10 @@ Python dependencies required at run time go into @file{requirements.txt} file. @item -Python packages required only at build time---e.g., those listed with -the @code{setup_requires} keyword in @file{setup.py}---or only for -testing---e.g., those in @code{tests_require}---go into +Python packages required only at build time---e.g., those listed under +@code{build-system.requires} in @file{pyproject.toml} or with the +@code{setup_requires} keyword in @file{setup.py}---or dependencies only +for testing---e.g., those in @code{tests_require} or @file{tox.ini}---go into @code{native-inputs}. The rationale is that (1) they do not need to be propagated because they are not needed at run time, and (2) in a cross-compilation context, it's the ``native'' input that we'd want. @@ -1069,11 +1089,16 @@ and then to browse them ``by hand'' using @code{car}, @code{cdr}, notably the fact that it is hard to read, error-prone, and a hindrance to proper type error reports. +@findex define-record-type* +@findex match-record +@cindex pattern matching Guix code should define appropriate data types (for instance, using @code{define-record-type*}) rather than abuse lists. In addition, it should use pattern matching, via Guile’s @code{(ice-9 match)} module, especially when matching lists (@pxref{Pattern Matching,,, guile, GNU -Guile Reference Manual}). +Guile Reference Manual}); pattern matching for records is better done +using @code{match-record} from @code{(guix records)}, which, unlike +@code{match}, verifies field names at macro-expansion time. @node Formatting Code @subsection Formatting Code @@ -1138,8 +1163,8 @@ This mailing list is backed by a Debbugs instance, which allows us to keep track of submissions (@pxref{Tracking Bugs and Patches}). Each message sent to that mailing list gets a new tracking number assigned; people can then follow up on the submission by sending email to -@code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking -number (@pxref{Sending a Patch Series}). +@code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} is +the tracking number (@pxref{Sending a Patch Series}). Please write commit logs in the ChangeLog format (@pxref{Change Logs,,, standards, GNU Coding Standards}); you can check the commit history for @@ -1149,15 +1174,6 @@ Before submitting a patch that adds or modifies a package definition, please run through this check list: @enumerate -@cindex @code{git format-patch} -@cindex @code{git-format-patch} -@item -When generating your patches with @code{git format-patch} or @code{git -send-email}, we recommend using the option @code{--base=}, perhaps with -the value @code{auto}. This option adds a note to the patch stating -which commit the patch is based on. This helps reviewers understand how -to apply and review your patches. - @item If the authors of the packaged software provide a cryptographic signature for the release tarball, make an effort to verify the @@ -1341,12 +1357,13 @@ guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as a subject, if your patch is to be applied on a branch other than @code{master}, say @code{core-updates}, specify it in the subject like -@samp{[PATCH core-updates] @dots{}}. You may use your email client or -the @command{git send-email} command (@pxref{Sending a Patch Series}). -We prefer to get patches in plain text messages, either inline or as -MIME attachments. You are advised to pay attention if your email client -changes anything like line breaks or indentation which could potentially -break the patches. +@samp{[PATCH core-updates] @dots{}}. + +You may use your email client or the @command{git send-email} command +(@pxref{Sending a Patch Series}). We prefer to get patches in plain +text messages, either inline or as MIME attachments. You are advised to +pay attention if your email client changes anything like line breaks or +indentation which could potentially break the patches. Expect some delay when you submit your very first patch to @email{guix-patches@@gnu.org}. You have to wait until you get an @@ -1354,7 +1371,7 @@ acknowledgement with the assigned tracking number. Future acknowledgements should not be delayed. When a bug is resolved, please close the thread by sending an email to -@email{@var{NNN}-done@@debbugs.gnu.org}. +@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}. @node Configuring Git @subsection Configuring Git @@ -1392,26 +1409,152 @@ git config --local format.thread shallow git config --local sendemail.thread no @end example -@unnumberedsubsec Sending a Patch Series -@anchor{Sending a Patch Series} +@node Sending a Patch Series +@subsection Sending a Patch Series @cindex patch series @cindex @code{git send-email} +@cindex @code{git format-patch} + +@unnumberedsubsubsec Single Patches +@anchor{Single Patches} +The @command{git send-email} command is the best way to send both single +patches and patch series (@pxref{Multiple Patches}) to the Guix mailing +list. Sending patches as email attachments may make them difficult to +review in some mail clients, and @command{git diff} does not store commit +metadata. + +@quotation Note +The @command{git send-email} command is provided by the @code{send-email} +output of the @code{git} package, i.e. @code{git:send-email}. +@end quotation + +The following command will create a patch email from the latest commit, +open it in your @var{EDITOR} or @var{VISUAL} for editing, and send it to +the Guix mailing list to be reviewed and merged: + +@example +$ git send-email -1 -a --base=auto --to=guix-patches@@gnu.org +@end example + +@quotation Tip +To add a prefix to the subject of your patch, you may use the +@option{--subject-prefix} option. The Guix project uses this to +specify that the patch is intended for a branch or repository +other than the @code{master} branch of +@url{https://git.savannah.gnu.org/cgit/guix.git}. + +@example +git send-email -1 -a --base=auto \ + --subject-prefix='PATCH core-updates' \ + --to=guix-patches@@gnu.org +@end example +@end quotation + +The patch email contains a three-dash separator line after the commit +message. You may ``annotate'' the patch with explanatory text by adding +it under this line. If you do not wish to annotate the email, you may +drop the @option{-a} flag (which is short for @option{--annotate}). + +The @option{--base=auto} flag automatically adds a note at the bottom +of the patch of the commit it was based on, making it easier for +maintainers to rebase and merge your patch. + +If you need to send a revised patch, don't resend it like this or send +a ``fix'' patch to be applied on top of the last one; instead, use +@command{git commit -a} or @url{https://git-rebase.io, @command{git rebase}} +to modify the commit, and use the @email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} +address and the @option{-v} flag with @command{git send-email}. + +@example +$ git commit -a +$ git send-email -1 -a --base=auto -v@var{REVISION} \ + --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org +@end example + +@quotation Note +Due to an apparent bug in @command{git send-email}, +@option{-v @var{REVISION}} (with the space) will not work; you +@emph{must} use @option{-v@var{REVISION}}. +@end quotation -When sending a patch series (e.g., using @code{git send-email}), please -first send one message to @email{guix-patches@@gnu.org}, and then send -subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure -they are kept together. See -@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation} -for more information. You can install @command{git send-email} with -@command{guix install git:send-email}. -@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html - -To maximize the chances that you patch series is reviewed, the preferred -submission way is to use the @code{etc/teams.scm} script to notify the -appropriate team members (@pxref{Teams}). - -@unnumberedsubsec Teams -@anchor{Teams} +You can find out @var{ISSUE_NUMBER} either by searching on the mumi +interface at @url{issues.guix.gnu.org} for the name of your patch or +reading the acknowledgement email sent automatically by Debbugs in +reply to incoming bugs and patches, which contains the bug number. + +@unnumberedsubsubsec Notifying Teams +@anchor{Notifying Teams} +@cindex teams +The @file{etc/teams.scm} script may be used to notify all those who +may be interested in your patch of its existence (@pxref{Teams}). +Use @command{etc/teams.scm list-teams} to display all the teams, +decide which team(s) your patch relates to, and use +@command{etc/teams.scm cc} to output various @command{git send-email} +flags which will notify the appropriate team members, or use +@command{etc/teams.scm cc-members} to detect the appropriate teams +automatically. + +@unnumberedsubsubsec Multiple Patches +@anchor{Multiple Patches} +@cindex cover letter +While @command{git send-email} alone will suffice for a single +patch, an unfortunate flaw in Debbugs means you need to be more +careful when sending multiple patches: if you send them all to the +@email{guix-patches@@gnu.org} address, a new issue will be created +for each patch! + +When sending a series of patches, it's best to send a Git ``cover +letter'' first, to give reviewers an overview of the patch series. +We can create a directory called @file{outgoing} containing both +our patch series and a cover letter called @file{0000-cover-letter.patch} +with @command{git format-patch}. + +@example +$ git format-patch -@var{NUMBER_COMMITS} -o outgoing \ + --cover-letter --base=auto +@end example + +We can now send @emph{just} the cover letter to the +@email{guix-patches@@gnu.org} address, which will create an issue +that we can send the rest of the patches to. + +@example +$ git send-email outgoing/0000-cover-letter.patch -a \ + --to=guix-patches@@gnu.org \ + $(etc/teams.scm cc-members ...) +$ rm outgoing/0000-cover-letter.patch # we don't want to resend it! +@end example + +Ensure you edit the email to add an appropriate subject line and +blurb before sending it. Note the automatically generated shortlog +and diffstat below the blurb. + +Once the Debbugs mailer has replied to your cover letter email, you +can send the actual patches to the newly-created issue address. + +@example +$ git send-email outgoing/*.patch \ + --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \ + $(etc/teams.scm cc-members ...) +$ rm -rf outgoing # we don't need these anymore +@end example + +Thankfully, this @command{git format-patch} dance is not necessary +to send an amended patch series, since an issue already exists for +the patchset. + +@example +$ git send-email -@var{NUMBER_COMMITS} \ + -v@var{REVISION} --base=auto \ + --to @var{ISSUE_NUMBER}@@debbugs.gnu.org +@end example + +If need be, you may use @option{--cover-letter -a} to send another cover +letter, e.g. for explaining what's changed since the last revision, and +these changes are necessary. + +@node Teams +@subsection Teams @cindex teams There are several teams mentoring different parts of the Guix source @@ -1435,7 +1578,7 @@ You can run the following command to have the @code{Mentors} team put in CC of a patch series: @example -$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch +$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch @end example The appropriate team or teams can also be inferred from the modified @@ -1444,7 +1587,7 @@ current Git repository to review, you can run: @example $ guix shell -D guix -[env]$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch +[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch @end example @node Tracking Bugs and Patches @@ -1687,23 +1830,27 @@ It additionally calls @code{make check-channel-news} to be sure @subsection Commit Policy -If you get commit access, please make sure to follow -the policy below (discussions of the policy can take place on +If you get commit access, please make sure to follow the policy below +(discussions of the policy can take place on @email{guix-devel@@gnu.org}). -Non-trivial patches should always be posted to -@email{guix-patches@@gnu.org} (trivial patches include fixing typos, -etc.). This mailing list fills the patch-tracking database -(@pxref{Tracking Bugs and Patches}). - -For patches that just add a new package, and a simple one, it's OK to -commit, if you're confident (which means you successfully built it in a -chroot setup, and have done a reasonable copyright and license -auditing). Likewise for package upgrades, except upgrades that trigger -a lot of rebuilds (for example, upgrading GnuTLS or GLib). We have a -mailing list for commit notifications (@email{guix-commits@@gnu.org}), -so people can notice. Before pushing your changes, make sure to run -@code{git pull --rebase}. +Changes should be posted to @email{guix-patches@@gnu.org}. This mailing +list fills the patch-tracking database (@pxref{Tracking Bugs and +Patches}). It also allows patches to be picked up and tested by the +quality assurance tooling; the result of that testing eventually shows +up on the dashboard at +@indicateurl{https://qa.guix.gnu.org/issue/@var{ISSUE_NUMBER}}, where +@var{ISSUE_NUMBER} is the number assigned by the issue tracker. Leave +time for a review, without committing anything (@pxref{Submitting +Patches}). If you didn’t receive any reply after one week (two weeks +for more significant changes), and if you're confident, it's OK to +commit. + +As an exception, some changes considered ``trivial'' or ``obvious'' may +be pushed directly. This includes changes to fix typos and reverting +commits that caused immediate problems. This is subject to being +adjusted, allowing individuals to commit directly on non-controversial +changes on parts they’re familiar with. When pushing a commit on behalf of somebody else, please add a @code{Signed-off-by} line at the end of the commit log message---e.g., @@ -1718,14 +1865,6 @@ right before pushing: make check-channel-news @end example -For anything else, please post to @email{guix-patches@@gnu.org} and -leave time for a review, without committing anything (@pxref{Submitting -Patches}). If you didn’t receive any reply after two weeks, and if -you're confident, it's OK to commit. - -That last part is subject to being adjusted, allowing individuals to commit -directly on non-controversial changes on parts they’re familiar with. - @subsection Addressing Issues Peer review (@pxref{Submitting Patches}) and tools such as diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index b61adc06da..b9fb916f4a 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -11,7 +11,7 @@ @set SUBSTITUTE-TOR-URL https://4zwzi66wwdaalbhgnix55ea3ab4pvvw66ll2ow53kjub6se4q2bclcyd.onion @copying -Copyright @copyright{} 2019 Ricardo Wurmus@* +Copyright @copyright{} 2019, 2022 Ricardo Wurmus@* Copyright @copyright{} 2019 Efraim Flashner@* Copyright @copyright{} 2019 Pierre Neidhardt@* Copyright @copyright{} 2020 Oleg Pykhalov@* @@ -21,6 +21,8 @@ Copyright @copyright{} 2020 Brice Waegeneire@* Copyright @copyright{} 2020 André Batista@* Copyright @copyright{} 2020 Christine Lemmer-Webber@* Copyright @copyright{} 2021 Joshua Branson@* +Copyright @copyright{} 2022 Maxim Cournoyer@* +Copyright @copyright{} 2023 Ludovic Courtès Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -71,8 +73,10 @@ Weblate} (@pxref{Translating Guix,,, guix, GNU Guix reference manual}). * Scheme tutorials:: Meet your new favorite language! * Packaging:: Packaging tutorials * System Configuration:: Customizing the GNU System -* Advanced package management:: Power to the users! +* Containers:: Isolated environments and nested systems +* Advanced package management:: Power to the users! * Environment management:: Control environment +* Installing Guix on a Cluster:: High-performance computing. * Acknowledgments:: Thanks! * GNU Free Documentation License:: The license of this document. @@ -81,18 +85,44 @@ Weblate} (@pxref{Translating Guix,,, guix, GNU Guix reference manual}). @detailmenu --- The Detailed Node Listing --- -Scheme tutorials - -* A Scheme Crash Course:: Learn the basics of Scheme - Packaging -* Packaging Tutorial:: Let's add a package to Guix! +* Packaging Tutorial:: A tutorial on how to add packages to Guix. System Configuration * Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. +* Guix System Image API:: Customizing images to target specific platforms. +* Using security keys:: How to use security keys with Guix System. +* Connecting to Wireguard VPN:: Connecting to a Wireguard VPN. +* Customizing a Window Manager:: Handle customization of a Window manager on Guix System. +* Running Guix on a Linode Server:: Running Guix on a Linode Server +* Setting up a bind mount:: Setting up a bind mount in the file-systems definition. +* Getting substitutes from Tor:: Configuring Guix daemon to get substitutes through Tor. +* Setting up NGINX with Lua:: Configuring NGINX web-server to load Lua modules. +* Music Server with Bluetooth Audio:: Headless music player with Bluetooth output. + +Containers + +* Guix Containers:: Perfectly isolated environments +* Guix System Containers:: A system inside your system + +Advanced package management + +* Guix Profiles in Practice:: Strategies for multiple profiles and manifests. + +Environment management + +* Guix environment via direnv:: Setup Guix environment with direnv + +Installing Guix on a Cluster + +* Setting Up a Head Node:: The node that runs the daemon. +* Setting Up Compute Nodes:: Client nodes. +* Cluster Network Access:: Dealing with network access restrictions. +* Cluster Disk Usage:: Disk usage considerations. +* Cluster Security Considerations:: Keeping the cluster secure. @end detailmenu @end menu @@ -299,7 +329,8 @@ Scheme Primer}}, by Christine Lemmer-Webber and the Spritely Institute. @i{Scheme at a Glance}}, by Steve Litt. @item -@uref{https://mitpress.mit.edu/sites/default/files/sicp/index.html, +@c There used to be a copy at mitpress.mit.edu but it vanished. +@uref{https://sarabander.github.io/sicp/, @i{Structure and Interpretation of Computer Programs}}, by Harold Abelson and Gerald Jay Sussman, with Julie Sussman. Colloquially known as ``SICP'', this book is a reference. @@ -311,9 +342,6 @@ guix install sicp info-reader info sicp @end example -An @uref{https://sarabander.github.io/sicp/, unofficial ebook} is also -available. - @end itemize You'll find more books, tutorials and other resources at @@ -1371,12 +1399,14 @@ reference. * Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. * Guix System Image API:: Customizing images to target specific platforms. +* Using security keys:: How to use security keys with Guix System. * Connecting to Wireguard VPN:: Connecting to a Wireguard VPN. * Customizing a Window Manager:: Handle customization of a Window manager on Guix System. * Running Guix on a Linode Server:: Running Guix on a Linode Server * Setting up a bind mount:: Setting up a bind mount in the file-systems definition. * Getting substitutes from Tor:: Configuring Guix daemon to get substitutes through Tor. * Setting up NGINX with Lua:: Configuring NGINX web-server to load Lua modules. +* Music Server with Bluetooth Audio:: Headless music player with Bluetooth output. @end menu @node Auto-Login to a Specific TTY @@ -1873,6 +1903,65 @@ guix system image --image-type=hurd-qcow2 my-hurd-os.scm will instead produce a Hurd QEMU image. +@node Using security keys +@section Using security keys +@cindex 2FA, two-factor authentication +@cindex U2F, Universal 2nd Factor +@cindex security key, configuration + +The use of security keys can improve your security by providing a second +authentication source that cannot be easily stolen or copied, at least +for a remote adversary (something that you have), to the main secret (a +passphrase -- something that you know), reducing the risk of +impersonation. + +The example configuration detailed below showcases what minimal +configuration needs to be made on your Guix System to allow the use of a +Yubico security key. It is hoped the configuration can be useful for +other security keys as well, with minor adjustments. + +@subsection Configuration for use as a two-factor authenticator (2FA) + +To be usable, the udev rules of the system should be extended with +key-specific rules. The following shows how to extend your udev rules +with the @file{lib/udev/rules.d/70-u2f.rules} udev rule file provided by +the @code{libfido2} package from the @code{(gnu packages +security-token)} module and add your user to the @samp{"plugdev"} group +it uses: + +@lisp +(use-package-modules ... security-token ...) +... +(operating-system + ... + (users (cons* (user-account + (name "your-user") + (group "users") + (supplementary-groups + '("wheel" "netdev" "audio" "video" + "plugdev")) ;<- added system group + (home-directory "/home/your-user")) + %base-user-accounts)) + ... + (services + (cons* + ... + (udev-rules-service 'fido2 libfido2 #:groups '("plugdev"))))) +@end lisp + +After re-configuring your system and re-logging in your graphical +session so that the new group is in effect for your user, you can verify +that your key is usable by launching: + +@example +guix shell ungoogled-chromium -- chromium chrome://settings/securityKeys +@end example + +and validating that the security key can be reset via the ``Reset your +security key'' menu. If it works, congratulations, your security key is +ready to be used with applications supporting two-factor authentication +(2FA). + @node Connecting to Wireguard VPN @section Connecting to Wireguard VPN @@ -2454,6 +2543,594 @@ ngx.say(stdout) #$(local-file "index.lua")))))))))))))) @end lisp +@node Music Server with Bluetooth Audio +@section Music Server with Bluetooth Audio +@cindex mpd +@cindex music server, headless +@cindex bluetooth, ALSA configuration + +MPD, the Music Player Daemon, is a flexible server-side application for +playing music. Client programs on different machines on the network --- +a mobile phone, a laptop, a desktop workstation --- can connect to it to +control the playback of audio files from your local music collection. +MPD decodes the audio files and plays them back on one or many outputs. + +By default MPD will play to the default audio device. In the example +below we make things a little more interesting by setting up a headless +music server. There will be no graphical user interface, no Pulseaudio +daemon, and no local audio output. Instead we will configure MPD with +two outputs: a bluetooth speaker and a web server to serve audio streams +to any streaming media player. + +Bluetooth is often rather frustrating to set up. You will have to pair +your Bluetooth device and make sure that the device is automatically +connected as soon as it powers on. The Bluetooth system service +returned by the @code{bluetooth-service} procedure provides the +infrastructure needed to set this up. + +Reconfigure your system with at least the following services and +packages: + +@lisp +(operating-system + ;; … + (packages (cons* bluez bluez-alsa + %base-packages)) + (services + ;; … + (dbus-service #:services (list bluez-alsa)) + (bluetooth-service #:auto-enable? #t))) +@end lisp + +Start the @code{bluetooth} service and then use @command{bluetoothctl} +to scan for Bluetooth devices. Try to identify your Bluetooth speaker +and pick out its device ID from the resulting list of devices that is +indubitably dominated by a baffling smorgasbord of your neighbors' home +automation gizmos. This only needs to be done once: + +@example +$ bluetoothctl +[NEW] Controller 00:11:22:33:95:7F BlueZ 5.40 [default] + +[bluetooth]# power on +[bluetooth]# Changing power on succeeded + +[bluetooth]# agent on +[bluetooth]# Agent registered + +[bluetooth]# default-agent +[bluetooth]# Default agent request successful + +[bluetooth]# scan on +[bluetooth]# Discovery started +[CHG] Controller 00:11:22:33:95:7F Discovering: yes +[NEW] Device AA:BB:CC:A4:AA:CD My Bluetooth Speaker +[NEW] Device 44:44:FF:2A:20:DC My Neighbor's TV +@dots{} + +[bluetooth]# pair AA:BB:CC:A4:AA:CD +Attempting to pair with AA:BB:CC:A4:AA:CD +[CHG] Device AA:BB:CC:A4:AA:CD Connected: yes + +[My Bluetooth Speaker]# [CHG] Device AA:BB:CC:A4:AA:CD UUIDs: 0000110b-0000-1000-8000-00xxxxxxxxxx +[CHG] Device AA:BB:CC:A4:AA:CD UUIDs: 0000110c-0000-1000-8000-00xxxxxxxxxx +[CHG] Device AA:BB:CC:A4:AA:CD UUIDs: 0000110e-0000-1000-8000-00xxxxxxxxxx +[CHG] Device AA:BB:CC:A4:AA:CD Paired: yes +Pairing successful + +[CHG] Device AA:BB:CC:A4:AA:CD Connected: no + +[bluetooth]# +[bluetooth]# trust AA:BB:CC:A4:AA:CD +[bluetooth]# [CHG] Device AA:BB:CC:A4:AA:CD Trusted: yes +Changing AA:BB:CC:A4:AA:CD trust succeeded + +[bluetooth]# +[bluetooth]# connect AA:BB:CC:A4:AA:CD +Attempting to connect to AA:BB:CC:A4:AA:CD +[bluetooth]# [CHG] Device AA:BB:CC:A4:AA:CD RSSI: -63 +[CHG] Device AA:BB:CC:A4:AA:CD Connected: yes +Connection successful + +[My Bluetooth Speaker]# scan off +[CHG] Device AA:BB:CC:A4:AA:CD RSSI is nil +Discovery stopped +[CHG] Controller 00:11:22:33:95:7F Discovering: no +@end example + +Congratulations, you can now automatically connect to your Bluetooth +speaker! + +It is now time to configure ALSA to use the @emph{bluealsa} Bluetooth +module, so that you can define an ALSA pcm device corresponding to your +Bluetooth speaker. For a headless server using @emph{bluealsa} with a +fixed Bluetooth device is likely simpler than configuring Pulseaudio and +its stream switching behavior. We configure ALSA by crafting a custom +@code{alsa-configuration} for the @code{alsa-service-type}. The +configuration will declare a @code{pcm} type @code{bluealsa} from the +@code{bluealsa} module provided by the @code{bluez-alsa} package, and +then define a @code{pcm} device of that type for your Bluetooth speaker. + +All that is left then is to make MPD send audio data to this ALSA +device. We also add a secondary MPD output that makes the currently +played audio files available as a stream through a web server on port +8080. When enabled a device on the network could listen to the audio +stream by connecting any capable media player to the HTTP server on port +8080, independent of the status of the Bluetooth speaker. + +What follows is the outline of an @code{operating-system} declaration +that should accomplish the above-mentioned tasks: + +@lisp +(use-modules (gnu)) +(use-service-modules audio dbus sound #;… etc) +(use-package-modules audio linux #;… etc) +(operating-system + ;; … + (packages (cons* bluez bluez-alsa + %base-packages)) + (services + ;; … + (service mpd-service-type + (mpd-configuration + (user "your-username") + (music-dir "/path/to/your/music") + (address "192.168.178.20") + (outputs (list (mpd-output + (type "alsa") + (name "MPD") + (extra-options + ;; Use the same name as in the ALSA + ;; configuration below. + '((device . "pcm.btspeaker")))) + (mpd-output + (type "httpd") + (name "streaming") + (enabled? #false) + (always-on? #true) + (tags? #true) + (mixer-type 'null) + (extra-options + '((encoder . "vorbis") + (port . "8080") + (bind-to-address . "192.168.178.20") + (max-clients . "0") ;no limit + (quality . "5.0") + (format . "44100:16:1")))))))) + (dbus-service #:services (list bluez-alsa)) + (bluetooth-service #:auto-enable? #t) + (service alsa-service-type + (alsa-configuration + (pulseaudio? #false) ;we don't need it + (extra-options + #~(string-append "\ +# Declare Bluetooth audio device type \"bluealsa\" from bluealsa module +pcm_type.bluealsa @{ + lib \"" #$(file-append bluez-alsa "/lib/alsa-lib/libasound_module_pcm_bluealsa.so") "\" +@} + +# Declare control device type \"bluealsa\" from the same module +ctl_type.bluealsa @{ + lib \"" #$(file-append bluez-alsa "/lib/alsa-lib/libasound_module_ctl_bluealsa.so") "\" +@} + +# Define the actual Bluetooth audio device. +pcm.btspeaker @{ + type bluealsa + device \"AA:BB:CC:A4:AA:CD\" # unique device identifier + profile \"a2dp\" +@} + +# Define an associated controller. +ctl.btspeaker @{ + type bluealsa +@} +")))))) +@end lisp + +Enjoy the music with the MPD client of your choice or a media player +capable of streaming via HTTP! + + +@c ********************************************************************* +@node Containers +@chapter Containers + +The kernel Linux provides a number of shared facilities that are +available to processes in the system. These facilities include a shared +view on the file system, other processes, network devices, user and +group identities, and a few others. Since Linux 3.19 a user can choose +to @emph{unshare} some of these shared facilities for selected +processes, providing them (and their child processes) with a different +view on the system. + +A process with an unshared @code{mount} namespace, for example, has its +own view on the file system --- it will only be able to see directories +that have been explicitly bound in its mount namespace. A process with +its own @code{proc} namespace will consider itself to be the only +process running on the system, running as PID 1. + +Guix uses these kernel features to provide fully isolated environments +and even complete Guix System containers, lightweight virtual machines +that share the host system's kernel. This feature comes in especially +handy when using Guix on a foreign distribution to prevent interference +from foreign libraries or configuration files that are available +system-wide. + +@menu +* Guix Containers:: Perfectly isolated environments +* Guix System Containers:: A system inside your system +@end menu + +@node Guix Containers +@section Guix Containers + +The easiest way to get started is to use @command{guix shell} with the +@option{--container} option. @xref{Invoking guix shell,,, guix, GNU +Guix Reference Manual} for a reference of valid options. + +The following snippet spawns a minimal shell process with most +namespaces unshared from the system. The current working directory is +visible to the process, but anything else on the file system is +unavailable. This extreme isolation can be very useful when you want to +rule out any sort of interference from environment variables, globally +installed libraries, or configuration files. + +@example +guix shell --container +@end example + +It is a bleak environment, barren, desolate. You will find that not +even the GNU coreutils are available here, so to explore this deserted +wasteland you need to use built-in shell commands. Even the usually +gigantic @file{/gnu/store} directory is reduced to a faint shadow of +itself. + +@example sh +$ echo /gnu/store/* +/gnu/store/@dots{}-gcc-10.3.0-lib +/gnu/store/@dots{}-glibc-2.33 +/gnu/store/@dots{}-bash-static-5.1.8 +/gnu/store/@dots{}-ncurses-6.2.20210619 +/gnu/store/@dots{}-bash-5.1.8 +/gnu/store/@dots{}-profile +/gnu/store/@dots{}-readline-8.1.1 +@end example + +@cindex exiting a container +There isn't much you can do in an environment like this other than +exiting it. You can use @key{^D} or @command{exit} to terminate this +limited shell environment. + +@cindex exposing directories, container +@cindex sharing directories, container +@cindex mapping locations, container +You can make other directories available inside of the container +environment; use @option{--expose=DIRECTORY} to bind-mount the given +directory as a read-only location inside the container, or use +@option{--share=DIRECTORY} to make the location writable. With an +additional mapping argument after the directory name you can control the +name of the directory inside the container. In the following example we +map @file{/etc} on the host system to @file{/the/host/etc} inside a +container in which the GNU coreutils are installed. + +@example sh +$ guix shell --container --share=/etc=/the/host/etc coreutils +$ ls /the/host/etc +@end example + +Similarly, you can prevent the current working directory from being +mapped into the container with the @option{--no-cwd} option. Another +good idea is to create a dedicated directory that will serve as the +container's home directory, and spawn the container shell from that +directory. + +@cindex hide system libraries, container +@cindex avoid ABI mismatch, container +On a foreign system a container environment can be used to compile +software that cannot possibly be linked with system libraries or with +the system's compiler toolchain. A common use-case in a research +context is to install packages from within an R session. Outside of a +container environment there is a good chance that the foreign compiler +toolchain and incompatible system libraries are found first, resulting +in incompatible binaries that cannot be used by R. In a container shell +this problem disappears, as system libraries and executables simply +aren't available due to the unshared @code{mount} namespace. + +Let's take a comprehensive manifest providing a comfortable development +environment for use with R: + +@lisp +(specifications->manifest + (list "r-minimal" + + ;; base packages + "bash-minimal" + "glibc-locales" + "nss-certs" + + ;; Common command line tools lest the container is too empty. + "coreutils" + "grep" + "which" + "wget" + "sed" + + ;; R markdown tools + "pandoc" + + ;; Toolchain and common libraries for "install.packages" + "gcc-toolchain@@10" + "gfortran-toolchain" + "gawk" + "tar" + "gzip" + "unzip" + "make" + "cmake" + "pkg-config" + "cairo" + "libxt" + "openssl" + "curl" + "zlib")) +@end lisp + +Let's use this to run R inside a container environment. For convenience +we share the @code{net} namespace to use the host system's network +interfaces. Now we can build R packages from source the traditional way +without having to worry about ABI mismatch or incompatibilities. + +@example sh +$ guix shell --container --network --manifest=manifest.scm -- R + +R version 4.2.1 (2022-06-23) -- "Funny-Looking Kid" +Copyright (C) 2022 The R Foundation for Statistical Computing +@dots{} +> e <- Sys.getenv("GUIX_ENVIRONMENT") +> Sys.setenv(GIT_SSL_CAINFO=paste0(e, "/etc/ssl/certs/ca-certificates.crt")) +> Sys.setenv(SSL_CERT_FILE=paste0(e, "/etc/ssl/certs/ca-certificates.crt")) +> Sys.setenv(SSL_CERT_DIR=paste0(e, "/etc/ssl/certs")) +> install.packages("Cairo", lib=paste0(getwd())) +@dots{} +* installing *source* package 'Cairo' ... +@dots{} +* DONE (Cairo) + +The downloaded source packages are in + '/tmp/RtmpCuwdwM/downloaded_packages' +> library("Cairo", lib=getwd()) +> # success! +@end example + +Using container shells is fun, but they can become a little cumbersome +when you want to go beyond just a single interactive process. Some +tasks become a lot easier when they sit on the rock solid foundation of +a proper Guix System and its rich set of system services. The next +section shows you how to launch a complete Guix System inside of a +container. + + +@node Guix System Containers +@section Guix System Containers + +The Guix System provides a wide array of interconnected system services +that are configured declaratively to form a dependable stateless GNU +System foundation for whatever tasks you throw at it. Even when using +Guix on a foreign distribution you can benefit from the design of Guix +System by running a system instance as a container. Using the same +kernel features of unshared namespaces mentioned in the previous +section, the resulting Guix System instance is isolated from the host +system and only shares file system locations that you explicitly +declare. + +A Guix System container differs from the shell process created by +@command{guix shell --container} in a number of important ways. While +in a container shell the containerized process is a Bash shell process, +a Guix System container runs the Shepherd as PID 1. In a system +container all system services (@pxref{Services,,, guix, GNU Guix +Reference Manual}) are set up just as they would be on a Guix System in +a virtual machine or on bare metal---this includes daemons managed by +the GNU@tie{}Shepherd (@pxref{Shepherd Services,,, guix, GNU Guix +Reference Manual}) as well as other kinds of extensions to the operating +system (@pxref{Service Composition,,, guix, GNU Guix Reference Manual}). + +The perceived increase in complexity of running a Guix System container +is easily justified when dealing with more complex applications that +have higher or just more rigid requirements on their execution +contexts---configuration files, dedicated user accounts, directories for +caches or log files, etc. In Guix System the demands of this kind of +software are satisfied through the deployment of system services. + + +@node A Database Container +@subsection A Database Container + +A good example might be a PostgreSQL database server. Much of the +complexity of setting up such a database server is encapsulated in this +deceptively short service declaration: + +@lisp +(service postgresql-service-type + (postgresql-configuration + (postgresql postgresql-14))) +@end lisp + +A complete operating system declaration for use with a Guix System +container would look something like this: + +@lisp +(use-modules (gnu)) +(use-package-modules databases) +(use-service-modules databases) + +(operating-system + (host-name "container") + (timezone "Europe/Berlin") + (file-systems (cons (file-system + (device (file-system-label "does-not-matter")) + (mount-point "/") + (type "ext4")) + %base-file-systems)) + (bootloader (bootloader-configuration + (bootloader grub-bootloader) + (targets '("/dev/sdX")))) + (services + (cons* (service postgresql-service-type + (postgresql-configuration + (postgresql postgresql-14) + (config-file + (postgresql-config-file + (log-destination "stderr") + (hba-file + (plain-file "pg_hba.conf" + "\ +local all all trust +host all all 10.0.0.1/32 trust")) + (extra-config + '(("listen_addresses" "*") + ("log_directory" "/var/log/postgresql"))))))) + (service postgresql-role-service-type + (postgresql-role-configuration + (roles + (list (postgresql-role + (name "test") + (create-database? #t)))))) + %base-services))) +@end lisp + +With @code{postgresql-role-service-type} we define a role ``test'' and +create a matching database, so that we can test right away without any +further manual setup. The @code{postgresql-config-file} settings allow +a client from IP address 10.0.0.1 to connect without requiring +authentication---a bad idea in production systems, but convenient for +this example. + +Let's build a script that will launch an instance of this Guix System as +a container. Write the @code{operating-system} declaration above to a +file @file{os.scm} and then use @command{guix system container} to build +the launcher. (@pxref{Invoking guix system,,, guix, GNU Guix Reference +Manual}). + +@example +$ guix system container os.scm +The following derivations will be built: + /gnu/store/@dots{}-run-container.drv + @dots{} +building /gnu/store/@dots{}-run-container.drv... +/gnu/store/@dots{}-run-container +@end example + +Now that we have a launcher script we can run it to spawn the new system +with a running PostgreSQL service. Note that due to some as yet +unresolved limitations we need to run the launcher as the root user, for +example with @command{sudo}. + +@example +$ sudo /gnu/store/@dots{}-run-container +system container is running as PID 5983 +@dots{} +@end example + +Background the process with @key{Ctrl-z} followed by @command{bg}. Note +the process ID in the output; we will need it to connect to the +container later. You know what? Let's try attaching to the container +right now. We will use @command{nsenter}, a tool provided by the +@code{util-linux} package: + +@example +$ guix shell util-linux +$ sudo nsenter -a -t 5983 +root@@container /# pgrep -a postgres +49 /gnu/store/@dots{}-postgresql-14.4/bin/postgres -D /var/lib/postgresql/data --config-file=/gnu/store/@dots{}-postgresql.conf -p 5432 +51 postgres: checkpointer +52 postgres: background writer +53 postgres: walwriter +54 postgres: autovacuum launcher +55 postgres: stats collector +56 postgres: logical replication launcher +root@@container /# exit +@end example + +The PostgreSQL service is running in the container! + + +@node Container Networking +@subsection Container Networking +@cindex container networking + +What good is a Guix System running a PostgreSQL database service as a +container when we can only talk to it with processes originating in the +container? It would be much better if we could talk to the database +over the network. + +The easiest way to do this is to create a pair of connected virtual +Ethernet devices (known as @code{veth}). We move one of the devices +(@code{ceth-test}) into the @code{net} namespace of the container and +leave the other end (@code{veth-test}) of the connection on the host +system. + +@example +pid=5983 +ns="guix-test" +host="veth-test" +client="ceth-test" + +# Attach the new net namespace "guix-test" to the container PID. +sudo ip netns attach $ns $pid + +# Create the pair of devices +sudo ip link add $host type veth peer name $client + +# Move the client device into the container's net namespace +sudo ip link set $client netns $ns +@end example + +Then we configure the host side: + +@example +sudo ip link set $host up +sudo ip addr add 10.0.0.1/24 dev $host +@end example + +@dots{}and then we configure the client side: + +@example +sudo ip netns exec $ns ip link set lo up +sudo ip netns exec $ns ip link set $client up +sudo ip netns exec $ns ip addr add 10.0.0.2/24 dev $client +@end example + +At this point the host can reach the container at IP address 10.0.0.2, +and the container can reach the host at IP 10.0.0.1. This is all we +need to talk to the database server inside the container from the host +system on the outside. + +@example +$ psql -h 10.0.0.2 -U test +psql (14.4) +Type "help" for help. + +test=> CREATE TABLE hello (who TEXT NOT NULL); +CREATE TABLE +test=> INSERT INTO hello (who) VALUES ('world'); +INSERT 0 1 +test=> SELECT * FROM hello; + who +------- + world +(1 row) +@end example + +Now that we're done with this little demonstration let's clean up: + +@example +sudo kill $pid +sudo ip netns del $ns +sudo ip link del $host +@end example + + @c ********************************************************************* @node Advanced package management @chapter Advanced package management @@ -2843,8 +3520,8 @@ to reproduce the exact same profile: GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles GUIX_EXTRA=$HOME/.guix-extra -mkdir "$GUIX_EXTRA"/my-project -guix pull --channels=channel-specs.scm --profile "$GUIX_EXTRA/my-project/guix" +mkdir -p "$GUIX_EXTRA"/my-project +guix pull --channels=channel-specs.scm --profile="$GUIX_EXTRA/my-project/guix" mkdir -p "$GUIX_EXTRA_PROFILES/my-project" "$GUIX_EXTRA"/my-project/guix/bin/guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project @@ -2977,6 +3654,380 @@ will have predefined environment variables and procedures. Run @command{direnv allow} to setup the environment for the first time. + +@c ********************************************************************* +@node Installing Guix on a Cluster +@chapter Installing Guix on a Cluster + +@cindex cluster installation +@cindex high-performance computing, HPC +@cindex HPC, high-performance computing +Guix is appealing to scientists and @acronym{HPC, high-performance +computing} practitioners: it makes it easy to deploy potentially complex +software stacks, and it lets you do so in a reproducible fashion---you +can redeploy the exact same software on different machines and at +different points in time. + +In this chapter we look at how a cluster sysadmin can install Guix for +system-wide use, such that it can be used on all the cluster nodes, and +discuss the various tradeoffs@footnote{This chapter is adapted from a +@uref{https://hpc.guix.info/blog/2017/11/installing-guix-on-a-cluster/, +blog post published on the Guix-HPC web site in 2017}.}. + +@quotation Note +Here we assume that the cluster is running a GNU/Linux distro other than +Guix System and that we are going to install Guix on top of it. +@end quotation + +@menu +* Setting Up a Head Node:: The node that runs the daemon. +* Setting Up Compute Nodes:: Client nodes. +* Cluster Network Access:: Dealing with network access restrictions. +* Cluster Disk Usage:: Disk usage considerations. +* Cluster Security Considerations:: Keeping the cluster secure. +@end menu + +@node Setting Up a Head Node +@section Setting Up a Head Node + +The recommended approach is to set up one @emph{head node} running +@command{guix-daemon} and exporting @file{/gnu/store} over NFS to +compute nodes. + +Remember that @command{guix-daemon} is responsible for spawning build +processes and downloads on behalf of clients (@pxref{Invoking +guix-daemon,,, guix, GNU Guix Reference Manual}), and more generally +accessing @file{/gnu/store}, which contains all the package binaries +built by all the users (@pxref{The Store,,, guix, GNU Guix Reference +Manual}). ``Client'' here refers to all the Guix commands that users +see, such as @code{guix install}. On a cluster, these commands may be +running on the compute nodes and we'll want them to talk to the head +node's @code{guix-daemon} instance. + +To begin with, the head node can be installed following the usual binary +installation instructions (@pxref{Binary Installation,,, guix, GNU Guix +Reference Manual}). Thanks to the installation script, this should be +quick. Once installation is complete, we need to make some adjustments. + +Since we want @code{guix-daemon} to be reachable not just from the head +node but also from the compute nodes, we need to arrange so that it +listens for connections over TCP/IP. To do that, we'll edit the systemd +startup file for @command{guix-daemon}, +@file{/etc/systemd/system/guix-daemon.service}, and add a +@code{--listen} argument to the @code{ExecStart} line so that it looks +something like this: + +@example +ExecStart=/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon --build-users-group=guixbuild --listen=/var/guix/daemon-socket/socket --listen=0.0.0.0 +@end example + +For these changes to take effect, the service needs to be restarted: + +@example +systemctl daemon-reload +systemctl restart guix-daemon +@end example + +@quotation Note +The @code{--listen=0.0.0.0} bit means that @code{guix-daemon} will +process @emph{all} incoming TCP connections on port 44146 +(@pxref{Invoking guix-daemon,,, guix, GNU Guix Reference Manual}). This +is usually fine in a cluster setup where the head node is reachable +exclusively from the cluster's local area network---you don't want that +to be exposed to the Internet! +@end quotation + +The next step is to define our NFS exports in +@uref{https://linux.die.net/man/5/exports,@file{/etc/exports}} by adding +something along these lines: + +@example +/gnu/store *(ro) +/var/guix *(rw, async) +/var/log/guix *(ro) +@end example + +The @file{/gnu/store} directory can be exported read-only since only +@command{guix-daemon} on the master node will ever modify it. +@file{/var/guix} contains @emph{user profiles} as managed by @code{guix +package}; thus, to allow users to install packages with @code{guix +package}, this must be read-write. + +Users can create as many profiles as they like in addition to the +default profile, @file{~/.guix-profile}. For instance, @code{guix +package -p ~/dev/python-dev -i python} installs Python in a profile +reachable from the @code{~/dev/python-dev} symlink. To make sure that +this profile is protected from garbage collection---i.e., that Python +will not be removed from @file{/gnu/store} while this profile exists---, +@emph{home directories should be mounted on the head node} as well so +that @code{guix-daemon} knows about these non-standard profiles and +avoids collecting software they refer to. + +It may be a good idea to periodically remove unused bits from +@file{/gnu/store} by running @command{guix gc} (@pxref{Invoking guix +gc,,, guix, GNU Guix Reference Manual}). This can be done by adding a +crontab entry on the head node: + +@example +root@@master# crontab -e +@end example + +@noindent +... with something like this: + +@example +# Every day at 5AM, run the garbage collector to make sure +# at least 10 GB are free on /gnu/store. +0 5 * * 1 /usr/local/bin/guix gc -F10G +@end example + +We're done with the head node! Let's look at compute nodes now. + +@node Setting Up Compute Nodes +@section Setting Up Compute Nodes + +First of all, we need compute nodes to mount those NFS directories that +the head node exports. This can be done by adding the following lines +to @uref{https://linux.die.net/man/5/fstab,@file{/etc/fstab}}: + +@example +@var{head-node}:/gnu/store /gnu/store nfs defaults,_netdev,vers=3 0 0 +@var{head-node}:/var/guix /var/guix nfs defaults,_netdev,vers=3 0 0 +@var{head-node}:/var/log/guix /var/log/guix nfs defaults,_netdev,vers=3 0 0 +@end example + +@noindent +... where @var{head-node} is the name or IP address of your head node. +From there on, assuming the mount points exist, you should be able to +mount each of these on the compute nodes. + +Next, we need to provide a default @command{guix} command that users can +run when they first connect to the cluster (eventually they will invoke +@command{guix pull}, which will provide them with their ``own'' +@command{guix} command). Similar to what the binary installation script +did on the head node, we'll store that in @file{/usr/local/bin}: + +@example +mkdir -p /usr/local/bin +ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix \ + /usr/local/bin/guix +@end example + +We then need to tell @code{guix} to talk to the daemon running on our +master node, by adding these lines to @code{/etc/profile}: + +@example +GUIX_DAEMON_SOCKET="guix://@var{head-node}" +export GUIX_DAEMON_SOCKET +@end example + +To avoid warnings and make sure @code{guix} uses the right locale, we +need to tell it to use locale data provided by Guix (@pxref{Application +Setup,,, guix, GNU Guix Reference Manual}): + +@example +GUIX_LOCPATH=/var/guix/profiles/per-user/root/guix-profile/lib/locale +export GUIX_LOCPATH + +# Here we must use a valid locale name. Try "ls $GUIX_LOCPATH/*" +# to see what names can be used. +LC_ALL=fr_FR.utf8 +export LC_ALL +@end example + +For convenience, @code{guix package} automatically generates +@file{~/.guix-profile/etc/profile}, which defines all the environment +variables necessary to use the packages---@code{PATH}, +@code{C_INCLUDE_PATH}, @code{PYTHONPATH}, etc. Thus it's a good idea to +source it from @code{/etc/profile}: + +@example +GUIX_PROFILE="$HOME/.guix-profile" +if [ -f "$GUIX_PROFILE/etc/profile" ]; then + . "$GUIX_PROFILE/etc/profile" +fi +@end example + +Last but not least, Guix provides command-line completion notably for +Bash and zsh. In @code{/etc/bashrc}, consider adding this line: + +@verbatim +. /var/guix/profiles/per-user/root/current-guix/etc/bash_completion.d/guix +@end verbatim + +Voilà! + +You can check that everything's in place by logging in on a compute node +and running: + +@example +guix install hello +@end example + +The daemon on the head node should download pre-built binaries on your +behalf and unpack them in @file{/gnu/store}, and @command{guix install} +should create @file{~/.guix-profile} containing the +@file{~/.guix-profile/bin/hello} command. + +@node Cluster Network Access +@section Network Access + +Guix requires network access to download source code and pre-built +binaries. The good news is that only the head node needs that since +compute nodes simply delegate to it. + +It is customary for cluster nodes to have access at best to a +@emph{white list} of hosts. Our head node needs at least +@code{ci.guix.gnu.org} in this white list since this is where it gets +pre-built binaries from by default, for all the packages that are in +Guix proper. + +Incidentally, @code{ci.guix.gnu.org} also serves as a +@emph{content-addressed mirror} of the source code of those packages. +Consequently, it is sufficient to have @emph{only} +@code{ci.guix.gnu.org} in that white list. + +Software packages maintained in a separate repository such as one of the +various @uref{https://hpc.guix.info/channels, HPC channels} are of +course unavailable from @code{ci.guix.gnu.org}. For these packages, you +may want to extend the white list such that source and pre-built +binaries (assuming this-party servers provide binaries for these +packages) can be downloaded. As a last resort, users can always +download source on their workstation and add it to the cluster's +@file{/gnu/store}, like this: + +@verbatim +GUIX_DAEMON_SOCKET=ssh://compute-node.example.org \ + guix download http://starpu.gforge.inria.fr/files/starpu-1.2.3/starpu-1.2.3.tar.gz +@end verbatim + +The above command downloads @code{starpu-1.2.3.tar.gz} @emph{and} sends +it to the cluster's @code{guix-daemon} instance over SSH. + +Air-gapped clusters require more work. At the moment, our suggestion +would be to download all the necessary source code on a workstation +running Guix. For instance, using the @option{--sources} option of +@command{guix build} (@pxref{Invoking guix build,,, guix, GNU Guix +Reference Manual}), the example below downloads all the source code the +@code{openmpi} package depends on: + +@example +$ guix build --sources=transitive openmpi + +@dots{} + +/gnu/store/xc17sm60fb8nxadc4qy0c7rqph499z8s-openmpi-1.10.7.tar.bz2 +/gnu/store/s67jx92lpipy2nfj5cz818xv430n4b7w-gcc-5.4.0.tar.xz +/gnu/store/npw9qh8a46lrxiwh9xwk0wpi3jlzmjnh-gmp-6.0.0a.tar.xz +/gnu/store/hcz0f4wkdbsvsdky3c0vdvcawhdkyldb-mpfr-3.1.5.tar.xz +/gnu/store/y9akh452n3p4w2v631nj0injx7y0d68x-mpc-1.0.3.tar.gz +/gnu/store/6g5c35q8avfnzs3v14dzl54cmrvddjm2-glibc-2.25.tar.xz +/gnu/store/p9k48dk3dvvk7gads7fk30xc2pxsd66z-hwloc-1.11.8.tar.bz2 +/gnu/store/cry9lqidwfrfmgl0x389cs3syr15p13q-gcc-5.4.0.tar.xz +/gnu/store/7ak0v3rzpqm2c5q1mp3v7cj0rxz0qakf-libfabric-1.4.1.tar.bz2 +/gnu/store/vh8syjrsilnbfcf582qhmvpg1v3rampf-rdma-core-14.tar.gz +… +@end example + +(In case you're wondering, that's more than 320@ MiB of +@emph{compressed} source code.) + +We can then make a big archive containing all of this (@pxref{Invoking +guix archive,,, guix, GNU Guix Reference Manual}): + +@verbatim +$ guix archive --export \ + `guix build --sources=transitive openmpi` \ + > openmpi-source-code.nar +@end verbatim + +@dots{} and we can eventually transfer that archive to the cluster on +removable storage and unpack it there: + +@verbatim +$ guix archive --import < openmpi-source-code.nar +@end verbatim + +This process has to be repeated every time new source code needs to be +brought to the cluster. + +As we write this, the research institutes involved in Guix-HPC do not +have air-gapped clusters though. If you have experience with such +setups, we would like to hear feedback and suggestions. + +@node Cluster Disk Usage +@section Disk Usage + +@cindex disk usage, on a cluster +A common concern of sysadmins' is whether this is all going to eat a lot +of disk space. If anything, if something is going to exhaust disk +space, it's going to be scientific data sets rather than compiled +software---that's our experience with almost ten years of Guix usage on +HPC clusters. Nevertheless, it's worth taking a look at how Guix +contributes to disk usage. + +First, having several versions or variants of a given package in +@file{/gnu/store} does not necessarily cost much, because +@command{guix-daemon} implements deduplication of identical files, and +package variants are likely to have a number of common files. + +As mentioned above, we recommend having a cron job to run @code{guix gc} +periodically, which removes @emph{unused} software from +@file{/gnu/store}. However, there's always a possibility that users will +keep lots of software in their profiles, or lots of old generations of +their profiles, which is ``live'' and cannot be deleted from the +viewpoint of @command{guix gc}. + +The solution to this is for users to regularly remove old generations of +their profile. For instance, the following command removes generations +that are more than two-month old: + +@example +guix package --delete-generations=2m +@end example + +Likewise, it's a good idea to invite users to regularly upgrade their +profile, which can reduce the number of variants of a given piece of +software stored in @file{/gnu/store}: + +@example +guix pull +guix upgrade +@end example + +As a last resort, it is always possible for sysadmins to do some of this +on behalf of their users. Nevertheless, one of the strengths of Guix is +the freedom and control users get on their software environment, so we +strongly recommend leaving users in control. + +@node Cluster Security Considerations +@section Security Considerations + +@cindex security, on a cluster +On an HPC cluster, Guix is typically used to manage scientific software. +Security-critical software such as the operating system kernel and +system services such as @code{sshd} and the batch scheduler remain under +control of sysadmins. + +The Guix project has a good track record delivering security updates in +a timely fashion (@pxref{Security Updates,,, guix, GNU Guix Reference +Manual}). To get security updates, users have to run @code{guix pull && +guix upgrade}. + +Because Guix uniquely identifies software variants, it is easy to see if +a vulnerable piece of software is in use. For instance, to check whether +the glibc@ 2.25 variant without the mitigation patch against +``@uref{https://www.qualys.com/2017/06/19/stack-clash/stack-clash.txt,Stack +Clash}'', one can check whether user profiles refer to it at all: + +@example +guix gc --referrers /gnu/store/…-glibc-2.25 +@end example + +This will report whether profiles exist that refer to this specific +glibc variant. + + @c ********************************************************************* @node Acknowledgments @chapter Acknowledgments @@ -2998,8 +4049,10 @@ information on these fine people. The @file{THANKS} file lists people who have helped by reporting bugs, taking care of the infrastructure, providing artwork and themes, making suggestions, and more---thank you! -This document includes adapted sections from articles that have previously -been published on the Guix blog at @uref{https://guix.gnu.org/blog}. +This document includes adapted sections from articles that have +previously been published on the Guix blog at +@uref{https://guix.gnu.org/blog} and on the Guix-HPC blog at +@uref{https://hpc.guix.info/blog}. @c ********************************************************************* diff --git a/doc/guix.texi b/doc/guix.texi index a173bea15f..eddfc58cb3 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -10,8 +10,8 @@ @include version.texi @c Identifier of the OpenPGP key used to sign tarballs and such. -@set OPENPGP-SIGNING-KEY-ID 27D586A4F8900854329FF09F1260E46482E63562 -@set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=127547 +@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5 +@set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=15145 @c Base URL for downloads. @set BASE-URL https://ftp.gnu.org/gnu/guix @@ -22,14 +22,14 @@ @set SUBSTITUTE-URLS https://@value{SUBSTITUTE-SERVER-1} https://@value{SUBSTITUTE-SERVER-2} @copying -Copyright @copyright{} 2012-2022 Ludovic Courtès@* +Copyright @copyright{} 2012-2023 Ludovic Courtès@* Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@* Copyright @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2014, 2015, 2016 Alex Kost@* Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@* -Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari@* +Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021, 2023 Leo Famulari@* 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@* @@ -49,7 +49,7 @@ 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, 2022 Hartmut Goebel@* -Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@* +Copyright @copyright{} 2017, 2019, 2020, 2021, 2022 Maxim Cournoyer@* Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@* Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017 Andy Wingo@* @@ -60,7 +60,7 @@ Copyright @copyright{} 2018, 2021 Oleg Pykhalov@* Copyright @copyright{} 2018 Mike Gerwitz@* Copyright @copyright{} 2018 Pierre-Antoine Rouby@* Copyright @copyright{} 2018, 2019 Gábor Boskovits@* -Copyright @copyright{} 2018, 2019, 2020 Florian Pelz@* +Copyright @copyright{} 2018, 2019, 2020, 2022 Florian Pelz@* Copyright @copyright{} 2018 Laura Lazzati@* Copyright @copyright{} 2018 Alex Vong@* Copyright @copyright{} 2019 Josh Holland@* @@ -107,6 +107,11 @@ Copyright @copyright{} 2022 Karl Hallsby@* Copyright @copyright{} 2022 Justin Veilleux@* Copyright @copyright{} 2022 Reily Siegel@* Copyright @copyright{} 2022 Simon Streit@* +Copyright @copyright{} 2022 (@* +Copyright @copyright{} 2022 John Kehayias@* +Copyright @copyright{} 2022 Ivan Vilata-i-Balaguer@* +Copyright @copyright{} 2023 Giacomo Leidi@* +Copyright @copyright{} 2022 Antero Mejr@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -162,8 +167,9 @@ package management tool written for the GNU system. This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN, GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}), -Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), and -Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you +Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), +Brazilian Portuguese (@pxref{Top,,, guix.pt_BR, Manual de referência do +GNU Guix}), and Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you would like to translate it in your native language, consider joining @uref{https://translate.fedoraproject.org/projects/guix/documentation-manual, Weblate} (@pxref{Translating Guix}). @@ -948,9 +954,11 @@ version 3.0.3 or later; @item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version 0.1.0 or later; @item -@uref{https://gnutls.org/, GnuTLS}, specifically its Guile bindings -(@pxref{Guile Preparations, how to install the GnuTLS bindings for -Guile,, gnutls-guile, GnuTLS-Guile}); +@uref{https://gitlab.com/gnutls/guile/, Guile-GnuTLS} (@pxref{Guile +Preparations, how to install the GnuTLS bindings for Guile,, +gnutls-guile, GnuTLS-Guile})@footnote{The Guile bindings to +@uref{https://gnutls.org/, GnuTLS} were distributed as part of GnuTLS +until version 3.7.8 included.}; @item @uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0 or later; @@ -1404,7 +1412,7 @@ when transferring files to and from build machines. File name of the Unix-domain socket @command{guix-daemon} is listening to on that machine. -@item @code{overload-threshold} (default: @code{0.6}) +@item @code{overload-threshold} (default: @code{0.8}) The load threshold above which a potential offload machine is disregarded by the offload scheduler. The value roughly translates to the total processor usage of the build machine, ranging from 0.0 (0%) to @@ -1517,8 +1525,10 @@ To install the policy run this command as root: semodule -i etc/guix-daemon.cil @end example -Then relabel the file system with @code{restorecon} or by a different -mechanism provided by your system. +Then relabel the file system with @code{restorecon -vR /} or by a +different mechanism provided by your system. You may need to remount +@file{/gnu/store} to make it writable first, e.g. with @code{mount -o +remount,rw /gnu/store}. Once the policy is installed, the file system has been relabeled, and the daemon has been restarted, it should be running in the @@ -1551,7 +1561,7 @@ but it would be preferable to define socket rules for only this label. @code{guix gc} cannot access arbitrary links to profiles. By design, the file label of the destination of a symlink is independent of the file label of the link itself. Although all profiles under -$localstatedir are labelled, the links to these profiles inherit the +@file{$localstatedir} are labelled, the links to these profiles inherit the label of the directory they are in. For links in the user’s home directory this will be @code{user_home_t}. But for links from the root user’s home directory, or @file{/tmp}, or the HTTP server’s working @@ -1590,7 +1600,7 @@ effectively running @code{guix-daemon} executable is upgraded. @node Invoking guix-daemon @section Invoking @command{guix-daemon} - +@cindex @command{guix-daemon} The @command{guix-daemon} program implements all the functionality to access the store. This includes launching build processes, running the garbage collector, querying the availability of a build result, etc. It @@ -2094,6 +2104,19 @@ want to avoid auto-loading the Emacs packages installed with Guix, you can do so by running Emacs with the @option{--no-site-file} option (@pxref{Init File,,, emacs, The GNU Emacs Manual}). +@quotation Note +Emacs can now compile packages natively. Under the default +configuration, this means that Emacs packages will now be +just-in-time (JIT) compiled as you use them, and the results +stored in a subdirectory of your @code{user-emacs-directory}. + +Furthermore, the build system for Emacs packages transparently +supports native compilation, but note, that +@code{emacs-minimal}---the default Emacs for building +packages---has been configured without native compilation. +To natively compile your emacs packages ahead of time, use a +transformation like @option{--with-input=emacs-minimal=emacs}. +@end quotation @node Upgrading Guix @section Upgrading Guix @@ -2217,6 +2240,9 @@ Linux-libre driver. Free firmware exists for both and is available out-of-the-box on Guix System, as part of @code{%base-firmware} (@pxref{operating-system Reference, @code{firmware}}). +The installer warns you early on if it detects devices that are known +@emph{not} to work due to the lack of free firmware or free drivers. + @cindex RYF, Respects Your Freedom The @uref{https://www.fsf.org/, Free Software Foundation} runs @uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a @@ -2939,11 +2965,12 @@ 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: +Source the system profile as well as 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 /var/guix/profiles/system/profile/etc/profile source /home/@var{user}/.guix-profile/etc/profile @end example @@ -3314,6 +3341,7 @@ retaining precise @dfn{provenance tracking} of the software. @cindex package installation @cindex package removal @cindex profile +@cindex @command{guix package} The @command{guix package} command is the tool that allows users to install, upgrade, and remove packages, as well as rolling back to previous configurations. These operations work on a user @@ -3400,19 +3428,25 @@ The @var{options} can be among the following: @itemx -i @var{package} @dots{} Install the specified @var{package}s. -Each @var{package} may specify either a simple package name, such as -@code{guile}, or a package name followed by an at-sign and version number, -such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter -case, the newest version prefixed by @code{1.8} is selected). +Each @var{package} may specify a simple package name, such as +@code{guile}, optionally followed by an at-sign and version number, +such as @code{guile@@3.0.7} or simply @code{guile@@3.0}. In the latter +case, the newest version prefixed by @code{3.0} is selected. -If no version number is specified, the -newest available version will be selected. In addition, @var{package} +If no version number is specified, the newest available version will be +selected. In addition, such a @var{package} specification may contain a colon, followed by the name of one of the outputs of the package, as in @code{gcc:doc} or @code{binutils@@2.22:lib} -(@pxref{Packages with Multiple Outputs}). Packages with a corresponding +(@pxref{Packages with Multiple Outputs}). + +Packages with a corresponding name (and optionally version) are searched for among the GNU distribution modules (@pxref{Package Modules}). +Alternatively, a @var{package} can directly specify a store file name +such as @file{/gnu/store/...-guile-3.0.7}, as produced by, e.g., +@code{guix build}. + @cindex propagated inputs Sometimes packages have @dfn{propagated inputs}: these are dependencies that automatically get installed along with the required package @@ -4307,6 +4341,7 @@ guix package}). @cindex garbage collector @cindex disk space +@cindex @command{guix gc} Packages that are installed, but not used, may be @dfn{garbage-collected}. The @command{guix gc} command allows users to explicitly run the garbage collector to reclaim space from the @file{/gnu/store} directory. It is @@ -4511,6 +4546,18 @@ import, unless it was started with @option{--disable-deduplication} this option is primarily useful when the daemon was running with @option{--disable-deduplication}. +@item --vacuum-database +@cindex vacuum the store database +@comment Avoid words like 'repair,' 'compress,' and 'optimize.' +Guix uses an sqlite database to keep track of the items in (@pxref{The Store}). +Over time it is possible that the database may grow to a large size and become +fragmented. As a result, one may wish to clear the freed space and join the +partially used pages in the database left behind from removed packages or after +running the garbage collector. Running @command{sudo guix gc +--vacuum-database} will lock the database and @code{VACUUM} the store, +defragmenting the database and purging freed pages, unlocking the database when +it finishes. + @end table @node Invoking guix pull @@ -4527,7 +4574,7 @@ the distribution currently available on your local machine. To update that distribution, along with the Guix tools, you must run @command{guix pull}: the command downloads the latest Guix source code and package descriptions, and deploys it. Source code is downloaded from a -@uref{https://git-scm.com, Git} repository, by default the official +@uref{https://git-scm.com/book/en/, Git} repository, by default the official GNU@tie{}Guix repository, though this can be customized. @command{guix pull} ensures that the code it downloads is @emph{authentic} by verifying that commits are signed by Guix developers. @@ -4627,7 +4674,7 @@ but it supports the following options: @itemx --branch=@var{branch} Download code for the @code{guix} channel from the specified @var{url}, at the given @var{commit} (a valid Git commit ID represented as a hexadecimal -string), or @var{branch}. +string or the name of a tag), or @var{branch}. @cindex @file{channels.scm}, configuration file @cindex configuration file for channels @@ -4779,6 +4826,34 @@ of Guix to be used is defined by a commit or by a channel description file created by @command{guix describe} (@pxref{Invoking guix describe}). +Let's assume that you want to travel to those days of November 2020 when +version 1.2.0 of Guix was released and, once you're there, run the +@command{guile} of that time: + +@example +guix time-machine --commit=v1.2.0 -- \ + environment -C --ad-hoc guile -- guile +@end example + +The command above fetches Guix@tie{}1.2.0 and runs its @command{guix +environment} command to spawn an environment in a container running +@command{guile} (@command{guix environment} has since been subsumed by +@command{guix shell}; @pxref{Invoking guix shell}). It's like driving a +DeLorean@footnote{If you don't know what a DeLorean is, consider +traveling back to the 1980's.}! The first @command{guix time-machine} +invocation can be expensive: it may have to download or even build a +large number of packages; the result is cached though and subsequent +commands targeting the same commit are almost instantaneous. + +@quotation Note +The history of Guix is immutable and @command{guix time-machine} +provides the exact same software as they are in a specific Guix +revision. Naturally, no security fixes are provided for old versions +of Guix or its channels. A careless use of @command{guix time-machine} +opens the door to security vulnerabilities. @xref{Invoking guix pull, +@option{--allow-downgrades}}. +@end quotation + The general syntax is: @example @@ -4795,7 +4870,7 @@ this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull @itemx --branch=@var{branch} Use the @code{guix} channel from the specified @var{url}, at the given @var{commit} (a valid Git commit ID represented as a hexadecimal -string), or @var{branch}. +string or the name of a tag), or @var{branch}. @item --channels=@var{file} @itemx -C @var{file} @@ -4952,6 +5027,7 @@ declaration, and so on. @cindex reproducibility @cindex replicating Guix +@cindex @command{guix describe} Often you may want to answer questions like: ``Which revision of Guix am I using?'' or ``Which channels am I using?'' This is useful information in many situations: if you want to @emph{replicate} an environment on a different @@ -5047,6 +5123,8 @@ Display information about @var{profile}. @cindex @command{guix archive} @cindex archive +@cindex exporting files from the store +@cindex importing files to the store The @command{guix archive} command allows users to @dfn{export} files from the store into a single archive, and to later @dfn{import} them on a machine that runs Guix. @@ -5539,6 +5617,18 @@ add a meta-data file @file{.guix-channel} that contains: (directory "guix")) @end lisp +The modules must be @b{underneath} the specified directory, as the +@code{directory} changes Guile's @code{load-path}. For example, if +@file{.guix-channel} has @code{(directory "base")}, then a module +defined as @code{(define-module (gnu packages fun))} must be located at +@code{base/gnu/packages/fun.scm}. + +Doing this allows for only parts of a repository to be used as a +channel, as Guix expects valid Guile modules when pulling. For +instance, @command{guix deploy} machine configuration files are not +valid Guile modules, and treating them as such would make @command{guix +pull} fail. + @node Declaring Channel Dependencies @section Declaring Channel Dependencies @@ -5805,6 +5895,7 @@ easily distributed to users who do not run Guix. @cindex reproducible build environments @cindex development environments @cindex @command{guix environment} +@cindex @command{guix shell} @cindex environment, package build environment The purpose of @command{guix shell} is to make it easy to create one-off software environments, without changing one's profile. It is typically @@ -6187,6 +6278,33 @@ directory: guix shell --container --expose=$HOME=/exchange guile -- guile @end example +@cindex symbolic links, guix shell +@item --symlink=@var{spec} +@itemx -S @var{spec} +For containers, create the symbolic links specified by @var{spec}, as +documented in @ref{pack-symlink-option}. + +@cindex file system hierarchy standard (FHS) +@cindex FHS (file system hierarchy standard) +@item --emulate-fhs +@itemx -F +When used with @option{--container}, emulate a +@uref{https://refspecs.linuxfoundation.org/fhs.shtml, Filesystem +Hierarchy Standard (FHS)} configuration within the container, providing +@file{/bin}, @file{/lib}, and other directories and files specified by +the FHS. + +As Guix deviates from the FHS specification, this +option sets up the container to more closely mimic that of other +GNU/Linux distributions. This is useful for reproducing other +development environments, testing, and using programs which expect the +FHS specification to be followed. With this option, the container will +include a version of glibc that will read +@file{/etc/ld.so.cache} within the container for the shared library +cache (contrary to glibc in regular Guix usage) and set up the +expected FHS directories: @file{/bin}, @file{/etc}, @file{/lib}, and +@file{/usr} from the container's profile. + @item --rebuild-cache @cindex caching, of profiles @cindex caching, in @command{guix shell} @@ -6235,6 +6353,8 @@ package transformation options (@pxref{Package Transformation Options}). @node Invoking guix environment @section Invoking @command{guix environment} +@cindex @command{guix environment} + The purpose of @command{guix environment} is to assist in creating development environments. @@ -6604,6 +6724,22 @@ directory: guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile @end example +@item --emulate-fhs +@item -F +For containers, emulate a Filesystem Hierarchy Standard (FHS) +configuration within the container, see +@uref{https://refspecs.linuxfoundation.org/fhs.shtml, the official +specification}. As Guix deviates from the FHS specification, this +option sets up the container to more closely mimic that of other +GNU/Linux distributions. This is useful for reproducing other +development environments, testing, and using programs which expect the +FHS specification to be followed. With this option, the container will +include a version of @code{glibc} which will read +@code{/etc/ld.so.cache} within the container for the shared library +cache (contrary to @code{glibc} in regular Guix usage) and set up the +expected FHS directories: @code{/bin}, @code{/etc}, @code{/lib}, and +@code{/usr} from the container's profile. + @end table @command{guix environment} @@ -6614,6 +6750,8 @@ transformation options (@pxref{Package Transformation Options}). @node Invoking guix pack @section Invoking @command{guix pack} +@cindex @command{guix pack} + Occasionally you want to pass software to people who are not (yet!) lucky enough to be using Guix. You'd tell them to run @command{guix package -i @var{something}}, but that's not possible in this case. This @@ -6938,6 +7076,7 @@ Compress the resulting tarball using @var{tool}---one of @code{gzip}, @code{zstd}, @code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no compression. +@anchor{pack-symlink-option} @item --symlink=@var{spec} @itemx -S @var{spec} Add the symlinks specified by @var{spec} to the pack. This option can @@ -7032,6 +7171,8 @@ for Fortran development. For other languages, please use @node Invoking guix git authenticate @section Invoking @command{guix git authenticate} +@cindex @command{guix git authenticate} + The @command{guix git authenticate} command authenticates a Git checkout following the same rule as for channels (@pxref{channel-authentication, channel authentication}). That is, starting from a given commit, it @@ -7933,8 +8074,9 @@ vintage!): "0lappv4slgb5spyqbh6yl5r013zv72yqg2pcl30mginf3wdqd8k9")))))) @end lisp -The example above corresponds to what the @option{--with-source} package -transformation option does. Essentially @code{hello-2.2} preserves all +The example above corresponds to what the @option{--with-version} +or @option{--with-source} package transformations option do. +Essentially @code{hello-2.2} preserves all the fields of @code{hello}, except @code{version} and @code{source}, which it overrides. Note that the original @code{hello} variable is still there, in the @code{(gnu packages base)} module, unchanged. When @@ -7971,20 +8113,20 @@ following forms: @item (delete @var{name}@dots{}) Delete from the inputs packages with the given @var{name}s (strings). -@item (append @var{package}@dots{}) -Add @var{package}s to the end of the input list. - @item (prepend @var{package}@dots{}) Add @var{package}s to the front of the input list. + +@item (append @var{package}@dots{}) +Add @var{package}s to the end of the input list. @end table The example below removes the GMP and ACL inputs of Coreutils and adds -libcap to the back of the input list: +libcap to the front of the input list: @lisp (modify-inputs (package-inputs coreutils) (delete "gmp" "acl") - (append libcap)) + (prepend libcap)) @end lisp The example below replaces the @code{guile} package from the inputs of @@ -7995,7 +8137,7 @@ The example below replaces the @code{guile} package from the inputs of (replace "guile" guile-2.2)) @end lisp -The last type of clause is @code{prepend}, to add inputs to the front of +The last type of clause is @code{append}, to add inputs at the back of the list. @end deffn @@ -8498,7 +8640,7 @@ The main build system is @code{gnu-build-system}, which implements the standard build procedure for GNU and many other packages. It is provided by the @code{(guix build-system gnu)} module. -@defvr {Scheme Variable} gnu-build-system +@defvar gnu-build-system @code{gnu-build-system} represents the GNU Build System, and variants thereof (@pxref{Configuration, configuration and makefile conventions,, standards, GNU Coding Standards}). @@ -8589,7 +8731,7 @@ guix size}). @end table Most other build systems support these keyword arguments. -@end defvr +@end defvar Other @code{<build-system>} objects are defined to support other conventions and tools used by free software packages. They inherit most @@ -8597,7 +8739,7 @@ of @code{gnu-build-system}, and differ mainly in the set of inputs implicitly added to the build process, and in the list of phases executed. Some of these build systems are listed below. -@defvr {Scheme Variable} ant-build-system +@defvar ant-build-system This variable is exported by @code{(guix build-system ant)}. It implements the build procedure for Java packages that can be built with @url{https://ant.apache.org/, Ant build tool}. @@ -8625,9 +8767,9 @@ The parameter @code{#:build-target} can be used to specify the Ant task that should be run during the @code{build} phase. By default the ``jar'' task will be run. -@end defvr +@end defvar -@defvr {Scheme Variable} android-ndk-build-system +@defvar android-ndk-build-system @cindex Android distribution @cindex Android NDK build system This variable is exported by @code{(guix build-system android-ndk)}. It @@ -8644,11 +8786,11 @@ has no conflicting files. For the time being, cross-compilation is not supported - so right now the libraries and header files are assumed to be host tools. -@end defvr +@end defvar -@defvr {Scheme Variable} asdf-build-system/source -@defvrx {Scheme Variable} asdf-build-system/sbcl -@defvrx {Scheme Variable} asdf-build-system/ecl +@defvar asdf-build-system/source +@defvarx asdf-build-system/sbcl +@defvarx asdf-build-system/ecl These variables, exported by @code{(guix build-system asdf)}, implement build procedures for Common Lisp packages using @@ -8692,9 +8834,9 @@ naming conventions suggest, or if several systems must be compiled, the @code{#:asd-systems} parameter can be used to specify the list of system names. -@end defvr +@end defvar -@defvr {Scheme Variable} cargo-build-system +@defvar cargo-build-system @cindex Rust programming language @cindex Cargo (Rust build system) This variable is exported by @code{(guix build-system cargo)}. It @@ -8723,9 +8865,9 @@ to create a source crate for future use. The @code{install} phase installs the binaries defined by the crate. Unless @code{install-source? #f} is defined it will also install a source crate repository of itself and unpacked sources, to ease in future hacking on rust packages. -@end defvr +@end defvar -@defvr {Scheme Variable} chicken-build-system +@defvar chicken-build-system This variable is exported by @code{(guix build-system chicken)}. It builds @uref{https://call-cc.org/, CHICKEN Scheme} modules, also called ``eggs'' or ``extensions''. CHICKEN generates C source code, which then @@ -8747,9 +8889,9 @@ For example, if you are packaging the @code{srfi-1} egg: Egg dependencies must be defined in @code{propagated-inputs}, not @code{inputs} because CHICKEN doesn't embed absolute references in compiled eggs. Test dependencies should go to @code{native-inputs}, as usual. -@end defvr +@end defvar -@defvr {Scheme Variable} copy-build-system +@defvar copy-build-system This variable is exported by @code{(guix build-system copy)}. It supports builds of simple packages that don't require much compiling, mostly just moving files around. @@ -8808,12 +8950,12 @@ e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}. @item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to @file{share/my-app/file}. @end itemize -@end defvr +@end defvar @cindex Clojure (programming language) @cindex simple Clojure build system -@defvr {Scheme Variable} clojure-build-system +@defvar clojure-build-system This variable is exported by @code{(guix build-system clojure)}. It implements a simple build procedure for @uref{https://clojure.org/, Clojure} packages using plain old @code{compile} in Clojure. Cross-compilation is not supported @@ -8866,9 +9008,9 @@ This phase installs all top-level files with base name matching @code{#:doc-regex} parameter. All files (recursively) inside the documentation directories specified in @code{#:doc-dirs} are installed as well. @end table -@end defvr +@end defvar -@defvr {Scheme Variable} cmake-build-system +@defvar cmake-build-system This variable is exported by @code{(guix build-system cmake)}. It implements the build procedure for packages using the @url{https://www.cmake.org, CMake build tool}. @@ -8883,9 +9025,9 @@ parameter specifies in abstract terms the flags passed to the compiler; it defaults to @code{"RelWithDebInfo"} (short for ``release mode with debugging information''), which roughly means that code is compiled with @code{-O2 -g}, as is the case for Autoconf-based packages by default. -@end defvr +@end defvar -@defvr {Scheme Variable} dune-build-system +@defvar dune-build-system This variable is exported by @code{(guix build-system dune)}. It supports builds of packages using @uref{https://dune.build/, Dune}, a build tool for the OCaml programming language. It is implemented as an extension @@ -8910,9 +9052,9 @@ 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 +@end defvar -@defvr {Scheme variable} elm-build-system +@defvar elm-build-system This variable is exported by @code{(guix build-system elm)}. It implements a build procedure for @url{https://elm-lang.org, Elm} packages similar to @samp{elm install}. @@ -8964,9 +9106,9 @@ We are not yet able to run tests for Elm projects because neither Node.js-based @url{https://github.com/rtfeldman/node-test-runner, @command{elm-test}} runner has been packaged for Guix yet. @end itemize -@end defvr +@end defvar -@defvr {Scheme Variable} go-build-system +@defvar go-build-system This variable is exported by @code{(guix build-system go)}. It implements a build procedure for Go packages using the standard @url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies, @@ -8992,11 +9134,15 @@ 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 +@url{https://golang.org/doc/install/source#environment, +in their documentation}. + +The key @code{#:go} can be used to specify the Go compiler package with +which to build the package. -@defvr {Scheme Variable} glib-or-gtk-build-system +@end defvar + +@defvar glib-or-gtk-build-system This variable is exported by @code{(guix build-system glib-or-gtk)}. It is intended for use with packages making use of GLib or GTK+. @@ -9030,9 +9176,9 @@ specified with the @code{#:glib} parameter. @end table Both phases are executed after the @code{install} phase. -@end defvr +@end defvar -@defvr {Scheme Variable} guile-build-system +@defvar guile-build-system This build system is for Guile packages that consist exclusively of Scheme code and that are so lean that they don't even have a makefile, let alone a @file{configure} script. It compiles Scheme code using @command{guild @@ -9045,9 +9191,9 @@ This build system supports cross-compilation by using the Packages built with @code{guile-build-system} must provide a Guile package in their @code{native-inputs} field. -@end defvr +@end defvar -@defvr {Scheme Variable} julia-build-system +@defvar julia-build-system This variable is exported by @code{(guix build-system julia)}. It implements the build procedure used by @uref{https://julialang.org/, julia} packages, which essentially is similar to running @samp{julia -e @@ -9090,9 +9236,9 @@ Some older packages that aren't using @file{Project.toml} yet, will require this file to be created, too. It is internally done if the arguments @code{#:julia-package-name} and @code{#:julia-package-uuid} are provided. -@end defvr +@end defvar -@defvr {Scheme Variable} maven-build-system +@defvar maven-build-system This variable is exported by @code{(guix build-system maven)}. It implements a build procedure for @uref{https://maven.apache.org, Maven} packages. Maven is a dependency and lifecycle management tool for Java. A user of Maven @@ -9132,17 +9278,17 @@ The @code{#:maven-plugins} argument is a list of maven plugins used during the build, with the same format as the @code{inputs} fields of the package declaration. Its default value is @code{(default-maven-plugins)} which is also exported. -@end defvr +@end defvar -@defvr {Scheme Variable} minetest-mod-build-system +@defvar 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 +@end defvar -@defvr {Scheme Variable} minify-build-system +@defvar minify-build-system This variable is exported by @code{(guix build-system minify)}. It implements a minification procedure for simple JavaScript packages. @@ -9155,18 +9301,18 @@ output. When the input JavaScript files are not all located in the @file{src} directory, the parameter @code{#:javascript-files} can be used to specify a list of file names to feed to the minifier. -@end defvr +@end defvar -@defvr {Scheme Variable} mozilla-build-system +@defvar mozilla-build-system This variable is exported by @code{(guix build-system mozilla)}. It sets the @code{--target} and @code{--host} configuration flags to what software developed by Mozilla expects -- due to historical reasons, Mozilla software expects @code{--host} to be the system that is cross-compiled from and @code{--target} to be the system that is cross-compiled to, contrary to the standard Autotools conventions. -@end defvr +@end defvar -@defvr {Scheme Variable} ocaml-build-system +@defvar ocaml-build-system This variable is exported by @code{(guix build-system ocaml)}. It implements a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists of choosing the correct set of commands to run for each package. OCaml @@ -9207,9 +9353,9 @@ fine because it is in the OCaml compiler directory. In guix though, these libraries cannot be found and we use @env{CAML_LD_LIBRARY_PATH}. This variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where @file{.so} libraries should be installed. -@end defvr +@end defvar -@defvr {Scheme Variable} python-build-system +@defvar python-build-system This variable is exported by @code{(guix build-system python)}. It implements the more or less standard build procedure used by Python packages, which consists in running @code{python setup.py build} and @@ -9236,10 +9382,40 @@ instead of the default @code{"out"} output. This is useful for packages that include a Python package as only a part of the software, and thus want to combine the phases of @code{python-build-system} with another build system. Python bindings are a common usecase. +@end defvar -@end defvr +@defvar pyproject-build-system +This is a variable exported by @code{guix build-system pyproject}. It +is based on @var{python-build-system}, and adds support for +@file{pyproject.toml} and @url{https://peps.python.org/pep-0517/, PEP 517}. +It also supports a variety of build backends and test frameworks. + +The API is slightly different from @var{python-build-system}: +@itemize +@item +@code{#:use-setuptools?} and @code{#:test-target} is removed. +@item +@code{#:build-backend} is added. It defaults to @code{#false} and will try +to guess the appropriate backend based on @file{pyproject.toml}. +@item +@code{#:test-backend} is added. It defaults to @code{#false} and will guess +an appropriate test backend based on what is available in package inputs. +@item +@code{#:test-flags} is added. The default is @code{'()}. These flags are +passed as arguments to the test command. Note that flags for verbose output +is always enabled on supported backends. +@end itemize -@defvr {Scheme Variable} perl-build-system +It is considered ``experimental'' in that the implementation details are +not set in stone yet, however users are encouraged to try it for new +Python projects (even those using @file{setup.py}). The API is subject to +change, but any breaking changes in the Guix channel will be dealt with. + +Eventually this build system will be deprecated and merged back into +@var{python-build-system}, probably some time in 2024. +@end defvar + +@defvar perl-build-system This variable is exported by @code{(guix build-system perl)}. It implements the standard build procedure for Perl packages, which either consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}}, @@ -9257,9 +9433,9 @@ passes flags specified by the @code{#:make-maker-flags} or @code{#:module-build-flags} parameter, respectively. Which Perl package is used can be specified with @code{#:perl}. -@end defvr +@end defvar -@defvr {Scheme Variable} renpy-build-system +@defvar renpy-build-system This variable is exported by @code{(guix build-system renpy)}. It implements the more or less standard build procedure used by Ren'py games, which consists of loading @code{#:game} once, thereby creating bytecode for it. @@ -9270,9 +9446,9 @@ It further creates a wrapper script in @code{bin/} and a desktop entry in Which Ren'py package is used can be specified with @code{#:renpy}. Games can also be installed in outputs other than ``out'' by using @code{#:output}. -@end defvr +@end defvar -@defvr {Scheme Variable} qt-build-system +@defvar qt-build-system This variable is exported by @code{(guix build-system qt)}. It is intended for use with applications using Qt or KDE. @@ -9306,9 +9482,9 @@ or such. This phase is added after the @code{install} phase. @end table -@end defvr +@end defvar -@defvr {Scheme Variable} r-build-system +@defvar r-build-system This variable is exported by @code{(guix build-system r)}. It implements the build procedure used by @uref{https://r-project.org, R} packages, which essentially is little more than running @samp{R CMD @@ -9316,9 +9492,9 @@ INSTALL --library=/gnu/store/@dots{}} in an environment where @env{R_LIBS_SITE} contains the paths to all R package inputs. Tests are run after installation using the R function @code{tools::testInstalledPackage}. -@end defvr +@end defvar -@defvr {Scheme Variable} rakudo-build-system +@defvar rakudo-build-system This variable is exported by @code{(guix build-system rakudo)}. It implements the build procedure used by @uref{https://rakudo.org/, Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the @@ -9334,9 +9510,9 @@ Which perl6-tap-harness package used for the tests can be specified with Which perl6-zef package used for tests and installing can be specified with @code{#:zef} or removed by passing @code{#f} to the @code{with-zef?} parameter. -@end defvr +@end defvar -@defvr {Scheme Variable} rebar-build-system +@defvar 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. @@ -9377,9 +9553,9 @@ This installs the files created in the @i{default} profile, or some other profile specified with @code{#:install-profile}. @end table -@end defvr +@end defvar -@defvr {Scheme Variable} texlive-build-system +@defvar 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 build system sets the @env{TEXINPUTS} variable to find all TeX source @@ -9396,9 +9572,9 @@ and @code{#:texlive-latex-base}, respectively. The @code{#:tex-directory} parameter tells the build system where to install the built files under the texmf tree. -@end defvr +@end defvar -@defvr {Scheme Variable} ruby-build-system +@defvar ruby-build-system This variable is exported by @code{(guix build-system ruby)}. It implements the RubyGems build procedure used by Ruby packages, which involves running @code{gem build} followed by @code{gem install}. @@ -9414,9 +9590,9 @@ a traditional source release tarball. Which Ruby package is used can be specified with the @code{#:ruby} parameter. A list of additional flags to be passed to the @command{gem} command can be specified with the @code{#:gem-flags} parameter. -@end defvr +@end defvar -@defvr {Scheme Variable} waf-build-system +@defvar waf-build-system This variable is exported by @code{(guix build-system waf)}. It implements a build procedure around the @code{waf} script. The common phases---@code{configure}, @code{build}, and @code{install}---are @@ -9426,9 +9602,9 @@ script. The @code{waf} script is executed by the Python interpreter. Which Python package is used to run the script can be specified with the @code{#:python} parameter. -@end defvr +@end defvar -@defvr {Scheme Variable} scons-build-system +@defvar scons-build-system This variable is exported by @code{(guix build-system scons)}. It implements the build procedure used by the SCons software construction tool. This build system runs @code{scons} to build the package, @@ -9441,9 +9617,9 @@ can be overridden with @code{#:build-targets} and @code{#:install-targets} respectively. The version of Python used to run SCons can be specified by selecting the appropriate SCons package with the @code{#:scons} parameter. -@end defvr +@end defvar -@defvr {Scheme Variable} haskell-build-system +@defvar haskell-build-system This variable is exported by @code{(guix build-system haskell)}. It implements the Cabal build procedure used by Haskell packages, which involves running @code{runhaskell Setup.hs configure @@ -9460,9 +9636,9 @@ not found, the build system looks for @code{Setup.lhs} instead. Which Haskell compiler is used can be specified with the @code{#:haskell} parameter which defaults to @code{ghc}. -@end defvr +@end defvar -@defvr {Scheme Variable} dub-build-system +@defvar dub-build-system This variable is exported by @code{(guix build-system dub)}. It implements the Dub build procedure used by D packages, which involves running @code{dub build} and @code{dub run}. @@ -9470,10 +9646,10 @@ Installation is done by copying the files manually. Which D compiler is used can be specified with the @code{#:ldc} parameter which defaults to @code{ldc}. -@end defvr +@end defvar @anchor{emacs-build-system} -@defvr {Scheme Variable} emacs-build-system +@defvar emacs-build-system This variable is exported by @code{(guix build-system emacs)}. It implements an installation procedure similar to the packaging system of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}). @@ -9483,17 +9659,17 @@ byte compiles all Emacs Lisp files. Differently from the Emacs packaging system, the Info documentation files are moved to the standard documentation directory and the @file{dir} file is deleted. The Elisp package files are installed directly under @file{share/emacs/site-lisp}. -@end defvr +@end defvar -@defvr {Scheme Variable} font-build-system +@defvar font-build-system This variable is exported by @code{(guix build-system font)}. It implements an installation procedure for font packages where upstream provides pre-compiled TrueType, OpenType, etc.@: font files that merely need to be copied into place. It copies font files to standard locations in the output directory. -@end defvr +@end defvar -@defvr {Scheme Variable} meson-build-system +@defvar meson-build-system This variable is exported by @code{(guix build-system meson)}. It implements the build procedure for packages that use @url{https://mesonbuild.com, Meson} as their build system. @@ -9547,9 +9723,9 @@ is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}. This phase is the phase provided by @code{glib-or-gtk-build-system}, and it is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}. @end table -@end defvr +@end defvar -@defvr {Scheme Variable} linux-module-build-system +@defvar linux-module-build-system @code{linux-module-build-system} allows building Linux kernel modules. @cindex build phases @@ -9574,9 +9750,9 @@ kernel module. It is possible and useful to specify the Linux kernel to use for building the module (in the @code{arguments} form of a package using the @code{linux-module-build-system}, use the key @code{#:linux} to specify it). -@end defvr +@end defvar -@defvr {Scheme Variable} node-build-system +@defvar node-build-system This variable is exported by @code{(guix build-system node)}. It implements the build procedure used by @uref{https://nodejs.org, Node.js}, which implements an approximation of the @code{npm install} @@ -9585,23 +9761,23 @@ command, followed by an @code{npm test} command. Which Node.js package is used to interpret the @code{npm} commands can be specified with the @code{#:node} parameter which defaults to @code{node}. -@end defvr +@end defvar Lastly, for packages that do not need anything as sophisticated, a ``trivial'' build system is provided. It is trivial in the sense that it provides basically no support: it does not pull any implicit inputs, and does not have a notion of build phases. -@defvr {Scheme Variable} trivial-build-system +@defvar trivial-build-system This variable is exported by @code{(guix build-system trivial)}. This build system requires a @code{#:builder} argument. This argument must be a Scheme expression that builds the package output(s)---as with @code{build-expression->derivation} (@pxref{Derivations, @code{build-expression->derivation}}). -@end defvr +@end defvar -@defvr {Scheme Variable} channel-build-system +@defvar 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 @@ -9612,7 +9788,7 @@ 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 +@end defvar @node Build Phases @section Build Phases @@ -10464,11 +10640,11 @@ Some search paths are not tied by a single package but to many packages. To reduce duplications, some of them are pre-defined in @code{(guix search-paths)}. -@defvr {Scheme Variable} $SSL_CERT_DIR -@defvrx {Scheme Variable} $SSL_CERT_FILE +@defvar $SSL_CERT_DIR +@defvarx $SSL_CERT_FILE These two search paths indicate where X.509 certificates can be found (@pxref{X.509 Certificates}). -@end defvr +@end defvar These pre-defined search paths can be used as in the following example: @@ -10607,10 +10783,10 @@ location given the options that were passed to @command{configure}. Close the connection to @var{server}. @end deffn -@defvr {Scheme Variable} current-build-output-port +@defvar current-build-output-port This variable is bound to a SRFI-39 parameter, which refers to the port where build and error logs sent by the daemon should be written. -@end defvr +@end defvar Procedures that make RPCs all take a server object as their first argument. @@ -11035,7 +11211,7 @@ The @code{(guix monads)} module provides the @dfn{state monad}, which allows an additional value---the state---to be @emph{threaded} through monadic procedure calls. -@defvr {Scheme Variable} %state-monad +@defvar %state-monad The state monad. Procedures in the state monad can access and change the state that is threaded. @@ -11057,7 +11233,7 @@ increments the current state value: When ``run'' through @code{%state-monad}, we obtain that additional state value, which is the number of @code{square} calls. -@end defvr +@end defvar @deffn {Monadic Procedure} current-state Return the current state as a monadic value. @@ -11086,13 +11262,13 @@ state. Return two values: the resulting value, and the resulting state. The main interface to the store monad, provided by the @code{(guix store)} module, is as follows. -@defvr {Scheme Variable} %store-monad +@defvar %store-monad The store monad---an alias for @code{%state-monad}. Values in the store monad encapsulate accesses to the store. When its effect is needed, a value of the store monad must be ``evaluated'' by passing it to the @code{run-with-store} procedure (see below). -@end defvr +@end defvar @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)] Run @var{mval}, a monadic value in the store monad, in @var{store}, an @@ -11561,8 +11737,7 @@ This is the declarative counterpart of @code{text-file}. @end deffn @deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @ - [#:local-build? #t] - [#:options '()] + [#:local-build? #t] [#:options '()] Return an object representing the store item @var{name}, a file or directory computed by @var{gexp}. When @var{local-build?} is true (the default), the derivation is built locally. @var{options} is a list of @@ -11806,6 +11981,7 @@ replaced with some arbitrary object -- currently the list @node Invoking guix repl @section Invoking @command{guix repl} +@cindex @command{guix repl} @cindex REPL, read-eval-print loop, script The @command{guix repl} command makes it easier to program Guix in Guile by launching a Guile @dfn{read-eval-print loop} (REPL) for interactive @@ -11846,6 +12022,14 @@ lines at the top of the script: @code{!#} @end example +To make a script that launches an interactive REPL directly from the +shell, use the @code{--interactive} flag: + +@example +@code{#!/usr/bin/env -S guix repl --interactive} +@code{!#} +@end example + Without a file name argument, a Guile REPL is started, allowing for interactive use (@pxref{Using Guix Interactively}): @@ -11865,6 +12049,10 @@ of Guix. The available options are as follows: @table @code +@item --list-types +Display the @var{TYPE} options for @command{guix repl --type=TYPE} and +exit. + @item --type=@var{type} @itemx -t @var{type} Start a REPL of the given @var{TYPE}, which can be one of the following: @@ -11890,6 +12078,10 @@ Accept connections on localhost on port 37146. Accept connections on the Unix-domain socket @file{/tmp/socket}. @end table +@item --interactive +@itemx -i +Launch the interactive REPL after @var{file} is executed. + @item --load-path=@var{directory} @itemx -L @var{directory} Add @var{directory} to the front of the package module search path @@ -12373,14 +12565,15 @@ one provided by the distribution. The example below downloads the @code{ed} package: @example -guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz +guix build ed --with-source=mirror://gnu/ed/ed-1.4.tar.gz @end example As a developer, @option{--with-source} makes it easy to test release -candidates: +candidates, and even to test their impact on packages that depend on +them: @example -guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz +guix build elogind --with-source=@dots{}/shepherd-0.9.0rc1.tar.gz @end example @dots{} or to build from a checkout in a pristine environment: @@ -12574,7 +12767,9 @@ Coreutils in the dependency graph is rebuilt. @cindex upstream, latest version @item --with-latest=@var{package} -So you like living on the bleeding edge? This option is for you! It +@itemx --with-version=@var{package}=@var{version} +So you like living on the bleeding edge? The @option{--with-latest} +option is for you! It replaces occurrences of @var{package} in the dependency graph with its latest upstream version, as reported by @command{guix refresh} (@pxref{Invoking guix refresh}). @@ -12590,6 +12785,26 @@ of Guile-JSON: guix build guix --with-latest=guile-json @end example +The @option{--with-version} works similarly except that it lets you +specify that you want precisely @var{version}, assuming that version +exists upstream. For example, to spawn a development environment with +SciPy built against version 1.22.4 of NumPy (skipping its test suite +because hey, we're not gonna wait this long), you would run: + +@example +guix shell python python-scipy --with-version=python-numpy=1.22.4 +@end example + +@quotation Warning +Because they depend on source code published at a given point in time on +upstream servers, deployments made with @option{--with-latest} and +@option{--with-version} may be non-reproducible: source might disappear +or be modified in place on the servers. + +To deploy old software versions without compromising on reproducibility, +@pxref{Invoking guix time-machine, @command{guix time-machine}}. +@end quotation + There are limitations. First, in cases where the tool cannot or does not know how to authenticate source code, you are at risk of running malicious code; a warning is emitted in this case. Second, this option @@ -12598,10 +12813,10 @@ which is not always sufficient: there might be additional dependencies that need to be added, patches to apply, and more generally the quality assurance work that Guix developers normally do will be missing. -You've been warned! In all the other cases, it's a snappy way to stay -on top. We encourage you to submit patches updating the actual package -definitions once you have successfully tested an upgrade -(@pxref{Contributing}). +You've been warned! When those limitations are acceptable, it's a +snappy way to stay on top. We encourage you to submit patches updating +the actual package definitions once you have successfully tested an +upgrade with @option{--with-latest} (@pxref{Contributing}). @cindex test suite, skipping @item --without-tests=@var{package} @@ -13247,7 +13462,7 @@ guix import gem rails You can also ask for a specific version: @example -guix import gem @@7.0.4 +guix import gem rails@@7.0.4 @end example @table @code @@ -13339,6 +13554,10 @@ definitions are to be appended to existing user modules, as the list of used package modules need not be changed. The default is @option{--style=variable}. +When @option{--prefix=license:} is added, the importer will prefix +license atoms with @code{license:}, allowing a prefixed import of +@code{(guix licenses)}. + When @option{--archive=bioconductor} is added, metadata is imported from @uref{https://www.bioconductor.org/, Bioconductor}, a repository of R packages for the analysis and comprehension of high-throughput @@ -13786,6 +14005,25 @@ gnu/packages/multiprecision.scm:40:12: 6.1.2 is already the latest version of gm @end table +If for some reason you don't want to update to the latest version, you +can update to a specific version by appending an equal sign and the +desired version number to the package specification. Note that not all +updaters support this; an error is reported when an updater cannot +refresh to the specified version. + +@example +$ guix refresh trytond-party +gnu/packages/guile.scm:392:2: guile would be upgraded from 3.0.3 to 3.0.5 +$ guix refresh -u guile=3.0.4 +@dots{} +gnu/packages/guile.scm:392:2: guile: updating from version 3.0.3 to version 3.0.4... +@dots{} +$ guix refresh -u guile@@2.0=2.0.12 +@dots{} +gnu/packages/guile.scm:147:2: guile: updating from version 2.0.10 to version 2.0.12... +@dots{} +@end example + Sometimes the upstream name differs from the package name used in Guix, and @command{guix refresh} needs a little help. Most updaters honor the @code{upstream-name} property in package definitions, which can be used @@ -13909,7 +14147,8 @@ the updater for @uref{https://crates.io, Crates} packages. the updater for @uref{https://launchpad.net, Launchpad} packages. @item generic-html a generic updater that crawls the HTML page where the source tarball of -the package is hosted, when applicable. +the package is hosted, when applicable, or the HTML page specified by +the @code{release-monitoring-url} property of the package. @item generic-git a generic updater for packages hosted on Git repositories. It tries to @@ -14110,6 +14349,11 @@ otherwise. @node Invoking guix style @section Invoking @command{guix style} +@cindex @command{guix style} +@cindex styling rules +@cindex lint, code style +@cindex format, code style +@cindex format conventions 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 @@ -15348,6 +15592,7 @@ information about mismatches. @node Invoking guix copy @section Invoking @command{guix copy} +@cindex @command{guix copy} @cindex copy, of store items, over SSH @cindex SSH, copy of store items @cindex sharing store items across machines @@ -15465,6 +15710,7 @@ must be PID 1 of the container or one of its child processes. @node Invoking guix weather @section Invoking @command{guix weather} +@cindex @command{guix weather} Occasionally you're grumpy because substitutes are lacking and you end up building packages by yourself (@pxref{Substitutes}). The @command{guix weather} command reports on substitute availability on the @@ -15595,6 +15841,7 @@ Display the list of store items for which substitutes are missing. @node Invoking guix processes @section Invoking @command{guix processes} +@cindex @command{guix processes} The @command{guix processes} command can be useful to developers and system administrators, especially on multi-user machines and on build farms: it lists the current sessions (connections to the daemon), as well as information about @@ -15760,9 +16007,9 @@ $ file /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello @end example The major benefit of cross-compilation is that there are no performance -penaly compared to emulation using QEMU. There are however higher risks -that some packages fail to cross-compile because few users are using -this mechanism extensively. +penalty compared to emulation using QEMU. There are however higher +risks that some packages fail to cross-compile because fewer users are +using this mechanism extensively. @node Native Builds @section Native Builds @@ -16298,7 +16545,7 @@ The default set includes core utilities and it is good practice to install non-core utilities in user profiles (@pxref{Invoking guix package}). -@item @code{timezone} +@item @code{timezone} (default: @code{"Etc/UTC"}) A timezone identifying string---e.g., @code{"Europe/Paris"}. You can run the @command{tzselect} command to find out which timezone @@ -16459,6 +16706,7 @@ This is a list of symbols denoting mount flags. Recognized flags include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow access to special files), @code{no-suid} (ignore setuid and setgid bits), @code{no-atime} (do not update file access times), +@code{no-diratime} (likewise for directories only), @code{strict-atime} (update file access time), @code{lazy-time} (only update time on the in-memory version of the file inode), @code{no-exec} (disallow program execution), and @code{shared} (make the @@ -16565,28 +16813,28 @@ than by device name. See above for examples. The @code{(gnu system file-systems)} exports the following useful variables. -@defvr {Scheme Variable} %base-file-systems +@defvar %base-file-systems These are essential file systems that are required on normal systems, such as @code{%pseudo-terminal-file-system} and @code{%immutable-store} (see below). Operating system declarations should always contain at least these. -@end defvr +@end defvar -@defvr {Scheme Variable} %pseudo-terminal-file-system +@defvar %pseudo-terminal-file-system This is the file system to be mounted as @file{/dev/pts}. It supports @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference Manual}). Pseudo-terminals are used by terminal emulators such as @command{xterm}. -@end defvr +@end defvar -@defvr {Scheme Variable} %shared-memory-file-system +@defvar %shared-memory-file-system This file system is mounted as @file{/dev/shm} and is used to support memory sharing across processes (@pxref{Memory-mapped I/O, @code{shm_open},, libc, The GNU C Library Reference Manual}). -@end defvr +@end defvar -@defvr {Scheme Variable} %immutable-store +@defvar %immutable-store This file system performs a read-only ``bind mount'' of @file{/gnu/store}, making it read-only for all the users including @code{root}. This prevents against accidental modification by software @@ -16594,19 +16842,19 @@ running as @code{root} or by system administrators. The daemon itself is still able to write to the store: it remounts it read-write in its own ``name space.'' -@end defvr +@end defvar -@defvr {Scheme Variable} %binary-format-file-system +@defvar %binary-format-file-system The @code{binfmt_misc} file system, which allows handling of arbitrary executable file types to be delegated to user space. This requires the @code{binfmt.ko} kernel module to be loaded. -@end defvr +@end defvar -@defvr {Scheme Variable} %fuse-control-file-system +@defvar %fuse-control-file-system The @code{fusectl} file system, which allows unprivileged users to mount and unmount user-space FUSE file systems. This requires the @code{fuse.ko} kernel module to be loaded. -@end defvr +@end defvar The @code{(gnu system uuid)} module provides tools to deal with file system ``unique identifiers'' (UUIDs). @@ -16791,26 +17039,26 @@ This must be a @code{mapped-device-kind} object, which specifies how @end table @end deftp -@defvr {Scheme Variable} luks-device-mapping +@defvar luks-device-mapping This defines LUKS block device encryption using the @command{cryptsetup} command from the package with the same name. It relies on the @code{dm-crypt} Linux kernel module. -@end defvr +@end defvar -@defvr {Scheme Variable} raid-device-mapping +@defvar raid-device-mapping This defines a RAID device, which is assembled using the @code{mdadm} command from the package with the same name. It requires a Linux kernel module for the appropriate RAID level to be loaded, such as @code{raid456} for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10. -@end defvr +@end defvar @cindex LVM, logical volume manager -@defvr {Scheme Variable} lvm-device-mapping +@defvar lvm-device-mapping This defines one or more logical volumes for the Linux @uref{https://www.sourceware.org/lvm2/, Logical Volume Manager (LVM)}. The volume group is activated by the @command{vgchange} command from the @code{lvm2} package. -@end defvr +@end defvar @cindex disk encryption @cindex LUKS @@ -16904,7 +17152,7 @@ I/O faster, and thus paging out unused portions of program memory will expand the RAM available for such caching. For a more detailed description of how memory is managed from the -viewpoint of a monolithic kernel, @xref{Memory +viewpoint of a monolithic kernel, @pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}. The Linux kernel has support for swap partitions and swap files: the @@ -16916,6 +17164,19 @@ should consider ease of use when deciding between them. Partitions are allocated at disk formatting time (logical volumes notwithstanding), whereas files can be allocated and deallocated at any time. +@cindex hibernation +@cindex suspend to disk +Swap space is also required to put the system into @dfn{hibernation} +(also called @dfn{suspend to disk}), whereby memory is dumped to swap +before shutdown so it can be restored when the machine is eventually +restarted. Hibernation uses at most half the size of the RAM in the +configured swap space. The Linux kernel needs to know about the swap +space to be used to resume from hibernation on boot (@i{via} a kernel +argument). When using a swap file, its offset in the device holding it +also needs to be given to the kernel; that value has to be updated if +the file is initialized again as swap---e.g., because its size was +changed. + Note that swap space is not zeroed on shutdown, so sensitive data (such as passwords) may linger on it if it was paged out. As such, you should consider having your swap reside on an encrypted device (@pxref{Mapped @@ -17001,6 +17262,57 @@ Use the file @file{/btrfs/swapfile} as swap space, which depends on the file system mounted at @file{/btrfs}. Note how we use Guile's filter to select the file system in an elegant fashion! +@lisp +(swap-devices + (list + (swap-space + (target "/dev/mapper/my-swap") + (dependencies mapped-devices)))) + +(kernel-arguments + (cons* "resume=/dev/mapper/my-swap" + %default-kernel-arguments)) +@end lisp + +The above snippet of an @code{operating-system} declaration enables +the mapped device @file{/dev/mapper/my-swap} (which may be part of an +encrypted device) as swap space, and tells the kernel to use it for +hibernation via the @code{resume} kernel argument +(@pxref{operating-system Reference}, @code{kernel-arguments}). + +@lisp +(swap-devices + (list + (swap-space + (target "/swapfile") + (dependencies (filter (file-system-mount-point-predicate "/") + file-systems))))) + +(kernel-arguments + (cons* "resume=/swapfile" + "resume_offset=92514304" + %default-kernel-arguments)) +@end lisp + +This other snippet of @code{operating-system} enables the swap file +@file{/swapfile} for hibernation by telling the kernel about the file +(@code{resume} argument) and its offset on disk (@code{resume_offset} +argument). The latter value can be found in the output of the command +@command{filefrag -e} as the first number right under the +@code{physical_offset} column header (the second command extracts its +value directly): + +@smallexample +$ sudo filefrag -e /swapfile +Filesystem type is: ef53 +File size of /swapfile is 2463842304 (601524 blocks of 4096 bytes) + ext: logical_offset: physical_offset: length: expected: flags: + 0: 0.. 2047: 92514304.. 92516351: 2048: +@dots{} +$ sudo filefrag -e /swapfile | grep '^ *0:' | cut -d: -f3 | cut -d. -f1 + 92514304 +@end smallexample + @node User Accounts @section User Accounts @@ -17167,20 +17479,20 @@ What, user groups can have a password? Well, apparently yes. Unless For convenience, a variable lists all the basic user groups one may expect: -@defvr {Scheme Variable} %base-groups +@defvar %base-groups This is the list of basic user groups that users and/or packages expect to be present on the system. This includes groups such as ``root'', ``wheel'', and ``users'', as well as groups used to control access to specific devices such as ``audio'', ``disk'', and ``cdrom''. -@end defvr +@end defvar -@defvr {Scheme Variable} %base-user-accounts +@defvar %base-user-accounts This is the list of basic system accounts that programs may expect to find on a GNU/Linux system, such as the ``nobody'' account. Note that the ``root'' account is not included here. It is a special-case and is automatically added whether or not it is specified. -@end defvr +@end defvar @node Keyboard Layout @section Keyboard Layout @@ -17403,7 +17715,7 @@ IANA}. @end table @end deftp -@defvr {Scheme Variable} %default-locale-definitions +@defvar %default-locale-definitions A list of commonly used UTF-8 locales, used as the default value of the @code{locale-definitions} field of @code{operating-system} declarations. @@ -17415,7 +17727,7 @@ that follows the dot in the name (@pxref{Using gettextized software, normalized codeset,, libc, The GNU C Library Reference Manual}). So for instance it has @code{uk_UA.utf8} but @emph{not}, say, @code{uk_UA.UTF-8}. -@end defvr +@end defvar @subsection Locale Data Compatibility Considerations @@ -17513,6 +17825,17 @@ Service xorg-server has been stopped. Service xorg-server has been started. @end example +@cindex configuration, action for shepherd services +@cindex configuration file, of a shepherd service +For some services, @command{herd configuration} returns the name of the +service's configuration file, which can be handy to inspect its +configuration: + +@example +# herd configuration sshd +/gnu/store/@dots{}-sshd_config +@end example + The following sections document the available services, starting with the core services, that may be used in an @code{operating-system} declaration. @@ -17539,6 +17862,7 @@ declaration. * Web Services:: Web servers. * Certificate Services:: TLS certificates via Let's Encrypt. * DNS Services:: DNS daemons. +* VNC Services:: VNC daemons. * VPN Services:: VPN daemons. * Network File System:: NFS related services. * Samba Services:: Samba services. @@ -17562,7 +17886,7 @@ The @code{(gnu services base)} module provides definitions for the basic services that one expects from the system. The services exported by this module are listed below. -@defvr {Scheme Variable} %base-services +@defvar %base-services This variable contains a list of basic services (@pxref{Service Types and Services}, for more information on service objects) one would expect from the system: a login service (mingetty) on each tty, syslogd, @@ -17579,9 +17903,9 @@ this: (service openssh-service-type)) %base-services) @end lisp -@end defvr +@end defvar -@defvr {Scheme Variable} special-files-service-type +@defvar special-files-service-type This is the service that sets up ``special files'' such as @file{/bin/sh}; an instance of it is part of @code{%base-services}. @@ -17592,17 +17916,19 @@ and the second element is its target. By default it is: @cindex @file{/bin/sh} @cindex @file{sh}, in @file{/bin} @lisp -`(("/bin/sh" ,(file-append bash "/bin/sh"))) +`(("/bin/sh" ,(file-append bash "/bin/sh")) + ("/usr/bin/env" ,(file-append coreutils "/bin/env"))) @end lisp @cindex @file{/usr/bin/env} @cindex @file{env}, in @file{/usr/bin} -If you want to add, say, @code{/usr/bin/env} to your system, you can +If you want to add, say, @code{/bin/bash} to your system, you can change it to: @lisp `(("/bin/sh" ,(file-append bash "/bin/sh")) - ("/usr/bin/env" ,(file-append coreutils "/bin/env"))) + ("/usr/bin/env" ,(file-append coreutils "/bin/env")) + ("/bin/bash" ,(file-append bash "/bin/bash"))) @end lisp Since this is part of @code{%base-services}, you can use @@ -17610,7 +17936,7 @@ Since this is part of @code{%base-services}, you can use (@pxref{Service Reference, @code{modify-services}}). But the simple way to add a special file is @i{via} the @code{extra-special-file} procedure (see below). -@end defvr +@end defvar @deffn {Scheme Procedure} extra-special-file @var{file} @var{target} Use @var{target} as the ``special file'' @var{file}. @@ -17629,7 +17955,7 @@ symlink: Return a service that sets the host name to @var{name}. @end deffn -@defvr {Scheme Variable} console-font-service-type +@defvar console-font-service-type Install the given fonts on the specified ttys (fonts are per virtual console on the kernel Linux). The value of this service is a list of tty/font pairs. The font can be the name of a font provided by the @code{kbd} @@ -17644,7 +17970,7 @@ package or any valid argument to @command{setfont}, as in this example: font-terminus "/share/consolefonts/ter-132n"))) ; for HDPI @end lisp -@end defvr +@end defvar @deffn {Scheme Procedure} login-service @var{config} Return a service to run login according to @var{config}, a @@ -17968,11 +18294,11 @@ and caches. @end deffn -@defvr {Scheme Variable} %nscd-default-configuration +@defvar %nscd-default-configuration This is the default @code{<nscd-configuration>} value (see below) used by @code{nscd-service}. It uses the caches defined by @code{%nscd-default-caches}; see below. -@end defvr +@end defvar @deftp {Data Type} nscd-configuration This is the data type representing the name service cache daemon (nscd) @@ -18042,7 +18368,7 @@ Maximum size in bytes of the database cache. @end table @end deftp -@defvr {Scheme Variable} %nscd-default-caches +@defvar %nscd-default-caches List of @code{<nscd-cache>} objects used by default by @code{nscd-configuration} (see above). @@ -18051,7 +18377,7 @@ lookups. The latter provides better host name lookup performance, resilience in the face of unreliable name servers, and also better privacy---often the result of host name lookups is in local cache, so external name servers do not even need to be queried. -@end defvr +@end defvar @anchor{syslog-configuration-type} @cindex syslog @@ -18078,11 +18404,11 @@ Return a service that runs a syslog daemon according to @var{config}. information on the configuration file syntax. @end deffn -@defvr {Scheme Variable} guix-service-type +@defvar guix-service-type This is the type of the service that runs the build daemon, @command{guix-daemon} (@pxref{Invoking guix-daemon}). Its value must be a @code{guix-configuration} record as described below. -@end defvr +@end defvar @anchor{guix-configuration-type} @deftp {Data Type} guix-configuration @@ -18211,6 +18537,10 @@ herd set-http-proxy guix-daemon @item @code{tmpdir} (default: @code{#f}) A directory path where the @command{guix-daemon} will perform builds. +@item @code{environment} (default: @code{'()}) +Environment variables to be set before starting the daemon, as a list of +@code{key=value} strings. + @end table @end deftp @@ -18239,9 +18569,6 @@ udev rules can be provided as a list of files through the @var{rules} variable. The procedures @code{udev-rule}, @code{udev-rules-service} and @code{file->udev-rule} from @code{(gnu services base)} simplify the creation of such rule files. - -The @command{herd rules udev} command, as root, returns the name of the -directory containing all the active udev rules. @end deffn @deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}] @@ -18341,22 +18668,22 @@ well as in the @var{groups} of the @code{udev-rules-service} procedure. %desktop-services))) @end lisp -@defvr {Scheme Variable} urandom-seed-service-type +@defvar urandom-seed-service-type Save some entropy in @code{%random-seed-file} to seed @file{/dev/urandom} when rebooting. It also tries to seed @file{/dev/urandom} from @file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is readable. -@end defvr +@end defvar -@defvr {Scheme Variable} %random-seed-file +@defvar %random-seed-file This is the name of the file where some random bytes are saved by @var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting. It defaults to @file{/var/lib/random-seed}. -@end defvr +@end defvar @cindex mouse @cindex gpm -@defvr {Scheme Variable} gpm-service-type +@defvar gpm-service-type This is the type of the service that runs GPM, the @dfn{general-purpose mouse daemon}, which provides mouse support to the Linux console. GPM allows users to use the mouse in the console, notably to select, copy, @@ -18364,7 +18691,7 @@ and paste text. The value for services of this type must be a @code{gpm-configuration} (see below). This service is not part of @code{%base-services}. -@end defvr +@end defvar @deftp {Data Type} gpm-configuration Data type representing the configuration of GPM. @@ -18383,7 +18710,7 @@ The GPM package to use. @end deftp @anchor{guix-publish-service-type} -@deffn {Scheme Variable} guix-publish-service-type +@defvar guix-publish-service-type This is the service type for @command{guix publish} (@pxref{Invoking guix publish}). Its value must be a @code{guix-publish-configuration} object, as described below. @@ -18391,7 +18718,7 @@ object, as described below. This assumes that @file{/etc/guix} already contains a signing key pair as created by @command{guix archive --generate-key} (@pxref{Invoking guix archive}). If that is not the case, the service will fail to start. -@end deffn +@end defvar @deftp {Data Type} guix-publish-configuration Data type representing the configuration of the @code{guix publish} @@ -18522,7 +18849,7 @@ about the Pluggable Authentication Module (PAM) limits, refer to the @samp{pam_limits} man page from the @code{linux-pam} package. @end deffn -@defvr {Scheme Variable} greetd-service-type +@defvar 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. @@ -18583,7 +18910,7 @@ Here is example of switching from @code{mingetty-service-type} to ;; as illustrated above #| (service mingetty-service-type (mingetty-configuration (tty "tty8"))) |#)) @end lisp -@end defvr +@end defvar @deftp {Data Type} greetd-configuration Configuration record for the @code{greetd-service-type}. @@ -18631,6 +18958,10 @@ is recommended. @item @code{terminal-switch} (default: @code{#f}) Make this terminal active on start of @code{greetd}. +@item @code{source-profile?} (default: @code{#t}) +Whether to source @file{/etc/profile} and @file{~/.profile}, when they +exist. + @item @code{default-session-user} (default: @samp{"greeter"}) The user to use for running the greeter. @@ -18665,6 +18996,81 @@ are set right after mentioned variables, so that they can be overriden. @end table @end deftp +@deftp {Data Type} greetd-wlgreet-session +Generic configuration record for the wlgreet greetd greeter. + +@table @asis +@item @code{wlgreet} (default: @code{wlgreet}) +The package with the @command{/bin/wlgreet} command. + +@item @code{command} (default: @code{(file-append sway "/bin/sway")}) +Command to be started by @command{/bin/wlgreet} on successful login. + +@item @code{command-args} (default: @code{'()}) +Command arguments to pass to command. + +@item @code{output-mode} (default: @code{"all"}) +Option to use for @code{outputMode} in the TOML configuration file. + +@item @code{scale} (default: @code{1}) +Option to use for @code{scale} in the TOML configuration file. + +@item @code{background} (default: @code{'(0 0 0 0.9)}) +RGBA list to use as the background colour of the login prompt. + +@item @code{headline} (default: @code{'(1 1 1 1)}) +RGBA list to use as the headline colour of the UI popup. + +@item @code{prompt} (default: @code{'(1 1 1 1)}) +RGBA list to use as the prompt colour of the UI popup. + +@item @code{prompt-error} (default: @code{'(1 1 1 1)}) +RGBA list to use as the error colour of the UI popup. + +@item @code{border} (default: @code{'(1 1 1 1)}) +RGBA list to use as the border colour of the UI popup. + +@item @code{extra-env} (default: @code{'()}) +Extra environment variables to set on login. + +@end table +@end deftp + +@deftp {Data Type} greetd-wlgreet-sway-session +Sway-specific configuration record for the wlgreet greetd greeter. + +@table @asis +@item @code{wlgreet-session} (default: @code{(greetd-wlgreet-session)}) +A @code{greetd-wlgreet-session} record for generic wlgreet configuration, +on top of the Sway-specific @code{greetd-wlgreet-sway-session}. + +@item @code{sway} (default: @code{sway}) +The package providing the @command{/bin/sway} command. + +@item @code{sway-configuration} (default: #f) +File-like object providing an additional Sway configuration file to be +prepended to the mandatory part of the configuration. + +@end table + +Here is an example of a greetd configuration that uses wlgreet and Sway: + +@lisp + (greetd-configuration + ;; We need to give the greeter user these permissions, otherwise + ;; Sway will crash on launch. + (greeter-supplementary-groups (list "video" "input" "seat")) + (terminals + (list (greetd-terminal-configuration + (terminal-vt "1") + (terminal-switch #t) + (default-session-command + (greetd-wlgreet-sway-session + (sway-configuration + (local-file "sway-greetd.conf")))))))) +@end lisp +@end deftp + @node Scheduled Job Execution @subsection Scheduled Job Execution @@ -18695,9 +19101,8 @@ gexps to introduce job definitions that are passed to mcron ;; job's action as a Scheme procedure. #~(job '(next-hour '(3)) (lambda () - (execl (string-append #$findutils "/bin/updatedb") - "updatedb" - "--prunepaths=/tmp /var/tmp /gnu/store")) + (system* (string-append #$findutils "/bin/updatedb") + "--prunepaths=/tmp /var/tmp /gnu/store")) "updatedb")) (define garbage-collector-job @@ -18735,6 +19140,12 @@ the job would appear as ``Lambda function'' in the output of @command{herd schedule mcron}, which is not nearly descriptive enough! @end quotation +@quotation Tip +Avoid calling the Guile procedures @code{execl}, @code{execle} or +@code{execlp} inside a job specification, else mcron won't be able to +output the completion status of the job. +@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 @@ -18790,7 +19201,7 @@ also specify the number of tasks to display: # herd schedule mcron 10 @end example -@defvr {Scheme Variable} mcron-service-type +@defvar mcron-service-type This is the type of the @code{mcron} service, whose value is an @code{mcron-configuration} object. @@ -18798,22 +19209,35 @@ 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 +@end defvar +@c Generated via (generate-documentation) at the bottom of (gnu services +@c mcron). +@c %start of fragment @deftp {Data Type} mcron-configuration -Data type representing the configuration of mcron. +Available @code{mcron-configuration} fields are: @table @asis -@item @code{mcron} (default: @var{mcron}) +@item @code{mcron} (default: @code{mcron}) (type: file-like) The mcron package to use. -@item @code{jobs} +@item @code{jobs} (default: @code{()}) (type: list-of-gexps) 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}). +specifications,, mcron,GNU@tie{}mcron}). + +@item @code{log?} (default: @code{#t}) (type: boolean) +Log messages to standard output. + +@item @code{log-format} (default: @code{"~1@@*~a ~a: ~a~%"}) (type: string) +@code{(ice-9 format)} format string for log messages. The default value +produces messages like "@samp{@var{pid} @var{name}: @var{message}"} +(@pxref{Invoking mcron, Invoking,, mcron,GNU@tie{}mcron}). Each message +is also prefixed by a timestamp by GNU Shepherd. + @end table @end deftp - +@c %end of fragment @node Log Rotation @subsection Log Rotation @@ -18851,7 +19275,7 @@ produce log files already take care of that): %base-services))) @end lisp -@defvr {Scheme Variable} rottlog-service-type +@defvar rottlog-service-type This is the type of the Rottlog service, whose value is a @code{rottlog-configuration} object. @@ -18860,7 +19284,7 @@ Other services can extend this one with new @code{log-rotation} objects This service type can define mcron jobs (@pxref{Scheduled Job Execution}) to run the rottlog service. -@end defvr +@end defvar @deftp {Data Type} rottlog-configuration Data type representing the configuration of rottlog. @@ -18918,16 +19342,16 @@ Either @code{#f} or a gexp to execute once the rotation has completed. @end table @end deftp -@defvr {Scheme Variable} %default-rotations +@defvar %default-rotations Specifies weekly rotation of @code{%rotated-files} and of @file{/var/log/guix-daemon.log}. -@end defvr +@end defvar -@defvr {Scheme Variable} %rotated-files +@defvar %rotated-files The list of syslog-controlled files to be rotated. By default it is: @code{'("/var/log/messages" "/var/log/secure" "/var/log/debug" \ "/var/log/maillog")}. -@end defvr +@end defvar Some log files just need to be deleted periodically once they are old, without any other criterion and without any archival step. This is the @@ -18945,10 +19369,10 @@ case of build logs stored by @command{guix-daemon} under That ensures build logs do not accumulate endlessly. -@defvr {Scheme Variable} log-cleanup-service-type +@defvar log-cleanup-service-type This is the type of the service to delete old logs. Its value must be a @code{log-cleanup-configuration} record as described below. -@end defvr +@end defvar @deftp {Data Type} log-cleanup-configuration Data type representing the log cleanup configuration @@ -19057,7 +19481,7 @@ configuration or a simple DHCP client are often more appropriate. This section describes the various network setup services available, starting with static network configuration. -@defvr {Scheme Variable} static-networking-service-type +@defvar static-networking-service-type 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 @@ -19090,7 +19514,7 @@ a 24-bit netmask for the local network---meaning that any 10.0.2.@var{x} address is on the local area network (LAN). Traffic to addresses outside the local network is routed @i{via} 10.0.2.2. Host names are resolved by sending domain name system (DNS) queries to 10.0.2.3. -@end defvr +@end defvar @deftp {Data Type} static-networking This is the data type representing a static network configuration. @@ -19184,8 +19608,8 @@ This is the data type representing a network route. @table @asis @item @code{destination} -The route destination (a string), either an IP address or -@code{"default"} to denote the default route. +The route destination (a string), either an IP address and network mask +or @code{"default"} to denote the default route. @item @code{source} (default: @code{#f}) The route source. @@ -19219,30 +19643,46 @@ List of arguments for this type of link. @end deftp @cindex loopback device -@defvr {Scheme Variable} %loopback-static-networking +@defvar %loopback-static-networking This is the @code{static-networking} record representing the ``loopback device'', @code{lo}, for IP addresses 127.0.0.1 and ::1, and providing the @code{loopback} Shepherd service. -@end defvr +@end defvar @cindex networking, with QEMU @cindex QEMU, networking -@defvr {Scheme Variable} %qemu-static-networking +@defvar %qemu-static-networking This is the @code{static-networking} record representing network setup when using QEMU's user-mode network stack on @code{eth0} (@pxref{Using the user mode network stack,,, QEMU, QEMU Documentation}). -@end defvr +@end defvar @cindex DHCP, networking service -@defvr {Scheme Variable} dhcp-client-service-type +@defvar dhcp-client-service-type This is the type of services that run @var{dhcp}, a Dynamic Host Configuration -Protocol (DHCP) client, on all the non-loopback network interfaces. Its value -is the DHCP client package to use, @code{isc-dhcp} by default. -@end defvr +Protocol (DHCP) client. +@end defvar + +@deftp {Data Type} dhcp-client-configuration +Data type representing the configuration of the DHCP client service. + +@table @asis +@item @code{package} (default: @code{isc-dhcp}) +DHCP client package to use. + +@item @code{interfaces} (default: @code{'all}) +Either @code{'all} or the list of interface names that the DHCP client +should listen on---e.g., @code{'("eno1")}. + +When set to @code{'all}, the DHCP client listens on all the available +non-loopback interfaces that can be activated. Otherwise the DHCP +client listens only on the specified interfaces. +@end table +@end deftp @cindex NetworkManager -@defvr {Scheme Variable} network-manager-service-type +@defvar network-manager-service-type This is the service type for the @uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager} service. The value for this service type is a @@ -19250,7 +19690,7 @@ service. The value for this service type is a This service is part of @code{%desktop-services} (@pxref{Desktop Services}). -@end defvr +@end defvar @deftp {Data Type} network-manager-configuration Data type representing the configuration of NetworkManager. @@ -19307,11 +19747,15 @@ This is the list of available plugins for virtual private networks (VPNs). An example of this is the @code{network-manager-openvpn} package, which allows NetworkManager to manage VPNs @i{via} OpenVPN. +@item @code{iwd?} (default: @code{#f}) +NetworkManager will use iwd as a backend for wireless networking if this +option is set to @code{#t}, otherwise it will use wpa-supplicant. + @end table @end deftp @cindex Connman -@deffn {Scheme Variable} connman-service-type +@defvar connman-service-type This is the service type to run @url{https://01.org/connman,Connman}, a network connection manager. @@ -19325,7 +19769,7 @@ Its value must be an @end lisp See below for details about @code{connman-configuration}. -@end deffn +@end defvar @deftp {Data Type} connman-configuration Data Type representing the configuration of connman. @@ -19336,15 +19780,18 @@ The connman package to use. @item @code{disable-vpn?} (default: @code{#f}) When true, disable connman's vpn plugin. + +@item @code{iwd?} (default: @code{#f}) +When true, ConnMan uses iwd to connect to wireless networks. @end table @end deftp @cindex WPA Supplicant -@defvr {Scheme Variable} wpa-supplicant-service-type +@defvar wpa-supplicant-service-type This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA supplicant}, an authentication daemon required to authenticate against encrypted WiFi or ethernet networks. -@end defvr +@end defvar @deftp {Data Type} wpa-supplicant-configuration Data type representing the configuration of WPA Supplicant. @@ -19380,7 +19827,7 @@ List of additional command-line arguments to pass to the daemon. Some networking devices such as modems require special care, and this is what the services below focus on. -@defvr {Scheme Variable} modem-manager-service-type +@defvar modem-manager-service-type This is the service type for the @uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager} service. The value for this service type is a @@ -19388,7 +19835,7 @@ service. The value for this service type is a This service is part of @code{%desktop-services} (@pxref{Desktop Services}). -@end defvr +@end defvar @deftp {Data Type} modem-manager-configuration Data type representing the configuration of ModemManager. @@ -19403,7 +19850,7 @@ The ModemManager package to use. @cindex USB_ModeSwitch @cindex Modeswitching -@defvr {Scheme Variable} usb-modeswitch-service-type +@defvar usb-modeswitch-service-type This is the service type for the @uref{https://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch} service. The value for this service type is @@ -19417,7 +19864,7 @@ plugged in. This service is part of @code{%desktop-services} (@pxref{Desktop Services}). -@end defvr +@end defvar @deftp {Data Type} usb-modeswitch-configuration Data type representing the configuration of USB_ModeSwitch. @@ -19469,7 +19916,7 @@ For example: The package that provides the DHCP daemon. This package is expected to provide the daemon at @file{sbin/dhcpd} relative to its output directory. The default package is the -@uref{https://www.isc.org/products/DHCP, ISC's DHCP server}. +@uref{https://www.isc.org/dhcp/, ISC's DHCP server}. @item @code{config-file} (default: @code{#f}) The configuration file to use. This is required. It will be passed to @code{dhcpd} via its @code{-cf} option. This may be any ``file-like'' @@ -19497,7 +19944,7 @@ interfaces here; see @code{man dhcpd} for details. @cindex hostapd service, for Wi-Fi access points @cindex Wi-Fi access points, hostapd service -@defvr {Scheme Variable} hostapd-service-type +@defvar hostapd-service-type This is the service type to run the @uref{https://w1.fi/hostapd/, hostapd} daemon to set up WiFi (IEEE 802.11) access points and authentication servers. Its associated value must be a @@ -19511,7 +19958,7 @@ authentication servers. Its associated value must be a (ssid "My Network") (channel 12))) @end lisp -@end defvr +@end defvar @deftp {Data Type} hostapd-configuration This data type represents the configuration of the hostapd service, with @@ -19546,7 +19993,7 @@ configuration file reference. @end table @end deftp -@defvr {Scheme Variable} simulated-wifi-service-type +@defvar simulated-wifi-service-type This is the type of a service to simulate WiFi networking, which can be useful in virtual machines for testing purposes. The service loads the Linux kernel @@ -19555,11 +20002,11 @@ Linux kernel network that can be seen on @code{wlan0}, by default. The service's value is a @code{hostapd-configuration} record. -@end defvr +@end defvar @cindex iptables -@defvr {Scheme Variable} iptables-service-type +@defvar iptables-service-type This is the service type to set up an iptables configuration. iptables is a packet filtering framework supported by the Linux kernel. This service supports configuring iptables for both IPv4 and IPv6. A simple example @@ -19588,7 +20035,7 @@ COMMIT COMMIT ")))) @end lisp -@end defvr +@end defvar @deftp {Data Type} iptables-configuration The data type representing the configuration of iptables. @@ -19609,7 +20056,7 @@ objects}). @end deftp @cindex nftables -@defvr {Scheme Variable} nftables-service-type +@defvar nftables-service-type This is the service type to set up a nftables configuration. nftables is a netfilter project that aims to replace the existing iptables, ip6tables, arptables and ebtables framework. It provides a new packet filtering @@ -19621,7 +20068,7 @@ except those to the ssh port 22. To use it, simply write: @lisp (service nftables-service-type) @end lisp -@end defvr +@end defvar @deftp {Data Type} nftables-configuration The data type representing the configuration of nftables. @@ -19638,14 +20085,14 @@ The nftables ruleset to use. This may be any ``file-like'' object @cindex NTP (Network Time Protocol), service @cindex ntpd, service for the Network Time Protocol daemon @cindex real time clock -@defvr {Scheme Variable} ntp-service-type +@defvar ntp-service-type This is the type of the service running the @uref{https://www.ntp.org, Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep the system clock synchronized with that of the specified NTP servers. The value of this service is an @code{ntpd-configuration} object, as described below. -@end defvr +@end defvar @deftp {Data Type} ntp-configuration This is the data type for the NTP service configuration. @@ -19665,10 +20112,10 @@ The NTP package to use. @end table @end deftp -@defvr {Scheme Variable} %ntp-servers +@defvar %ntp-servers List of host names used as the default NTP servers. These are servers of the @uref{https://www.ntppool.org/en/, NTP Pool Project}. -@end defvr +@end defvar @deftp {Data Type} ntp-server The data type representing the configuration of a NTP server. @@ -19714,15 +20161,15 @@ clock synchronized with that of the given servers. @end lisp @end deffn -@defvr {Scheme Variable} %openntpd-servers +@defvar %openntpd-servers This variable is a list of the server addresses defined in @code{%ntp-servers}. -@end defvr +@end defvar @deftp {Data Type} openntpd-configuration @table @asis -@item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")}) -The openntpd executable to use. +@item @code{openntpd} (default: @code{openntpd}) +The openntpd package to use. @item @code{listen-on} (default: @code{'("127.0.0.1" "::1")}) A list of local IP addresses or hostnames the ntpd daemon should listen on. @item @code{query-from} (default: @code{'()}) @@ -19751,7 +20198,7 @@ IP addresses, @code{ntpd} will calculate a median constraint from all of them. @end deftp @cindex inetd -@deffn {Scheme variable} inetd-service-type +@defvar inetd-service-type This service runs the @command{inetd} (@pxref{inetd invocation,,, inetutils, GNU Inetutils}) daemon. @command{inetd} listens for connections on internet sockets, and lazily starts the specified server @@ -19788,7 +20235,7 @@ gateway @code{hostname}: @end lisp See below for more details about @code{inetd-configuration}. -@end deffn +@end defvar @deftp {Data Type} inetd-configuration Data type representing the configuration of @command{inetd}. @@ -19845,7 +20292,7 @@ detailed discussion of each configuration field. @cindex opendht, distributed hash table network service @cindex dhtproxy, for use with jami -@defvr {Scheme Variable} opendht-service-type +@defvar opendht-service-type This is the type of the service running a @uref{https://opendht.net, OpenDHT} node, @command{dhtnode}. The daemon can be used to host your own proxy service to the distributed hash table (DHT), for example to @@ -19864,7 +20311,7 @@ leading to connectivity problems. The value of this service is a @code{opendht-configuration} object, as described below. -@end defvr +@end defvar @c The fields documentation has been auto-generated using the @c configuration->documentation procedure from @@ -19909,13 +20356,13 @@ Spawn a proxy server listening to TLS connections on the specified port. @end deftp @cindex Tor -@defvr {Scheme Variable} tor-service-type +@defvar tor-service-type This is the type for a service that runs the @uref{https://torproject.org, Tor} anonymous networking daemon. The service is configured using a @code{<tor-configuration>} record. By default, the Tor daemon runs as the @code{tor} unprivileged user, which is a member of the @code{tor} group. -@end defvr +@end defvar @deftp {Data Type} tor-configuration @table @asis @@ -19989,7 +20436,7 @@ You might want an rsync daemon if you have files that you want available so anyone (or just yourself) can download existing files or upload new files. -@deffn {Scheme Variable} rsync-service-type +@defvar rsync-service-type This is the service type for the @uref{https://rsync.samba.org, rsync} daemon, The value for this service type is a @command{rsync-configuration} record as in this example: @@ -20009,7 +20456,7 @@ The value for this service type is a @end lisp See below for details about @code{rsync-configuration}. -@end deffn +@end defvar @deftp {Data Type} rsync-configuration Data type representing the configuration for @code{rsync-service}. @@ -20095,7 +20542,7 @@ You might want a syncthing daemon if you have files between two or more computers and want to sync them in real time, safely protected from prying eyes. -@deffn {Scheme Variable} syncthing-service-type +@defvar syncthing-service-type This is the service type for the @uref{https://syncthing.net/, syncthing} daemon, The value for this service type is a @command{syncthing-configuration} record as in this example: @@ -20135,7 +20582,7 @@ directory is @file{$HOME} of the specified Syncthing @code{user}. @end table @end deftp -@end deffn +@end defvar Furthermore, @code{(gnu services ssh)} provides the following services. @cindex SSH @@ -20179,7 +20626,7 @@ The other options should be self-descriptive. @cindex SSH @cindex SSH server -@deffn {Scheme Variable} openssh-service-type +@defvar openssh-service-type This is the type for the @uref{http://www.openssh.org, OpenSSH} secure shell daemon, @command{sshd}. Its value must be an @code{openssh-configuration} record as in this example: @@ -20204,7 +20651,7 @@ example: (const `(("charlie" ,(local-file "charlie.pub"))))) @end lisp -@end deffn +@end defvar @deftp {Data Type} openssh-configuration This is the configuration record for OpenSSH's @command{sshd}. @@ -20411,7 +20858,7 @@ Whether to enable password-based authentication. @end deftp @cindex AutoSSH -@deffn {Scheme Variable} autossh-service-type +@defvar autossh-service-type This is the type for the @uref{https://www.harding.motd.ca/autossh, AutoSSH} program that runs a copy of @command{ssh} and monitors it, restarting it as necessary should it die or stop passing traffic. @@ -20435,7 +20882,7 @@ system's @code{services} field: (user "pino") (ssh-options (list "-T" "-N" "-L" "8081:localhost:8081" "remote.net")))) @end lisp -@end deffn +@end defvar @deftp {Data Type} autossh-configuration This data type represents the configuration of an AutoSSH service. @@ -20491,7 +20938,7 @@ may cause undefined behaviour. @end deftp @cindex WebSSH -@deffn {Scheme Variable} webssh-service-type +@defvar webssh-service-type This is the type for the @uref{https://webssh.huashengdun.org/, WebSSH} program that runs a web SSH client. WebSSH can be run manually from the command-line by passing arguments to the binary @command{wssh} from the @@ -20528,7 +20975,7 @@ for HTTPS connection, add this call to the operating system's (body '("root /var/www;"))) (nginx-server-configuration-locations %webssh-configuration-nginx)))))))) @end lisp -@end deffn +@end defvar @deftp {Data Type} webssh-configuration Data type representing the configuration for @code{webssh-service}. @@ -20565,7 +21012,7 @@ Logging level. @end table @end deftp -@defvr {Scheme Variable} %facebook-host-aliases +@defvar %facebook-host-aliases This variable contains a string for use in @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each line contains a entry that maps a known server name of the Facebook @@ -20592,11 +21039,11 @@ This variable is typically used in the @code{hosts-file} field of an This mechanism can prevent programs running locally, such as Web browsers, from accessing Facebook. -@end defvr +@end defvar The @code{(gnu services avahi)} provides the following definition. -@defvr {Scheme Variable} avahi-service-type +@defvar avahi-service-type This is the service that runs @command{avahi-daemon}, a system-wide mDNS/DNS-SD responder that allows for service discovery and ``zero-configuration'' host name lookups (see @uref{https://avahi.org/}). @@ -20609,7 +21056,7 @@ Service Switch}, for information on host name resolution. Additionally, add the @var{avahi} package to the system profile so that commands such as @command{avahi-browse} are directly usable. -@end defvr +@end defvar @deftp {Data Type} avahi-configuration Data type representation the configuration for Avahi. @@ -20645,11 +21092,11 @@ This is a list of domains to browse. @end table @end deftp -@deffn {Scheme Variable} openvswitch-service-type +@defvar openvswitch-service-type This is the type of the @uref{https://www.openvswitch.org, Open vSwitch} service, whose value should be an @code{openvswitch-configuration} object. -@end deffn +@end defvar @deftp {Data Type} openvswitch-configuration Data type representing the configuration of Open vSwitch, a multilayer @@ -20663,7 +21110,7 @@ Package object of the Open vSwitch. @end table @end deftp -@defvr {Scheme Variable} pagekite-service-type +@defvar pagekite-service-type This is the service type for the @uref{https://pagekite.net, PageKite} service, a tunneling solution for making localhost servers publicly visible, even from behind restrictive firewalls or NAT without forwarded ports. The value for @@ -20678,7 +21125,7 @@ Here's an example exposing the local HTTP and SSH daemons: "raw/22:@@kitename:localhost:22:@@kitesecret")) (extra-file "/etc/pagekite.rc"))) @end lisp -@end defvr +@end defvar @deftp {Data Type} pagekite-configuration Data type representing the configuration of PageKite. @@ -20709,7 +21156,7 @@ Use this to add additional options and manage shared secrets out-of-band. @end table @end deftp -@defvr {Scheme Variable} yggdrasil-service-type +@defvar yggdrasil-service-type The service type for connecting to the @uref{https://yggdrasil-network.github.io/, Yggdrasil network}, an early-stage implementation of a fully end-to-end encrypted IPv6 network. @@ -20752,7 +21199,7 @@ signing and encryption keys are defined in @file{/etc/yggdrasil-private.conf} PrivateKey: 5c750... @} @end example -@end defvr +@end defvar @deftp {Data Type} yggdrasil-configuration Data type representing the configuration of Yggdrasil. @@ -20798,7 +21245,7 @@ address, delete everything except these options: @end deftp @cindex IPFS -@defvr {Scheme Variable} ipfs-service-type +@defvar ipfs-service-type The service type for connecting to the @uref{https://ipfs.io,IPFS network}, a global, versioned, peer-to-peer file system. Pass it a @code{ipfs-configuration} to change the ports used for the gateway and API. @@ -20811,7 +21258,7 @@ Here's an example configuration, using some non-standard ports: (gateway "/ip4/127.0.0.1/tcp/8880") (api "/ip4/127.0.0.1/tcp/8881"))) @end lisp -@end defvr +@end defvar @deftp {Data Type} ipfs-configuration Data type representing the configuration of IPFS. @@ -20829,7 +21276,7 @@ Address of the API endpoint, in ‘multiaddress’ format. @end deftp @cindex keepalived -@deffn {Scheme Variable} keepalived-service-type +@defvar keepalived-service-type This is the type for the @uref{https://www.keepalived.org/, Keepalived} routing software, @command{keepalived}. Its value must be an @code{keepalived-configuration} record as in this example for master @@ -20878,7 +21325,7 @@ vrrp_instance my-group @{ @} @} @end example -@end deffn +@end defvar @node Unattended Upgrades @subsection Unattended Upgrades @@ -20930,14 +21377,14 @@ To ensure that upgrades are actually happening, you can run @command{guix system describe}. To investigate upgrade failures, visit the unattended upgrade log file (see below). -@defvr {Scheme Variable} unattended-upgrade-service-type +@defvar unattended-upgrade-service-type This is the service type for unattended upgrades. It sets up an mcron job (@pxref{Scheduled Job Execution}) that runs @command{guix system reconfigure} from the latest version of the specified channels. Its value must be a @code{unattended-upgrade-configuration} record (see below). -@end defvr +@end defvar @deftp {Data Type} unattended-upgrade-configuration This data type represents the configuration of the unattended upgrade @@ -20977,6 +21424,17 @@ Therefore, uses of @code{local-file} within @file{config.scm} will work as expected. @xref{G-Expressions}, for information about @code{local-file} and @code{file-append}. +@item @code{operating-system-expression} (default: @code{#f}) +This field specifies an expression that evaluates to the operating +system to use for the upgrade. If no value is provided the +@code{operating-system-file} field value is used. + +@lisp +(unattended-upgrade-configuration + (operating-system-expression + #~(@@ (guix system install) installation-os))) +@end lisp + @item @code{services-to-restart} (default: @code{'(mcron)}) This field specifies the Shepherd services to restart when the upgrade completes. @@ -21031,6 +21489,7 @@ started by the @dfn{login manager}, by default the GNOME Display Manager (GDM). @cindex GDM @cindex GNOME, login manager +@anchor{gdm} GDM of course allows users to log in into window managers and desktop environments other than GNOME; for those using GNOME, GDM is required for features such as automatic screen locking. @@ -21047,7 +21506,7 @@ its user interface, and it can also start Wayland sessions. The former is required for the latter, to enable, set @code{wayland?} to @code{#t} in @code{gdm-configuration}. -@defvr {Scheme Variable} gdm-service-type +@defvar gdm-service-type This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME Desktop Manager} (GDM), a program that manages graphical display servers and handles graphical user logins. Its value must be a @code{gdm-configuration} @@ -21065,7 +21524,7 @@ automatically makes them available at the log-in screen. In addition, @file{~/.xsession} files are honored. When available, @file{~/.xsession} must be an executable that starts a window manager and/or other X clients. -@end defvr +@end defvar @deftp {Data Type} gdm-configuration @table @asis @@ -21076,6 +21535,12 @@ When @code{auto-login?} is false, GDM presents a log-in screen. When @code{auto-login?} is true, GDM logs in directly as @code{default-user}. +@item @code{auto-suspend?} (default @code{#t}) +When true, GDM will automatically suspend to RAM when nobody is +physically connected. When a machine is used via remote desktop or SSH, +this should be set to false to avoid GDM interrupting remote sessions or +rendering the machine unavailable. + @item @code{debug?} (default: @code{#f}) When true, GDM writes debug messages to its log. @@ -21088,6 +21553,12 @@ Configuration of the Xorg graphical server. @item @code{x-session} (default: @code{(xinitrc)}) Script to run before starting a X session. +@item @code{xdmcp?} (default: @code{#f}) +When true, enable the X Display Manager Control Protocol (XDMCP). This +should only be enabled in trusted environments, as the protocol is not +secure. When enabled, GDM listens for XDMCP queries on the UDP port +177. + @item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper}) File name of the @code{dbus-daemon} executable. @@ -21103,7 +21574,7 @@ environment. @end table @end deftp -@defvr {Scheme Variable} slim-service-type +@defvar slim-service-type This is the type for the SLiM graphical login manager for X11. Like GDM, SLiM looks for session types described by @file{.desktop} files and @@ -21134,7 +21605,7 @@ and tty8. (delete gdm-service-type))))) @end lisp -@end defvr +@end defvar @deftp {Data Type} slim-configuration Data type representing the configuration of @code{slim-service-type}. @@ -21200,15 +21671,15 @@ The SLiM package to use. @end table @end deftp -@defvr {Scheme Variable} %default-theme -@defvrx {Scheme Variable} %default-theme-name +@defvar %default-theme +@defvarx %default-theme-name The default SLiM theme and its name. -@end defvr +@end defvar @cindex login manager @cindex X11 login -@defvr {Scheme Variable} sddm-service-type +@defvar sddm-service-type This is the type of the service to run the @uref{https://github.com/sddm/sddm,SDDM display manager}. Its value must be a @code{sddm-configuration} record (see below). @@ -21221,7 +21692,7 @@ Here's an example use: (auto-login-user "alice") (auto-login-session "xfce.desktop"))) @end lisp -@end defvr +@end defvar @deftp {Data Type} sddm-configuration This data type represents the configuration of the SDDM login manager. @@ -21320,7 +21791,8 @@ Relogin after logout. @cindex lightdm, graphical login manager @cindex display manager, lightdm -@defvr {Scheme Variable} lightdm-service-type +@anchor{lightdm} +@defvar lightdm-service-type This is the type of the service to run the @url{https://github.com/canonical/lightdm,LightDM display manager}. Its value must be a @code{lightdm-configuration} record, which is documented @@ -21352,7 +21824,7 @@ more features and verbose logs could look like: (name "*") (user-session "ratpoison")))))) @end lisp -@end defvr +@end defvar @c The LightDM service documentation can be auto-generated via the @c 'generate-doc' procedure at the bottom of the (gnu services lightdm) @@ -21455,7 +21927,7 @@ The name of the icon theme to use. The name of the cursor theme to use. @item @code{cursor-theme-size} (default: @code{16}) (type: number) -The size to use for the the cursor theme. +The size to use for the cursor theme. @item @code{allow-debugging?} (type: maybe-boolean) Set to #t to enable debug log level. @@ -21523,10 +21995,11 @@ Extra configuration values to append to the seat configuration section. @cindex Xorg, configuration @deftp {Data Type} xorg-configuration -This data type represents the configuration of the Xorg graphical display -server. Note that there is no Xorg service; instead, the X server is started -by a ``display manager'' such as GDM, SDDM, and SLiM@. Thus, the configuration -of these display managers aggregates an @code{xorg-configuration} record. +This data type represents the configuration of the Xorg graphical +display server. Note that there is no Xorg service; instead, the X +server is started by a ``display manager'' such as GDM, SDDM, LightDM or +SLiM@. Thus, the configuration of these display managers aggregates an +@code{xorg-configuration} record. @table @asis @item @code{modules} (default: @code{%default-xorg-modules}) @@ -21609,14 +22082,14 @@ The @code{(gnu services cups)} module provides a Guix service definition for the CUPS printing service. To add printer support to a Guix system, add a @code{cups-service} to the operating system definition: -@deffn {Scheme Variable} cups-service-type +@defvar cups-service-type The service type for the CUPS print server. Its value should be a valid CUPS configuration (see below). To use the default settings, simply write: @lisp (service cups-service-type) @end lisp -@end deffn +@end defvar The CUPS configuration controls the basic things about your CUPS installation: what interfaces it listens on, what to do if a print job @@ -22436,7 +22909,7 @@ To simplify things, the module defines a variable containing the set of services that users typically expect on a machine with a graphical environment and networking: -@defvr {Scheme Variable} %desktop-services +@defvar %desktop-services This is a list of services that builds upon @code{%base-services} and adds or adjusts services for a typical ``desktop'' setup. @@ -22450,7 +22923,7 @@ AccountsService daemon that allows authorized users change system passwords, an NTP client (@pxref{Networking Services}), the Avahi daemon, and has the name service switch service configured to be able to use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}). -@end defvr +@end defvar The @code{%desktop-services} variable can be used as the @code{services} field of an @code{operating-system} declaration (@pxref{operating-system @@ -22489,14 +22962,14 @@ Alternatively you can also try starting GNOME on Wayland manually from a TTY with the command ``XDG_SESSION_TYPE=wayland exec dbus-run-session gnome-session``. Currently only GNOME has support for Wayland. -@defvr {Scheme Variable} gnome-desktop-service-type +@defvar gnome-desktop-service-type This is the type of the service that adds the @uref{https://www.gnome.org, GNOME} desktop environment. Its value is a @code{gnome-desktop-configuration} object (see below). This service adds the @code{gnome} package to the system profile, and extends polkit with the actions from @code{gnome-settings-daemon}. -@end defvr +@end defvar @deftp {Data Type} gnome-desktop-configuration Configuration record for the GNOME desktop environment. @@ -22507,7 +22980,7 @@ The GNOME package to use. @end table @end deftp -@defvr {Scheme Variable} xfce-desktop-service-type +@defvar xfce-desktop-service-type This is the type of a service to run the @uref{Xfce, https://xfce.org/} desktop environment. Its value is an @code{xfce-desktop-configuration} object (see below). @@ -22522,7 +22995,7 @@ the same profile to ensure compatibility. When using this service, you should add extra plugins (@code{xfce4-whiskermenu-plugin}, @code{xfce4-weather-plugin}, etc.) to the @code{packages} field of your @code{operating-system}. -@end defvr +@end defvar @deftp {Data Type} xfce-desktop-configuration Configuration record for the Xfce desktop environment. @@ -22533,7 +23006,7 @@ The Xfce package to use. @end table @end deftp -@deffn {Scheme Variable} mate-desktop-service-type +@defvar mate-desktop-service-type This is the type of the service that runs the @uref{https://mate-desktop.org/, MATE desktop environment}. Its value is a @code{mate-desktop-configuration} object (see below). @@ -22541,7 +23014,7 @@ object (see below). This service adds the @code{mate} package to the system profile, and extends polkit with the actions from @code{mate-settings-daemon}. -@end deffn +@end defvar @deftp {Data Type} mate-desktop-configuration Configuration record for the MATE desktop environment. @@ -22552,14 +23025,14 @@ The MATE package to use. @end table @end deftp -@deffn {Scheme Variable} lxqt-desktop-service-type +@defvar lxqt-desktop-service-type This is the type of the service that runs the @uref{https://lxqt-project.org, LXQt desktop environment}. Its value is a @code{lxqt-desktop-configuration} object (see below). This service adds the @code{lxqt} package to the system profile. -@end deffn +@end defvar @deftp {Data Type} lxqt-desktop-configuration Configuration record for the LXQt desktop environment. @@ -22570,10 +23043,10 @@ The LXQT package to use. @end table @end deftp -@deffn {Scheme Variable} enlightenment-desktop-service-type +@defvar enlightenment-desktop-service-type Return a service that adds the @code{enlightenment} package to the system profile, and extends dbus with actions from @code{efl}. -@end deffn +@end defvar @deftp {Data Type} enlightenment-desktop-service-configuration @table @asis @@ -22722,21 +23195,21 @@ capabilities to ordinary users. For example, an ordinary user can be granted the capability to suspend the system if the user is logged in locally. @end deffn -@defvr {Scheme Variable} polkit-wheel-service +@defvar polkit-wheel-service Service that adds the @code{wheel} group as admins to the Polkit service. This makes it so that users in the @code{wheel} group are queried for their own passwords when performing administrative actions instead of @code{root}'s, similar to the behaviour used by @code{sudo}. -@end defvr +@end defvar -@defvr {Scheme Variable} upower-service-type +@defvar upower-service-type Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a system-wide monitor for power consumption and battery levels, with the given configuration settings. It implements the @code{org.freedesktop.UPower} D-Bus interface, and is notably used by GNOME. -@end defvr +@end defvar @deftp {Data Type} upower-configuration Data type representation the configuration for UPower. @@ -22756,7 +23229,7 @@ Enable polling the kernel for battery level changes. Ignore the lid state, this can be useful if it's incorrect on a device. @item @code{use-percentage-for-policy?} (default: @code{#t}) -Whether a to use a policy based on battery percentage rather than on +Whether to use a policy based on battery percentage rather than on estimated time left. A policy based on battery percentage is usually more reliable. @@ -22816,30 +23289,30 @@ file-systems in read and write fashion, you'll need to have @code{ntfs-3g} installed system-wide. @end deffn -@deffn {Scheme Variable} colord-service-type +@defvar colord-service-type This is the type of the service that runs @command{colord}, a system service with a D-Bus interface to manage the color profiles of input and output devices such as screens and scanners. It is notably used by the GNOME Color Manager graphical tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web site} for more information. -@end deffn +@end defvar @cindex scanner access -@defvr {Scheme Variable} sane-service-type +@defvar sane-service-type This service provides access to scanners @i{via} @uref{http://www.sane-project.org, SANE} by installing the necessary udev rules. It is included in @code{%desktop-services} (@pxref{Desktop Services}) and relies by default on @code{sane-backends-minimal} package (see below) for hardware support. -@end defvr +@end defvar -@defvr {Scheme Variable} sane-backends-minimal +@defvar sane-backends-minimal The default package which the @code{sane-service-type} installs. It supports many recent scanners. -@end defvr +@end defvar -@defvr {Scheme Variable} sane-backends +@defvar sane-backends This package includes support for all scanners that @code{sane-backends-minimal} supports, plus older Hewlett-Packard scanners supported by @code{hplip} package. In order to use this on @@ -22865,7 +23338,7 @@ a system which relies on @code{%desktop-services}, you may use @dots{} (services %my-desktop-services)) @end lisp -@end defvr +@end defvar @deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()] Return a configuration allowing an application to access GeoClue @@ -22878,14 +23351,14 @@ this application is allowed location info access. An empty users list means that all users are allowed. @end deffn -@defvr {Scheme Variable} %standard-geoclue-applications +@defvar %standard-geoclue-applications The standard list of well-known GeoClue application configurations, granting authority to the GNOME date-and-time utility to ask for the current location in order to set the time zone, and allowing the IceCat and Epiphany web browsers to request location information. IceCat and Epiphany both query the user before allowing a web page to know the user's location. -@end defvr +@end defvar @deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @ [#:whitelist '()] @ @@ -22909,11 +23382,9 @@ manages all the Bluetooth devices and provides a number of D-Bus interfaces. When AUTO-ENABLE? is true, the bluetooth controller is powered automatically at boot, which can be useful when using a bluetooth keyboard or mouse. - -Users need to be in the @code{lp} group to access the D-Bus service. @end deffn -@deffn {Scheme Variable} bluetooth-service-type +@defvar bluetooth-service-type This is the type for the @uref{https://bluez.org/, Linux Bluetooth Protocol Stack} (BlueZ) system, which generates the @file{/etc/bluetooth/main.conf} configuration file. The value for this type is a @command{bluetooth-configuration} @@ -22924,7 +23395,7 @@ record as in this example: @end lisp See below for details about @code{bluetooth-configuration}. -@end deffn +@end defvar @deftp {Data Type} bluetooth-configuration Data type representing the configuration for @code{bluetooth-service}. @@ -23355,7 +23826,7 @@ Possible values are: @end table @end deftp -@defvr {Scheme Variable} gnome-keyring-service-type +@defvar gnome-keyring-service-type This is the type of the service that adds the @uref{https://wiki.gnome.org/Projects/GnomeKeyring, GNOME Keyring}. Its value is a @code{gnome-keyring-configuration} object (see below). @@ -23363,7 +23834,7 @@ value is a @code{gnome-keyring-configuration} object (see below). This service adds the @code{gnome-keyring} package to the system profile and extends PAM with entries using @code{pam_gnome_keyring.so}, unlocking a user's login keyring when they log in or setting its password with passwd. -@end defvr +@end defvar @deftp {Data Type} gnome-keyring-configuration Configuration record for the GNOME Keyring service. @@ -23389,7 +23860,7 @@ and ``passwd'' is with the value @code{passwd}. @end table @end deftp -@defvr {Scheme Variable} seatd-service-type +@defvar seatd-service-type @uref{https://sr.ht/~kennylevinsen/seatd/, seatd} is a minimal seat management daemon. @@ -23430,7 +23901,7 @@ Depending on your setup, you will have to not only add regular users, but also system users to this group. For instance, some greetd greeters require graphics and therefore also need to negotiate with seatd. -@end defvr +@end defvar @deftp {Data Type} seatd-configuration Configuration record for the seatd daemon service. @@ -23467,7 +23938,7 @@ The @code{(gnu services sound)} module provides a service to configure the Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the preferred ALSA output driver. -@deffn {Scheme Variable} alsa-service-type +@defvar alsa-service-type This is the type for the @uref{https://alsa-project.org/, Advanced Linux Sound Architecture} (ALSA) system, which generates the @file{/etc/asound.conf} configuration file. The value for this type is a @command{alsa-configuration} @@ -23478,7 +23949,7 @@ record as in this example: @end lisp See below for details about @code{alsa-configuration}. -@end deffn +@end defvar @deftp {Data Type} alsa-configuration Data type representing the configuration for @code{alsa-service}. @@ -23536,7 +24007,7 @@ pcm.!default @{ See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the details. -@deffn {Scheme Variable} pulseaudio-service-type +@defvar pulseaudio-service-type This is the type for the @uref{https://www.pulseaudio.org/, PulseAudio} sound server. It exists to allow system overrides of the default settings via @code{pulseaudio-configuration}, see below. @@ -23555,7 +24026,7 @@ detailed below. In the (admittedly unlikely) case, that you find yourself without a @code{pulseaudio} package, consider enabling it through the @code{alsa-service-type} above. @end quotation -@end deffn +@end defvar @deftp {Data Type} pulseaudio-configuration Data type representing the configuration for @code{pulseaudio-service}. @@ -23612,7 +24083,7 @@ above example to modify the existing @code{pulseaudio-service-type} via @end deftp -@deffn {Scheme Variable} ladspa-service-type +@defvar ladspa-service-type This service sets the @var{LADSPA_PATH} variable, so that programs, which respect it, e.g. PulseAudio, can load LADSPA plugins. @@ -23627,7 +24098,7 @@ The following example will setup the service to enable modules from the See @uref{http://plugin.org.uk/ladspa-swh/docs/ladspa-swh.html} for the details. -@end deffn +@end defvar @node Database Services @subsection Database Services @@ -23798,7 +24269,7 @@ here}. @end table @end deftp -@deffn {Scheme Variable} postgresql-role-service-type +@defvar postgresql-role-service-type This service allows to create PostgreSQL roles and databases after PostgreSQL service start. Here is an example of its use. @@ -23820,7 +24291,7 @@ example: (name "alice") (create-database? #t)))) @end lisp -@end deffn +@end defvar @deftp {Data Type} postgresql-role PostgreSQL manages database access permissions using the concept of @@ -23862,11 +24333,11 @@ The initial PostgreSQL roles to create. @subsubheading MariaDB/MySQL -@defvr {Scheme Variable} mysql-service-type +@defvar mysql-service-type This is the service type for a MySQL or MariaDB database server. Its value is a @code{mysql-configuration} object that specifies which package to use, as well as various settings for the @command{mysqld} daemon. -@end defvr +@end defvar @deftp {Data Type} mysql-configuration Data type representing the configuration of @var{mysql-service-type}. @@ -23906,11 +24377,11 @@ be disabled if you would rather do that manually. @subsubheading Memcached -@defvr {Scheme Variable} memcached-service-type +@defvar memcached-service-type This is the service type for the @uref{https://memcached.org/, Memcached} service, which provides a distributed in memory cache. The value for the service type is a @code{memcached-configuration} object. -@end defvr +@end defvar @lisp (service memcached-service-type) @@ -23940,10 +24411,10 @@ Additional command line options to pass to @code{memcached}. @subsubheading Redis -@defvr {Scheme Variable} redis-service-type +@defvar redis-service-type This is the service type for the @uref{https://redis.io/, Redis} key/value store, whose value is a @code{redis-configuration} object. -@end defvr +@end defvar @deftp {Data Type} redis-configuration Data type representing the configuration of redis. @@ -25383,7 +25854,7 @@ could instantiate a dovecot service like this: @subsubheading OpenSMTPD Service -@deffn {Scheme Variable} opensmtpd-service-type +@defvar opensmtpd-service-type This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD} service, whose value should be an @code{opensmtpd-configuration} object as in this example: @@ -25393,7 +25864,7 @@ as in this example: (opensmtpd-configuration (config-file (local-file "./my-smtpd.conf")))) @end lisp -@end deffn +@end defvar @deftp {Data Type} opensmtpd-configuration Data type representing the configuration of opensmtpd. @@ -25402,6 +25873,11 @@ Data type representing the configuration of opensmtpd. @item @code{package} (default: @var{opensmtpd}) Package object of the OpenSMTPD SMTP server. +@item @code{shepherd-requirement} (default: @code{'()}) +This option can be used to provide a list of symbols naming Shepherd services +that this service will depend on, such as @code{'networking} +if you want to configure OpenSMTPD to listen on non-loopback interfaces. + @item @code{config-file} (default: @code{%default-opensmtpd-config-file}) File-like object of the OpenSMTPD configuration file to use. By default it listens on the loopback network interface, and allows for mail from @@ -25422,7 +25898,7 @@ executed: @command{smtpctl}, @command{sendmail}, @command{send-mail}, @cindex MTA (mail transfer agent) @cindex SMTP -@deffn {Scheme Variable} exim-service-type +@defvar exim-service-type This is the type of the @uref{https://exim.org, Exim} mail transfer agent (MTA), whose value should be an @code{exim-configuration} object as in this example: @@ -25432,7 +25908,7 @@ as in this example: (exim-configuration (config-file (local-file "./my-exim.conf")))) @end lisp -@end deffn +@end defvar In order to use an @code{exim-service-type} service you must also have a @code{mail-aliases-service-type} service present in your @@ -25460,10 +25936,10 @@ variables. @cindex IMAP @cindex POP -@deffn {Scheme Variable} getmail-service-type +@defvar getmail-service-type This is the type of the @uref{http://pyropus.ca/software/getmail/, Getmail} mail retriever, whose value should be an @code{getmail-configuration}. -@end deffn +@end defvar Available @code{getmail-configuration} fields are: @@ -25751,7 +26227,7 @@ Defaults to @samp{()}. @cindex email aliases @cindex aliases, for email addresses -@deffn {Scheme Variable} mail-aliases-service-type +@defvar mail-aliases-service-type This is the type of the service which provides @code{/etc/aliases}, specifying how to deliver mail to users on this system. @@ -25760,7 +26236,7 @@ specifying how to deliver mail to users on this system. '(("postmaster" "bob") ("bob" "bob@@example.com" "bob@@example2.com"))) @end lisp -@end deffn +@end defvar The configuration for a @code{mail-aliases-service-type} service is an association list denoting how to deliver mail that comes to this @@ -25777,7 +26253,7 @@ deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}). @subsubheading GNU Mailutils IMAP4 Daemon @cindex GNU Mailutils IMAP4 Daemon -@deffn {Scheme Variable} imap4d-service-type +@defvar imap4d-service-type This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,, mailutils, GNU Mailutils Manual}), whose value should be an @code{imap4d-configuration} object as in this example: @@ -25787,7 +26263,7 @@ mailutils, GNU Mailutils Manual}), whose value should be an (imap4d-configuration (config-file (local-file "imap4d.conf")))) @end lisp -@end deffn +@end defvar @deftp {Data Type} imap4d-configuration Data type representing the configuration of @command{imap4d}. @@ -25808,10 +26284,10 @@ Mailutils Manual}, for details. @cindex CalDAV @cindex CardDAV -@deffn {Scheme Variable} radicale-service-type +@defvar radicale-service-type This is the type of the @uref{https://radicale.org, Radicale} CalDAV/CardDAV server whose value should be a @code{radicale-configuration}. -@end deffn +@end defvar @deftp {Data Type} radicale-configuration Data type representing the configuration of @command{radicale}. @@ -25840,7 +26316,7 @@ services: @subsubheading Prosody Service -@deffn {Scheme Variable} prosody-service-type +@defvar prosody-service-type This is the type for the @uref{https://prosody.im, Prosody XMPP communication server}. Its value must be a @code{prosody-configuration} record as in this example: @@ -25863,7 +26339,7 @@ record as in this example: See below for details about @code{prosody-configuration}. -@end deffn +@end defvar By default, Prosody does not need much configuration. Only one @code{virtualhosts} field is needed: it specifies the domain you wish @@ -26264,7 +26740,7 @@ string, you could instantiate a prosody service like this: @url{https://bitlbee.org,BitlBee} is a gateway that provides an IRC interface to a variety of messaging protocols such as XMPP. -@defvr {Scheme Variable} bitlbee-service-type +@defvar bitlbee-service-type This is the service type for the @url{https://bitlbee.org,BitlBee} IRC gateway daemon. Its value is a @code{bitlbee-configuration} (see below). @@ -26275,7 +26751,7 @@ services: @lisp (service bitlbee-service-type) @end lisp -@end defvr +@end defvar @deftp {Data Type} bitlbee-configuration This is the configuration for BitlBee, with the following fields: @@ -26308,11 +26784,11 @@ Configuration snippet added as-is to the BitlBee configuration file. meaning that one or more clients can attach to and detach from the central core. -@defvr {Scheme Variable} quassel-service-type +@defvar quassel-service-type This is the service type for the @url{https://quassel-irc.org/,Quassel} IRC backend daemon. Its value is a @code{quassel-configuration} (see below). -@end defvr +@end defvar @deftp {Data Type} quassel-configuration This is the configuration for Quassel, with the following fields: @@ -26546,7 +27022,7 @@ When left unspecified, the value from the account archive prevails. 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, +connection to the Internet has been lost. When left unspecified, the value from the account archive prevails. @item @code{bootstrap-hostnames} (type: maybe-string-list) @@ -26792,7 +27268,7 @@ Transmission's headless variant, @command{transmission-daemon}, as a system service, allowing users to share files via BitTorrent even when they are not logged in. -@deffn {Scheme Variable} transmission-daemon-service-type +@defvar transmission-daemon-service-type The service type for the Transmission Daemon BitTorrent client. Its value must be a @code{transmission-daemon-configuration} object as in this example: @@ -26824,7 +27300,7 @@ this example: (alt-speed-time-end (+ (* 60 (+ 12 5)) 30)))) ; 5:30 pm @end lisp -@end deffn +@end defvar Once the service is started, users can interact with the daemon through its Web interface (at @code{http://localhost:9091/}) or by using the @@ -27691,7 +28167,7 @@ the 2nd element of the pair is the password. Darkstat is a packet sniffer that captures network traffic, calculates statistics about usage, and serves reports over HTTP. -@defvar {Scheme Variable} darkstat-service-type +@defvar darkstat-service-type This is the service type for the @uref{https://unix4lyfe.org/darkstat/, darkstat} service, its value must be a @code{darkstat-configuration} record as in @@ -27736,7 +28212,7 @@ provided by the Linux kernel available for the Prometheus monitoring system. This service should be deployed on all physical nodes and virtual machines, where monitoring these statistics is desirable. -@defvar {Scheme variable} prometheus-node-exporter-service-type +@defvar prometheus-node-exporter-service-type This is the service type for the @uref{https://github.com/prometheus/node_exporter/, prometheus-node-exporter} service, its value must be a @code{prometheus-node-exporter-configuration}. @@ -27781,7 +28257,7 @@ and display results, and optionally @ref{zabbix-agent, data sources are supported, such as @ref{prometheus-node-exporter, Prometheus Node Exporter}). -@defvar {Scheme variable} zabbix-server-service-type +@defvar zabbix-server-service-type This is the service type for the Zabbix server service. Its value must be a @code{zabbix-server-configuration} record, shown below. @end defvar @@ -27798,7 +28274,7 @@ The zabbix-server package. @item @code{user} (default: @code{"zabbix"}) (type: string) User who will run the Zabbix server. -@item @code{group} (default: @code{"zabbix"}) (type: group) +@item @code{group} (default: @code{"zabbix"}) (type: string) Group who will run the Zabbix server. @item @code{db-host} (default: @code{"127.0.0.1"}) (type: string) @@ -27867,7 +28343,7 @@ with custom @uref{https://www.zabbix.com/documentation/current/en/manual/config/items/userparameters, @dfn{user parameters}}. -@defvar {Scheme variable} zabbix-agent-service-type +@defvar zabbix-agent-service-type This is the service type for the Zabbix agent service. Its value must be a @code{zabbix-agent-configuration} record, shown below. @end defvar @@ -27884,7 +28360,7 @@ The zabbix-agent package. @item @code{user} (default: @code{"zabbix"}) (type: string) User who will run the Zabbix agent. -@item @code{group} (default: @code{"zabbix"}) (type: group) +@item @code{group} (default: @code{"zabbix"}) (type: string) Group who will run the Zabbix agent. @item @code{hostname} (default: @code{""}) (type: string) @@ -27944,7 +28420,7 @@ to run on the same machine as the Zabbix server. This service works by extending the @ref{PHP-FPM} and @ref{NGINX} services with the configuration necessary for loading the Zabbix user interface. -@defvar {Scheme variable} zabbix-front-end-service-type +@defvar zabbix-front-end-service-type This is the service type for the Zabbix web frontend. Its value must be a @code{zabbix-front-end-configuration} record, shown below. @end defvar @@ -28015,9 +28491,9 @@ No ``keytab'' files are provided by this service---you must explicitly create th This service is known to work with the MIT client library, @code{mit-krb5}. Other implementations have not been tested. -@defvr {Scheme Variable} krb5-service-type +@defvar krb5-service-type A service type for Kerberos 5 clients. -@end defvr +@end defvar @noindent Here is an example of its use: @@ -28104,9 +28580,9 @@ management via Kerberos. You will need this service if you want PAM enabled applications to authenticate users using Kerberos. -@defvr {Scheme Variable} pam-krb5-service-type +@defvar pam-krb5-service-type A service type for the Kerberos 5 PAM module. -@end defvr +@end defvar @deftp {Data Type} pam-krb5-configuration Data type representing the configuration of the Kerberos 5 PAM module. @@ -28125,6 +28601,8 @@ Local accounts with lower values will silently fail to authenticate. @node LDAP Services @subsection LDAP Services @cindex LDAP + +@subsubheading Authentication against LDAP with nslcd @cindex nslcd, LDAP service The @code{(gnu services authentication)} module provides the @@ -28601,6 +29079,189 @@ Defaults to @samp{()}. @c %end of generated documentation for nslcd-configuration +@subsubheading LDAP Directory Server +@cindex LDAP, server + +The @code{(gnu services ldap)} module provides the +@code{directory-server-service-type}, which can be used to create and +launch an LDAP server instance. + +Here is an example configuration of the +@code{directory-server-service-type}: + +@lisp +(use-service-modules ldap) + +... +(operating-system + ... + (services + (cons + (service directory-server-service-type + (directory-server-instance-configuration + (slapd + (slapd-configuration + (root-password "@{PBKDF2_SHA256@}AAAgAG@dots{}ABSOLUTELYSECRET"))))) + %base-services))) +@end lisp + +The root password should be generated with the @command{pwdhash} utility +that is provided by the @code{389-ds-base} package. + +Note that changes to the directory server configuration will not be +applied to existing instances. You will need to back up and restore +server data manually. Only new directory server instances will be +created upon system reconfiguration. + +@c %start of generated documentation for directory-server-instance-configuration +@deftp {Data Type} directory-server-instance-configuration +Available @code{directory-server-instance-configuration} fields are: + +@table @asis +@item @code{package} (default: @code{389-ds-base}) (type: file-like) +The @code{389-ds-base} package. + +@item @code{config-version} (default: @code{2}) (type: number) +Sets the format version of the configuration file. To use the INF file +with @command{dscreate}, this parameter must be 2. + +@item @code{full-machine-name} (default: @code{"localhost"}) (type: string) +Sets the fully qualified hostname (FQDN) of this system. + +@item @code{selinux} (default: @code{#false}) (type: boolean) +Enables SELinux detection and integration during the installation of +this instance. If set to @code{#true}, @command{dscreate} auto-detects +whether SELinux is enabled. + +@item @code{strict-host-checking} (default: @code{#true}) (type: boolean) +Sets whether the server verifies the forward and reverse record set in +the @code{full-machine-name} parameter. When installing this instance with +GSSAPI authentication behind a load balancer, set this parameter to +@code{#false}. + +@item @code{systemd} (default: @code{#false}) (type: boolean) +Enables systemd platform features. If set to @code{#true}, +@command{dscreate} auto-detects whether systemd is installed. + +@item @code{slapd} (type: slapd-configuration) +Configuration of slapd. + +@deftp {Data Type} slapd-configuration +Available @code{slapd-configuration} fields are: + +@table @asis +@item @code{instance-name} (default: @code{"localhost"}) (type: string) +Sets the name of the instance. You can refer to this value in other +parameters of this INF file using the @code{@{instance_name@}} variable. +Note that this name cannot be changed after the installation! + +@item @code{user} (default: @code{"dirsrv"}) (type: string) +Sets the user name the ns-slapd process will use after the service +started. + +@item @code{group} (default: @code{"dirsrv"}) (type: string) +Sets the group name the ns-slapd process will use after the service +started. + +@item @code{port} (default: @code{389}) (type: number) +Sets the TCP port the instance uses for LDAP connections. + +@item @code{secure-port} (default: @code{636}) (type: number) +Sets the TCP port the instance uses for TLS-secured LDAP connections +(LDAPS). + +@item @code{root-dn} (default: @code{"cn=Directory Manager"}) (type: string) +Sets the @dfn{Distinquished Name} (DN) of the administrator account for this +instance. + +@item @code{root-password} (default: @code{"@{invalid@}YOU-SHOULD-CHANGE-THIS"}) (type: string) +Sets the password of the account specified in the @code{root-dn} +parameter. You can either set this parameter to a plain text password +@command{dscreate} hashes during the installation or to a +"@{algorithm@}hash" string generated by the @command{pwdhash} utility. +Note that setting a plain text password can be a security risk if +unprivileged users can read this INF file! + +@item @code{self-sign-cert} (default: @code{#true}) (type: boolean) +Sets whether the setup creates a self-signed certificate and enables TLS +encryption during the installation. This is not suitable for +production, but it enables administrators to use TLS right after the +installation. You can replace the self-signed certificate with a +certificate issued by a certificate authority. + +@item @code{self-sign-cert-valid-months} (default: @code{24}) (type: number) +Set the number of months the issued self-signed certificate will be +valid. + +@item @code{backup-dir} (default: @code{"/var/lib/dirsrv/slapd-@{instance_name@}/bak"}) (type: string) +Set the backup directory of the instance. + +@item @code{cert-dir} (default: @code{"/etc/dirsrv/slapd-@{instance_name@}"}) (type: string) +Sets the directory of the instance's Network Security Services (NSS) +database. + +@item @code{config-dir} (default: @code{"/etc/dirsrv/slapd-@{instance_name@}"}) (type: string) +Sets the configuration directory of the instance. + +@item @code{db-dir} (default: @code{"/var/lib/dirsrv/slapd-@{instance_name@}/db"}) (type: string) +Sets the database directory of the instance. + +@item @code{initconfig-dir} (default: @code{"/etc/dirsrv/registry"}) (type: string) +Sets the directory of the operating system's rc configuration directory. + +@item @code{ldif-dir} (default: @code{"/var/lib/dirsrv/slapd-@{instance_name@}/ldif"}) (type: string) +Sets the LDIF export and import directory of the instance. + +@item @code{lock-dir} (default: @code{"/var/lock/dirsrv/slapd-@{instance_name@}"}) (type: string) +Sets the lock directory of the instance. + +@item @code{log-dir} (default: @code{"/var/log/dirsrv/slapd-@{instance_name@}"}) (type: string) +Sets the log directory of the instance. + +@item @code{run-dir} (default: @code{"/run/dirsrv"}) (type: string) +Sets PID directory of the instance. + +@item @code{schema-dir} (default: @code{"/etc/dirsrv/slapd-@{instance_name@}/schema"}) (type: string) +Sets schema directory of the instance. + +@item @code{tmp-dir} (default: @code{"/tmp"}) (type: string) +Sets the temporary directory of the instance. +@end table +@end deftp + +@item @code{backend-userroot} (type: backend-userroot-configuration) +Configuration of the userroot backend. + +@deftp {Data Type} backend-userroot-configuration +Available @code{backend-userroot-configuration} fields are: + +@table @asis +@item @code{create-suffix-entry?} (default: @code{#false}) (type: boolean) +Set this parameter to @code{#true} to create a generic root node entry +for the suffix in the database. + +@item @code{require-index?} (default: @code{#false}) (type: boolean) +Set this parameter to @code{#true} to refuse unindexed searches in this +database. + +@item @code{sample-entries} (default: @code{"no"}) (type: string) +Set this parameter to @code{"yes"} to add latest version of sample +entries to this database. Or, use @code{"001003006"} to use the 1.3.6 +version sample entries. Use this option, for example, to create a +database for testing purposes. + +@item @code{suffix} (type: maybe-string) +Sets the root suffix stored in this database. If you do not set the +suffix attribute the install process will not create the backend/suffix. +You can also create multiple backends/suffixes by duplicating this +section. + +@end table +@end deftp +@end table +@end deftp +@c end of generated documentation for directory-server + @node Web Services @subsection Web Services @@ -28612,7 +29273,7 @@ the nginx web server, and also a fastcgi wrapper daemon. @subsubheading Apache HTTP Server -@deffn {Scheme Variable} httpd-service-type +@defvar httpd-service-type Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server (@dfn{httpd}). The value for this service type is a @code{httpd-configuration} record. @@ -28640,7 +29301,7 @@ the configuration. "DocumentRoot /srv/http/www.example.com") "\n"))))) @end lisp -@end deffn +@end defvar The details for the @code{httpd-configuration}, @code{httpd-module}, @code{httpd-config-file} and @code{httpd-virtualhost} record types are @@ -28681,9 +29342,9 @@ within the store, for example @code{(file-append mod-wsgi @end table @end deffn -@defvr {Scheme Variable} %default-httpd-modules +@defvar %default-httpd-modules A default list of @code{httpd-module} objects. -@end defvr +@end defvar @deffn {Data Type} httpd-config-file This data type represents a configuration file for the httpd service. @@ -28795,7 +29456,7 @@ of strings and G-expressions. @anchor{NGINX} @subsubheading NGINX -@deffn {Scheme Variable} nginx-service-type +@defvar nginx-service-type Service type for the @uref{https://nginx.org/,NGinx} web server. The value for this service type is a @code{<nginx-configuration>} record. @@ -28820,7 +29481,7 @@ blocks, as in this example: (root "/srv/http/extra-website") (try-files (list "$uri" "$uri/index.html"))))) @end lisp -@end deffn +@end defvar At startup, @command{nginx} has not yet read its configuration file, so it uses a default file to log error messages. If it fails to load its @@ -29094,9 +29755,9 @@ and end users. It proxies requests from clients and caches the accessed URLs such that multiple requests for the same resource only creates one request to the back-end. -@defvr {Scheme Variable} varnish-service-type +@defvar varnish-service-type Service type for the Varnish daemon. -@end defvr +@end defvar @deftp {Data Type} varnish-configuration Data type representing the @code{varnish} service configuration. @@ -29170,9 +29831,9 @@ Additional arguments to pass to the @command{varnishd} process. Patchwork is a patch tracking system. It can collect patches sent to a mailing list, and display them in a web interface. -@defvr {Scheme Variable} patchwork-service-type +@defvar patchwork-service-type Service type for Patchwork. -@end defvr +@end defvar The following example is an example of a minimal service for Patchwork, for the @code{patchwork.example.com} domain. @@ -29348,9 +30009,9 @@ Web interface to the Debbugs bug tracker, by default for @uref{https://bugs.gnu.org, the GNU instance}. Mumi is a Web server, but it also fetches and indexes mail retrieved from Debbugs. -@defvr {Scheme Variable} mumi-service-type +@defvar mumi-service-type This is the service type for Mumi. -@end defvr +@end defvar @deftp {Data Type} mumi-configuration Data type representing the Mumi service configuration. This type has the @@ -29393,9 +30054,9 @@ listens on a local TCP or UNIX socket. There is an intermediary the web server. The front-end indicates which backend program to run, passing that information to the @code{fcgiwrap} process. -@defvr {Scheme Variable} fcgiwrap-service-type +@defvar fcgiwrap-service-type A service type for the @code{fcgiwrap} FastCGI proxy. -@end defvr +@end defvar @deftp {Data Type} fcgiwrap-configuration Data type representing the configuration of the @code{fcgiwrap} service. @@ -29450,9 +30111,9 @@ something time-consuming (video converting, stats processing, etc.) @end itemize ...@: and much more. -@defvr {Scheme Variable} php-fpm-service-type +@defvar php-fpm-service-type A Service type for @code{php-fpm}. -@end defvr +@end defvar @deftp {Data Type} php-fpm-configuration Data Type for php-fpm service configuration. @@ -29628,24 +30289,25 @@ program is a customizable web interface to browse Guix packages, initially designed for users of high-performance computing (HPC) clusters. -@defvr {Scheme Variable} hpcguix-web-service-type +@defvar hpcguix-web-service-type The service type for @code{hpcguix-web}. -@end defvr +@end defvar @deftp {Data Type} hpcguix-web-configuration Data type for the hpcguix-web service configuration. @table @asis -@item @code{specs} -A gexp (@pxref{G-Expressions}) specifying the hpcguix-web service -configuration. The main items available in this spec are: +@item @code{specs} (default: @code{#f}) +Either @code{#f} or a gexp (@pxref{G-Expressions}) specifying the +hpcguix-web service configuration as an @code{hpcguix-web-configuration} +record. The main fields of that record type are: @table @asis @item @code{title-prefix} (default: @code{"hpcguix | "}) The page title prefix. @item @code{guix-command} (default: @code{"guix"}) -The @command{guix} command. +The @command{guix} command to use in examples that appear on HTML pages. @item @code{package-filter-proc} (default: @code{(const #t)}) A procedure specifying how to filter packages that are displayed. @@ -29685,10 +30347,9 @@ A typical hpcguix-web service declaration looks like this: (service hpcguix-web-service-type (hpcguix-web-configuration (specs - #~(define site-config - (hpcweb-configuration - (title-prefix "Guix-HPC - ") - (menu '(("/about" "ABOUT")))))))) + #~(hpcweb-configuration + (title-prefix "Guix-HPC - ") + (menu '(("/about" "ABOUT"))))))) @end lisp @quotation Note @@ -29708,7 +30369,7 @@ more information on X.509 certificates. The @uref{https://git.sr.ht/~sircmpwn/gmnisrv, gmnisrv} program is a simple @uref{https://gemini.circumlunar.space/, Gemini} protocol server. -@deffn {Scheme Variable} gmnisrv-service-type +@defvar gmnisrv-service-type This is the type of the gmnisrv service, whose value should be a @code{gmnisrv-configuration} object, as in this example: @@ -29717,7 +30378,7 @@ This is the type of the gmnisrv service, whose value should be a (gmnisrv-configuration (config-file (local-file "./my-gmnisrv.ini")))) @end lisp -@end deffn +@end defvar @deftp {Data Type} gmnisrv-configuration Data type representing the configuration of gmnisrv. @@ -29744,7 +30405,7 @@ The @uref{gemini://qwertqwefsday.eu/agate.gmi, Agate} program is a simple @uref{https://gemini.circumlunar.space/, Gemini} protocol server written in Rust. -@deffn {Scheme Variable} agate-service-type +@defvar agate-service-type This is the type of the agate service, whose value should be an @code{agate-service-type} object, as in this example: @@ -29772,7 +30433,7 @@ Of course, you'll have to replace @i{example.com} with your own domain name, and then point the Agate configuration towards the path of the generated key and certificate. -@end deffn +@end defvar @deftp {Data Type} agate-configuration Data type representing the configuration of Agate. @@ -29866,7 +30527,7 @@ By using this service, you agree to the ACME Subscriber Agreement, which can be found there: @url{https://acme-v01.api.letsencrypt.org/directory}. -@defvr {Scheme Variable} certbot-service-type +@defvar certbot-service-type A service type for the @code{certbot} Let's Encrypt client. Its value must be a @code{certbot-configuration} record as in this example: @@ -29890,7 +30551,7 @@ must be a @code{certbot-configuration} record as in this example: @end lisp See below for details about @code{certbot-configuration}. -@end defvr +@end defvar @deftp {Data Type} certbot-configuration Data type representing the configuration of the @code{certbot} service. @@ -30056,7 +30717,7 @@ and one slave, is: %base-services))) @end lisp -@deffn {Scheme Variable} knot-service-type +@defvar knot-service-type This is the type for the Knot DNS server. Knot DNS is an authoritative DNS server, meaning that it can serve multiple @@ -30068,7 +30729,7 @@ masters, and will serve it as an authoritative server. From the point of view of a resolver, there is no difference between master and slave. The following data types are used to configure the Knot DNS server: -@end deffn +@end defvar @deftp {Data Type} knot-key-configuration Data type representing a key. @@ -30477,7 +31138,7 @@ The list of knot-zone-configuration used by this configuration. @subsubheading Knot Resolver Service -@deffn {Scheme Variable} knot-resolver-service-type +@defvar knot-resolver-service-type This is the type of the knot resolver service, whose value should be an @code{knot-resolver-configuration} object as in this example: @@ -30492,8 +31153,8 @@ cache.size = 100 * MB ")))) @end lisp -For more information, refer its @url{https://knot-resolver.readthedocs.org/en/stable/daemon.html#configuration, manual}. -@end deffn +For more information, refer its @url{https://knot-resolver.readthedocs.io/en/stable/config-overview.html, manual}. +@end defvar @deftp {Data Type} knot-resolver-configuration Data type representing the configuration of knot-resolver. @@ -30515,7 +31176,7 @@ Number of milliseconds for @code{kres-cache-gc} to periodically trim the cache. @subsubheading Dnsmasq Service -@deffn {Scheme Variable} dnsmasq-service-type +@defvar dnsmasq-service-type This is the type of the dnsmasq service, whose value should be an @code{dnsmasq-configuration} object as in this example: @@ -30525,7 +31186,7 @@ This is the type of the dnsmasq service, whose value should be an (no-resolv? #t) (servers '("192.168.1.1")))) @end lisp -@end deffn +@end defvar @deftp {Data Type} dnsmasq-configuration Data type representing the configuration of dnsmasq. @@ -30760,6 +31421,159 @@ Defaults to @samp{()}. @c %end of fragment +@node VNC Services +@subsection VNC Services +@cindex VNC (virtual network computing) +@cindex XDMCP (x display manager control protocol) + +The @code{(gnu services vnc)} module provides services related to +@dfn{Virtual Network Computing} (VNC), which makes it possible to +locally use graphical Xorg applications running on a remote machine. +Combined with a graphical manager that supports the @dfn{X Display +Manager Control Protocol}, such as GDM (@pxref{gdm}) or LightDM +(@pxref{lightdm}), it is possible to remote an entire desktop for a +multi-user environment. + +@subsubheading Xvnc + +Xvnc is a VNC server that spawns its own X window server; which means it +can run on headless servers. The Xvnc implementations provided by the +@code{tigervnc-server} and @code{turbovnc} aim to be fast and efficient. + +@defvar xvnc-service-type + +The @code{xvnc-server-type} service can be configured via the +@code{xvnc-configuration} record, documented below. A second virtual +display could be made available on a remote machine via the +following configuration: +@end defvar + +@lisp +(service xvnc-service-type + (xvnc-configuration (display-number 10))) +@end lisp + +As a demonstration, the @command{xclock} command could then be started +on the remote machine on display number 10, and it could be displayed +locally via the @command{vncviewer} command: +@example +# Start xclock on the remote machine. +ssh -L5910:localhost:5910 @var{your-host} -- guix shell xclock \ + -- env DISPLAY=:10 xclock +# Access it via VNC. +guix shell tigervnc-client -- vncviewer localhost:5910 +@end example + +The following configuration combines XDMCP and Inetd to allow multiple +users to concurrently use the remote system and login graphically via +the GDM display manager: + +@lisp +(operating-system + [...] + (services (cons* + [...] + (service xvnc-service-type (xvnc-configuration + (display-number 5) + (localhost? #f) + (xdmcp? #t) + (inetd? #t))) + (modify-services %desktop-services + (gdm-service-type config => (gdm-configuration + (inherit config) + (auto-suspend? #f) + (xdmcp? #t))))))) +@end lisp + +A remote user could then connect to it by using the @command{vncviewer} +command or a compatible VNC client and start a desktop session of their +choosing: +@example +vncviewer remote-host:5905 +@end example + +@quotation Warning +Unless your machine is in a controlled environment, for security +reasons, the @code{localhost?} configuration of the +@code{xvnc-configuration} record should be left to its default @code{#t} +value and exposed via a secure means such as an SSH port forward. The +XDMCP port, UDP 177 should also be blocked from the outside by a +firewall, as it is not a secure protocol and can expose login +credentials in clear. +@end quotation + +@c Use (configuration->documentation 'xvnc-configuration) to regenerate +@c the documentation. +@c %start of fragment +@deftp {Data Type} xvnc-configuration +Available @code{xvnc-configuration} fields are: + +@table @asis +@item @code{xvnc} (default: @code{tigervnc-server}) (type: file-like) +The package that provides the Xvnc binary. + +@item @code{display-number} (default: @code{0}) (type: number) +The display number used by Xvnc. You should set this to a number not +already used a Xorg server. + +@item @code{geometry} (default: @code{"1024x768"}) (type: string) +The size of the desktop to be created. + +@item @code{depth} (default: @code{24}) (type: color-depth) +The pixel depth in bits of the desktop to be created. Accepted values +are 16, 24 or 32. + +@item @code{port} (type: maybe-port) +The port on which to listen for connections from viewers. When left +unspecified, it defaults to 5900 plus the display number. + +@item @code{ipv4?} (default: @code{#t}) (type: boolean) +Use IPv4 for incoming and outgoing connections. + +@item @code{ipv6?} (default: @code{#t}) (type: boolean) +Use IPv6 for incoming and outgoing connections. + +@item @code{password-file} (type: maybe-string) +The password file to use, if any. Refer to vncpasswd(1) to learn how to +generate such a file. + +@item @code{xdmcp?} (default: @code{#f}) (type: boolean) +Query the XDMCP server for a session. This enables users to log in a +desktop session from the login manager screen. For a multiple users +scenario, you'll want to enable the @code{inetd?} option as well, so +that each connection to the VNC server is handled separately rather than +shared. + +@item @code{inetd?} (default: @code{#f}) (type: boolean) +Use an Inetd-style service, which runs the Xvnc server on demand. + +@item @code{frame-rate} (default: @code{60}) (type: number) +The maximum number of updates per second sent to each client. + +@item @code{security-types} (default: @code{("None")}) (type: security-types) +The allowed security schemes to use for incoming connections. The +default is "None", which is safe given that Xvnc is configured to +authenticate the user via the display manager, and only for local +connections. Accepted values are any of the following: ("None" +"VncAuth" "Plain" "TLSNone" "TLSVnc" "TLSPlain" "X509None" "X509Vnc") + +@item @code{localhost?} (default: @code{#t}) (type: boolean) +Only allow connections from the same machine. It is set to #true by +default for security, which means SSH or another secure means should be +used to expose the remote port. + +@item @code{log-level} (default: @code{30}) (type: log-level) +The log level, a number between 0 and 100, 100 meaning most verbose +output. The log messages are output to syslog. + +@item @code{extra-options} (default: @code{()}) (type: strings) +This can be used to provide extra Xvnc options not exposed via this +<xvnc-configuration> record. + +@end table + +@end deftp +@c %end of fragment @node VPN Services @subsection VPN Services @@ -30771,12 +31585,12 @@ The @code{(gnu services vpn)} module provides services related to @subsubheading Bitmask -@defvr {Scheme Variable} bitmask-service-type +@defvar 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 +@end defvar @subsubheading OpenVPN @@ -30985,7 +31799,7 @@ The list of configuration for some clients. Currently, the strongSwan service only provides legacy-style configuration with @file{ipsec.conf} and @file{ipsec.secrets} files. -@defvr {Scheme Variable} strongswan-service-type +@defvar strongswan-service-type A service type for configuring strongSwan for IPsec @acronym{VPN, Virtual Private Networking}. Its value must be a @code{strongswan-configuration} record as in this example: @@ -30997,7 +31811,7 @@ Virtual Private Networking}. Its value must be a (ipsec-secrets "/etc/ipsec.secrets"))) @end lisp -@end defvr +@end defvar @deftp {Data Type} strongswan-configuration Data type representing the configuration of the StrongSwan service. @@ -31019,7 +31833,7 @@ The file name of your @file{ipsec.secrets}. If not @code{#f}, then this and @subsubheading Wireguard -@defvr {Scheme Variable} wireguard-service-type +@defvar wireguard-service-type A service type for a Wireguard tunnel interface. Its value must be a @code{wireguard-configuration} record as in this example: @@ -31035,7 +31849,7 @@ A service type for a Wireguard tunnel interface. Its value must be a (allowed-ips '("10.0.0.2/32"))))))) @end lisp -@end defvr +@end defvar @deftp {Data Type} wireguard-configuration Data type representing the configuration of the Wireguard service. @@ -31064,6 +31878,24 @@ the file does not exist. The authorized peers on this interface. This is a list of @var{wireguard-peer} records. +@item @code{pre-up} (default: @code{'()}) +The script commands to be run before setting up the interface. + +@item @code{post-up} (default: @code{'()}) +The script commands to be run after setting up the interface. + +@item @code{pre-down} (default: @code{'()}) +The script commands to be run before tearing down the interface. + +@item @code{post-down} (default: @code{'()}) +The script commands to be run after tearing down the interface. + +@item @code{table} (default: @code{"auto"}) +The routing table to which routes are added, as a string. There are two +special values: @code{"off"} that disables the creation of routes +altogether, and @code{"auto"} (the default) that adds routes to the +default table and enables special handling of default routes. + @end table @end deftp @@ -31081,6 +31913,10 @@ The optional endpoint for the peer, such as @item @code{public-key} The peer public-key represented as a base64 string. +@item @code{preshared-key} (default: @code{#f}) +An optional pre-shared key file for this peer. The given file will not +be autogenerated. + @item @code{allowed-ips} A list of IP addresses from which incoming traffic for this peer is allowed and to which incoming traffic for this peer is directed. @@ -31113,9 +31949,9 @@ The NFS service takes care of setting up all NFS component services, kernel configuration file systems, and installs configuration files in the locations that NFS expects. -@defvr {Scheme Variable} nfs-service-type +@defvar nfs-service-type A service type for a complete NFS server. -@end defvr +@end defvar @deftp {Data Type} nfs-configuration This data type represents the configuration of the NFS service and all @@ -31188,9 +32024,9 @@ universal addresses. Many NFS related services use this facility. Hence it is automatically started when a dependent service starts. -@defvr {Scheme Variable} rpcbind-service-type +@defvar rpcbind-service-type A service type for the RPC portmapper daemon. -@end defvr +@end defvar @deftp {Data Type} rpcbind-configuration @@ -31215,9 +32051,9 @@ instance. The pipefs file system is used to transfer NFS related data between the kernel and user space programs. -@defvr {Scheme Variable} pipefs-service-type +@defvar pipefs-service-type A service type for the pipefs pseudo file system. -@end defvr +@end defvar @deftp {Data Type} pipefs-configuration Data type representing the configuration of the pipefs pseudo file system service. @@ -31240,9 +32076,9 @@ Before exchanging RPC requests an RPC client must establish a security context. Typically this is done using the Kerberos command @command{kinit} or automatically at login time using PAM services (@pxref{Kerberos Services}). -@defvr {Scheme Variable} gss-service-type +@defvar gss-service-type A service type for the Global Security System (GSS) daemon. -@end defvr +@end defvar @deftp {Data Type} gss-configuration Data type representing the configuration of the GSS daemon service. @@ -31265,9 +32101,9 @@ The directory where the pipefs file system is mounted. The idmap daemon service provides mapping between user IDs and user names. Typically it is required in order to access file systems mounted via NFSv4. -@defvr {Scheme Variable} idmap-service-type +@defvar idmap-service-type A service type for the Identity Mapper (IDMAP) daemon. -@end defvr +@end defvar @deftp {Data Type} idmap-configuration Data type representing the configuration of the IDMAP daemon service. @@ -31307,11 +32143,43 @@ can also act as an Active Directory Domain Controller (AD DC) for other hosts in an heterougenious network with different types of Computer systems. -@defvar {Scheme variable} samba-service-type +@defvar samba-service-type The service type to enable the samba services @code{samba}, @code{nmbd}, @code{smbd} and @code{winbindd}. By default this service type does not -run as an AD DC, hence @code{samba} remains disabled. +run any of the Samba daemons; they must be enabled individually. + +Below is a basic example that configures a simple, anonymous +(unauthenticated) Samba file share exposing the @file{/public} +directory. + +@quotation Tip +The @file{/public} directory and its contents must be world +readable/writable, so you'll want to run @samp{chmod -R 777 /public} on +it. +@end quotation + +@quotation Caution +Such a Samba configuration should only be used in controlled +environments, and you should not share any private files using it, as +anyone connecting to your network would be able to access them. +@end quotation + +@lisp +(service samba-service-type (samba-configuration + (enable-smbd? #t) + (config-file (plain-file "smb.conf" "\ +[global] +map to guest = Bad User +logging = syslog@@1 + +[public] +browsable = yes +path = /public +read only = no +guest ok = yes +guest only = yes\n")))) +@end lisp @end defvar @@ -31323,41 +32191,42 @@ Configuration record for the Samba suite. The samba package to use. @item @code{config-file} (default: @code{#f}) -The config file to use. +The config file to use. To learn about its syntax, run @samp{man +smb.conf}. @item @code{enable-samba?} (default: @code{#f}) -Manually enable the @code{samba} daemon. +Enable the @code{samba} daemon. @item @code{enable-smbd?} (default: @code{#f}) -Manually enable the @code{smbd} daemon. +Enable the @code{smbd} daemon. @item @code{enable-nmbd?} (default: @code{#f}) -Manually enable the @code{nmbd} daemon. +Enable the @code{nmbd} daemon. @item @code{enable-winbindd?} (default: @code{#f}) -Manually enable the @code{winbindd} daemon. +Enable the @code{winbindd} daemon. @end table @end deftp -@cindex wsdd +@cindex wsdd, Web service discovery daemon @subsubheading Web Service Discovery Daemon -Web Service Discovery Daemon implements +The @acronym{WSDD, Web Service Discovery daemon} implements the @uref{http://docs.oasis-open.org/ws-dd/discovery/1.1/os/wsdd-discovery-1.1-spec-os.html, -Web Services Dynamic Discovery} protocol that enables host discovery -- -similar to Avahi -- over Multicast DNS. It is a drop-in replacement for -SMB hosts that have had SMBv1 disabled for security reasons. - -@defvr {Scheme Variable} wsdd-service-type +Web Services Dynamic Discovery} protocol that enables host discovery +over Multicast DNS, similar to what Avahi does. It is a drop-in +replacement for SMB hosts that have had SMBv1 disabled for security +reasons. +@defvar wsdd-service-type Service type for the WSD host daemon. The value for this service type is a @code{wsdd-configuration} record. The details for the @code{wsdd-configuration} record type are given below. -@end defvr +@end defvar -@deftp{Data Type} wsdd-configuration This data type represents the -configuration for the wsdd service. +@deftp {Data Type} wsdd-configuration +This data type represents the configuration for the wsdd service. @table @asis @@ -31711,7 +32580,7 @@ monitoring tool, as it will apply custom settings each time a new power source is detected. More information can be found at @uref{https://linrunner.de/en/tlp/tlp.html, TLP home page}. -@deffn {Scheme Variable} tlp-service-type +@defvar tlp-service-type The service type for the TLP tool. The default settings are optimised for battery life on most systems, but you can tweak them to your heart's content by adding a valid @code{tlp-configuration}: @@ -31721,7 +32590,7 @@ content by adding a valid @code{tlp-configuration}: (cpu-scaling-governor-on-ac (list "performance")) (sched-powersave-on-bat? #t))) @end lisp -@end deffn +@end defvar Each parameter definition is preceded by its type; for example, @samp{boolean foo} indicates that the @code{foo} parameter should be @@ -32237,12 +33106,12 @@ Defaults to @samp{#f}. The @code{(gnu services pm)} module provides an interface to thermald, a CPU frequency scaling service which helps prevent overheating. -@defvr {Scheme Variable} thermald-service-type +@defvar thermald-service-type This is the service type for @uref{https://01.org/linux-thermal-daemon/, thermald}, the Linux Thermal Daemon, which is responsible for controlling the thermal state of processors and preventing overheating. -@end defvr +@end defvar @deftp {Data Type} thermald-configuration Data type representing the configuration of @code{thermald-service-type}. @@ -32284,9 +33153,9 @@ The following example shows how one might run @code{mpd} as user (port "6666"))) @end lisp -@defvr {Scheme Variable} mpd-service-type +@defvar mpd-service-type The service type for @command{mpd} -@end defvr +@end defvar @deftp {Data Type} mpd-configuration Data type representing the configuration of @command{mpd}. @@ -32393,7 +33262,7 @@ services. virtualization management system. This daemon runs on host servers and performs required management tasks for virtualized guests. -@deffn {Scheme Variable} libvirt-service-type +@defvar libvirt-service-type This is the type of the @uref{https://libvirt.org, libvirt daemon}. Its value must be a @code{libvirt-configuration}. @@ -32403,7 +33272,7 @@ Its value must be a @code{libvirt-configuration}. (unix-sock-group "libvirt") (tls-port "16555"))) @end lisp -@end deffn +@end defvar @c Auto-generated with (generate-libvirt-documentation) Available @code{libvirt-configuration} fields are: @@ -32960,7 +33829,7 @@ standalone daemon, the main @code{libvirtd} daemon can be restarted without risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec() itself upon receiving @code{SIGUSR1}, to allow live upgrades without downtime. -@deffn {Scheme Variable} virtlog-service-type +@defvar virtlog-service-type This is the type of the virtlog daemon. Its value must be a @code{virtlog-configuration}. @@ -32969,7 +33838,7 @@ Its value must be a @code{virtlog-configuration}. (virtlog-configuration (max-clients 1000))) @end lisp -@end deffn +@end defvar @deftypevar {@code{libvirt} parameter} package libvirt Libvirt package. @@ -33107,7 +33976,7 @@ QEMU} emulator and the @code{binfmt_misc} feature of the kernel Linux. This feature only allows you to emulate GNU/Linux on a different architecture, but see below for GNU/Hurd support. -@defvr {Scheme Variable} qemu-binfmt-service-type +@defvar qemu-binfmt-service-type This is the type of the QEMU/binfmt service for transparent emulation. Its value must be a @code{qemu-binfmt-configuration} object, which specifies the QEMU package to use as well as the architecture we want to @@ -33123,7 +33992,7 @@ In this example, we enable transparent emulation for the ARM and aarch64 platforms. Running @code{herd stop qemu-binfmt} turns it off, and running @code{herd start qemu-binfmt} turns it back on (@pxref{Invoking herd, the @command{herd} command,, shepherd, The GNU Shepherd Manual}). -@end defvr +@end defvar @deftp {Data Type} qemu-binfmt-configuration This is the configuration for the @code{qemu-binfmt} service. @@ -33204,9 +34073,9 @@ $ guix shell socat -- socat unix-connect:/tmp/qga.sock stdio See @url{https://wiki.qemu.org/Features/GuestAgent,QEMU guest agent documentation} for more options and commands. -@defvr {Scheme Variable} qemu-guest-agent-service-type +@defvar qemu-guest-agent-service-type Service type for the QEMU guest agent service. -@end defvr +@end defvar @deftp {Data Type} qemu-guest-agent-configuration Configuration for the @code{qemu-guest-agent} service. @@ -33264,7 +34133,7 @@ initialize ``secrets'' inside the VM: SSH host keys, authorized substitute keys, and so on---see the explanation of @code{secret-root} below. -@defvr {Scheme Variable} hurd-vm-service-type +@defvar hurd-vm-service-type This is the type of the Hurd in a Virtual Machine service. Its value must be a @code{hurd-vm-configuration} object, which specifies the operating system (@pxref{operating-system Reference}) and the disk size @@ -33282,7 +34151,7 @@ For example: would create a disk image big enough to build GNU@tie{}Hello, with some extra memory. -@end defvr +@end defvar @deftp {Data Type} hurd-vm-configuration The data type representing the configuration for @@ -33479,13 +34348,13 @@ cluster node that supports multiple storage backends, and installs the @end lisp Users are advised to read the -@url{http://docs.ganeti.org/ganeti/master/html/admin.html,Ganeti +@url{https://docs.ganeti.org/docs/ganeti/3.0/html/admin.html,Ganeti administrators guide} to learn about the various cluster options and day-to-day operations. There is also a @url{https://guix.gnu.org/blog/2020/running-a-ganeti-cluster-on-guix/,blog post} describing how to configure and initialize a small cluster. -@defvr {Scheme Variable} ganeti-service-type +@defvar ganeti-service-type This is a service type that includes all the various services that Ganeti nodes should run. @@ -33493,7 +34362,7 @@ Its value is a @code{ganeti-configuration} object that defines the package to use for CLI operations, as well as configuration for the various daemons. Allowed file storage paths and available guest operating systems are also configured through this data type. -@end defvr +@end defvar @deftp {Data Type} ganeti-configuration The @code{ganeti} service takes the following configuration options: @@ -33534,6 +34403,10 @@ To override a setting, you must use the configuration type for that service: @item @code{file-storage-paths} (default: @code{'()}) List of allowed directories for file storage backend. +@item @code{hooks} (default: @code{#f}) +When set, this should be a file-like object containing a directory with +@url{https://docs.ganeti.org/docs/ganeti/3.0/html/hooks.html,cluster execution hooks}. + @item @code{os} (default: @code{%default-ganeti-os}) List of @code{<ganeti-os>} records. @end table @@ -33568,12 +34441,30 @@ The name for this OS provider. It is only used to specify where the configuration ends up. Setting it to ``debootstrap'' will create @file{/etc/ganeti/instance-debootstrap}. -@item @code{extension} -The file extension for variants of this OS type. For example -@file{.conf} or @file{.scm}. +@item @code{extension} (default: @code{#f}) +The file extension for variants of this OS type. For example @file{.conf} +or @file{.scm}. It will be appended to the variant file name if set. @item @code{variants} (default: @code{'()}) -List of @code{ganeti-os-variant} objects for this OS. +This must be either a list of @code{ganeti-os-variant} objects for this OS, +or a ``file-like'' object (@pxref{G-Expressions, file-like objects}) +representing the variants directory. + +To use the Guix OS provider with variant definitions residing in a local +directory instead of declaring individual variants (see @var{guix-variants} +below), you can do: + +@lisp +(ganeti-os + (name "guix") + (variants (local-file "ganeti-guix-variants" + #:recursive? #true))) +@end lisp + +Note that you will need to maintain the @file{variants.list} file +(see @code{@url{https://docs.ganeti.org/docs/ganeti/3.0/man/ganeti-os-interface.html, +ganeti-os-interface(7)}}) +manually in this case. @end table @end deftp @@ -33591,13 +34482,13 @@ A configuration file for this variant. @end table @end deftp -@defvr {Scheme Variable} %default-debootstrap-hooks +@defvar %default-debootstrap-hooks This variable contains hooks to configure networking and the GRUB bootloader. -@end defvr +@end defvar -@defvr {Scheme Variable} %default-debootstrap-extra-pkgs +@defvar %default-debootstrap-extra-pkgs This variable contains a list of packages suitable for a fully-virtualized guest. -@end defvr +@end defvar @deftp {Data Type} debootstrap-configuration @@ -33668,7 +34559,7 @@ This is a helper procedure that creates a @code{ganeti-os} record. It takes a list of variants produced by @code{guix-variant}. @end deffn -@defvr {Scheme Variable} %default-debootstrap-variants +@defvar %default-debootstrap-variants This is a convenience variable to make the debootstrap provider work ``out of the box'' without users having to declare variants manually. It contains a single debootstrap variant with the default configuration: @@ -33678,9 +34569,9 @@ contains a single debootstrap variant with the default configuration: "default" (debootstrap-configuration))) @end lisp -@end defvr +@end defvar -@defvr {Scheme Variable} %default-guix-variants +@defvar %default-guix-variants This is a convenience variable to make the Guix OS provider work without additional configuration. It creates a virtual machine that has an SSH server, a serial console, and authorizes the Ganeti hosts SSH keys. @@ -33691,7 +34582,7 @@ server, a serial console, and authorizes the Ganeti hosts SSH keys. (file-append ganeti-instance-guix "/share/doc/ganeti-instance-guix/examples/dynamic.scm"))) @end lisp -@end defvr +@end defvar Users can implement support for OS providers unbeknownst to Guix by extending the @code{ganeti-os} and @code{ganeti-os-variant} records appropriately. @@ -33717,11 +34608,11 @@ interface limiting, please reach out to @email{guix-devel@@gnu.org}. The rest of this section documents the various services that are included by @code{ganeti-service-type}. -@defvr {Scheme Variable} ganeti-noded-service-type +@defvar ganeti-noded-service-type @command{ganeti-noded} is the daemon responsible for node-specific functions within the Ganeti system. The value of this service must be a @code{ganeti-noded-configuration} object. -@end defvr +@end defvar @deftp {Data Type} ganeti-noded-configuration This is the configuration for the @code{ganeti-noded} service. @@ -33764,14 +34655,14 @@ Note that this will leak encryption details to the log files, use with caution. @end table @end deftp -@defvr {Scheme Variable} ganeti-confd-service-type +@defvar ganeti-confd-service-type @command{ganeti-confd} answers queries related to the configuration of a Ganeti cluster. The purpose of this daemon is to have a highly available and fast way to query cluster configuration values. It is automatically active on all @dfn{master candidates}. The value of this service must be a @code{ganeti-confd-configuration} object. -@end defvr +@end defvar @deftp {Data Type} ganeti-confd-configuration This is the configuration for the @code{ganeti-confd} service. @@ -33792,7 +34683,7 @@ When true, the daemon performs additional logging for debugging purposes. @end table @end deftp -@defvr {Scheme Variable} ganeti-wconfd-service-type +@defvar ganeti-wconfd-service-type @command{ganeti-wconfd} is the daemon that has authoritative knowledge about the cluster configuration and is the only entity that can accept changes to it. All jobs that need to modify the configuration will do so @@ -33801,7 +34692,7 @@ by sending appropriate requests to this daemon. It only runs on the The value of this service must be a @code{ganeti-wconfd-configuration} object. -@end defvr +@end defvar @deftp {Data Type} ganeti-wconfd-configuration This is the configuration for the @code{ganeti-wconfd} service. @@ -33821,14 +34712,14 @@ When true, the daemon performs additional logging for debugging purposes. @end table @end deftp -@defvr {Scheme Variable} ganeti-luxid-service-type +@defvar ganeti-luxid-service-type @command{ganeti-luxid} is a daemon used to answer queries related to the configuration and the current live state of a Ganeti cluster. Additionally, it is the authoritative daemon for the Ganeti job queue. Jobs can be submitted via this daemon and it schedules and starts them. It takes a @code{ganeti-luxid-configuration} object. -@end defvr +@end defvar @deftp {Data Type} ganeti-luxid-configuration This is the configuration for the @code{ganeti-luxid} service. @@ -33848,7 +34739,7 @@ When true, the daemon performs additional logging for debugging purposes. @end table @end deftp -@defvr {Scheme Variable} ganeti-rapi-service-type +@defvar ganeti-rapi-service-type @command{ganeti-rapi} provides a remote API for Ganeti clusters. It runs on the master node and can be used to perform cluster actions programmatically via a JSON-based RPC protocol. @@ -33856,11 +34747,11 @@ via a JSON-based RPC protocol. Most query operations are allowed without authentication (unless @var{require-authentication?} is set), whereas write operations require explicit authorization via the @file{/var/lib/ganeti/rapi/users} file. See -the @url{http://docs.ganeti.org/ganeti/master/html/rapi.html, Ganeti Remote +the @url{https://docs.ganeti.org/docs/ganeti/3.0/html/rapi.html, Ganeti Remote API documentation} for more information. The value of this service must be a @code{ganeti-rapi-configuration} object. -@end defvr +@end defvar @deftp {Data Type} ganeti-rapi-configuration This is the configuration for the @code{ganeti-rapi} service. @@ -33904,7 +34795,7 @@ Note that this will leak encryption details to the log files, use with caution. @end table @end deftp -@defvr {Scheme Variable} ganeti-kvmd-service-type +@defvar ganeti-kvmd-service-type @command{ganeti-kvmd} is responsible for determining whether a given KVM instance was shut down by an administrator or a user. Normally Ganeti will restart an instance that was not stopped through Ganeti itself. If the @@ -33914,7 +34805,7 @@ marks the instance as @dfn{USER_down} instead of @dfn{ERROR_down} when it shuts down gracefully by itself. It takes a @code{ganeti-kvmd-configuration} object. -@end defvr +@end defvar @deftp {Data Type} ganeti-kvmd-configuration @@ -33928,13 +34819,13 @@ When true, the daemon performs additional logging for debugging purposes. @end table @end deftp -@defvr {Scheme Variable} ganeti-mond-service-type +@defvar ganeti-mond-service-type @command{ganeti-mond} is an optional daemon that provides Ganeti monitoring functionality. It is responsible for running data collectors and publish the collected information through a HTTP interface. It takes a @code{ganeti-mond-configuration} object. -@end defvr +@end defvar @deftp {Data Type} ganeti-mond-configuration @@ -33955,12 +34846,12 @@ When true, the daemon performs additional logging for debugging purposes. @end table @end deftp -@defvr {Scheme Variable} ganeti-metad-service-type +@defvar ganeti-metad-service-type @command{ganeti-metad} is an optional daemon that can be used to provide information about the cluster to instances or OS install scripts. It takes a @code{ganeti-metad-configuration} object. -@end defvr +@end defvar @deftp {Data Type} ganeti-metad-configuration @@ -33981,7 +34872,7 @@ When true, the daemon performs additional logging for debugging purposes. @end table @end deftp -@defvr {Scheme Variable} ganeti-watcher-service-type +@defvar ganeti-watcher-service-type @command{ganeti-watcher} is a script designed to run periodically and ensure the health of a cluster. It will automatically restart instances that have stopped without Ganeti's consent, and repairs DRBD links in case a node has @@ -33993,7 +34884,7 @@ node it is running on is declared offline by known master candidates. It can be paused on all nodes with @command{gnt-cluster watcher pause}. The service takes a @code{ganeti-watcher-configuration} object. -@end defvr +@end defvar @deftp {Data Type} ganeti-watcher-configuration @@ -34023,7 +34914,7 @@ When @code{#t}, the script performs additional logging for debugging purposes. @end table @end deftp -@defvr {Scheme Variable} ganeti-cleaner-service-type +@defvar ganeti-cleaner-service-type @command{ganeti-cleaner} is a script designed to run periodically and remove old files from the cluster. This service type controls two @dfn{cron jobs}: one intended for the master node that permanently purges old cluster jobs, @@ -34033,7 +34924,7 @@ it is safe to include even on non-master nodes as it will disable itself as necessary. It takes a @code{ganeti-cleaner-configuration} object. -@end defvr +@end defvar @deftp {Data Type} ganeti-cleaner-configuration @@ -34057,27 +34948,24 @@ How often to run the node cleaning job. The default is once per day, at The @code{(gnu services version-control)} module provides a service to allow remote access to local Git repositories. There are three options: -the @code{git-daemon-service}, which provides access to repositories via +the @code{git-daemon-service-type}, which provides access to repositories via the @code{git://} unsecured TCP-based protocol, extending the @code{nginx} web server to proxy some requests to @code{git-http-backend}, or providing a web interface with @code{cgit-service-type}. -@deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)] - -Return a service that runs @command{git daemon}, a simple TCP server to +@defvar git-daemon-service-type +Type for a service that runs @command{git daemon}, a simple TCP server to expose repositories over the Git protocol for anonymous access. -The optional @var{config} argument should be a -@code{<git-daemon-configuration>} object, by default it allows read-only -access to exported@footnote{By creating the magic file -@file{git-daemon-export-ok} in the repository directory.} repositories under -@file{/srv/git}. - -@end deffn +The value for this service type is a @code{<git-daemon-configuration>} +record, by default it allows read-only access to exported@footnote{By +creating the magic file @file{git-daemon-export-ok} in the repository +directory.} repositories under @file{/srv/git}. +@end defvar @deftp {Data Type} git-daemon-configuration -Data type representing the configuration for @code{git-daemon-service}. +Data type representing the configuration for @code{git-daemon-service-type}. @table @asis @item @code{package} (default: @code{git}) @@ -34114,8 +35002,8 @@ Whether to listen on an alternative port, which defaults to 9418. If not empty, only allow access to this list of directories. @item @code{extra-options} (default: @code{'()}) -Extra options will be passed to @command{git daemon}, please run -@command{man git-daemon} for more information. +Extra options that will be passed to @command{git daemon}.@footnote{Run +@command{man git-daemon} for more information.} @end table @end deftp @@ -35188,7 +36076,21 @@ Data type representing the configuration for @code{gitolite-service-type}. @table @asis @item @code{package} (default: @var{gitolite}) -Gitolite package to use. +Gitolite package to use. There are optional Gitolite dependencies that +are not included in the default package, such as Redis and git-annex. +These features can be made available by using the @code{make-gitolite} +procedure in the @code{(gnu packages version-control}) module to produce +a variant of Gitolite with the desired additional dependencies. + +The following code returns a package in which the Redis and git-annex +programs can be invoked by Gitolite's scripts: + +@example +(use-modules (gnu packages databases) + (gnu packages haskell-apps) + (gnu packages version-control)) +(make-gitolite (list redis git-annex)) +@end example @item @code{user} (default: @var{git}) User to use for Gitolite. This will be user that you use when accessing @@ -35230,6 +36132,15 @@ A value like @code{#o0027} will give read access to the group used by Gitolite (by default: @code{git}). This is necessary when using Gitolite with software like cgit or gitweb. +@item @code{local-code} (default: @code{"$rc@{GL_ADMIN_BASE@}/local"}) +Allows you to add your own non-core programs, or even override the +shipped ones with your own. + +Please supply the FULL path to this variable. By default, directory +called "local" in your gitolite clone is used, providing the benefits of +versioning them as well as making changes to them without having to log +on to the server. + @item @code{unsafe-pattern} (default: @code{#f}) An optional Perl regular expression for catching unsafe configurations in the configuration file. See @@ -35391,13 +36302,32 @@ like to serve. @node Game Services @subsection Game Services +@subsubheading Joycond service +@cindex joycond +The joycond service allows the pairing of Nintendo joycon game +controllers over Bluetooth. (@pxref{Desktop Services} for setting up +Bluetooth.) + +@deftp {Data Type} joycond-configuration +Data type representing the configuration of @command{joycond}. + +@table @asis +@item @code{package} (default: @code{joycond}) +The joycond package to use. +@end table +@end deftp + +@defvar joycond-service-type +Service type for the joycond service. +@end defvar + @subsubheading The Battle for Wesnoth Service @cindex wesnothd @uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn based tactical strategy game, with several single player campaigns, and multiplayer games (both networked and local). -@defvar {Scheme Variable} wesnothd-service-type +@defvar wesnothd-service-type Service type for the wesnothd service. Its value must be a @code{wesnothd-configuration} object. To run wesnothd in the default configuration, instantiate it as: @@ -35428,7 +36358,7 @@ The @code{(gnu services pam-mount)} module provides a service allowing users to mount volumes when they log in. It should be able to mount any volume format supported by the system. -@defvar {Scheme Variable} pam-mount-service-type +@defvar pam-mount-service-type Service type for PAM Mount support. @end defvar @@ -35523,7 +36453,7 @@ There is a script to run the coordinator component of the Guix Build Coordinator, but the Guix service uses a custom Guile script instead, to provide better integration with G-expressions used in the configuration. -@defvar {Scheme Variable} guix-build-coordinator-service-type +@defvar guix-build-coordinator-service-type Service type for the Guix Build Coordinator. Its value must be a @code{guix-build-coordinator-configuration} object. @end defvar @@ -35572,7 +36502,7 @@ The Guile package with which to run the Guix Build Coordinator. @end table @end deftp -@defvar {Scheme Variable} guix-build-coordinator-agent-service-type +@defvar guix-build-coordinator-agent-service-type Service type for a Guix Build Coordinator agent. Its value must be a @code{guix-build-coordinator-agent-configuration} object. @end defvar @@ -35601,6 +36531,9 @@ will use the current system it's running on as the default. @item @code{max-parallel-builds} (default: @code{1}) The number of builds to perform in parallel. +@item @code{max-allocated-builds} (default: @code{#f}) +The maximum number of builds this agent can be allocated. + @item @code{max-1min-load-average} (default: @code{#f}) Load average value to look at when considering starting new builds, if the 1 minute load average exceeds this value, the agent will wait before @@ -35695,7 +36628,7 @@ type below assists in running this script. This is an additional tool that may be useful when building derivations contained within an instance of the Guix Data Service. -@defvar {Scheme Variable} guix-build-coordinator-queue-builds-service-type +@defvar guix-build-coordinator-queue-builds-service-type Service type for the guix-build-coordinator-queue-builds-from-guix-data-service script. Its value must be a @code{guix-build-coordinator-queue-builds-configuration} @@ -35748,7 +36681,7 @@ packages, derivations and lint warnings. The data is stored in a PostgreSQL database, and available through a web interface. -@defvar {Scheme Variable} guix-data-service-type +@defvar guix-data-service-type Service type for the Guix Data Service. Its value must be a @code{guix-data-service-configuration} object. The service optionally extends the getmail service, as the guix-commits mailing list is used to @@ -35796,7 +36729,7 @@ Extra command line options for @code{guix-data-service-process-jobs}. The @uref{https://git.cbaines.net/guix/nar-herder/about/,Nar Herder} is a utility for managing a collection of nars. -@defvar {Scheme Variable} nar-herder-type +@defvar nar-herder-type Service type for the Guix Data Service. Its value must be a @code{nar-herder-configuration} object. The service optionally extends the getmail service, as the guix-commits mailing list is used to @@ -35897,7 +36830,7 @@ space and provides a more responsive and configurable alternative to the in-kernel OOM killer. It is useful to prevent the system from becoming unresponsive when it runs out of memory. -@deffn {Scheme Variable} earlyoom-service-type +@defvar earlyoom-service-type The service type for running @command{earlyoom}, the Early OOM daemon. Its value must be a @code{earlyoom-configuration} object, described below. The service can be instantiated in its default configuration @@ -35906,7 +36839,7 @@ with: @lisp (service earlyoom-service-type) @end lisp -@end deffn +@end defvar @deftp {Data Type} earlyoom-configuration This is the configuration record for the @code{earlyoom-service-type}. @@ -35956,7 +36889,7 @@ modules at boot. This is especially useful for modules that don't autoload and need to be manually loaded, as is the case with @code{ddcci}. -@deffn {Scheme Variable} kernel-module-loader-service-type +@defvar kernel-module-loader-service-type The service type for loading loadable kernel modules at boot with @command{modprobe}. Its value must be a list of strings representing module names. For example loading the drivers provided by @@ -35982,7 +36915,7 @@ parameters, can be done as follow: %base-services)) (kernel-loadable-modules (list ddcci-driver-linux))) @end lisp -@end deffn +@end defvar @cindex rasdaemon @cindex Platform Reliability, Availability and Serviceability daemon @@ -36039,7 +36972,7 @@ For detailed information about the types of error events gathered and how to make sense of them, see the kernel administrator's guide at @url{https://www.kernel.org/doc/html/latest/admin-guide/ras.html}. -@defvr {Scheme Variable} rasdaemon-service-type +@defvar rasdaemon-service-type Service type for the @command{rasdaemon} service. It accepts a @code{rasdaemon-configuration} object. Instantiating like @@ -36049,7 +36982,7 @@ Service type for the @command{rasdaemon} service. It accepts a will load with a default configuration, which monitors all events and logs to syslogd. -@end defvr +@end defvar @deftp {Data Type} rasdaemon-configuration The data type representing the configuration of @command{rasdaemon}. @@ -36074,7 +37007,7 @@ memory. The Linux Kernel documentation has more information about @uref{https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html,zram} devices. -@deffn {Scheme Variable} zram-device-service-type +@defvar zram-device-service-type This service creates the zram block device, formats it as swap and enables it as a swap device. The service's value is a @code{zram-device-configuration} record. @@ -36107,16 +37040,16 @@ up not being used much for the reasons described there. @end table @end deftp -@end deffn +@end defvar @node Hurd Services @subsection Hurd Services -@defvr {Scheme Variable} hurd-console-service-type +@defvar hurd-console-service-type This service starts the fancy @code{VGA} console client on the Hurd. The service's value is a @code{hurd-console-configuration} record. -@end defvr +@end defvar @deftp {Data Type} hurd-console-configuration This is the data type representing the configuration for the @@ -36128,11 +37061,11 @@ The Hurd package to use. @end table @end deftp -@defvr {Scheme Variable} hurd-getty-service-type +@defvar hurd-getty-service-type This service starts a tty using the Hurd @code{getty} program. The service's value is a @code{hurd-getty-configuration} record. -@end defvr +@end defvar @deftp {Data Type} hurd-getty-configuration This is the data type representing the configuration for the @@ -36160,14 +37093,14 @@ An integer specifying the baud rate of the tty. The @code{(gnu services authentication)} module provides a DBus service to read and identify fingerprints via a fingerprint sensor. -@defvr {Scheme Variable} fprintd-service-type +@defvar fprintd-service-type The service type for @command{fprintd}, which provides the fingerprint reading capability. @lisp (service fprintd-service-type) @end lisp -@end defvr +@end defvar @cindex sysctl @subsubheading System Control Service @@ -36175,7 +37108,7 @@ reading capability. The @code{(gnu services sysctl)} provides a service to configure kernel parameters at boot. -@defvr {Scheme Variable} sysctl-service-type +@defvar sysctl-service-type The service type for @command{sysctl}, which modifies kernel parameters under @file{/proc/sys/}. To enable IPv4 forwarding, it can be instantiated as: @@ -36200,7 +37133,7 @@ kernel parameters that you want (@pxref{Service Reference, %default-sysctl-settings))))) @end lisp -@end defvr +@end defvar @deftp {Data Type} sysctl-configuration The data type representing the configuration of @command{sysctl}. @@ -36214,10 +37147,10 @@ An association list specifies kernel parameters and their values. @end table @end deftp -@defvr {Scheme Variable} %default-sysctl-settings +@defvar %default-sysctl-settings An association list specifying the default @command{sysctl} parameters on Guix System. -@end defvr +@end defvar @cindex pcscd @subsubheading PC/SC Smart Card Daemon Service @@ -36228,7 +37161,7 @@ daemon program for pcsc-lite and the MuscleCard framework. It is a resource manager that coordinates communications with smart card readers, smart cards and cryptographic tokens that are connected to the system. -@defvr {Scheme Variable} pcscd-service-type +@defvar pcscd-service-type Service type for the @command{pcscd} service. Its value must be a @code{pcscd-configuration} object. To run pcscd in the default configuration, instantiate it as: @@ -36236,7 +37169,7 @@ configuration, instantiate it as: @lisp (service pcscd-service-type) @end lisp -@end defvr +@end defvar @deftp {Data Type} pcscd-configuration The data type representing the configuration of @command{pcscd}. @@ -36289,10 +37222,10 @@ The @uref{https://linuxwacom.github.io/, inputattach} service allows you to use input devices such as Wacom tablets, touchscreens, or joysticks with the Xorg display server. -@deffn {Scheme Variable} inputattach-service-type +@defvar inputattach-service-type Type of a service that runs @command{inputattach} on a device and dispatches events from it. -@end deffn +@end defvar @deftp {Data Type} inputattach-configuration @table @asis @@ -36316,10 +37249,10 @@ If true, this must be the name of a file to log messages to. @cindex dictionary The @code{(gnu services dict)} module provides the following service: -@defvr {Scheme Variable} dicod-service-type +@defvar dicod-service-type This is the type of the service that runs the @command{dicod} daemon, an implementation of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}). -@end defvr +@end defvar @deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)] Return a service that runs the @command{dicod} daemon, an implementation @@ -36392,10 +37325,10 @@ List of strings or gexps representing the arguments for the database @end table @end deftp -@defvr {Scheme Variable} %dicod-database:gcide +@defvar %dicod-database:gcide A @code{<dicod-database>} object serving the GNU Collaborative International Dictionary of English using the @code{gcide} package. -@end defvr +@end defvar The following is an example @code{dicod-service} configuration. @@ -36420,13 +37353,13 @@ The following is an example @code{dicod-service} configuration. The @code{(gnu services docker)} module provides the following services. -@defvr {Scheme Variable} docker-service-type +@defvar docker-service-type This is the type of the service that runs @url{https://www.docker.com,Docker}, a daemon that can execute application bundles (sometimes referred to as ``containers'') in isolated environments. -@end defvr +@end defvar @deftp {Data Type} docker-configuration This is the data type representing the configuration of Docker and Containerd. @@ -36469,7 +37402,7 @@ This must be a list of strings where each string has the form @end deftp @cindex Singularity, container service -@defvr {Scheme Variable} singularity-service-type +@defvar singularity-service-type This is the type of the service that allows you to run @url{https://www.sylabs.io/singularity/, Singularity}, a Docker-style tool to create and run application bundles (aka. ``containers''). The value for this @@ -36478,14 +37411,14 @@ service is the Singularity package to use. The service does not install a daemon; instead, it installs helper programs as setuid-root (@pxref{Setuid Programs}) such that unprivileged users can invoke @command{singularity run} and similar commands. -@end defvr +@end defvar @cindex Audit @subsubheading Auditd Service The @code{(gnu services auditd)} module provides the following service. -@defvr {Scheme Variable} auditd-service-type +@defvar auditd-service-type This is the type of the service that runs @url{https://people.redhat.com/sgrubb/audit/,auditd}, @@ -36518,7 +37451,7 @@ to view a report of all recorded events. The audit daemon by default logs into the file @file{/var/log/audit.log}. -@end defvr +@end defvar @deftp {Data Type} auditd-configuration This is the data type representing the configuration of auditd. @@ -36541,7 +37474,7 @@ instantiate on startup. The @code{(gnu services science)} module provides the following service. -@defvr {Scheme Variable} rshiny-service-type +@defvar rshiny-service-type This is a type of service which is used to run a webapp created with @code{r-shiny}. This service sets the @env{R_LIBS_USER} environment @@ -36581,14 +37514,14 @@ runApp(launch.browser=0, port=4202)~%\n" @end table @end deftp -@end defvr +@end defvar @cindex Nix @subsubheading Nix service The @code{(gnu services nix)} module provides the following service. -@defvr {Scheme Variable} nix-service-type +@defvar nix-service-type This is the type of the service that runs build daemon of the @url{https://nixos.org/nix/, Nix} package manager. Here is an example showing @@ -36622,7 +37555,7 @@ $ ln -s "/nix/var/nix/profiles/per-user/$USER/profile" ~/.nix-profile $ source /run/current-system/profile/etc/profile.d/nix.sh @end example -@end defvr +@end defvar @deftp {Data Type} nix-configuration This data type represents the configuration of the Nix daemon. @@ -36634,6 +37567,15 @@ The Nix package to use. @item @code{sandbox} (default: @code{#t}) Specifies whether builds are sandboxed by default. +@item @code{build-directory} (default: @code{"/tmp"}) +The directory where build directory are stored during builds. +This is useful to change if, for example, the default location does not +have enough space to hold build trees for big packages. + +This is similar to setting the @env{TMPDIR} environment variable for +@command{guix-daemon}. @ref{Build Environment Setup, @env{TMPDIR}}, +for more info. + @item @code{build-sandbox-items} (default: @code{'()}) This is a list of strings or objects appended to the @code{build-sandbox-items} field of the configuration file. @@ -36676,7 +37618,7 @@ Service developers can extend the @code{fail2ban-service-type} service type itself via the usual service extension mechanism. @end table -@defvr {Scheme Variable} fail2ban-service-type +@defvar fail2ban-service-type This is the type of the service that runs @code{fail2ban} daemon. Below is an example of a basic, explicit configuration: @@ -36696,7 +37638,7 @@ is an example of a basic, explicit configuration: (service openssh-service-type)) %base-services) @end lisp -@end defvr +@end defvar @deffn {Scheme Procedure} fail2ban-jail-service @var{svc-type} @var{jail} Extend @var{svc-type}, a @code{<service-type>} object with @var{jail}, a @@ -36973,13 +37915,13 @@ defaults to root. 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 +@defvar %setuid-programs 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}. -@end defvr +@end defvar Under the hood, the actual setuid programs are created in the @file{/run/setuid-programs} directory at system activation time. The @@ -37116,15 +38058,15 @@ to the name service cache daemon (@pxref{Base Services, For convenience, the following variables provide typical NSS configurations. -@defvr {Scheme Variable} %default-nss +@defvar %default-nss This is the default name service switch configuration, a @code{name-service-switch} object. -@end defvr +@end defvar -@defvr {Scheme Variable} %mdns-host-lookup-nss +@defvar %mdns-host-lookup-nss This is the name service switch configuration with support for host name lookup over multicast DNS (mDNS) for host names ending in @code{.local}. -@end defvr +@end defvar The reference for name service switch configuration is given below. It is a direct mapping of the configuration file format of the C library , so @@ -37213,9 +38155,9 @@ file system, you would write: (initrd-modules (cons "megaraid_sas" %base-initrd-modules))) @end lisp -@defvr {Scheme Variable} %base-initrd-modules +@defvar %base-initrd-modules This is the list of kernel modules included in the initrd by default. -@end defvr +@end defvar Furthermore, if you need lower-level customization, the @code{initrd} field of an @code{operating-system} declaration allows @@ -37326,15 +38268,17 @@ here is how to use it and customize it further. @cindex initrd @cindex initial RAM disk @deffn {Scheme Procedure} raw-initrd @var{file-systems} @ - [#:linux-modules '()] [#:mapped-devices '()] @ - [#:keyboard-layout #f] @ - [#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f] + [#:linux-modules '()] [#:pre-mount #t] [#:mapped-devices '()] @ + [#:keyboard-layout #f] [#:helper-packages '()] @ + [#:qemu-networking? #f] [#:volatile-root? #f] Return a derivation that builds a raw initrd. @var{file-systems} is a list of file systems to be mounted by the initrd, possibly in addition to the root file system specified on the kernel command line via @option{root}. @var{linux-modules} is a list of kernel modules to be loaded at boot time. @var{mapped-devices} is a list of device mappings to realize before @var{file-systems} are mounted (@pxref{Mapped Devices}). +@var{pre-mount} is a G-expression to evaluate before realizing +@var{mapped-devices}. @var{helper-packages} is a list of packages to be copied in the initrd. It may include @code{e2fsck/static} or other packages needed by the initrd to check @@ -37420,8 +38364,9 @@ The type of a bootloader configuration declaration. @cindex BIOS, bootloader The bootloader to use, as a @code{bootloader} object. For now @code{grub-bootloader}, @code{grub-efi-bootloader}, -@code{grub-efi-netboot-bootloader}, @code{grub-efi-removable-bootloader}, -@code{extlinux-bootloader} and @code{u-boot-bootloader} are supported. +@code{grub-efi-removable-bootloader}, @code{grub-efi-netboot-bootloader}, +@code{grub-efi-netboot-removable-bootloader}, @code{extlinux-bootloader} +and @code{u-boot-bootloader} are supported. @cindex ARM, bootloaders @cindex AArch64, bootloaders @@ -37430,15 +38375,29 @@ modules. In particular, @code{(gnu bootloader u-boot)} contains definitions of bootloaders for a wide range of ARM and AArch64 systems, using the @uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}. +@vindex grub-bootloader +@code{grub-bootloader} allows you to boot in particular Intel-based machines +in ``legacy'' BIOS mode. + @vindex grub-efi-bootloader @code{grub-efi-bootloader} allows to boot on modern systems using the @dfn{Unified Extensible Firmware Interface} (UEFI). This is what you should use if the installation image contains a @file{/sys/firmware/efi} directory when you boot it on your system. -@vindex grub-bootloader -@code{grub-bootloader} allows you to boot in particular Intel-based machines -in ``legacy'' BIOS mode. +@vindex grub-efi-removable-bootloader +@code{grub-efi-removable-bootloader} allows you to boot your system from +removable media by writing the GRUB file to the UEFI-specification location of +@file{/EFI/BOOT/BOOTX64.efi} of the boot directory, usually @file{/boot/efi}. +This is also useful for some UEFI firmwares that ``forget'' their configuration +from their non-volatile storage. Like @code{grub-efi-bootloader}, this can only +be used if the @file{/sys/firmware/efi} directory is available. + +@quotation Note +This @emph{will} overwrite the GRUB file from any other operating systems that +also place their GRUB file in the UEFI-specification location; making them +unbootable. +@end quotation @vindex grub-efi-netboot-bootloader @code{grub-efi-netboot-bootloader} allows you to boot your system over network @@ -37447,9 +38406,10 @@ build a diskless Guix system. 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. +Configuration, @code{targets}}) below the sub-directory @file{efi/Guix}, 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 during installation. 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 @@ -37478,25 +38438,34 @@ 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}. +directory for 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 store link exposes the whole store through TFTP@. Both points need to be -considered carefully for security aspects. +considered carefully for security aspects. It is advised to disable any TFTP +write access! + +Please note, that this bootloader will not modify the ‘UEFI Boot Manager’ of +the system. Beside the @code{grub-efi-netboot-bootloader}, the already mentioned TFTP and NFS servers, you also need a properly configured DHCP server to make the booting over netboot possible. For all this we can currently only recommend you to look for instructions about @acronym{PXE, Preboot eXecution Environment}. -@vindex grub-efi-removable-bootloader -@code{grub-efi-removable-bootloader} allows you to boot your system from -removable media by writing the GRUB file to the UEFI-specification location of -@file{/EFI/BOOT/BOOTX64.efi} of the boot directory, usually @file{/boot/efi}. -This is also useful for some UEFI firmwares that ``forget'' their configuration -from their non-volatile storage. Like @code{grub-efi-bootloader}, this can only -be used if the @file{/sys/firmware/efi} directory is available. +If a local EFI System Partition (ESP) or a similar partition with a FAT +file system is mounted in @code{targets}, then symlinks cannot be +created. In this case everything will be prepared for booting from +local storage, matching the behavior of @code{grub-efi-bootloader}, with +the difference that all GRUB binaries are copied to @code{targets}, +necessary for booting over the network. + +@vindex grub-efi-netboot-removable-bootloader +@code{grub-efi-netboot-removable-bootloader} is identical to +@code{grub-efi-netboot-bootloader} with the exception that the +sub-directory @file{efi/boot} will be used instead of @file{efi/Guix} to +comply with the UEFI specification for removable media. @quotation Note This @emph{will} overwrite the GRUB file from any other operating systems that @@ -37733,8 +38702,9 @@ like @end lisp @node Invoking guix system -@section Invoking @code{guix system} +@section Invoking @command{guix system} +@cindex @command{guix system} Once you have written an operating system declaration as seen in the previous section, it can be @dfn{instantiated} using the @command{guix system} command. The synopsis is: @@ -38379,8 +39349,9 @@ Again, the default output format is Dot/Graphviz, but you can pass @end table @node Invoking guix deploy -@section Invoking @code{guix deploy} +@section Invoking @command{guix deploy} +@cindex @command{guix deploy} We've already seen @code{operating-system} declarations used to manage a machine's configuration locally. Suppose you need to configure multiple machines, though---perhaps you're managing a service on the web that's @@ -38651,7 +39622,7 @@ $ qemu-system-x86_64 \ -nic user,model=virtio-net-pci \ -enable-kvm -m 2048 \ -device virtio-blk,drive=myhd \ - -drive if=none,file=/tmp/qemu-image,id=myhd + -drive if=none,file=guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2,id=myhd @end example Here is what each of these options means: @@ -38687,8 +39658,9 @@ better performance than if it were emulating a complete disk drive. See the QEMU and KVM documentation for more info. @item -drive if=none,file=/tmp/qemu-image,id=myhd -Use our QCOW image, the @file{/tmp/qemu-image} file, as the backing -store of the ``myhd'' drive. +Use our QCOW image, the +@file{guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2} file, as +the backing store of the ``myhd'' drive. @end table The default @command{run-vm.sh} script that is returned by an invocation of @@ -38917,11 +39889,10 @@ The service type for an @emph{extensible} service looks like this: (compose concatenate) ;concatenate the list of rules (extend (lambda (config rules) - (match config - (($ <udev-configuration> udev initial-rules) - (udev-configuration - (udev udev) ;the udev package to use - (rules (append initial-rules rules))))))))) + (udev-configuration + (inherit config) + (rules (append (udev-configuration-rules config) + rules))))))) @end lisp This is the service type for the @@ -39175,17 +40146,17 @@ type @var{target-type}; return the root service adjusted accordingly. Lastly, the @code{(gnu services)} module also defines several essential service types, some of which are listed below. -@defvr {Scheme Variable} system-service-type +@defvar system-service-type This is the root of the service graph. It produces the system directory as returned by the @command{guix system build} command. -@end defvr +@end defvar -@defvr {Scheme Variable} boot-service-type +@defvar boot-service-type The type of the ``boot service'', which produces the @dfn{boot script}. The boot script is what the initial RAM disk runs when booting. -@end defvr +@end defvar -@defvr {Scheme Variable} etc-service-type +@defvar etc-service-type The type of the @file{/etc} service. This service is used to create files under @file{/etc} and can be extended by passing it name/file tuples such as: @@ -39196,23 +40167,23 @@ passing it name/file tuples such as: In this example, the effect would be to add an @file{/etc/issue} file pointing to the given file. -@end defvr +@end defvar -@defvr {Scheme Variable} setuid-program-service-type +@defvar setuid-program-service-type Type for the ``setuid-program service''. This service collects lists of executable file names, passed as gexps, and adds them to the set of setuid and setgid programs on the system (@pxref{Setuid Programs}). -@end defvr +@end defvar -@defvr {Scheme Variable} profile-service-type +@defvar profile-service-type Type of the service that populates the @dfn{system profile}---i.e., the programs under @file{/run/current-system/profile}. Other services can extend it by passing it lists of packages to add to the system profile. -@end defvr +@end defvar @cindex provenance tracking, of the operating system @anchor{provenance-service-type} -@defvr {Scheme Variable} provenance-service-type +@defvar provenance-service-type This is the type of the service that records @dfn{provenance meta-data} in the system itself. It creates several files under @file{/run/current-system}: @@ -39258,9 +40229,9 @@ comparison less trivial. This service is automatically added to your operating system configuration when you use @command{guix system reconfigure}, @command{guix system init}, or @command{guix deploy}. -@end defvr +@end defvar -@defvr {Scheme Variable} linux-loadable-module-service-type +@defvar linux-loadable-module-service-type Type of the service that collects lists of packages containing kernel-loadable modules, and adds them to the set of kernel-loadable modules. @@ -39277,7 +40248,7 @@ such as below: This does not actually load modules at bootup, only adds it to the kernel profile so that it @emph{can} be loaded by other means. -@end defvr +@end defvar @node Shepherd Services @subsection Shepherd Services @@ -39452,14 +40423,47 @@ This, as you can see, is a fairly sophisticated way to say hello. info on actions. @end deftp -@defvr {Scheme Variable} shepherd-root-service-type +@cindex configuration file, of Shepherd services +@deffn {Scheme Procedure} shepherd-configuration-action +Return a @code{configuration} action to display @var{file}, which should +be the name of the service's configuration file. + +It can be useful to equip services with that action. For example, the +service for the Tor anonymous router (@pxref{Networking Services, +@code{tor-service-type}}) is defined roughly like this: + +@lisp +(let ((torrc (plain-file "torrc" @dots{}))) + (shepherd-service + (provision '(tor)) + (requirement '(user-processes loopback syslogd)) + + (start #~(make-forkexec-constructor + (list #$(file-append tor "/bin/tor") "-f" #$torrc) + #:user "tor" #:group "tor")) + (stop #~(make-kill-destructor)) + (actions (list (shepherd-configuration-action torrc))) + (documentation "Run the Tor anonymous network overlay."))) +@end lisp + +Thanks to this action, administrators can inspect the configuration file +passed to @command{tor} with this shell command: + +@example +cat $(herd configuration tor) +@end example + +This can come in as a handy debugging tool! +@end deffn + +@defvar shepherd-root-service-type The service type for the Shepherd ``root service''---i.e., PID@tie{}1. 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 +@end defvar @deftp {Data Type} shepherd-configuration This data type represents the Shepherd's configuration. @@ -39494,9 +40498,9 @@ system: (shepherd my-shepherd)))))) @end lisp -@defvr {Scheme Variable} %shepherd-root-service +@defvar %shepherd-root-service This service represents PID@tie{}1. -@end defvr +@end defvar @node Complex Configurations @subsection Complex Configurations @@ -40095,12 +41099,13 @@ 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. -* SSH: Secure Shell. Setting up the secure shell client. -* Desktop: Desktop Home Services. Services for graphical environments. -* Guix: Guix Home Services. Services for Guix. +* Shells: Shells Home Services. POSIX shells, Bash, Zsh. +* Mcron: Mcron Home Service. Scheduled User's Job Execution. +* Power Management: Power Management Home Services. Services for battery power. +* 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 @@ -40113,7 +41118,7 @@ user. @cindex environment variables -@defvr {Scheme Variable} home-environment-variables-service-type +@defvar 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 @@ -40128,13 +41133,15 @@ The easiest way to extend a service type, without defining a new service type is to use the @code{simple-service} helper from @code{(gnu services)}. +@findex literal-string @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))) + ("_JAVA_AWT_WM_NONREPARENTING" . #t) + ("LITERAL_VALUE" . ,(literal-string "$@{abc@}")))) @end lisp If you include such a service in you home environment definition, it @@ -40142,11 +41149,17 @@ 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 LESSHISTFILE="$XDG_CACHE_HOME/.lesshst" +export SHELL="/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh" export _JAVA_AWT_WM_NONREPARENTING +export LITERAL_VALUE='$@{abc@}' @end example +Notice that @code{literal-string} above lets us declare that a value is +to be interpreted as a @dfn{literal string}, meaning that ``special +characters'' such as the dollar sign will not be interpreted by the +shell. + @quotation Note Make sure that module @code{(gnu packages shells)} is imported with @code{use-modules} or any other way, this namespace contains the @@ -40166,9 +41179,9 @@ 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 +@end defvar -@defvr {Scheme Variable} home-profile-service-type +@defvar 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 @@ -40189,19 +41202,19 @@ 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 +@end defvar There are few more essential services, but users are not expected to extend them. -@defvr {Scheme Variable} home-service-type +@defvar 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 +@end defvar -@defvr {Scheme Variable} home-run-on-first-login-service-type +@defvar 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 @@ -40212,9 +41225,9 @@ users @emph{should not} use this service, in most cases it's better to extend @code{home-shepherd-service-type} with a Shepherd service (@pxref{Shepherd Services}), or extend the shell's startup file with the required command using the appropriate service type. -@end defvr +@end defvar -@defvr {Scheme Variable} home-files-service-type +@defvar home-files-service-type The service of this type allows to specify a list of files, which will go to @file{~/.guix-home/files}, usually this directory contains configuration files (to be more precise it contains symlinks to files in @@ -40238,9 +41251,9 @@ backs up already existing, but clashing configs and other things, is a part of essential home services (enabled by default), but it's possible to use alternative services to implement more advanced use cases like read-only home. Feel free to experiment and share your results. -@end defvr +@end defvar -@defvr {Scheme Variable} home-xdg-configuration-files-service-type +@defvar home-xdg-configuration-files-service-type The service is very similiar to @code{home-files-service-type} (and actually extends it), but used for defining files, which will go to @file{~/.guix-home/files/.config}, which will be symlinked to @@ -40254,15 +41267,15 @@ following format: ;; -> $XDG_CONFIG_DIR/sway/config (by symlink-manager) ("tmux/tmux.conf" ,(local-file "./tmux.conf"))) @end lisp -@end defvr +@end defvar -@defvr {Scheme Variable} home-activation-service-type +@defvar 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 +@end defvar -@defvr {Scheme Variable} home-symlink-manager-service-type +@defvar home-symlink-manager-service-type The service of this type generates a guile script, which will be executed during activation of home environment, and do a few following steps: @@ -40300,7 +41313,7 @@ If there is a clashing files on the way, they will be backed up. symlink-manager is a part of essential home services and is enabled and used by default. -@end defvr +@end defvar @node Shells Home Services @@ -40523,7 +41536,7 @@ for home services is that they have to be declared in a @code{home-environment} record instead of an @code{operating-system} record. -@defvr {Scheme Variable} home-mcron-service-type +@defvar 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. @@ -40532,19 +41545,109 @@ 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 +@end defvar @deftp {Data Type} home-mcron-configuration -Data type representing the configuration of mcron. +Available @code{home-mcron-configuration} fields are: +@c Auto-generated with (gnu home services mcron)'s +@c generate-documentation procedure. +@c %start of fragment @table @asis -@item @code{mcron} (default: @var{mcron}) +@item @code{mcron} (default: @code{mcron}) (type: file-like) The mcron package to use. -@item @code{jobs} +@item @code{jobs} (default: @code{()}) (type: list-of-gexps) 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}). +specifications,, mcron,GNU@tie{}mcron}). + +@item @code{log?} (default: @code{#t}) (type: boolean) +Log messages to standard output. + +@item @code{log-format} (default: @code{"~1@@*~a ~a: ~a~%"}) (type: string) +@code{(ice-9 format)} format string for log messages. The default value +produces messages like "@samp{@var{pid} @var{name}: @var{message}"} +(@pxref{Invoking mcron, Invoking,, mcron,GNU@tie{}mcron}). Each message +is also prefixed by a timestamp by GNU Shepherd. + +@end table +@end deftp +@c %end of fragment + +@node Power Management Home Services +@subsection Power Management Home Services + +@cindex power management +The @code{(gnu home services pm)} module provides home services +pertaining to battery power. + +@defvar home-batsignal-service-type +Service for @code{batsignal}, a program that monitors battery levels +and warns the user through desktop notifications when their battery +is getting low. You can also configure a command to be run when the +battery level passes a point deemed ``dangerous''. This service is +configured with the @code{home-batsignal-configuration} record. +@end defvar + +@deftp {Data Type} home-batsignal-configuration +Data type representing the configuration for batsignal. + +@table @asis +@item @code{warning-level} (default: @code{15}) +The battery level to send a warning message at. + +@item @code{warning-message} (default: @code{#f}) +The message to send as a notification when the battery level reaches +the @code{warning-level}. Setting to @code{#f} uses the default +message. + +@item @code{critical-level} (default: @code{5}) +The battery level to send a critical message at. + +@item @code{critical-message} (default: @code{#f}) +The message to send as a notification when the battery level reaches +the @code{critical-level}. Setting to @code{#f} uses the default +message. + +@item @code{danger-level} (default: @code{2}) +The battery level to run the @code{danger-command} at. + +@item @code{danger-command} (default: @code{#f}) +The command to run when the battery level reaches the @code{danger-level}. +Setting to @code{#f} disables running the command entirely. + +@item @code{full-level} (default: @code{#f}) +The battery level to send a full message at. Setting to @code{#f} +disables sending the full message entirely. + +@item @code{full-message} (default: @code{#f}) +The message to send as a notification when the battery level reaches +the @code{full-level}. Setting to @code{#f} uses the default message. + +@item @code{batteries} (default: @code{'()}) +The batteries to monitor. Setting to @code{'()} tries to find batteries +automatically. + +@item @code{poll-delay} (default: @code{60}) +The time in seconds to wait before checking the batteries again. + +@item @code{icon} (default: @code{#f}) +A file-like object to use as the icon for battery notifications. Setting +to @code{#f} disables notification icons entirely. + +@item @code{notifications?} (default: @code{#t}) +Whether to send any notifications. + +@item @code{notifications-expire?} (default: @code{#f}) +Whether notifications sent expire after a time. + +@item @code{notification-command} (default: @code{#f}) +Command to use to send messages. Setting to @code{#f} sends a notification +through @code{libnotify}. + +@item @code{ignore-missing?} (default: @code{#f}) +Whether to ignore missing battery errors. @end table @end deftp @@ -40559,7 +41662,7 @@ new services; Guix Home then takes care of starting the @code{shepherd} daemon for you when you log in, which in turns starts the services you asked for. -@defvr {Scheme Variable} home-shepherd-service-type +@defvar 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 @@ -40569,7 +41672,7 @@ 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{home-shepherd-configuration}, as described below. -@end defvr +@end defvar @deftp {Data Type} home-shepherd-configuration This data type represents the Shepherd's configuration. @@ -40601,7 +41704,7 @@ 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 +@defvar home-openssh-service-type This is the type of the service to set up the OpenSSH client. It takes care of several things: @@ -40645,7 +41748,7 @@ running @command{ssh chbouib} will automatically connect to The value associated with a @code{home-openssh-service-type} instance must be a @code{home-openssh-configuration} record, as describe below. -@end defvr +@end defvar @deftp {Data Type} home-openssh-configuration This is the datatype representing the OpenSSH client and server @@ -40770,7 +41873,7 @@ The @code{(gnu home services desktop)} module provides services that you may find useful on ``desktop'' systems running a graphical user environment such as Xorg. -@defvr {Scheme Variable} home-redshift-service-type +@defvar home-redshift-service-type This is the service type for @uref{https://github.com/jonls/redshift, Redshift}, a program that adjusts the display color temperature according to the time of day. Its associated value must be a @@ -40786,7 +41889,7 @@ longitude, might look like this: (latitude 35.81) ;northern hemisphere (longitude -0.80))) ;west of Greenwich @end lisp -@end defvr +@end defvar @deftp {Data Type} home-redshift-configuration Available @code{home-redshift-configuration} fields are: @@ -40841,13 +41944,27 @@ format. @end deftp +@defvar home-dbus-service-type +This is the service type for running a session-specific D-Bus, for +unprivileged applications that require D-Bus to be running. +@end defvar + +@deftp {Data Type} home-dbus-configuration +The configuration record for @code{home-dbus-service-type}. + +@table @asis +@item @code{dbus} (default: @code{dbus}) +The package providing the @code{/bin/dbus-daemon} command. +@end table +@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 +@defvar 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 @@ -40869,12 +41986,14 @@ A typical extension for adding a channel might look like this: (list (channel (name 'variant-packages) - (url "https://example.org/variant-packages.git"))) + (url "https://example.org/variant-packages.git")))) @end lisp -@end defvr +@end defvar @node Invoking guix home -@section Invoking @code{guix home} +@section Invoking @command{guix home} + +@cindex @command{guix home} Once you have written a home environment declaration (@pxref{Declaring the Home Environment,,,,}, it can be @dfn{instantiated} using the @@ -41340,52 +42459,52 @@ corresponding system, as a string. It can be The @code{(guix platforms @dots{})} modules export the following variables, each of which is bound to a @code{platform} record. -@defvr {Scheme Variable} armv7-linux +@defvar armv7-linux Platform targeting ARM v7 CPU running GNU/Linux. -@end defvr +@end defvar -@defvr {Scheme Variable} aarch64-linux +@defvar aarch64-linux Platform targeting ARM v8 CPU running GNU/Linux. -@end defvr +@end defvar -@defvr {Scheme Variable} mips64-linux +@defvar mips64-linux Platform targeting MIPS little-endian 64-bit CPU running GNU/Linux. -@end defvr +@end defvar -@defvr {Scheme Variable} powerpc-linux +@defvar powerpc-linux Platform targeting PowerPC big-endian 32-bit CPU running GNU/Linux. -@end defvr +@end defvar -@defvr {Scheme Variable} powerpc64le-linux +@defvar powerpc64le-linux Platform targeting PowerPC little-endian 64-bit CPU running GNU/Linux. -@end defvr +@end defvar -@defvr {Scheme Variable} riscv64-linux +@defvar riscv64-linux Platform targeting RISC-V 64-bit CPU running GNU/Linux. -@end defvr +@end defvar -@defvr {Scheme Variable} i686-linux +@defvar i686-linux Platform targeting x86 CPU running GNU/Linux. -@end defvr +@end defvar -@defvr {Scheme Variable} x86_64-linux +@defvar x86_64-linux Platform targeting x86 64-bit CPU running GNU/Linux. -@end defvr +@end defvar -@defvr {Scheme Variable} i686-mingw +@defvar i686-mingw Platform targeting x86 CPU running Windows, with run-time support from MinGW. -@end defvr +@end defvar -@defvr {Scheme Variable} x86_64-mingw +@defvar x86_64-mingw Platform targeting x86 64-bit CPU running Windows, with run-time support from MinGW. -@end defvr +@end defvar -@defvr {Scheme Variable} i586-gnu +@defvar i586-gnu Platform targeting x86 CPU running GNU/Hurd (also referred to as ``GNU''). -@end defvr +@end defvar @node System Images @chapter Creating System Images @@ -41665,24 +42784,24 @@ from them to simplify the @code{image} definition. The @code{(gnu system image)} module provides the following @code{image} definition variables. -@defvr {Scheme Variable} efi-disk-image +@defvar efi-disk-image A MBR disk-image composed of two partitions: a 64 bits ESP partition and a ROOT boot partition. This image can be used on most @code{x86_64} and @code{i686} machines, supporting BIOS or UEFI booting. -@end defvr +@end defvar -@defvr {Scheme Variable} efi32-disk-image +@defvar efi32-disk-image Same as @code{efi-disk-image} but with a 32 bits EFI partition. -@end defvr +@end defvar -@defvr {Scheme Variable} iso9660-image +@defvar iso9660-image An ISO-9660 image composed of a single bootable partition. This image can also be used on most @code{x86_64} and @code{i686} machines. -@end defvr +@end defvar -@defvr {Scheme Variable} docker-image +@defvar docker-image A Docker image that can be used to spawn a Docker container. -@end defvr +@end defvar Using the @code{efi-disk-image} we can simplify our previous @code{image} declaration this way: @@ -41753,74 +42872,74 @@ record. There are several @code{image-type} records provided by the @code{(gnu system image)} and the @code{(gnu system images @dots{})} modules. -@defvr {Scheme Variable} efi-raw-image-type +@defvar efi-raw-image-type Build an image based on the @code{efi-disk-image} image. -@end defvr +@end defvar -@defvr {Scheme Variable} efi32-raw-image-type +@defvar efi32-raw-image-type Build an image based on the @code{efi32-disk-image} image. -@end defvr +@end defvar -@defvr {Scheme Variable} qcow2-image-type +@defvar qcow2-image-type Build an image based on the @code{efi-disk-image} image but with the @code{compressed-qcow2} image format. -@end defvr +@end defvar -@defvr {Scheme Variable} iso-image-type +@defvar iso-image-type Build a compressed image based on the @code{iso9660-image} image. -@end defvr +@end defvar -@defvr {Scheme Variable} uncompressed-iso-image-type +@defvar uncompressed-iso-image-type Build an image based on the @code{iso9660-image} image but with the @code{compression?} field set to @code{#false}. -@end defvr +@end defvar -@defvr {Scheme Variable} docker-image-type +@defvar docker-image-type Build an image based on the @code{docker-image} image. -@end defvr +@end defvar -@defvr {Scheme Variable} raw-with-offset-image-type +@defvar raw-with-offset-image-type Build an MBR image with a single partition starting at a @code{1024KiB} offset. This is useful to leave some room to install a bootloader in the post-MBR gap. -@end defvr +@end defvar -@defvr {Scheme Variable} pinebook-pro-image-type +@defvar pinebook-pro-image-type Build an image that is targeting the Pinebook Pro machine. The MBR image contains a single partition starting at a @code{9MiB} offset. The @code{u-boot-pinebook-pro-rk3399-bootloader} bootloader will be installed in this gap. -@end defvr +@end defvar -@defvr {Scheme Variable} rock64-image-type +@defvar rock64-image-type Build an image that is targeting the Rock64 machine. The MBR image contains a single partition starting at a @code{16MiB} offset. The @code{u-boot-rock64-rk3328-bootloader} bootloader will be installed in this gap. -@end defvr +@end defvar -@defvr {Scheme Variable} novena-image-type +@defvar novena-image-type Build an image that is targeting the Novena machine. It has the same characteristics as @code{raw-with-offset-image-type}. -@end defvr +@end defvar -@defvr {Scheme Variable} pine64-image-type +@defvar pine64-image-type Build an image that is targeting the Pine64 machine. It has the same characteristics as @code{raw-with-offset-image-type}. -@end defvr +@end defvar -@defvr {Scheme Variable} hurd-image-type +@defvar hurd-image-type Build an image that is targeting a @code{i386} machine running the Hurd kernel. The MBR image contains a single ext2 partitions with specific @code{file-system-options} flags. -@end defvr +@end defvar -@defvr {Scheme Variable} hurd-qcow2-image-type +@defvar hurd-qcow2-image-type Build an image similar to the one built by the @code{hurd-image-type} but with the @code{format} set to @code{'compressed-qcow2}. -@end defvr +@end defvar -@defvr {Scheme Variable} wsl2-image-type +@defvar wsl2-image-type Build an image for the @acronym{WSL2, Windows Subsystem for Linux 2}. It can be imported by running: @@ -41829,7 +42948,7 @@ wsl --import Guix ./guix ./wsl2-image.tar.gz wsl -d Guix @end example -@end defvr +@end defvar So, if we get back to the @code{guix system image} command taking an @code{operating-system} declaration as argument. By default, the @@ -42435,7 +43554,7 @@ traditional bootstrap of the rest of the Guix System. Work is ongoing to to bring these bootstraps to the @code{arm-linux} and @code{aarch64-linux} architectures and to the Hurd. -If you are interested, join us on @samp{#bootstrappable} on the Freenode +If you are interested, join us on @samp{#bootstrappable} on the Libera.Chat IRC network or discuss on @email{bug-mes@@gnu.org} or @email{gash-devel@@nongnu.org}. diff --git a/doc/htmlxref.cnf b/doc/htmlxref.cnf index 21efbe2ddc..d8a7aa12c9 100644 --- a/doc/htmlxref.cnf +++ b/doc/htmlxref.cnf @@ -1,7 +1,7 @@ # htmlxref.cnf - reference file for free Texinfo manuals on the web. # Modified by Ludovic Courtès <ludo@gnu.org> for the GNU Guix manual. -htmlxrefversion=2022-08-04.13; # UTC +htmlxrefversion=2022-12-18.15; # UTC # Copyright 2010-2020, 2022 Free Software Foundation, Inc. # @@ -409,6 +409,8 @@ GUILE_GNOME = ${GS}/guile-gnome/docs guile-gtk node ${GS}/guile-gtk/docs/guile-gtk/ +guile-netlink mono https://git.lepiller.eu/guile-netlink/manual/manual.html + guile-rpc mono ${GS}/guile-rpc/manual/guile-rpc.html guile-rpc node ${GS}/guile-rpc/manual/html_node/ @@ -420,6 +422,8 @@ GUIX = ${GUIX_ROOT}/manual guix.es node ${GUIX}/es/html_node/ guix.fr mono ${GUIX}/fr/guix.fr.html guix.fr node ${GUIX}/fr/html_node/ + guix.pt_BR mono ${GUIX}/pt-br/guix.pt_BR.html + guix.pt_BR node ${GUIX}/pt-br/html_node/ guix.ru mono ${GUIX}/ru/guix.ru.html guix.ru node ${GUIX}/ru/html_node/ guix.zh_CN mono ${GUIX}/zh-cn/guix.zh_CN.html @@ -428,10 +432,12 @@ GUIX = ${GUIX_ROOT}/manual guix node ${GUIX}/en/html_node/ GUIX_COOKBOOK = ${GUIX_ROOT}/cookbook - guix-cookbook.de mono ${GUIX_COOKBOOK}/de/guix-cookbook.html + guix-cookbook.de mono ${GUIX_COOKBOOK}/de/guix-cookbook.de.html guix-cookbook.de node ${GUIX_COOKBOOK}/de/html_node/ - guix-cookbook.fr mono ${GUIX_COOKBOOK}/fr/guix-cookbook.html + guix-cookbook.fr mono ${GUIX_COOKBOOK}/fr/guix-cookbook.fr.html guix-cookbook.fr node ${GUIX_COOKBOOK}/fr/html_node/ + guix-cookbook.sk mono ${GUIX_COOKBOOK}/sk/guix-cookbook.sk.html + guix-cookbook.sk node ${GUIX_COOKBOOK}/sk/html_node/ guix-cookbook mono ${GUIX_COOKBOOK}/en/guix-cookbook.html guix-cookbook node ${GUIX_COOKBOOK}/en/html_node/ diff --git a/doc/local.mk b/doc/local.mk index 445be17027..89285b9f35 100644 --- a/doc/local.mk +++ b/doc/local.mk @@ -179,19 +179,31 @@ sub_commands_mans = \ $(srcdir)/%D%/guix-archive.1 \ $(srcdir)/%D%/guix-build.1 \ $(srcdir)/%D%/guix-challenge.1 \ + $(srcdir)/%D%/guix-container.1 \ + $(srcdir)/%D%/guix-copy.1 \ $(srcdir)/%D%/guix-deploy.1 \ + $(srcdir)/%D%/guix-describe.1 \ $(srcdir)/%D%/guix-download.1 \ $(srcdir)/%D%/guix-edit.1 \ $(srcdir)/%D%/guix-environment.1 \ $(srcdir)/%D%/guix-gc.1 \ + $(srcdir)/%D%/guix-git.1 \ + $(srcdir)/%D%/guix-graph.1 \ $(srcdir)/%D%/guix-hash.1 \ + $(srcdir)/%D%/guix-home.1 \ $(srcdir)/%D%/guix-import.1 \ $(srcdir)/%D%/guix-lint.1 \ + $(srcdir)/%D%/guix-offload.1 \ + $(srcdir)/%D%/guix-pack.1 \ $(srcdir)/%D%/guix-package.1 \ + $(srcdir)/%D%/guix-processes.1 \ $(srcdir)/%D%/guix-publish.1 \ $(srcdir)/%D%/guix-pull.1 \ $(srcdir)/%D%/guix-refresh.1 \ + $(srcdir)/%D%/guix-repl.1 \ + $(srcdir)/%D%/guix-shell.1 \ $(srcdir)/%D%/guix-size.1 \ + $(srcdir)/%D%/guix-style.1 \ $(srcdir)/%D%/guix-system.1 \ $(srcdir)/%D%/guix-time-machine.1 \ $(srcdir)/%D%/guix-weather.1 |