From patchwork Wed Feb 21 16:47:29 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Ludovic_Court=C3=A8s?= X-Patchwork-Id: 60875 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 0FA4727BBEA; Wed, 21 Feb 2024 17:11:28 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-3.7 required=5.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI,RCVD_IN_MSPIKE_H2,SPF_HELO_PASS, URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id CFDA427BBE9 for ; Wed, 21 Feb 2024 17:11:25 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rcq7H-0003cE-TD; Wed, 21 Feb 2024 12:10:44 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rcq7F-0003YB-Ac for guix-patches@gnu.org; Wed, 21 Feb 2024 12:10:41 -0500 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rcq7E-0006Bh-WC for guix-patches@gnu.org; Wed, 21 Feb 2024 12:10:41 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rcq7b-000896-9n for guix-patches@gnu.org; Wed, 21 Feb 2024 12:11:03 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#69302] [PATCH 1/2] doc: Add =?utf-8?q?=E2=80=9CGetting?= Started with the =?utf-8?b?U3lzdGVt4oCd?= section. Resent-From: Ludovic =?utf-8?q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Wed, 21 Feb 2024 17:11:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 69302 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 69302@debbugs.gnu.org Cc: Ludovic =?utf-8?q?Court=C3=A8s?= Received: via spool by 69302-submit@debbugs.gnu.org id=B69302.170853541431131 (code B ref 69302); Wed, 21 Feb 2024 17:11:03 +0000 Received: (at 69302) by debbugs.gnu.org; 21 Feb 2024 17:10:14 +0000 Received: from localhost ([127.0.0.1]:55150 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rcq6m-00085s-RP for submit@debbugs.gnu.org; Wed, 21 Feb 2024 12:10:14 -0500 Received: from eggs.gnu.org ([209.51.188.92]:48230) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rcpta-0004ht-LZ for 69302@debbugs.gnu.org; Wed, 21 Feb 2024 11:56:36 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rcpl2-0008WJ-8r; Wed, 21 Feb 2024 11:47:44 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:References:In-Reply-To:Date:Subject:To: From; bh=0VE+GLGQiZjIyOElgjPyd9lMiY0EQd50IdkZvErbWEA=; b=mLDdzm7IZZPxZm2jsVS9 1RkV+io+sthY/mOQsef/TLrzKixr4NRrIqKt/tggGjn9VzAZ7z2Sx48fzUQ+n3GVQbA8306XdtAoW LCIFg9AVXwilD9G1KCFYqfW9H9i/MRoflqgrfCQrzRzihLiDt3x3dzeVTGBYEUusjcEp6AddOK6a+ zMVPDNvCvsQaZqSvG4Q0NaPaCHABiYxFanq9u89WccRo2jPvajNEEIsGg7oTV7D98pa9OaZ4Tp732 sFfZ6eNrkwJn4BqyPWNq26AGYbPLvrPerqERP7jh6adNRn8Avf2UMdcr4neySV7u03siF7NqUP+c9 eaPOkZP8IGI7Ew==; From: Ludovic =?utf-8?q?Court=C3=A8s?= Date: Wed, 21 Feb 2024 17:47:29 +0100 Message-ID: X-Mailer: git-send-email 2.41.0 In-Reply-To: References: MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches * doc/guix.texi (Getting Started with the System): New node. (After System Installation): Refer to it. Remove note about ‘sudo guix pull’. (Getting Started): Refer to it. Remove note about ‘guix system roll-back’. (Features): Refer to it. (Using the Configuration System): Adjust intro. Add “Troubleshooting” note that mentions ‘guix style -f’ for misplaced parens. (Instantiating the System): Simplify and cross-reference “Getting Started with the System”. Change-Id: Ie74f598450e8059a4579a016e2aeca2edd7696a7 --- doc/guix.texi | 310 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 234 insertions(+), 76 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 9966a8e697..e7f59c8bfd 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -357,6 +357,7 @@ Top System Configuration +* Getting Started with the System:: Your first steps. * Using the Configuration System:: Customizing your GNU system. * operating-system Reference:: Detail of operating-system declarations. * File Systems:: Configuring file system mounts. @@ -2875,8 +2876,8 @@ Proceeding with the Installation @node After System Installation @section After System Installation -Success, you've now booted into Guix System! From then on, you can update the -system whenever you want by running, say: +Success, you've now booted into Guix System! You can upgrade the system +whenever you want by running: @example guix pull @@ -2884,24 +2885,10 @@ After System Installation @end example @noindent -This builds a new system generation with the latest packages and services -(@pxref{Invoking guix system}). We recommend doing that regularly so that -your system includes the latest security updates (@pxref{Security Updates}). +This builds a new system @dfn{generation} with the latest packages and +services. -@c See . -@quotation Note -@cindex sudo vs. @command{guix pull} -Note that @command{sudo guix} runs your user's @command{guix} command and -@emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged. To -explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}. - -The difference matters here, because @command{guix pull} updates -the @command{guix} command and package definitions only for the user it is run -as. This means that if you choose to use @command{guix system reconfigure} in -root's login shell, you'll need to @command{guix pull} separately. -@end quotation - -Now, @pxref{Getting Started}, and +Now, @pxref{Getting Started with the System}, and join us on @code{#guix} on the Libera Chat IRC network or on @email{guix-devel@@gnu.org} to share your experience! @@ -3155,22 +3142,9 @@ Getting Started @end example Upon completion, the system runs the latest versions of its software -packages. When you eventually reboot, you'll notice a sub-menu in the -bootloader that reads ``Old system generations'': it's what allows you -to boot @emph{an older generation of your system}, should the latest -generation be ``broken'' or otherwise unsatisfying. Just like for -packages, you can always @emph{roll back} to a previous generation -@emph{of the whole system}: - -@example -sudo guix system roll-back -@end example - -There are many things you'll probably want to tweak on your system: -adding new user accounts, adding new system services, fiddling with the -configuration of those services, etc. The system configuration is -@emph{entirely} described in the @file{/etc/config.scm} file. -@xref{Using the Configuration System}, to learn how to change it. +packages. Just like for packages, you can always @emph{roll back} to a +previous generation @emph{of the whole system}. @xref{Getting Started +with the System}, to learn how to manage your system. Now you know enough to get started! @@ -3279,7 +3253,7 @@ Features of their profile, which was known to work well. Similarly, the global system configuration on Guix is subject to transactional upgrades and roll-back -(@pxref{Using the Configuration System}). +(@pxref{Getting Started with the System}). All packages in the package store may be @emph{garbage-collected}. Guix can determine which packages are still referenced by user @@ -17088,6 +17062,7 @@ System Configuration instance to support new system services. @menu +* Getting Started with the System:: Your first steps. * Using the Configuration System:: Customizing your GNU system. * operating-system Reference:: Detail of operating-system declarations. * File Systems:: Configuring file system mounts. @@ -17108,14 +17083,212 @@ System Configuration * Defining Services:: Adding new service definitions. @end menu +@node Getting Started with the System +@section Getting Started + +@cindex system configuration file +@cindex configuration file, of the system +You're reading this section probably because you have just installed +Guix System (@pxref{System Installation}) and would like to know where +to go from here. If you're already familiar with GNU/Linux system +administration, the way Guix System is configured is very different from +what you're used to: you won't install a system service by running +@command{guix install}, you won't configure services by modifying files +under @file{/etc}, and you won't create user accounts by invoking +@command{useradd}; instead, all these aspects are spelled out in a +@dfn{system configuration file}. + +The first step with Guix System is thus to write the @dfn{system +configuration file}; luckily, system installation already generated one +for you and stored it under @file{/etc/config.scm}. + +@quotation Note +You can store your system configuration file anywhere you like---it +doesn't have to be at @file{/etc/config.scm}. It's a good idea to keep +it under version control, for instance in a Git repository. +@end quotation + +The @emph{entire} configuration of the system---user accounts, system +services, timezone, locale settings---is declared this file, which +follows this template: + +@lisp +(use-modules (gnu)) +(use-package-modules @dots{}) +(use-service-modules @dots{}) + +(operating-system + (host-name @dots{}) + (timezone @dots{}) + (locale @dots{}) + (bootloader @dots{}) + (file-systems @dots{}) + (users @dots{}) + (packages @dots{}) + (services @dots{})) +@end lisp + +This configuration file is in fact a Scheme program; the first lines +pull in modules providing variables you might need in the rest of the +file---e.g., packages, services, etc. The @code{operating-system} form +declares the system configuration as a @dfn{record} with a number of +@dfn{fields}. @xref{Using the Configuration System}, to view complete +examples and learn what to put in there. + +The second step, once you have this configuration file, is to test it. +Of course, you can skip this step if you're feeling lucky---you choose! +To do that, pass your configuration file to @command{guix system vm} (no +need to be root, you can do that as a regular user): + +@example +guix system vm /etc/config.scm +@end example + +@noindent +This command returns the name of a shell script that starts a virtual +machine (VM) running the system @emph{as described in the configuration +file}: + +@example +/gnu/store/@dots{}-run-vm.sh +@end example + +@noindent +In this VM, you can log in as @code{root} with no password. That's a +good way to check that your configuration file is correct and that it +gives the expected result, without touching your system. @xref{Invoking +guix system}, for more information. + +@cindex system instantiation +@cindex reconfiguring the system +The third step, once you're happy with your configuration, is to +@dfn{instantiate} it---make this configuration effective on your system. +To do that, run: + +@example +sudo guix system reconfigure /etc/config.scm +@end example + +@cindex upgrading system services +@cindex system services, upgrading +@noindent +This operation is @dfn{transactional}: either it succeeds and you end up +with an upgraded system, or it fails and nothing has changed. Note that +it does @emph{not} restart system services that were already running. +Thus, to upgrade those services, you have to reboot or to explicitly +restart them; for example, to restart the secure shell (SSH) daemon, you +would run: + +@example +sudo herd restart sshd +@end example + +@quotation Note +System services are managed by the Shepherd (@pxref{Jump Start,,, +shepherd, The GNU Shepherd Manual}). The @code{herd} command lets you +inspect, start, and stop services. To view the status of services, run: + +@example +sudo herd status +@end example + +To view detailed information about a given service, add its name to the +command: + +@example +sudo herd status sshd +@end example + +@xref{Services}, for more information. +@end quotation + +@cindex provenance, of the system +The system records its @dfn{provenance}---the configuration file and +channels that were used to deploy it. You can view it like so: + +@example +guix system describe +@end example + +Additionally, @command{guix system reconfigure} preserves previous +system generations, which you can list: + +@example +guix system list-generations +@end example + +@noindent +@cindex roll back, for the system +Crucially, that means that you can always @emph{roll back} to an earlier +generation should something go wrong! When you eventually reboot, +you'll notice a sub-menu in the bootloader that reads ``Old system +generations'': it's what allows you to boot @emph{an older generation of +your system}, should the latest generation be ``broken'' or otherwise +unsatisfying. You can also ``permanently'' roll back, like so: + +@example +sudo guix system roll-back +@end example + +@noindent +Alternatively, you can use @command{guix system switch-generation} to +switch to a specific generation. + +Once in a while, you'll want to delete old generations that you do not +need anymore to allow @dfn{garbage collection} to free space +(@pxref{Invoking guix gc}). For example, to remove generations older +than 4 months, run: + +@example +sudo guix system delete-generations 4m +@end example + +From there on, anytime you want to change something in the system +configuration, be it adding a user account or changing parameters of a +service, you will first update your configuration file and then run +@command{guix system reconfigure} as shown above. +@cindex upgrade, of the system +Likewise, to @emph{upgrade} system software, you first fetch an +up-to-date Guix and then reconfigure your system with that new Guix: + +@example +guix pull +sudo guix system reconfigure /etc/config.scm +@end example + +@noindent +We recommend doing that regularly so that your system includes the +latest security updates (@pxref{Security Updates}). + +@c See . +@quotation Note +@cindex sudo vs. @command{guix pull} +@command{sudo guix} runs your user's @command{guix} command and +@emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged. + +The difference matters here, because @command{guix pull} updates +the @command{guix} command and package definitions only for the user it is run +as. This means that if you choose to use @command{guix system reconfigure} in +root's login shell, you'll need to @command{guix pull} separately. +@end quotation + +That's it! If you're getting starting with Guix entirely, +@pxref{Getting Started}. The next sections dive in more detail into the +crux of the matter: system configuration. + @node Using the Configuration System @section Using the Configuration System +The previous section showed the overall workflow you would follow when +administrating a Guix System machine (@pxref{Getting Started with the +System}). Let's now see in more detail what goes into the system +configuration file. + The operating system is configured by providing an @code{operating-system} declaration in a file that can then be passed to -the @command{guix system} command (@pxref{Invoking guix system}). A -simple setup, with the default Linux-Libre -kernel, initial RAM disk, and a couple of system services added to those +the @command{guix system} command, as we've seen before (@pxref{Invoking +guix system}). A simple setup, with the default Linux-Libre kernel, +initial RAM disk, and a couple of system services added to those provided by default looks like this: @findex operating-system @@ -17123,8 +17296,8 @@ Using the Configuration System @include os-config-bare-bones.texi @end lisp -The configuration is declarative and hopefully mostly self-describing. -It is actually code in the Scheme programming language; the whole +The configuration is declarative. +It is code in the Scheme programming language; the whole @code{(operating-system @dots{})} expression produces a @dfn{record} with a number of @dfn{fields}. Some of the fields defined @@ -17133,16 +17306,21 @@ Using the Configuration System which case they get a default value. @xref{operating-system Reference}, for details about all the available fields. -Below we discuss the effect of some of the most important fields, -and how to @dfn{instantiate} the operating system using -@command{guix system}. +Below we discuss the meaning of some of the most important fields. -@quotation Do not panic -@cindex Scheme programming language, getting started -Intimidated by the Scheme language or curious about it? The Cookbook -has a short section to get started that explains the fundamentals, which -you will find helpful when hacking your configuration. @xref{A Scheme -Crash Course,,, guix-cookbook, GNU Guix Cookbook}. +@quotation Troubleshooting +The configuration file is a Scheme program and you might get the syntax +or semantics wrong as you get started. Syntactic issues such as +misplaced parentheses can often be identified by reformatting your file: + +@example +guix style -f config.scm +@end example + +The Cookbook has a short section to get started with the Scheme +programming language that explains the fundamentals, which you will find +helpful when hacking your configuration. @xref{A Scheme Crash Course,,, +guix-cookbook, GNU Guix Cookbook}. @end quotation @unnumberedsubsec Bootloader @@ -17337,16 +17515,13 @@ Using the Configuration System @unnumberedsubsec Instantiating the System +@cindex system instantiation +@cindex reconfiguring the system Assuming the @code{operating-system} declaration -is stored in the @file{my-system-config.scm} -file, the @command{guix system reconfigure my-system-config.scm} command -instantiates that configuration, and makes it the default GRUB boot -entry (@pxref{Invoking guix system}). - -@quotation Note -We recommend that you keep this @file{my-system-config.scm} file safe -and under version control to easily track changes to your configuration. -@end quotation +is stored in the @file{config.scm} +file, the @command{sudo guix system reconfigure config.scm} command +instantiates that configuration, and makes it the default boot +entry. @xref{Getting Started with the System}, for an overview. The normal way to change the system configuration is by updating this file and re-running @command{guix system reconfigure}. One should never @@ -17356,23 +17531,6 @@ Using the Configuration System but also prevent you from rolling back to previous versions of your system, should you ever need to. -@cindex roll-back, of the operating system -Speaking of roll-back, each time you run @command{guix system -reconfigure}, a new @dfn{generation} of the system is created---without -modifying or deleting previous generations. Old system generations get -an entry in the bootloader boot menu, allowing you to boot them in case -something went wrong with the latest generation. Reassuring, no? The -@command{guix system list-generations} command lists the system -generations available on disk. It is also possible to roll back the -system via the commands @command{guix system roll-back} and -@command{guix system switch-generation}. - -Although the @command{guix system reconfigure} command will not modify -previous generations, you must take care when the current generation is not -the latest (e.g., after invoking @command{guix system roll-back}), since -the operation might overwrite a later generation (@pxref{Invoking guix -system}). - @unnumberedsubsec The Programming Interface At the Scheme level, the bulk of an @code{operating-system} declaration From patchwork Wed Feb 21 16:47:30 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: =?utf-8?q?Ludovic_Court=C3=A8s?= X-Patchwork-Id: 60874 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 3207F27BBE2; Wed, 21 Feb 2024 17:11:17 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-3.7 required=5.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI,RCVD_IN_MSPIKE_H2,SPF_HELO_PASS, URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id D47A027BBE9 for ; Wed, 21 Feb 2024 17:11:12 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rcq7G-0003Ye-TV; Wed, 21 Feb 2024 12:10:42 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rcq7E-0003Y2-T5 for guix-patches@gnu.org; Wed, 21 Feb 2024 12:10:40 -0500 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rcq7E-0006Bb-I0 for guix-patches@gnu.org; Wed, 21 Feb 2024 12:10:40 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rcq7a-00088y-R1 for guix-patches@gnu.org; Wed, 21 Feb 2024 12:11:02 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#69302] [PATCH 2/2] doc: Add =?utf-8?b?4oCcSW5zcGVjdGluZyBTZXJ2?= =?utf-8?b?aWNlc+KAnQ==?= section. Resent-From: Ludovic =?utf-8?q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Wed, 21 Feb 2024 17:11:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 69302 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 69302@debbugs.gnu.org Cc: Ludovic =?utf-8?q?Court=C3=A8s?= Received: via spool by 69302-submit@debbugs.gnu.org id=B69302.170853541231119 (code B ref 69302); Wed, 21 Feb 2024 17:11:02 +0000 Received: (at 69302) by debbugs.gnu.org; 21 Feb 2024 17:10:12 +0000 Received: from localhost ([127.0.0.1]:55147 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rcq6m-00085p-CC for submit@debbugs.gnu.org; Wed, 21 Feb 2024 12:10:12 -0500 Received: from eggs.gnu.org ([209.51.188.92]:48230) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rcptZ-0004ht-NI for 69302@debbugs.gnu.org; Wed, 21 Feb 2024 11:56:34 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rcpl3-0008WV-7k; Wed, 21 Feb 2024 11:47:45 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:References:In-Reply-To:Date:Subject:To: From; bh=ofQVT7g62sEJgTdJrwpeenupjuO0qtlaJfyIPf0BMTs=; b=AkDr4bVwNmiGcwmTsDZo BwidyGYdRZO+k2bkAQBovnXHrkbbAK6GschhBNyMluCVuHOlcnWgqR3quiWC9cQNfSXBvOSksn+wZ GhBHCSNprYBGNXeGjA8NKNghLS5qyFVsvNVq6cCr+5zYXIwL9LPlbDqYs9P2HMfJnH7w0RHzHFLls zoLhE9D783kKjqpx5Kvf66NirAQmbYEz1Frdn8uHIJtKUguL3/9bdWcPkqZ51EEonQj+HFfD6b/yr QSwyA9hh5kpKPm9HO6HydVDc45Q6bV2B+2aJyLPoHIWbd9q+hhJDk6OIX9Hr4ZcdlCHrSOwsWGW5M k2QrGHzDdbCq5A==; From: Ludovic =?utf-8?q?Court=C3=A8s?= Date: Wed, 21 Feb 2024 17:47:30 +0100 Message-ID: <29cc7ff49d15dda51a3c2eb091a4bf603d1f097b.1708527097.git.ludo@gnu.org> X-Mailer: git-send-email 2.41.0 In-Reply-To: References: MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches * doc/guix.texi (Inspecting Services): New subsection. Change-Id: I71378101de913a494e0d0e93cc76434c5a70b520 --- doc/guix.texi | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/doc/guix.texi b/doc/guix.texi index e7f59c8bfd..ea2629a768 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -17513,6 +17513,61 @@ Using the Configuration System (delete avahi-service-type)) @end lisp +@unnumberedsubsec Inspecting Services + +@cindex troubleshooting, for system services +@cindex inspecting system services +@cindex system services, inspecting +As you work on your system configuration, you might wonder why some +system service doesn't show up or why the system as not as you expected. +There are several ways to inspect and troubleshoot problems. + +@cindex dependency graph, of Shepherd services +First, you can inspect the dependency graph of Shepherd services like +so: + +@example +guix system shepherd-graph /etc/config.scm | \ + guix shell xdot -- xdot - +@end example + +This lets you visualize the Shepherd services as defined in +@file{/etc/config.scm}. Each box is a service as would be shown by +@command{herd status} on the running system, and each arrow denotes a +dependency (in the sense that if service @var{A} depends on @var{B}, +then @var{B} must be started before @var{A}). + +@cindex extension graph, of services +Not all ``services'' are Shepherd services though, since Guix System +uses a broader definition of the term (@pxref{Services}). To visualize +system services and their relations at a higher level, run: + +@example +guix system extension-graph /etc/config.scm | \ + guix shell xdot -- xdot - +@end example + +This lets you view the @dfn{service extension graph}: how services +``extend'' each other, for instance by contributing to their +configuration. @xref{Service Composition}, to understand the meaning of +this graph. + +Last, you may also find it useful to inspect your system configuration +at the REPL (@pxref{Using Guix Interactively}). Here is an example +session: + +@example +$ guix repl +scheme@@(guix-user)> ,use (gnu) +scheme@@(guix-user)> (define os (load "config.scm")) +scheme@@(guix-user)> ,pp (map service-kind (operating-system-services os)) +$1 = (# + @dots{}) +@end example + +@xref{Service Reference}, to learn about the Scheme interface to +manipulate and inspect services. + @unnumberedsubsec Instantiating the System @cindex system instantiation