7.2.13 Invoking guix system

Once you have written an operating system declaration, as seen in the previous section, it can be instantiated using the guix system command. The synopsis is:

guix system options… action file

file must be the name of a file containing an operating-system declaration. action specifies how the operating system is instantiate. Currently the following values are supported:

reconfigure

Build the operating system described in file, activate it, and switch to it²⁰.

This effects all the configuration specified in file: user accounts, system services, global package list, setuid programs, etc.

It also adds a GRUB menu entry for the new OS configuration, and moves entries for older configurations to a submenu—unless --no-grub is passed.

It is highly recommended to run guix pull once before you run guix system reconfigure for the first time (see Invoking guix pull). Failing to do that you would see an older version of Guix once reconfigure has completed.

build

Build the operating system’s derivation, which includes all the configuration files and programs needed to boot and run the system. This action does not actually install anything.

init

Populate the given directory with all the files necessary to run the operating system specified in file. This is useful for first-time installations of GuixSD. For instance:

guix system init my-os-config.scm /mnt

copies to /mnt all the store items required by the configuration specified in my-os-config.scm. This includes configuration files, packages, and so on. It also creates other essential files needed for the system to operate correctly—e.g., the /etc, /var, and /run directories, and the /bin/sh file.

This command also installs GRUB on the device specified in my-os-config, unless the --no-grub option was passed.

vm

Build a virtual machine that contain the operating system declared in file, and return a script to run that virtual machine (VM). Arguments given to the script are passed as is to QEMU.

The VM shares its store with the host system.

Additional file systems can be shared between the host and the VM using the --share and --expose command-line options: the former specifies a directory to be shared with write access, while the latter provides read-only access to the shared directory.

The example below creates a VM in which the user’s home directory is accessible read-only, and where the /exchange directory is a read-write mapping of the host’s $HOME/tmp:

guix system vm my-config.scm \
   --expose=$HOME --share=$HOME/tmp=/exchange

On GNU/Linux, the default is to boot directly to the kernel; this has the advantage of requiring only a very tiny root disk image since the host’s store can then be mounted.

The --full-boot option forces a complete boot sequence, starting with the bootloader. This requires more disk space since a root image containing at least the kernel, initrd, and bootloader data files must be created. The --image-size option can be used to specify the image’s size.

vm-image

disk-image

Return a virtual machine or disk image of the operating system declared in file that stands alone. Use the --image-size option to specify the size of the image.

When using vm-image, the returned image is in qcow2 format, which the QEMU emulator can efficiently use.

When using disk-image, a raw disk image is produced; it can be copied as is to a USB stick, for instance. Assuming /dev/sdc is the device corresponding to a USB stick, one can copy the image on it using the following command:

# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc

container

Return a script to run the operating system declared in file within a container. Containers are a set of lightweight isolation mechanisms provided by the kernel Linux-libre. Containers are substantially less resource-demanding than full virtual machines since the kernel, shared objects, and other resources can be shared with the host system; this also means they provide thinner isolation.

Currently, the script must be run as root in order to support more than a single user and group. The container shares its store with the host system.

As with the vm action (see guix system vm), additional file systems to be shared between the host and container can be specified using the --share and --expose options:

guix system container my-config.scm \
   --expose=$HOME --share=$HOME/tmp=/exchange

Note: This option requires Linux-libre 3.19 or newer.

options can contain any of the common build options provided by guix build (see Invoking guix build). In addition, options can contain one of the following:

--system=system

-s system

Attempt to build for system instead of the host’s system type. This works as per guix build (see Invoking guix build).

--derivation

-d

Return the derivation file name of the given operating system without building anything.

--image-size=size

For the vm-image and disk-image actions, create an image of the given size. size may be a number of bytes, or it may include a unit as a suffix (see size specifications in GNU Coreutils).

--on-error=strategy

Apply strategy when an error occurs when reading file. strategy may be one of the following:

nothing-special

Report the error concisely and exit. This is the default strategy.

backtrace

Likewise, but also display a backtrace.

debug

Report the error and enter Guile’s debugger. From there, you can run commands such as ,bt to get a backtrace, ,locals to display local variable values, and more generally inspect the program’s state. See Debug Commands in GNU Guile Reference Manual, for a list of available debugging commands.

Note that all the actions above, except build and init, rely on KVM support in the Linux-Libre kernel. Specifically, the machine should have hardware virtualization support, the corresponding KVM kernel module should be loaded, and the /dev/kvm device node must exist and be readable and writable by the user and by the daemon’s build users.

Once you have built, configured, re-configured, and re-re-configured your GuixSD installation, you may find it useful to list the operating system generations available on disk—and that you can choose from the GRUB boot menu:

list-generations

List a summary of each generation of the operating system available on disk, in a human-readable way. This is similar to the --list-generations option of guix package (see Invoking guix package).

Optionally, one can specify a pattern, with the same syntax that is used in guix package --list-generations, to restrict the list of generations displayed. For instance, the following command displays generations up to 10-day old:

$ guix system list-generations 10d

The guix system command has even more to offer! The following sub-commands allow you to visualize how your system services relate to each other:

extension-graph

Emit in Dot/Graphviz format to standard output the service extension graph of the operating system defined in file (see Service Composition, for more information on service extensions.)

The command:

$ guix system extension-graph file | dot -Tpdf > services.pdf

produces a PDF file showing the extension relations among services.

dmd-graph

Emit in Dot/Graphviz format to standard output the dependency graph of dmd services of the operating system defined in file. See dmd Services, for more information and for an example graph.