Newer
Older
@example
$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
@end example
These options are parsed independently, and the result is appended to
the parsed command-line options.
@end defvr
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
@node Invoking guix download
@section Invoking @command{guix download}
When writing a package definition, developers typically need to download
the package's source tarball, compute its SHA256 hash, and write that
hash in the package definition (@pxref{Defining Packages}). The
@command{guix download} tool helps with this task: it downloads a file
from the given URI, adds it to the store, and prints both its file name
in the store and its SHA256 hash.
The fact that the downloaded file is added to the store saves bandwidth:
when the developer eventually tries to build the newly defined package
with @command{guix build}, the source tarball will not have to be
downloaded again because it is already in the store. It is also a
convenient way to temporarily stash files, which may be deleted
eventually (@pxref{Invoking guix gc}).
The @command{guix download} command supports the same URIs as used in
package definitions. In particular, it supports @code{mirror://} URIs.
@code{https} URIs (HTTP over TLS) are supported @emph{provided} the
Guile bindings for GnuTLS are available in the user's environment; when
they are not available, an error is raised. @xref{Guile Preparations,
how to install the GnuTLS bindings for Guile,, gnutls-guile,
GnuTLS-Guile}, for more information.
The following option is available:
@table @code
@item --format=@var{fmt}
@itemx -f @var{fmt}
Write the hash in the format specified by @var{fmt}. For more
information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
@node Invoking guix hash
@section Invoking @command{guix hash}
The @command{guix hash} command computes the SHA256 hash of a file.
It is primarily a convenience tool for anyone contributing to the
distribution: it computes the cryptographic hash of a file, which can be
used in the definition of a package (@pxref{Defining Packages}).
The general syntax is:
@example
guix hash @var{option} @var{file}
@end example
@command{guix hash} has the following option:
@table @code
@item --format=@var{fmt}
@itemx -f @var{fmt}
Write the hash in the format specified by @var{fmt}.
Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
(@code{hex} and @code{hexadecimal} can be used as well).
If the @option{--format} option is not specified, @command{guix hash}
will output the hash in @code{nix-base32}. This representation is used
in the definitions of packages.
@item --recursive
@itemx -r
Compute the hash on @var{file} recursively.
In this case, the hash is computed on an archive containing @var{file},
including its children if it is a directory. Some of @var{file}'s
meta-data is part of the archive; for instance, when @var{file} is a
regular file, the hash is different depending on whether @var{file} is
executable or not. Meta-data such as time stamps has no impact on the
hash (@pxref{Invoking guix archive}).
@c FIXME: Replace xref above with xref to an ``Archive'' section when
@c it exists.
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
@node Invoking guix import
@section Invoking @command{guix import}
@cindex importing packages
@cindex package import
@cindex package conversion
The @command{guix import} command is useful for people willing to add a
package to the distribution but who'd rather do as little work as
possible to get there---a legitimate demand. The command knows of a few
repositories from which it can ``import'' package meta-data. The result
is a package definition, or a template thereof, in the format we know
(@pxref{Defining Packages}).
The general syntax is:
@example
guix import @var{importer} @var{options}@dots{}
@end example
@var{importer} specifies the source from which to import package
meta-data, and @var{options} specifies a package identifier and other
options specific to @var{importer}. Currently, the available
``importers'' are:
@table @code
@item gnu
Import meta-data for the given GNU package. This provides a template
for the latest version of that GNU package, including the hash of its
source tarball, and its canonical synopsis and description.
Additional information such as the package's dependencies and its
license needs to be figured out manually.
For example, the following command returns a package definition for
GNU@tie{}Hello:
@example
guix import gnu hello
@end example
Specific command-line options are:
@table @code
@item --key-download=@var{policy}
As for @code{guix refresh}, specify the policy to handle missing OpenPGP
keys when verifying the package's signature. @xref{Invoking guix
refresh, @code{--key-download}}.
@end table
@item pypi
@cindex pypi
Import meta-data from the @uref{https://pypi.python.org/, Python Package
Index}@footnote{This functionality requires Guile-JSON to be installed.
@xref{Requirements}.}. Information is taken from the JSON-formatted
description available at @code{pypi.python.org} and usually includes all
the relevant information, including package dependencies.
The command below imports meta-data for the @code{itsdangerous} Python
package:
@example
guix import pypi itsdangerous
@end example
@item cpan
@cindex CPAN
Import meta-data from @uref{https://www.metacpan.org/, MetaCPAN}.
Information is taken from the JSON-formatted meta-data provided through
@uref{https://api.metacpan.org/, MetaCPAN's API} and includes most
relevant information, such as module dependencies. License information
should be checked closely. If Perl is available in the store, then the
@code{corelist} utility will be used to filter core modules out of the
list of dependencies.
The command command below imports meta-data for the @code{Acme::Boolean}
Perl module:
@example
guix import cpan Acme::Boolean
@end example
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
@item nix
Import meta-data from a local copy of the source of the
@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
relies on the @command{nix-instantiate} command of
@uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
typically written in a mixture of Nix-language and Bash code. This
command only imports the high-level package structure that is written in
the Nix language. It normally includes all the basic fields of a
package definition.
When importing a GNU package, the synopsis and descriptions are replaced
by their canonical upstream variant.
As an example, the command below imports the package definition of
LibreOffice (more precisely, it imports the definition of the package
bound to the @code{libreoffice} top-level attribute):
@example
guix import nix ~/path/to/nixpkgs libreoffice
@end example
@end table
The structure of the @command{guix import} code is modular. It would be
useful to have more importers for other package formats, and your help
is welcome here (@pxref{Contributing}).
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
@node Invoking guix refresh
@section Invoking @command{guix refresh}
The primary audience of the @command{guix refresh} command is developers
of the GNU software distribution. By default, it reports any packages
provided by the distribution that are outdated compared to the latest
upstream version, like this:
@example
$ guix refresh
gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
@end example
It does so by browsing each package's FTP directory and determining the
highest version number of the source tarballs
therein@footnote{Currently, this only works for GNU packages.}.
When passed @code{--update}, it modifies distribution source files to
update the version numbers and source tarball hashes of those packages'
recipes (@pxref{Defining Packages}). This is achieved by downloading
each package's latest source tarball and its associated OpenPGP
signature, authenticating the downloaded tarball against its signature
using @command{gpg}, and finally computing its hash. When the public
key used to sign the tarball is missing from the user's keyring, an
attempt is made to automatically retrieve it from a public key server;
when it's successful, the key is added to the user's keyring; otherwise,
@command{guix refresh} reports an error.
The following options are supported:
@table @code
@item --update
@itemx -u
Update distribution source files (package recipes) in place.
@xref{Defining Packages}, for more information on package definitions.
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
@item --select=[@var{subset}]
@itemx -s @var{subset}
Select all the packages in @var{subset}, one of @code{core} or
@code{non-core}.
The @code{core} subset refers to all the packages at the core of the
distribution---i.e., packages that are used to build ``everything
else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
changing one of these packages in the distribution entails a rebuild of
all the others. Thus, such updates are an inconvenience to users in
terms of build time or bandwidth used to achieve the upgrade.
The @code{non-core} subset refers to the remaining packages. It is
typically useful in cases where an update of the core packages would be
inconvenient.
@end table
In addition, @command{guix refresh} can be passed one or more package
names, as in this example:
@example
guix refresh -u emacs idutils
@end example
@noindent
The command above specifically updates the @code{emacs} and
@code{idutils} packages. The @code{--select} option would have no
effect in this case.
When considering whether to upgrade a package, it is sometimes
convenient to know which packages would be affected by the upgrade and
should be checked for compatibility. For this the following option may
be used when passing @command{guix refresh} one or more package names:
@table @code
@item --list-dependent
@itemx -l
List top-level dependent packages that would need to be rebuilt as a
result of upgrading one or more packages.
@end table
Be aware that the @code{--list-dependent} option only
@emph{approximates} the rebuilds that would be required as a result of
an upgrade. More rebuilds might be required under some circumstances.
@example
$ guix refresh --list-dependent flex
Building the following 120 packages would ensure 213 dependent packages are rebuilt:
hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{}
@end example
The command above lists a set of packages that could be built to check
for compatibility with an upgraded @code{flex} package.
The following options can be used to customize GnuPG operation:
@table @code
@item --gpg=@var{command}
Use @var{command} as the GnuPG 2.x command. @var{command} is searched
for in @code{$PATH}.
@item --key-download=@var{policy}
Handle missing OpenPGP keys according to @var{policy}, which may be one
of:
@table @code
@item always
Always download missing OpenPGP keys from the key server, and add them
to the user's GnuPG keyring.
@item never
Never try to download missing OpenPGP keys. Instead just bail out.
@item interactive
When a package signed with an unknown OpenPGP key is encountered, ask
the user whether to download it or not. This is the default behavior.
@end table
@item --key-server=@var{host}
Use @var{host} as the OpenPGP key server when importing a public key.
@node Invoking guix lint
@section Invoking @command{guix lint}
The @command{guix lint} is meant to help package developers avoid common
errors and use a consistent style. It runs a number of checks on a
given set of packages in order to find common mistakes in their
definitions. Available @dfn{checkers} include (see
@code{--list-checkers} for a complete list):
@table @code
@item synopsis
@itemx description
Validate certain typographical and stylistic rules about package
descriptions and synopses.
@item inputs-should-be-native
Identify inputs that should most likely be native inputs.
@item source
@itemx home-page
Probe @code{home-page} and @code{source} URLs and report those that are
invalid.
@end table
The general syntax is:
@example
guix lint @var{options} @var{package}@dots{}
@end example
If no package is given on the command line, then all packages are checked.
The @var{options} may be zero or more of the following:
@table @code
@item --checkers
@itemx -c
Only enable the checkers specified in a comma-separated list using the
names returned by @code{--list-checkers}.
@item --list-checkers
@itemx -l
List and describe all the available checkers that will be run on packages
and exit.
@end table
@node Invoking guix environment
@section Invoking @command{guix environment}
@cindex reproducible build environments
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
The purpose of @command{guix environment} is to assist hackers in
creating reproducible development environments without polluting their
package profile. The @command{guix environment} tool takes one or more
packages, builds all of the necessary inputs, and creates a shell
environment to use them.
The general syntax is:
@example
guix environment @var{options} @var{package}@dots{}
@end example
The following examples spawns a new shell that is capable of building
the GNU Guile source code:
@example
guix environment guile
@end example
If the specified packages are not built yet, @command{guix environment}
automatically builds them. The new shell's environment is an augmented
version of the environment that @command{guix environment} was run in.
It contains the necessary search paths for building the given package
added to the existing environment variables. To create a ``pure''
environment in which the original environment variables have been unset,
use the @code{--pure} option.
Additionally, more than one package may be specified, in which case the
union of the inputs for the given packages are used. For example, the
command below spawns a shell where all of the dependencies of both Guile
and Emacs are available:
@example
guix environment guile emacs
@end example
Sometimes an interactive shell session is not desired. The
@code{--exec} option can be used to specify the command to run instead.
@example
guix environment guile --exec=make
@end example
The following options are available:
@table @code
@item --expression=@var{expr}
@itemx -e @var{expr}
Create an environment for the package that @var{expr} evaluates to.
@item --load=@var{file}
@itemx -l @var{file}
Create an environment for the package that the code within @var{file}
evaluates to.
@item --exec=@var{command}
@item -E @var{command}
Execute @var{command} in the new environment.
@item --pure
Unset existing environment variables when building the new environment.
This has the effect of creating an environment in which search paths
only contain package inputs.
@item --search-paths
Display the environment variable definitions that make up the
environment.
@end table
It also supports all of the common build options that @command{guix
build} supports (@pxref{Invoking guix build, common build options}).
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
@node Invoking guix publish
@section Invoking @command{guix publish}
The purpose of @command{guix publish} is to enable users to easily share
their store with others. When @command{guix publish} runs, it spawns an
HTTP server which allows anyone with network access to obtain
substitutes from it. This means that any machine running Guix can also
act as if it were a build farm, since the HTTP interface is
Hydra-compatible.
For security, each substitute is signed, allowing recipients to check
their authenticity and integrity (@pxref{Substitutes}). Because
@command{guix publish} uses the system's signing key, which is only
readable by the system administrator, it must run as root.
The general syntax is:
@example
guix publish @var{options}@dots{}
@end example
Running @command{guix publish} without any additional arguments will
spawn an HTTP server on port 8080:
@example
guix publish
@end example
Once a publishing server has been authorized (@pxref{Invoking guix
archive}), the daemon may download substitutes from it:
@example
guix-daemon --substitute-urls=http://example.org:8080
@end example
The following options are available:
@table @code
@item --port=@var{port}
@itemx -p @var{port}
Listen for HTTP requests on @var{port}.
@item --repl[=@var{port}]
@itemx -r [@var{port}]
Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
Reference Manual}) on @var{port} (37146 by default).
@end table
@c *********************************************************************
@node GNU Distribution
@chapter GNU Distribution
@cindex Guix System Distribution
@cindex GSD
Guix comes with a distribution of the GNU system consisting entirely of
free software@footnote{The term ``free'' here refers to the
@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
users of that software}.}. The
distribution can be installed on its own (@pxref{System Installation}),
but it is also possible to install Guix as a package manager on top of
an installed GNU/Linux system (@pxref{Installation}). To distinguish
between the two, we refer to the standalone distribution as the Guix
System Distribution, or GNU@tie{}GSD.
The distribution provides core GNU packages such as GNU libc, GCC, and
Binutils, as well as many GNU and non-GNU applications. The complete
list of available packages can be browsed
@url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):
guix package --list-available
Our goal has been to provide a practical 100% free software distribution of
Linux-based and other variants of GNU, with a focus on the promotion and
tight integration of GNU components, and an emphasis on programs and
tools that help users exert that freedom.
Packages are currently available on the following platforms:
@table @code
@item x86_64-linux
Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
@item i686-linux
Intel 32-bit architecture (IA32), Linux-Libre kernel;
@item armhf-linux
ARMv7-A architecture with hard float, Thumb-2 and VFP3D16 coprocessor,
using the EABI hard-float ABI, and Linux-Libre kernel.
@item mips64el-linux
little-endian 64-bit MIPS processors, specifically the Loongson series,
n32 application binary interface (ABI), and Linux-Libre kernel.
@end table
GSD itself is currently only available on @code{i686} and @code{x86_64}.
@noindent
For information on porting to other architectures or kernels,
@xref{Porting}.
* System Installation:: Installing the whole operating system.
* System Configuration:: Configuring the operating system.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
* Package Modules:: Packages from the programmer's viewpoint.
* Packaging Guidelines:: Growing the distribution.
* Bootstrapping:: GNU/Linux built from scratch.
* Porting:: Targeting another platform or kernel.
@end menu
Building this distribution is a cooperative effort, and you are invited
to join! @xref{Contributing}, for information about how you can help.
@node System Installation
@section System Installation
@cindex Guix System Distribution
This section explains how to install the Guix System Distribution
on a machine. The Guix package manager can
also be installed on top of a running GNU/Linux system,
@pxref{Installation}.
@ifinfo
@c This paragraph is for people reading this from tty2 of the
@c installation image.
You're reading this documentation with an Info reader. For details on
how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
link that follows: @pxref{Help,,, info, Info: An Introduction}. Hit
@kbd{l} afterwards to come back here.
@end ifinfo
As of version @value{VERSION}, the Guix System Distribution (GSD) is
not production-ready. It may contain bugs and lack important
features. Thus, if you are looking for a stable production system that
respects your freedom as a computer user, a good solution at this point
is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
more established GNU/Linux distributions}. We hope you can soon switch
to the GSD without fear, of course. In the meantime, you can
also keep using your distribution and try out the package manager on top
of it (@pxref{Installation}).
Before you proceed with the installation, be aware of the following
noteworthy limitations applicable to version @value{VERSION}:
@itemize
@item
The installation process does not include a graphical user interface and
requires familiarity with GNU/Linux (see the following subsections to
get a feel of what that means.)
@item
The system does not yet provide GNOME and KDE; it provides Xfce, though,
if graphical desktop environments are your thing.
Support for the Logical Volume Manager (LVM) is missing.
@item
Few system services are currently supported out-of-the-box
(@pxref{Services}).
@item
On the order of 1,200 packages are available, which means that you may
occasionally find that a useful package is missing.
@end itemize
You've been warned. But more than a disclaimer, this is an invitation
to report issues (and success stories!), and join us in improving it.
@xref{Contributing}, for more info.
@subsection USB Stick Installation
An installation image for USB sticks can be downloaded from
@code{ftp://alpha.gnu.org/gnu/guix/gsd-usb-install-@value{VERSION}.@var{system}.xz},
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
where @var{system} is one of:
@table @code
@item x86_64-linux
for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
@item i686-linux
for a 32-bit GNU/Linux system on Intel-compatible CPUs.
@end table
This image contains a single partition with the tools necessary for an
installation. It is meant to be copied @emph{as is} to a large-enough
USB stick.
To copy the image to a USB stick, follow these steps:
@enumerate
@item
Decompress the image using the @command{xz} command:
@example
xz -d gsd-usb-install-@value{VERSION}.@var{system}.xz
@end example
@item
Insert a USB stick of 1@tie{}GiB or more in your machine, and determine
its device name. Assuming that USB stick is known as @file{/dev/sdX},
copy the image with:
@example
dd if=gsd-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
@end example
Access to @file{/dev/sdX} usually requires root privileges.
@end enumerate
Once this is done, you should be able to reboot the system and boot from
the USB stick. The latter usually requires you to get in the BIOS' boot
menu, where you can choose to boot from the USB stick.
@subsection Preparing for Installation
Once you have successfully booted the image on the USB stick, you should
end up with a root prompt. Several console TTYs are configured and can
be used to run commands as root. TTY2 shows this documentation,
browsable using the Info reader commands (@pxref{Help,,, info, Info: An
Introduction}).
To install the system, you would:
@enumerate
@item
Configure the network, by running @command{dhclient eno1} (to get an
automatically assigned IP address from the wired network interface
controller@footnote{
@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
The name @code{eno1} is for the first on-board Ethernet controller. The
interface name for an Ethernet controller that is in the first slot of
the first PCI bus, for instance, would be @code{enp1s0}. Use
@command{ifconfig -a} to list all the available network interfaces.}),
or using the @command{ifconfig} command.
The system automatically loads drivers for your network interface
controllers.
Setting up network access is almost always a requirement because the
image does not contain all the software and tools that may be needed.
@item
Unless this has already been done, you must partition and format the
target partitions.
Preferably, assign partitions a label so that you can easily and
reliably refer to them in @code{file-system} declarations (@pxref{File
Systems}). This is typically done using the @code{-L} option of
@command{mkfs.ext4} and related commands.
The installation image includes Parted (@pxref{Overview,,, parted, GNU
Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
encryption, and e2fsprogs, the suite of tools to manipulate
ext2/ext3/ext4 file systems.
@item
Once that is done, mount the target root partition under @file{/mnt}.
@item
Lastly, run @code{deco start cow-store /mnt}.
This will make @file{/gnu/store} copy-on-write, such that packages added
to it during the installation phase will be written to the target disk
rather than kept in memory.
@end enumerate
@subsection Proceeding with the Installation
With the target partitions ready, you now have to edit a file and
provide the declaration of the operating system to be installed. To
that end, the installation system comes with two text editors: GNU nano
(@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
It is better to store that file on the target root file system, say, as
@file{/mnt/etc/config.scm}.
A minimal operating system configuration, with just the bare minimum and
only a root account would look like this (on the installation system,
this example is available as @file{/etc/configuration-template.scm}):
@include os-config.texi
@end example
@noindent
For more information on @code{operating-system} declarations,
@pxref{Using the Configuration System}.
Once that is done, the new system must be initialized (remember that the
target root file system is mounted under @file{/mnt}):
@example
guix system init /mnt/etc/config.scm /mnt
@end example
@noindent
This will copy all the necessary files, and install GRUB on
@file{/dev/sdX}, unless you pass the @option{--no-grub} option. For
more information, @pxref{Invoking guix system}. This command may trigger
downloads or builds of missing packages, which can take some time.
Once that command has completed---and hopefully succeeded!---you can
run @command{reboot} and boot into the new system. Cross fingers, and
join us on @code{#guix} on the Freenode IRC network or on
@file{guix-devel@@gnu.org} to share your experience---good or not so
good.
@subsection Building the Installation Image
The installation image described above was built using the @command{guix
system} command, specifically:
@example
guix system disk-image --image-size=850MiB gnu/system/install.scm
@end example
@xref{Invoking guix system}, for more information. See
@file{gnu/system/install.scm} in the source tree for more information
about the installation image.
@node System Configuration
@section System Configuration
@cindex system configuration
The Guix System Distribution supports a consistent whole-system configuration
mechanism. By that we mean that all aspects of the global system
configuration---such as the available system services, timezone and
locale settings, user accounts---are declared in a single place. Such
a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
One of the advantages of putting all the system configuration under the
control of Guix is that it supports transactional system upgrades, and
makes it possible to roll-back to a previous system instantiation,
should something go wrong with the new one (@pxref{Features}). Another
one is that it makes it easy to replicate the exact same configuration
across different machines, or at different points in time, without
having to resort to additional administration tools layered on top of
the system's own tools.
@c Yes, we're talking of Puppet, Chef, & co. here. ↑
This section describes this mechanism. First we focus on the system
administrator's viewpoint---explaining how the system is configured and
instantiated. Then we show how this mechanism can be extended, for
instance to support new system services.
@menu
* Using the Configuration System:: Customizing your GNU system.
* operating-system Reference:: Detail of operating-system declarations.
* File Systems:: Configuring file system mounts.
* Mapped Devices:: Block device extra processing.
* User Accounts:: Specifying user accounts.
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* GRUB Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
* Defining Services:: Adding new service definitions.
@end menu
@node Using the Configuration System
@subsection Using the Configuration System
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 system services, the default Linux-Libre
kernel, initial RAM disk, and boot loader looks like this:
@findex operating-system
@lisp
(use-modules (gnu) ; for 'user-account', '%base-services', etc.
(gnu packages emacs) ; for 'emacs'
(gnu services ssh)) ; for 'lsh-service'
(operating-system
(host-name "komputilo")
(timezone "Europe/Paris")
(bootloader (grub-configuration
(device "/dev/sda")))
(file-systems (cons (file-system
(device "/dev/sda1") ; or partition label
(mount-point "/")
(type "ext3"))
%base-file-systems))
(users (list (user-account
(name "alice")
(comment "Bob's sister")
(home-directory "/home/alice"))))
(packages (cons emacs %base-packages))
(services (cons (lsh-service #:port 2222 #:root-login? #t)
%base-services)))
@end lisp
This example should be self-describing. Some of the fields defined
above, such as @code{host-name} and @code{bootloader}, are mandatory.
Others, such as @code{packages} and @code{services}, can be omitted, in
which case they get a default value.
@vindex %base-packages
The @code{packages} field lists
packages that will be globally visible on the system, for all user
accounts---i.e., in every user's @code{PATH} environment variable---in
addition to the per-user profiles (@pxref{Invoking guix package}). The
@var{%base-packages} variable provides all the tools one would expect
for basic user and administrator tasks---including the GNU Core
Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
editor, @command{find}, @command{grep}, etc. The example above adds
Emacs to those, taken from the @code{(gnu packages emacs)} module
(@pxref{Package Modules}).
@vindex %base-services
The @code{services} field lists @dfn{system services} to be made
available when the system starts (@pxref{Services}).
The @code{operating-system} declaration above specifies that, in
addition to the basic services, we want the @command{lshd} secure shell
daemon listening on port 2222, and allowing remote @code{root} logins
(@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
@code{lsh-service} arranges so that @code{lshd} is started with the
right command-line options, possibly with supporting configuration files
generated as needed (@pxref{Defining Services}). @xref{operating-system
Reference}, for details about the available @code{operating-system}
fields.
Assuming the above snippet 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}). The normal way to change the
system's configuration is by updating this file and re-running the
@command{guix system} command.
At the Scheme level, the bulk of an @code{operating-system} declaration
is instantiated with the following monadic procedure (@pxref{The Store
Monad}):
@deffn {Monadic Procedure} operating-system-derivation os
Return a derivation that builds @var{os}, an @code{operating-system}
object (@pxref{Derivations}).
The output of the derivation is a single directory that refers to all
the packages, configuration files, and other supporting files needed to
instantiate @var{os}.
@end deffn
@node operating-system Reference
@subsection @code{operating-system} Reference
This section summarizes all the options available in
@code{operating-system} declarations (@pxref{Using the Configuration
System}).
@deftp {Data Type} operating-system
This is the data type representing an operating system configuration.
By that, we mean all the global system configuration, not per-user
configuration (@pxref{Using the Configuration System}).
@table @asis
@item @code{kernel} (default: @var{linux-libre})
The package object of the operating system to use@footnote{Currently
only the Linux-libre kernel is supported. In the future, it will be
possible to use the GNU@tie{}Hurd.}.
@item @code{bootloader}
The system bootloader configuration object. @xref{GRUB Configuration}.
@item @code{initrd} (default: @code{base-initrd})
A two-argument monadic procedure that returns an initial RAM disk for
the Linux kernel. @xref{Initial RAM Disk}.
@item @code{firmware} (default: @var{%base-firmware})
@cindex firmware
List of firmware packages loadable by the operating system kernel.
The default includes firmware needed for Atheros-based WiFi devices
(Linux-libre module @code{ath9k}.)
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
@item @code{host-name}
The host name.
@item @code{hosts-file}
@cindex hosts file
A zero-argument monadic procedure that returns a text file for use as
@file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
Reference Manual}). The default is to produce a file with entries for
@code{localhost} and @var{host-name}.
@item @code{mapped-devices} (default: @code{'()})
A list of mapped devices. @xref{Mapped Devices}.
@item @code{file-systems}
A list of file systems. @xref{File Systems}.
@item @code{swap-devices} (default: @code{'()})
@cindex swap devices
A list of strings identifying devices to be used for ``swap space''
(@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}).
For example, @code{'("/dev/sda3")}.
@item @code{users} (default: @code{'()})
@itemx @code{groups} (default: @var{%base-groups})
List of user accounts and groups. @xref{User Accounts}.
@item @code{skeletons} (default: @code{(default-skeletons)})
A monadic list of pairs of target file name and files. These are the
files that will be used as skeletons as new accounts are created.
For instance, a valid value may look like this:
@example
(mlet %store-monad ((bashrc (text-file "bashrc" "\
export PATH=$HOME/.guix-profile/bin")))
(return `((".bashrc" ,bashrc))))
@end example
@item @code{issue} (default: @var{%default-issue})
A string denoting the contents of the @file{/etc/issue} file, which is
what displayed when users log in on a text console.
@item @code{packages} (default: @var{%base-packages})
The set of packages installed in the global profile, which is accessible
at @file{/run/current-system/profile}.
The default set includes core utilities, but it is good practice to
install non-core utilities in user profiles (@pxref{Invoking guix
package}).
@item @code{timezone}
A timezone identifying string---e.g., @code{"Europe/Paris"}.
@item @code{locale} (default: @code{"en_US.utf8"})
The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
Library Reference Manual}). @xref{Locales}, for more information.
@item @code{locale-definitions} (default: @var{%default-locale-definitions})
The list of locale definitions to be compiled and that may be used at
run time. @xref{Locales}.
@item @code{name-service-switch} (default: @var{%default-nss})
Configuration of libc's name service switch (NSS)---a
@code{<name-service-switch>} object. @xref{Name Service Switch}, for
details.
@item @code{services} (default: @var{%base-services})
A list of monadic values denoting system services. @xref{Services}.