* [bug#69302] [PATCH 0/2] New "Getting Started" section for Guix System @ 2024-02-21 14:58 Ludovic Courtès 2024-02-21 16:47 ` [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section Ludovic Courtès 2024-02-21 16:47 ` [bug#69302] [PATCH 2/2] doc: Add “Inspecting Services” section Ludovic Courtès 0 siblings, 2 replies; 19+ messages in thread From: Ludovic Courtès @ 2024-02-21 14:58 UTC (permalink / raw) To: 69302; +Cc: Ludovic Courtès Hello Guix! It was recently brought to my attention (by an unsatisfied family member, so I couldn’t ignore it) that the documentation didn’t really tell you how to get started with Guix System: the main entry point was the “Using the Configuration System” section, which dives straight into the details of what to put in the config file, with page-long examples. Only at the bottom did it finally mention ‘guix system reconfigure’. These patches aim to improve on that: the new “Getting Started” section tries to give an overview of what it’s like to manage a Guix System machine. The goal is the same as for the other “Getting Started” section: to have something relatively short, with command blocks and links to the relevant sections to learn more. The second patch adds a subsection showing three ways to inspect a system configuration. Feedback welcome! Ludo’. Ludovic Courtès (2): doc: Add “Getting Started with the System” section. doc: Add “Inspecting Services” section. doc/guix.texi | 365 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 289 insertions(+), 76 deletions(-) base-commit: ffcce77ec488e3c89401ad77fafa65fcd9e9f5be -- 2.41.0 ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section. 2024-02-21 14:58 [bug#69302] [PATCH 0/2] New "Getting Started" section for Guix System Ludovic Courtès @ 2024-02-21 16:47 ` Ludovic Courtès 2024-02-22 15:57 ` Oleg Pykhalov 2024-02-22 19:09 ` [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section pelzflorian (Florian Pelz) 2024-02-21 16:47 ` [bug#69302] [PATCH 2/2] doc: Add “Inspecting Services” section Ludovic Courtès 1 sibling, 2 replies; 19+ messages in thread From: Ludovic Courtès @ 2024-02-21 16:47 UTC (permalink / raw) To: 69302; +Cc: Ludovic Courtès * 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 <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>. -@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 <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>. +@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 -- 2.41.0 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section. 2024-02-21 16:47 ` [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section Ludovic Courtès @ 2024-02-22 15:57 ` Oleg Pykhalov 2024-02-24 11:26 ` Ludovic Courtès 2024-02-22 19:09 ` [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section pelzflorian (Florian Pelz) 1 sibling, 1 reply; 19+ messages in thread From: Oleg Pykhalov @ 2024-02-22 15:57 UTC (permalink / raw) To: Ludovic Courtès; +Cc: 69302 [-- Attachment #1: Type: text/plain, Size: 1285 bytes --] Hello Ludovic, Ludovic Courtès <ludo@gnu.org> writes: […] > +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. What are your thoughts on the description of the 'file-systems' and 'bootloader' fields? Should users not rely on them during this test? Additionally, static networking configuration will not function correctly in the generated '/gnu/store/...-run-vm.sh' script unless specific flags are provided. Regards, Oleg. [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 861 bytes --] ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section. 2024-02-22 15:57 ` Oleg Pykhalov @ 2024-02-24 11:26 ` Ludovic Courtès 2024-02-24 22:24 ` Oleg Pykhalov 0 siblings, 1 reply; 19+ messages in thread From: Ludovic Courtès @ 2024-02-24 11:26 UTC (permalink / raw) To: Oleg Pykhalov; +Cc: 69302 Hi Oleg, Oleg Pykhalov <go.wigust@gmail.com> skribis: >> +@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. > > What are your thoughts on the description of the 'file-systems' and > 'bootloader' fields? Should users not rely on them during this test? These fields have no effect when using ‘guix system vm’. Did you mean that this should be clarified? > Additionally, static networking configuration will not function > correctly in the generated '/gnu/store/...-run-vm.sh' script unless > specific flags are provided. Good point. I see several ways out of it: (1) change ‘virtualized-operating-system’ to replace ‘static-networking-service-type’ with ‘dhcp-client-service-type’, or (2) mention it in the doc, or (3) do nothing, assuming that people using static networking are already advanced users and not really the target audience of this section. Thoughts? Ludo’. ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section. 2024-02-24 11:26 ` Ludovic Courtès @ 2024-02-24 22:24 ` Oleg Pykhalov 2024-02-24 22:35 ` Ludovic Courtès 0 siblings, 1 reply; 19+ messages in thread From: Oleg Pykhalov @ 2024-02-24 22:24 UTC (permalink / raw) To: Ludovic Courtès; +Cc: 69302 [-- Attachment #1: Type: text/plain, Size: 1764 bytes --] Ludovic Courtès <ludo@gnu.org> writes: > Oleg Pykhalov <go.wigust@gmail.com> skribis: > >>> +@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. >> >> What are your thoughts on the description of the 'file-systems' and >> 'bootloader' fields? Should users not rely on them during this test? > > These fields have no effect when using ‘guix system vm’. Did you mean > that this should be clarified? Indeed, other fields lacking effects should also be clarified for better understanding. >> Additionally, static networking configuration will not function >> correctly in the generated '/gnu/store/...-run-vm.sh' script unless >> specific flags are provided. > > Good point. I see several ways out of it: (1) change > ‘virtualized-operating-system’ to replace > ‘static-networking-service-type’ with ‘dhcp-client-service-type’, or (2) > mention it in the doc, or (3) do nothing, assuming that people using > static networking are already advanced users and not really the target > audience of this section. > > Thoughts? I believe option (2) will be beneficial. Additionally, if you have experience using 'avahi' while running a guest virtual machine with '/gnu/store/...-run-vm.sh,' I would appreciate knowing if it operates similarly to the host system. My assumption is that the guest can discover .local hosts, but external hosts may not be able to find the guest virtual machine. Thanks, Oleg. [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 861 bytes --] ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section. 2024-02-24 22:24 ` Oleg Pykhalov @ 2024-02-24 22:35 ` Ludovic Courtès 2024-02-25 14:48 ` [bug#69302] [PATCH v2 0/2] New "Getting Started" section for Guix System Ludovic Courtès ` (2 more replies) 0 siblings, 3 replies; 19+ messages in thread From: Ludovic Courtès @ 2024-02-24 22:35 UTC (permalink / raw) To: Oleg Pykhalov; +Cc: 69302 Oleg Pykhalov <go.wigust@gmail.com> skribis: > Ludovic Courtès <ludo@gnu.org> writes: [...] >> These fields have no effect when using ‘guix system vm’. Did you mean >> that this should be clarified? > > Indeed, other fields lacking effects should also be clarified for better > understanding. OK, I’ll do that. >> Good point. I see several ways out of it: (1) change >> ‘virtualized-operating-system’ to replace >> ‘static-networking-service-type’ with ‘dhcp-client-service-type’, or (2) >> mention it in the doc, or (3) do nothing, assuming that people using >> static networking are already advanced users and not really the target >> audience of this section. >> >> Thoughts? > > I believe option (2) will be beneficial. OK. > Additionally, if you have experience using 'avahi' while running a > guest virtual machine with '/gnu/store/...-run-vm.sh,' I would > appreciate knowing if it operates similarly to the host system. My > assumption is that the guest can discover .local hosts, but external > hosts may not be able to find the guest virtual machine. It’s plausible, I never tried. Thanks, Ludo’. ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH v2 0/2] New "Getting Started" section for Guix System 2024-02-24 22:35 ` Ludovic Courtès @ 2024-02-25 14:48 ` Ludovic Courtès 2024-02-25 14:48 ` [bug#69302] [PATCH v2 1/2] doc: Add “Getting Started with the System” section Ludovic Courtès 2024-02-25 14:48 ` [bug#69302] [PATCH v2 2/2] doc: Add “Inspecting Services” section Ludovic Courtès 2 siblings, 0 replies; 19+ messages in thread From: Ludovic Courtès @ 2024-02-25 14:48 UTC (permalink / raw) To: 69302; +Cc: Oleg Pykhalov, Ludovic Courtès, pelzflorian (Florian Pelz) Hello, This new version addresses typos, wording problems, and omissions reported by Florian and Oleg. I also adjusted the commit log to read “Move” instead of “Remove” for bits that were moved from one place to another. Thoughts? Ludo’. Ludovic Courtès (2): doc: Add “Getting Started with the System” section. doc: Add “Inspecting Services” section. doc/guix.texi | 375 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 299 insertions(+), 76 deletions(-) base-commit: b386c11e7804e0b577411d930b60f1e0a4a0382c -- 2.41.0 ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH v2 1/2] doc: Add “Getting Started with the System” section. 2024-02-24 22:35 ` Ludovic Courtès 2024-02-25 14:48 ` [bug#69302] [PATCH v2 0/2] New "Getting Started" section for Guix System Ludovic Courtès @ 2024-02-25 14:48 ` Ludovic Courtès 2024-02-27 11:21 ` pelzflorian (Florian Pelz) 2024-02-25 14:48 ` [bug#69302] [PATCH v2 2/2] doc: Add “Inspecting Services” section Ludovic Courtès 2 siblings, 1 reply; 19+ messages in thread From: Ludovic Courtès @ 2024-02-25 14:48 UTC (permalink / raw) To: 69302; +Cc: Oleg Pykhalov, Ludovic Courtès, pelzflorian (Florian Pelz) * doc/guix.texi (Getting Started with the System): New node. (After System Installation): Refer to it. Move note about ‘sudo guix pull’ to the “Getting Started with the System”. (Getting Started): Refer to it. Move note about ‘guix system roll-back’ to “Getting Started with the System”. (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 | 320 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 244 insertions(+), 76 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 671cdab6f8..0634d5051e 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -358,6 +358,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. @@ -2879,8 +2880,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 @@ -2888,24 +2889,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 <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>. -@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! @@ -3159,22 +3146,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! @@ -3283,7 +3257,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 @@ -17101,6 +17075,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. @@ -17121,14 +17096,222 @@ 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 +@uref{https://git-scm.com/book/en/, Git repository}. +@end quotation + +The @emph{entire} configuration of the system---user accounts, system +services, timezone, locale settings---is declared in 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. + +@quotation Note +When using @command{guix system vm}, aspects tied to your hardware such +as file systems and mapped devices are overridden because they cannot be +meaningfully tested in the VM@. Other aspects such as static network +configuration (@pxref{Networking Setup, +@code{static-networking-service-type}}) are @emph{not} overridden but +they may not work inside the VM@. +@end quotation + +@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 <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>. +@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 +administering 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 (@pxref{Invoking guix system}), as +we've seen before. 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 @@ -17136,8 +17319,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 @@ -17146,16 +17329,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 @@ -17350,16 +17538,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 @@ -17369,23 +17554,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 -- 2.41.0 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH v2 1/2] doc: Add “Getting Started with the System” section. 2024-02-25 14:48 ` [bug#69302] [PATCH v2 1/2] doc: Add “Getting Started with the System” section Ludovic Courtès @ 2024-02-27 11:21 ` pelzflorian (Florian Pelz) 2024-02-27 11:39 ` pelzflorian (Florian Pelz) 2024-02-28 21:48 ` Ludovic Courtès 0 siblings, 2 replies; 19+ messages in thread From: pelzflorian (Florian Pelz) @ 2024-02-27 11:21 UTC (permalink / raw) To: Ludovic Courtès; +Cc: Oleg Pykhalov, 69302 Hi Ludo. Ludovic Courtès <ludo@gnu.org> writes: > +@node Getting Started with the System > +@section Getting Started Is it intended that @node and @section have different names? I’m not sure if “info texinfo” means @node and @section should be the same. Is it confusing that we also have a chapter with the same name? @node Getting Started @chapter Getting Started Otherwise LGTM. Regards, Florian ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH v2 1/2] doc: Add “Getting Started with the System” section. 2024-02-27 11:21 ` pelzflorian (Florian Pelz) @ 2024-02-27 11:39 ` pelzflorian (Florian Pelz) 2024-02-28 21:48 ` Ludovic Courtès 1 sibling, 0 replies; 19+ messages in thread From: pelzflorian (Florian Pelz) @ 2024-02-27 11:39 UTC (permalink / raw) To: Ludovic Courtès; +Cc: Oleg Pykhalov, 69302 "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> writes: > I’m not sure if “info texinfo” means @node and @section should be the > same. P.S. @node and @section are not the same in the German translation. It appears to be fine, though perhaps confusing. Regards, Florian ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH v2 1/2] doc: Add “Getting Started with the System” section. 2024-02-27 11:21 ` pelzflorian (Florian Pelz) 2024-02-27 11:39 ` pelzflorian (Florian Pelz) @ 2024-02-28 21:48 ` Ludovic Courtès 2024-03-01 9:18 ` pelzflorian (Florian Pelz) 1 sibling, 1 reply; 19+ messages in thread From: Ludovic Courtès @ 2024-02-28 21:48 UTC (permalink / raw) To: pelzflorian (Florian Pelz); +Cc: Oleg Pykhalov, 69302 Hi! "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis: > Ludovic Courtès <ludo@gnu.org> writes: >> +@node Getting Started with the System >> +@section Getting Started > > Is it intended that @node and @section have different names? Yes. Node names must be unique within a single Info file; section names don’t have to. In this case, I think it’s enough to call it “Getting Started” because it’s in the “System” chapter, but we need to disambiguate the node name. Hope that makes sense! Ludo’. ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH v2 1/2] doc: Add “Getting Started with the System” section. 2024-02-28 21:48 ` Ludovic Courtès @ 2024-03-01 9:18 ` pelzflorian (Florian Pelz) 2024-03-02 16:28 ` bug#69302: " Ludovic Courtès 0 siblings, 1 reply; 19+ messages in thread From: pelzflorian (Florian Pelz) @ 2024-03-01 9:18 UTC (permalink / raw) To: Ludovic Courtès; +Cc: Oleg Pykhalov, 69302 Ludovic Courtès <ludo@gnu.org> writes: > In this case, I think it’s enough to call it “Getting Started” because > it’s in the “System” chapter, but we need to disambiguate the node name. With your patch, we’d have URLs: https://guix.gnu.org/manual/en/html_node/Getting-Started.html https://guix.gnu.org/manual/en/html_node/Getting-Started-with-the-System.html Even though the titles are “4 Getting Started” vs. a smaller “11.1 Getting Started”. There is no confusion. Yes, LGTM. Regards, Florian ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#69302: [PATCH v2 1/2] doc: Add “Getting Started with the System” section. 2024-03-01 9:18 ` pelzflorian (Florian Pelz) @ 2024-03-02 16:28 ` Ludovic Courtès 0 siblings, 0 replies; 19+ messages in thread From: Ludovic Courtès @ 2024-03-02 16:28 UTC (permalink / raw) To: pelzflorian (Florian Pelz); +Cc: Oleg Pykhalov, 69302-done Hi, "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis: > Ludovic Courtès <ludo@gnu.org> writes: >> In this case, I think it’s enough to call it “Getting Started” because >> it’s in the “System” chapter, but we need to disambiguate the node name. > > With your patch, we’d have URLs: > > https://guix.gnu.org/manual/en/html_node/Getting-Started.html > > https://guix.gnu.org/manual/en/html_node/Getting-Started-with-the-System.html > > Even though the titles are “4 Getting Started” vs. a smaller “11.1 > Getting Started”. > > There is no confusion. Yes, LGTM. I fixed the typo you pointed out and pushed as edde7ee1bcb098663038014190e79578ed0d99db. Thanks! Ludo’. ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH v2 2/2] doc: Add “Inspecting Services” section. 2024-02-24 22:35 ` Ludovic Courtès 2024-02-25 14:48 ` [bug#69302] [PATCH v2 0/2] New "Getting Started" section for Guix System Ludovic Courtès 2024-02-25 14:48 ` [bug#69302] [PATCH v2 1/2] doc: Add “Getting Started with the System” section Ludovic Courtès @ 2024-02-25 14:48 ` Ludovic Courtès 2024-02-27 11:54 ` pelzflorian (Florian Pelz) 2 siblings, 1 reply; 19+ messages in thread From: Ludovic Courtès @ 2024-02-25 14:48 UTC (permalink / raw) To: 69302; +Cc: Oleg Pykhalov, Ludovic Courtès, pelzflorian (Florian Pelz) * 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 0634d5051e..3e5514cf45 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -17536,6 +17536,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{sudo 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 = (#<service-type localed cabba93> + @dots{}) +@end example + +@xref{Service Reference}, to learn about the Scheme interface to +manipulate and inspect services. + @unnumberedsubsec Instantiating the System @cindex system instantiation -- 2.41.0 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH v2 2/2] doc: Add “Inspecting Services” section. 2024-02-25 14:48 ` [bug#69302] [PATCH v2 2/2] doc: Add “Inspecting Services” section Ludovic Courtès @ 2024-02-27 11:54 ` pelzflorian (Florian Pelz) 0 siblings, 0 replies; 19+ messages in thread From: pelzflorian (Florian Pelz) @ 2024-02-27 11:54 UTC (permalink / raw) To: Ludovic Courtès; +Cc: Oleg Pykhalov, 69302 One typo you have not addressed yet: > +@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. is not as you expected Otherwise LGTM. Regards, Florian ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section. 2024-02-21 16:47 ` [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section Ludovic Courtès 2024-02-22 15:57 ` Oleg Pykhalov @ 2024-02-22 19:09 ` pelzflorian (Florian Pelz) 2024-02-24 11:30 ` Ludovic Courtès 1 sibling, 1 reply; 19+ messages in thread From: pelzflorian (Florian Pelz) @ 2024-02-22 19:09 UTC (permalink / raw) To: Ludovic Courtès; +Cc: 69302 To: Ludovic Courtès <ludo@gnu.org> Cc: 69302@debbugs.gnu.org Subject: Re: [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section. From: "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> Gcc: nnfolder+archive:sent.2024-02 --text follows this line-- This rewrite makes Guix System more approachable. Thank you for the tip with “guix style -f”! Ludovic Courtès <ludo@gnu.org> writes: > * doc/guix.texi (Getting Started with the System): New node. > (After System Installation): Refer to it. Remove note about ‘sudo guix > pull’. I was alarmed that you remove the note about sudo, but indeed you just moved it and not removed. > (Getting Started): Refer to it. Remove note about ‘guix system roll-back’. As above. > +@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 Could you add a reference @uref{https://git-scm.com/book/en/, Git} like we do in the “Invoking guix pull” section? > +The @emph{entire} configuration of the system---user accounts, system > +services, timezone, locale settings---is declared this file, which > +follows this template: is declared *in* this file > @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 “administering” seems more correct than “administrating”. I’m not a native English speaker though. > 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}). […] Could you move the (@pxref{Invoking guix system}) before the “, as we've seen before”? Otherwise it appears as if “before” refers to “Invoking guix system”. Regards, Florian ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section. 2024-02-22 19:09 ` [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section pelzflorian (Florian Pelz) @ 2024-02-24 11:30 ` Ludovic Courtès 0 siblings, 0 replies; 19+ messages in thread From: Ludovic Courtès @ 2024-02-24 11:30 UTC (permalink / raw) To: pelzflorian (Florian Pelz); +Cc: 69302 Hi! "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis: > This rewrite makes Guix System more approachable. Thank you for the tip > with “guix style -f”! :-) > Ludovic Courtès <ludo@gnu.org> writes: >> * doc/guix.texi (Getting Started with the System): New node. >> (After System Installation): Refer to it. Remove note about ‘sudo guix >> pull’. > > I was alarmed that you remove the note about sudo, but indeed you just > moved it and not removed. > >> (Getting Started): Refer to it. Remove note about ‘guix system roll-back’. > > As above. Right, I’ll clarify that in the commit log. > Could you add a reference @uref{https://git-scm.com/book/en/, Git} like > we do in the “Invoking guix pull” section? Sure, will do. >> +The previous section showed the overall workflow you would follow when >> +administrating a Guix System machine (@pxref{Getting Started with the > > “administering” seems more correct than “administrating”. I’m not a > native English speaker though. Probably, I’m always hesitant. >> 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}). […] > > Could you move the (@pxref{Invoking guix system}) before the “, as we've > seen before”? Otherwise it appears as if “before” refers to “Invoking > guix system”. I like to avoid parenthetical expressions in the middle of a sentence, as it breaks the flow, but in this case you’re right that it makes the text ambiguous. I’ll change it. Thanks! Ludo’. ^ permalink raw reply [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH 2/2] doc: Add “Inspecting Services” section. 2024-02-21 14:58 [bug#69302] [PATCH 0/2] New "Getting Started" section for Guix System Ludovic Courtès 2024-02-21 16:47 ` [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section Ludovic Courtès @ 2024-02-21 16:47 ` Ludovic Courtès 2024-02-22 17:56 ` pelzflorian (Florian Pelz) 1 sibling, 1 reply; 19+ messages in thread From: Ludovic Courtès @ 2024-02-21 16:47 UTC (permalink / raw) To: 69302; +Cc: Ludovic Courtès * 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 = (#<service-type localed cabba93> + @dots{}) +@end example + +@xref{Service Reference}, to learn about the Scheme interface to +manipulate and inspect services. + @unnumberedsubsec Instantiating the System @cindex system instantiation -- 2.41.0 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* [bug#69302] [PATCH 2/2] doc: Add “Inspecting Services” section. 2024-02-21 16:47 ` [bug#69302] [PATCH 2/2] doc: Add “Inspecting Services” section Ludovic Courtès @ 2024-02-22 17:56 ` pelzflorian (Florian Pelz) 0 siblings, 0 replies; 19+ messages in thread From: pelzflorian (Florian Pelz) @ 2024-02-22 17:56 UTC (permalink / raw) To: Ludovic Courtès; +Cc: 69302 Hello Ludo. Ludovic Courtès <ludo@gnu.org> writes: > * doc/guix.texi (Inspecting Services): New subsection. I like this showcasing of useful features. However, typo: > +@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. is not as you expected Also: > +@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 Perhaps @command{sudo herd status} to avoid confusion? Regards, Florian ^ permalink raw reply [flat|nested] 19+ messages in thread
end of thread, other threads:[~2024-03-02 16:28 UTC | newest] Thread overview: 19+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2024-02-21 14:58 [bug#69302] [PATCH 0/2] New "Getting Started" section for Guix System Ludovic Courtès 2024-02-21 16:47 ` [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section Ludovic Courtès 2024-02-22 15:57 ` Oleg Pykhalov 2024-02-24 11:26 ` Ludovic Courtès 2024-02-24 22:24 ` Oleg Pykhalov 2024-02-24 22:35 ` Ludovic Courtès 2024-02-25 14:48 ` [bug#69302] [PATCH v2 0/2] New "Getting Started" section for Guix System Ludovic Courtès 2024-02-25 14:48 ` [bug#69302] [PATCH v2 1/2] doc: Add “Getting Started with the System” section Ludovic Courtès 2024-02-27 11:21 ` pelzflorian (Florian Pelz) 2024-02-27 11:39 ` pelzflorian (Florian Pelz) 2024-02-28 21:48 ` Ludovic Courtès 2024-03-01 9:18 ` pelzflorian (Florian Pelz) 2024-03-02 16:28 ` bug#69302: " Ludovic Courtès 2024-02-25 14:48 ` [bug#69302] [PATCH v2 2/2] doc: Add “Inspecting Services” section Ludovic Courtès 2024-02-27 11:54 ` pelzflorian (Florian Pelz) 2024-02-22 19:09 ` [bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section pelzflorian (Florian Pelz) 2024-02-24 11:30 ` Ludovic Courtès 2024-02-21 16:47 ` [bug#69302] [PATCH 2/2] doc: Add “Inspecting Services” section Ludovic Courtès 2024-02-22 17:56 ` pelzflorian (Florian Pelz)
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/guix.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.