Toggle diff (411 lines)
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
