doc: Add “Getting Started with the System” section.
* 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
This commit is contained in:
Ludovic Courtès
parent
efdaa885b0
commit
60c9a339df
320
doc/guix.texi
320
doc/guix.texi
|
|
@ -358,6 +358,7 @@ Foreign Architectures
|
|||
|
||||
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 @@ unless your configuration specifies otherwise
|
|||
@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 @@ sudo guix system reconfigure /etc/config.scm
|
|||
@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 @@ sudo guix system reconfigure /etc/config.scm
|
|||
@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 @@ out to have a serious bug, users may roll back to the previous instance
|
|||
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 @@ instantiated. Then we show how this mechanism can be extended, for
|
|||
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 @@ instance to support new system services.
|
|||
* 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 @@ provided by default looks like this:
|
|||
@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 @@ Others, such as @code{packages} and @code{services}, can be omitted, in
|
|||
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 @@ Alternatively, the @code{modify-services} macro can be used:
|
|||
|
||||
@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 @@ fact, you must avoid that since that would not only void your warranty
|
|||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue