Copyright @copyright{} 2020 Marcin Karpezo@*
Copyright @copyright{} 2020 Brice Waegeneire@*
Copyright @copyright{} 2020 André Batista@*
-Copyright @copyright{} 2020 Christopher Lemmer Webber
+Copyright @copyright{} 2020 Christine Lemmer-Webber@*
+Copyright @copyright{} 2021 Joshua Branson@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@c TRANSLATORS: You can replace the following paragraph with information on
@c how to join your own translation team and how to report issues with the
@c translation.
-If you would like to translate this document in your native language, consider
-joining the @uref{https://translationproject.org/domain/guix-cookbook.html,
-Translation Project}.
+This manual is also available in French (@pxref{Top,,, guix-cookbook.fr,
+Livre de recettes de GNU Guix}) and German (@pxref{Top,,,
+guix-cookbook.de, GNU-Guix-Kochbuch}). If you would like to translate
+this document in your native language, consider joining
+@uref{https://translate.fedoraproject.org/projects/guix/documentation-cookbook,
+Weblate} (@pxref{Translating Guix,,, guix, GNU Guix reference manual}).
@menu
* Scheme tutorials:: Meet your new favorite language!
System Configuration
-* Customizing the Kernel:: Creating and using a custom Linux kernel
-
+* Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY
+* Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System.
@end detailmenu
@end menu
Guix makes it possible to streamline the process by adding as many ``package
declaration directories'' as you want.
-Create a directory, say @file{~./guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH}
+Create a directory, say @file{~/guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH}
environment variable:
@example
"17pjvprmdrx4h6bb1hhc98w9qi6ki7yl57f090n9kbhswxqfs7s3"))
(patches (search-patches "libgit2-mtime-0.patch"))
(modules '((guix build utils)))
- (snippet '(begin
- ;; Remove bundled software.
- (delete-file-recursively "deps")
- #true))))
+ ;; Remove bundled software.
+ (snippet '(delete-file-recursively "deps"))))
(build-system cmake-build-system)
(outputs '("out" "debug"))
(arguments
(("#!/bin/sh") (string-append "#!" (which "sh"))))
(substitute* "tests/clar/fs.h"
(("/bin/cp") (which "cp"))
- (("/bin/rm") (which "rm")))
- #true))
+ (("/bin/rm") (which "rm")))))
;; Run checks more verbosely.
(replace 'check
(lambda _ (invoke "./libgit2_clar" "-v" "-Q")))
(add-after 'unpack 'make-files-writable-for-tests
(lambda _ (for-each make-file-writable (find-files "." ".*")))))))
(inputs
- `(("libssh2" ,libssh2)
- ("http-parser" ,http-parser)
- ("python" ,python-wrapper)))
+ (list libssh2 http-parser python-wrapper))
(native-inputs
- `(("pkg-config" ,pkg-config)))
+ (list pkg-config))
(propagated-inputs
;; These two libraries are in 'Requires.private' in libgit2.pc.
- `(("openssl" ,openssl)
- ("zlib" ,zlib)))
+ (list openssl zlib))
(home-page "https://libgit2.github.com/")
(synopsis "Library providing Git core methods")
(description
@subsubsection Inputs
-First, a syntactic comment: See the quasi-quote / comma syntax?
-
-@lisp
- (native-inputs
- `(("pkg-config" ,pkg-config)))
-@end lisp
-
-is equivalent to
-
-@lisp
- (native-inputs
- (list (list "pkg-config" pkg-config)))
-@end lisp
-
-You'll mostly see the former because it's shorter.
-
There are 3 different input types. In short:
@table @asis
and @emph{propagated inputs} will be fetched: the @emph{native inputs} are not required to
install a package from a substitute.
+@quotation Note
+You may see here and there snippets where package inputs are written
+quite differently, like so:
+
+@lisp
+;; The "old style" for inputs.
+(inputs
+ `(("libssh2" ,libssh2)
+ ("http-parser" ,http-parser)
+ ("python" ,python-wrapper)))
+@end lisp
+
+This is the ``old style'', where each input in the list is explicitly
+given a label (a string). It is still supported but we recommend using
+the style above instead. @xref{package Reference,,, guix, GNU Guix
+Reference Manual}, for more info.
+@end quotation
+
@subsubsection Outputs
Just like how a package can have multiple inputs, it can also produce multiple
reference.
@menu
+* Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY
* Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System.
+* Guix System Image API:: Customizing images to target specific platforms.
* Connecting to Wireguard VPN:: Connecting to a Wireguard VPN.
* Customizing a Window Manager:: Handle customization of a Window manager on Guix System.
* Running Guix on a Linode Server:: Running Guix on a Linode Server
* Setting up NGINX with Lua:: Configuring NGINX web-server to load Lua modules.
@end menu
+@node Auto-Login to a Specific TTY
+@section Auto-Login to a Specific TTY
+
+While the Guix manual explains auto-login one user to @emph{all} TTYs (
+@pxref{auto-login to TTY,,, guix, GNU Guix Reference Manual}), some
+might prefer a situation, in which one user is logged into one TTY with
+the other TTYs either configured to login different users or no one at
+all. Note that one can auto-login one user to any TTY, but it is
+usually advisable to avoid @code{tty1}, which, by default, is used to
+log warnings and errors.
+
+Here is how one might set up auto login for one user to one tty:
+
+@lisp
+(define (auto-login-to-tty config tty user)
+ (if (string=? tty (mingetty-configuration-tty config))
+ (mingetty-configuration
+ (inherit config)
+ (auto-login user))
+ config))
+
+(define %my-services
+ (modify-services %base-services
+ ;; @dots{}
+ (mingetty-service-type config =>
+ (auto-login-to-tty
+ config "tty3" "alice"))))
+
+(operating-system
+ ;; @dots{}
+ (services %my-services))
+@end lisp
+
+One could also @code{compose} (@pxref{Higher-Order Functions,,, guile,
+The Guile Reference Manual}) @code{auto-login-to-tty} to login multiple
+users to multiple ttys.
+
+Finally, here is a note of caution. Setting up auto login to a TTY,
+means that anyone can turn on your computer and run commands as your
+regular user.
+However, if you have an encrypted root partition, and thus already need
+to enter a passphrase when the system boots, auto-login might be a
+convenient option.
+
+
@node Customizing the Kernel
@section Customizing the Kernel
kernel, since certain modules which are expected to be built may not be
available for inclusion into the initrd.
+@node Guix System Image API
+@section Guix System Image API
+
+Historically, Guix System is centered around an @code{operating-system}
+structure. This structure contains various fields ranging from the
+bootloader and kernel declaration to the services to install.
+
+Depending on the target machine, that can go from a standard
+@code{x86_64} machine to a small ARM single board computer such as the
+Pine64, the image constraints can vary a lot. The hardware
+manufacturers will impose different image formats with various partition
+sizes and offsets.
+
+To create images suitable for all those machines, a new abstraction is
+necessary: that's the goal of the @code{image} record. This record
+contains all the required information to be transformed into a
+standalone image, that can be directly booted on any target machine.
+
+@lisp
+(define-record-type* <image>
+ image make-image
+ image?
+ (name image-name ;symbol
+ (default #f))
+ (format image-format) ;symbol
+ (target image-target
+ (default #f))
+ (size image-size ;size in bytes as integer
+ (default 'guess))
+ (operating-system image-operating-system ;<operating-system>
+ (default #f))
+ (partitions image-partitions ;list of <partition>
+ (default '()))
+ (compression? image-compression? ;boolean
+ (default #t))
+ (volatile-root? image-volatile-root? ;boolean
+ (default #t))
+ (substitutable? image-substitutable? ;boolean
+ (default #t)))
+@end lisp
+
+This record contains the operating-system to instantiate. The
+@code{format} field defines the image type and can be @code{efi-raw},
+@code{qcow2} or @code{iso9660} for instance. In the future, it could be
+extended to @code{docker} or other image types.
+
+A new directory in the Guix sources is dedicated to images definition. For now
+there are four files:
+
+@itemize @bullet
+@item @file{gnu/system/images/hurd.scm}
+@item @file{gnu/system/images/pine64.scm}
+@item @file{gnu/system/images/novena.scm}
+@item @file{gnu/system/images/pinebook-pro.scm}
+@end itemize
+
+Let's have a look to @file{pine64.scm}. It contains the
+@code{pine64-barebones-os} variable which is a minimal definition of an
+operating-system dedicated to the @b{Pine A64 LTS} board.
+
+@lisp
+(define pine64-barebones-os
+ (operating-system
+ (host-name "vignemale")
+ (timezone "Europe/Paris")
+ (locale "en_US.utf8")
+ (bootloader (bootloader-configuration
+ (bootloader u-boot-pine64-lts-bootloader)
+ (targets '("/dev/vda"))))
+ (initrd-modules '())
+ (kernel linux-libre-arm64-generic)
+ (file-systems (cons (file-system
+ (device (file-system-label "my-root"))
+ (mount-point "/")
+ (type "ext4"))
+ %base-file-systems))
+ (services (cons (service agetty-service-type
+ (agetty-configuration
+ (extra-options '("-L")) ; no carrier detect
+ (baud-rate "115200")
+ (term "vt100")
+ (tty "ttyS0")))
+ %base-services))))
+@end lisp
+
+The @code{kernel} and @code{bootloader} fields are pointing to packages
+dedicated to this board.
+
+Right below, the @code{pine64-image-type} variable is also defined.
+
+@lisp
+(define pine64-image-type
+ (image-type
+ (name 'pine64-raw)
+ (constructor (cut image-with-os arm64-disk-image <>))))
+@end lisp
+
+It's using a record we haven't talked about yet, the @code{image-type} record,
+defined this way:
+
+@lisp
+(define-record-type* <image-type>
+ image-type make-image-type
+ image-type?
+ (name image-type-name) ;symbol
+ (constructor image-type-constructor)) ;<operating-system> -> <image>
+@end lisp
+
+The main purpose of this record is to associate a name to a procedure
+transforming an @code{operating-system} to an image. To understand why
+it is necessary, let's have a look to the command producing an image
+from an @code{operating-system} configuration file:
+
+@example
+guix system image my-os.scm
+@end example
+
+This command expects an @code{operating-system} configuration but how
+should we indicate that we want an image targeting a Pine64 board? We
+need to provide an extra information, the @code{image-type}, by passing
+the @code{--image-type} or @code{-t} flag, this way:
+
+@example
+guix system image --image-type=pine64-raw my-os.scm
+@end example
+
+This @code{image-type} parameter points to the @code{pine64-image-type}
+defined above. Hence, the @code{operating-system} declared in
+@code{my-os.scm} will be applied the @code{(cut image-with-os
+arm64-disk-image <>)} procedure to turn it into an image.
+
+The resulting image looks like:
+
+@lisp
+(image
+ (format 'disk-image)
+ (target "aarch64-linux-gnu")
+ (operating-system my-os)
+ (partitions
+ (list (partition
+ (inherit root-partition)
+ (offset root-offset)))))
+@end lisp
+
+which is the aggregation of the @code{operating-system} defined in
+ @code{my-os.scm} to the @code{arm64-disk-image} record.
+
+But enough Scheme madness. What does this image API bring to the Guix user?
+
+One can run:
+
+@example
+mathieu@@cervin:~$ guix system --list-image-types
+The available image types are:
+
+ - pinebook-pro-raw
+ - pine64-raw
+ - novena-raw
+ - hurd-raw
+ - hurd-qcow2
+ - qcow2
+ - uncompressed-iso9660
+ - efi-raw
+ - arm64-raw
+ - arm32-raw
+ - iso9660
+@end example
+
+and by writing an @code{operating-system} file based on
+@code{pine64-barebones-os}, you can customize your image to your
+preferences in a file (@file{my-pine-os.scm}) like this:
+
+@lisp
+(use-modules (gnu services linux)
+ (gnu system images pine64))
+
+(let ((base-os pine64-barebones-os))
+ (operating-system
+ (inherit base-os)
+ (timezone "America/Indiana/Indianapolis")
+ (services
+ (cons
+ (service earlyoom-service-type
+ (earlyoom-configuration
+ (prefer-regexp "icecat|chromium")))
+ (operating-system-user-services base-os)))))
+@end lisp
+
+run:
+
+@example
+guix system image --image-type=pine64-raw my-pine-os.scm
+@end example
+
+or,
+
+@example
+guix system image --image-type=hurd-raw my-hurd-os.scm
+@end example
+
+to get an image that can be written directly to a hard drive and booted
+from.
+
+Without changing anything to @code{my-hurd-os.scm}, calling:
+
+@example
+guix system image --image-type=hurd-qcow2 my-hurd-os.scm
+@end example
+
+will instead produce a Hurd QEMU image.
+
@node Connecting to Wireguard VPN
@section Connecting to Wireguard VPN
cat ~/.ssh/<username>_rsa.pub
@end example
-Power the Linode down. In the Linode's Disks/Configurations tab, resize
-the Debian disk to be smaller. 30 GB is recommended.
+Power the Linode down.
+
+In the Linode's Storage tab, resize the Debian disk to be smaller.
+30 GB free space is recommended. Then click "Add a disk", and fill
+out the form with the following:
-In the Linode settings, "Add a disk", with the following:
@itemize @bullet
@item
Label: "Guix"
Set it to the remaining size
@end itemize
-On the "configuration" field that comes with the default image, press
-"..." and select "Edit", then on that menu add to @file{/dev/sdc} the "Guix"
-label.
+In the Configurations tab, press "Edit" on the default Debian profile.
+Under "Block Device Assignment" click "Add a Device". It should be
+@file{/dev/sdc} and you can select the "Guix" disk. Save Changes.
Now "Add a Configuration", with the following:
@itemize @bullet
Turn off all the filesystem/boot helpers
@end itemize
-Now power it back up, picking the Debian configuration. Once it's
-booted up, ssh in your server via @code{ssh
+Now power it back up, booting with the Debian configuration. Once it's
+running, ssh to your server via @code{ssh
root@@@var{<your-server-IP-here>}}. (You can find your server IP address in
your Linode Summary section.) Now you can run the "install guix from
@pxref{Binary Installation,,, guix, GNU Guix}" steps:
@end lisp
The last line in the above example lets you log into the server as root
-and set the initial root password. After you have done this, you may
+and set the initial root password (see the note at the end of this
+recipe about root login). After you have done this, you may
delete that line from your configuration and reconfigure to prevent root
login.
-Save your ssh public key (eg: @file{~/.ssh/id_rsa.pub}) as
-@file{@var{<your-username-here>}_rsa.pub} and your
+Copy your ssh public key (eg: @file{~/.ssh/id_rsa.pub}) as
+@file{@var{<your-username-here>}_rsa.pub} and put
@file{guix-config.scm} in the same directory. In a new terminal run
these commands.
@example
sftp root@@<remote server ip address>
-put /home/<username>/ssh/id_rsa.pub .
-put /path/to/linode/guix-config.scm .
+put /path/to/files/<username>_rsa.pub .
+put /path/to/files/guix-config.scm .
@end example
In your first terminal, mount the guix drive:
mount /dev/sdc /mnt/guix
@end example
-Due to the way we set things up above, we do not install GRUB
-completely. Instead we install only our grub configuration file. So we
-need to copy over some of the other GRUB stuff that is already there:
+Due to the way we set up the bootloader section of the guix-config.scm,
+only the grub configuration file will be installed. So, we need to copy
+over some of the other GRUB stuff already installed on the Debian system:
@example
mkdir -p /mnt/guix/boot/grub
the ``Launch Console'' option in your linode. Choose the ``Glish''
instead of ``Weblish''. Now you should be able to ssh into the machine.
-Horray! At this point you can shut down the server, delete the
+Hooray! At this point you can shut down the server, delete the
Debian disk, and resize the Guix to the rest of the size.
Congratulations!
@item
Easier upgrades and maintenance: Multiple profiles make it easy to keep
-package listings at hand and make upgrades completely friction-less.
+package listings at hand and make upgrades completely frictionless.
@end itemize
Concretely, here follows some typical profiles:
HCoop / jackhill / guix / guix.git / blobdiff