diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix-cookbook.texi | 66 | ||||
| -rw-r--r-- | doc/guix.texi | 45 |
2 files changed, 94 insertions, 17 deletions
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index f371364746..795e7d3b25 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -21,6 +21,7 @@ Copyright @copyright{} 2020 Brice Waegeneire@* Copyright @copyright{} 2020 André Batista@* Copyright @copyright{} 2020 Christine Lemmer-Webber@* Copyright @copyright{} 2021 Joshua Branson@* +Copyright @copyright{} 2022 Maxim Cournoyer* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -95,6 +96,7 @@ System Configuration * 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. +* Using security keys:: How to use security keys with Guix System. * 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. Running Guix on a Linode Server @@ -1380,6 +1382,7 @@ reference. * 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. +* Using security keys:: How to use security keys with Guix System. * 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 @@ -1883,6 +1886,65 @@ guix system image --image-type=hurd-qcow2 my-hurd-os.scm will instead produce a Hurd QEMU image. +@node Using security keys +@section Using security keys +@cindex 2FA, two-factor authentication +@cindex U2F, Universal 2nd Factor +@cindex security key, configuration + +The use of security keys can improve your security by providing a second +authentication source that cannot be easily stolen or copied, at least +for a remote adversary (something that you have), to the main secret (a +passphrase -- something that you know), reducing the risk of +impersonation. + +The example configuration detailed below showcases what minimal +configuration needs to be made on your Guix System to allow the use of a +Yubico security key. It is hoped the configuration can be useful for +other security keys as well, with minor adjustments. + +@subsection Configuration for use as a two-factor authenticator (2FA) + +To be usable, the udev rules of the system should be extended with +key-specific rules. The following shows how to extend your udev rules +with the @file{lib/udev/rules.d/70-u2f.rules} udev rule file provided by +the @code{libfido2} package from the @code{(gnu packages +security-token)} module and add your user to the @samp{"plugdev"} group +it uses: + +@lisp +(use-package-modules ... security-token ...) +... +(operating-system + ... + (users (cons* (user-account + (name "your-user") + (group "users") + (supplementary-groups + '("wheel" "netdev" "audio" "video" + "plugdev")) ;<- added system group + (home-directory "/home/your-user")) + %base-user-accounts)) + ... + (services + (cons* + ... + (udev-rules-service 'fido2 libfido2 #:groups '("plugdev"))))) +@end lisp + +After re-configuring your system and re-logging in your graphical +session so that the new group is in effect for your user, you can verify +that your key is usable by launching: + +@example +guix shell ungoogled-chromium -- chromium chrome://settings/securityKeys +@end example + +and validating that the security key can be reset via the ``Reset your +security key'' menu. If it works, congratulations, your security key is +ready to be used with applications supporting two-factor authentication +(2FA). + @node Connecting to Wireguard VPN @section Connecting to Wireguard VPN @@ -3441,8 +3503,8 @@ to reproduce the exact same profile: GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles GUIX_EXTRA=$HOME/.guix-extra -mkdir "$GUIX_EXTRA"/my-project -guix pull --channels=channel-specs.scm --profile "$GUIX_EXTRA/my-project/guix" +mkdir -p "$GUIX_EXTRA"/my-project +guix pull --channels=channel-specs.scm --profile="$GUIX_EXTRA/my-project/guix" mkdir -p "$GUIX_EXTRA_PROFILES/my-project" "$GUIX_EXTRA"/my-project/guix/bin/guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project diff --git a/doc/guix.texi b/doc/guix.texi index eaecfd0daa..e547d469f4 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -60,7 +60,7 @@ Copyright @copyright{} 2018, 2021 Oleg Pykhalov@* Copyright @copyright{} 2018 Mike Gerwitz@* Copyright @copyright{} 2018 Pierre-Antoine Rouby@* Copyright @copyright{} 2018, 2019 Gábor Boskovits@* -Copyright @copyright{} 2018, 2019, 2020 Florian Pelz@* +Copyright @copyright{} 2018, 2019, 2020, 2022 Florian Pelz@* Copyright @copyright{} 2018 Laura Lazzati@* Copyright @copyright{} 2018 Alex Vong@* Copyright @copyright{} 2019 Josh Holland@* @@ -1409,7 +1409,7 @@ when transferring files to and from build machines. File name of the Unix-domain socket @command{guix-daemon} is listening to on that machine. -@item @code{overload-threshold} (default: @code{0.6}) +@item @code{overload-threshold} (default: @code{0.8}) The load threshold above which a potential offload machine is disregarded by the offload scheduler. The value roughly translates to the total processor usage of the build machine, ranging from 0.0 (0%) to @@ -3423,19 +3423,25 @@ The @var{options} can be among the following: @itemx -i @var{package} @dots{} Install the specified @var{package}s. -Each @var{package} may specify either a simple package name, such as -@code{guile}, or a package name followed by an at-sign and version number, -such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter -case, the newest version prefixed by @code{1.8} is selected). +Each @var{package} may specify a simple package name, such as +@code{guile}, optionally followed by an at-sign and version number, +such as @code{guile@@3.0.7} or simply @code{guile@@3.0}. In the latter +case, the newest version prefixed by @code{3.0} is selected. -If no version number is specified, the -newest available version will be selected. In addition, @var{package} +If no version number is specified, the newest available version will be +selected. In addition, such a @var{package} specification may contain a colon, followed by the name of one of the outputs of the package, as in @code{gcc:doc} or @code{binutils@@2.22:lib} -(@pxref{Packages with Multiple Outputs}). Packages with a corresponding +(@pxref{Packages with Multiple Outputs}). + +Packages with a corresponding name (and optionally version) are searched for among the GNU distribution modules (@pxref{Package Modules}). +Alternatively, a @var{package} can directly specify a store file name +such as @file{/gnu/store/...-guile-3.0.7}, as produced by, e.g., +@code{guix build}. + @cindex propagated inputs Sometimes packages have @dfn{propagated inputs}: these are dependencies that automatically get installed along with the required package @@ -4834,6 +4840,15 @@ invocation can be expensive: it may have to download or even build a large number of packages; the result is cached though and subsequent commands targeting the same commit are almost instantaneous. +@quotation Note +The history of Guix is immutable and @command{guix time-machine} +provides the exact same software as they are in a specific Guix +revision. Naturally, no security fixes are provided for old versions +of Guix or its channels. A careless use of @command{guix time-machine} +opens the door to security vulnerabilities. @xref{Invoking guix pull, +@option{--allow-downgrades}}. +@end quotation + The general syntax is: @example @@ -8080,20 +8095,20 @@ following forms: @item (delete @var{name}@dots{}) Delete from the inputs packages with the given @var{name}s (strings). -@item (append @var{package}@dots{}) -Add @var{package}s to the end of the input list. - @item (prepend @var{package}@dots{}) Add @var{package}s to the front of the input list. + +@item (append @var{package}@dots{}) +Add @var{package}s to the end of the input list. @end table The example below removes the GMP and ACL inputs of Coreutils and adds -libcap to the back of the input list: +libcap to the front of the input list: @lisp (modify-inputs (package-inputs coreutils) (delete "gmp" "acl") - (append libcap)) + (prepend libcap)) @end lisp The example below replaces the @code{guile} package from the inputs of @@ -8104,7 +8119,7 @@ The example below replaces the @code{guile} package from the inputs of (replace "guile" guile-2.2)) @end lisp -The last type of clause is @code{prepend}, to add inputs to the front of +The last type of clause is @code{append}, to add inputs at the back of the list. @end deffn |