11.1 Getting Started

You’re reading this section probably because you have just installed Guix System (see 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 guix install, you won’t configure services by modifying files under /etc, and you won’t create user accounts by invoking useradd; instead, all these aspects are spelled out in a system configuration file.

The first step with Guix System is thus to write the system configuration file; luckily, system installation already generated one for you and stored it under /etc/config.scm.

Note: You can store your system configuration file anywhere you like—it doesn’t have to be at /etc/config.scm. It’s a good idea to keep it under version control, for instance in a Git repository.

The entire configuration of the system—user accounts, system services, timezone, locale settings—is declared in this file, which follows this template:

(use-modules (gnu))
(use-package-modules …)
(use-service-modules …)

(operating-system
  (host-name …)
  (timezone …)
  (locale …)
  (bootloader …)
  (file-systems …)
  (users …)
  (packages …)
  (services …))

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 operating-system form declares the system configuration as a record with a number of fields. See 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 guix system vm (no need to be root, you can do that as a regular user):

guix system vm /etc/config.scm

This command returns the name of a shell script that starts a virtual machine (VM) running the system as described in the configuration file:

/gnu/store/…-run-vm.sh

In this VM, you can log in as 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. See Invoking guix system, for more information.

Note: When using 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 (see static-networking-service-type) are not overridden but they may not work inside the VM.

The third step, once you’re happy with your configuration, is to instantiate it—make this configuration effective on your system. To do that, run:

sudo guix system reconfigure /etc/config.scm

This operation is transactional: either it succeeds and you end up with an upgraded system, or it fails and nothing has changed. Note that it does 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:

sudo herd restart sshd

Note: System services are managed by the Shepherd (see Jump Start in The GNU Shepherd Manual). The herd command lets you inspect, start, and stop services. To view the status of services, run:

sudo herd status

To view detailed information about a given service, add its name to the command:

sudo herd status sshd

See Services, for more information.

The system records its provenance—the configuration file and channels that were used to deploy it. You can view it like so:

guix system describe

Additionally, guix system reconfigure preserves previous system generations, which you can list:

guix system list-generations

Crucially, that means that you can always 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 an older generation of your system, should the latest generation be “broken” or otherwise unsatisfying. You can also “permanently” roll back, like so:

sudo guix system roll-back

Alternatively, you can use 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 garbage collection to free space (see Invoking guix gc). For example, to remove generations older than 4 months, run:

sudo guix system delete-generations 4m

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 guix system reconfigure as shown above. Likewise, to upgrade system software, you first fetch an up-to-date Guix and then reconfigure your system with that new Guix:

guix pull
sudo guix system reconfigure /etc/config.scm

We recommend doing that regularly so that your system includes the latest security updates (see Security Updates).

Note: sudo guix runs your user’s guix command and not root’s, because sudo leaves PATH unchanged.

The difference matters here, because guix pull updates the guix command and package definitions only for the user it is run as. This means that if you choose to use guix system reconfigure in root’s login shell, you’ll need to guix pull separately.

That’s it! If you’re getting started with Guix entirely, see Getting Started. The next sections dive in more detail into the crux of the matter: system configuration.