Differences

This shows you the differences between two versions of the page.

--- manuals:distributions:guix [2023/12/20 12:18] – tomas.volf
+++ manuals:distributions:guix [2026/08/19 14:43] (current) – Update Guix platform inheritance and deployment examples aither
@@ Line 1: / Line 1: @@
+<page>manuals:distributions:guix</page>
+<kb-managed
+  source="contract/pages/manuals-distributions-guix.txt"
+  test="kb/guix#*"
+/>
 ====== GNU Guix System ======
-[[https://guix.gnu.org|GNU Guix System]] is a distribution based on Guix package
-manager. It allows one to declaratively configure the system and its services,
-a concept shared with [[manuals:distributions:nixos]]. While NixOS uses the Nix
-language, Guix is built with Guile Scheme. This page describes Guix specifics on vpsFree.cz's
-VPS.
-===== Configuration =====
+[[https://guix.gnu.org/|GNU Guix System]] is a distribution where the system,
-The VPS is created from a template which contains a minimal system with SSH.
+services, and packages are described declaratively in Guile Scheme. Like
-You can log in with a generated password or deploy your public key using vpsAdmin.
+[[manuals:distributions:nixos|NixOS]], it creates system generations when the
-The system can then be configured using ''guix system reconfigure''.
+configuration changes and lets you return to an earlier generation.
-System configuration is stored in directory ''/etc/config'':
+===== How the template works =====
-  * ''vpsadminos.scm'' contains configuration specific to our environment
+The vpsFree template contains a minimal Guix System with OpenSSH and two files:
-  * ''system.scm'' loads ''vpsadminos.scm'' and is meant to be edited to configure the system
-<code>
+  * ''/etc/config/system.scm'' is your main system configuration;
-# . /etc/profile
+  * ''/etc/config/vpsadminos.scm'' makes Guix work inside a vpsAdminOS container.
-# guix pull
-# hash guix
-# guix system reconfigure /etc/config/system.scm
-</code>
-Networking is handled by /ifcfg.add script, which is generated by vpsadminos on every VPS restart.  The script is executed using vpsadminos-networking shepherd service.  Due to how dynamic the environment is (IPv6 route changes on every reboot), using static-networking-service-type is simply not possible.
+''system.scm'' resolves ''%ct-operating-system-base'' from the ''vpsadminos''
+module and inherits it. Keep the module lookup and inheritance: the platform
+base provides the container bootloader, file systems, kernel placeholder,
+packages, services, and network integration. The current versions of both files
+are available in the
+[[https://github.com/vpsfreecz/vpsadminos/tree/staging/image-scripts/images/guix|Guix template sources]].
-===== Known issues =====
+The kernel is managed by vpsAdminOS. Do not add your own Linux kernel or a
+bootloader intended for a physical machine to the configuration.
-  * halt (graceful shutdown) has been observed to sometimes hang, please report in case it's still a problem.
+===== Editing the configuration =====
-  * cgroups v1 are not mounted. cgroups do not seem to be needed by the base system, contact us in case it's a problem for some service or submit a patch to the [[https://github.com/vpsfreecz/vpsadminos/tree/staging/image-scripts/images/guix|template]].
-  * Hostname cannot be set using the vpsAdmin.
-  * /gnu/store is not mounted with noatime flag.  This could lead to reproducibility issues.
-===== Alternative configuration for guix deploy =====
+Start by editing ''/etc/config/system.scm''. The host name, timezone, and locale
+are visible there as defaults that you can change. You can also add fields such
+as ''packages'', which Guix evaluates directly. Keep the ''platform-system''
+lookup and ''(inherit platform-system)'' so the platform-specific settings
+remain active.
-Slightly adjusted, single file, alternative configuration can be found below to be used as a starting point for your ''guix deploy'' setup.  It pretty much is just an amalgamation of the default setup into one file, with few tweaks here and there.  Differences are:
+When changing services, first derive and bind the service list outside the
+''operating-system'' record, then assign that binding to the ''services'' field.
+The deployment example below follows this pattern. Guix evaluates service
+fields after loading the configuration, so they must not depend on bindings
+from its temporary configuration module.
-  * No dhcp-client-service-type, 'networking is handled directly by vpsadminos-networking service.
+Activate the configuration as ''root'':
-  * No password authentication is allowed for ssh.
-  * In a single file.
-  * Added parts for guix deploy
-<code scheme>
+<code bash>
-(use-modules (gnu)
+#!/usr/bin/env bash
-             (gnu machine)
+set -eo pipefail
-             (gnu machine ssh)
-             (gnu packages bash)
-             (gnu packages certs)
-             (gnu packages ssh)
-             (gnu services networking)
-             (gnu services shepherd)
-             (gnu services ssh)
-             (guix build-system trivial)
-             (guix packages)
-             (srfi srfi-1))
-;;; The bootloader is not required.  This is running inside a container, and the
+# Use the Guix revision that built the active system generation.
-;;; start menu is populated by parsing /var/guix/profiles.  However bootloader
+export GUIX_PROFILE=/run/current-system/profile
-;;; is a mandatory field, and the typical grub-bootloader requires users to
+# shellcheck disable=SC1091
-;;; always pass the --no-bootloader flag.  By providing this bootloader
+. "$GUIX_PROFILE/etc/profile"
-;;; configuration (it does not do anything, but installs fine), we remove the
+hash guix
-;;; need to remember to pass the flag.  At the cost of ~8MB in /boot.
-(define %ct-bootloader
-  (bootloader-configuration
-   ;; This one can be installed without efivars and without block device.
-   (bootloader grub-efi-netboot-removable-bootloader)
-   (targets '("/boot"))))
-;;; It seems any package can be passed as an kernel, so create empty one for
+test -r /etc/config/system.scm
-;;; that purpose.
+test -r /etc/config/vpsadminos.scm
-(define %ct-dummy-kernel
+test -r /run/current-system/channels.scm
-  (package
+guix time-machine -C /run/current-system/channels.scm -- \
-    (name "dummy-kernel")
+  system reconfigure -L /etc/config /etc/config/system.scm
-    (version "1")
+</code>
-    (source #f)
-    (build-system trivial-build-system)
-    (arguments
-     (list
-      #:builder #~(mkdir #$output)))
-    (synopsis "Dummy kernel")
-    (description
-     "In container environment, the kernel is provided by the host.  However we
-still need to specify a kernel in the operating-system definition, hence this
-package.")
-    (home-page #f)
-    (license #f)))
-(define %ct-file-systems
+''guix time-machine'' uses the channels recorded in the active generation, so
-  (cons* (file-system                   ; Dummy rootfs
+reconfiguration does not depend on later channel-history changes. The
-           (device "/dev/null")
+''-L /etc/config'' option makes the ''vpsadminos'' module available. The command
-           (mount-point "/")
+builds and immediately activates a new generation. Before logging out, verify
-           (type "dummy"))
+that SSH and the services you need are running. See the manuals for
-         ;; Used by vpsadminos scripting.  Can go away once /run as a whole is
+[[https://guix.gnu.org/manual/en/html_node/Invoking-guix-time_002dmachine.html|guix time-machine]]
-         ;; on tmpfs.
+and [[https://guix.gnu.org/manual/en/html_node/Invoking-guix-system.html|guix system]]
-         (file-system
+for details.
-           (device "none")
-           (mount-point "/run/vpsadminos")
-           (type "tmpfs")
-           (check? #f)
-           (flags '(no-suid no-dev no-exec))
-           (options "mode=0755")
-           (create-mount-point? #t))
-         (map (λ (fs)
-                (cond
-                 ;; %immutable-store is usually mounted with no-atime.  That
-                 ;; does not work in the vpsFree (causing the boot to hang), so
-                 ;; we need to delete the flag.
-                 ((eq? fs %immutable-store)
-                  (file-system
-                    (inherit fs)
-                    (flags (delete 'no-atime (file-system-flags fs)))))
-                 (else
-                  fs)))
-              (fold delete
-                    %base-file-systems
-                    (list
-                     ;; Already mounted by vpsadminos
-                     %pseudo-terminal-file-system
-                     ;; Cannot be mounted due to the permissions
-                     %debug-file-system
-                     %efivars-file-system)))))
-(define vpsadminos-networking
+===== Updating Guix =====
-  (shepherd-service
-   (requirement '(file-system-/run/vpsadminos))
-   (provision '(vpsadminos-networking networking loopback))
-   (documentation "Setup network on vpsAdminOS")
-   (one-shot? #t)
-   (start #~(lambda _ (invoke #$(file-append bash "/bin/bash")
-                              "-c" "
-[ -f  /run/vpsadminos/network ] && exit 0
-touch /run/vpsadminos/network
-\"$SHELL\" /ifcfg.add
-")))))
-(define %ct-services
+The example above selects the Guix revision and channels that built the active
-  (cons* (service mingetty-service-type
+system generation. Reconfiguration therefore does not require ''guix pull''
-                  (mingetty-configuration
+before every configuration change, keeping repeated deployments predictable.
-                   (tty "console")))
-         (simple-service 'vpsadminos-networking
-                         shepherd-root-service-type (list vpsadminos-networking))
-         (modify-services %base-services
+When you intentionally update Guix, first record the current channels with
-           (delete console-font-service-type)
+''guix describe''. Then run ''guix pull'', load the updated profile as instructed
-           (delete agetty-service-type)
+by the command, and reconfigure again. Read the news before changing revisions,
-           (delete mingetty-service-type)
+and allow extra time, memory, and disk space for the build. The
-           (delete urandom-seed-service-type)
+[[https://guix.gnu.org/manual/en/html_node/Channels.html|channels manual]]
-           ;; loopback is configured by vpsadminos-networking
+explains channels and pinned revisions.
-           (delete static-networking-service-type)
-           ;; We need no rules.
-           (udev-service-type config =>
-                              (udev-configuration
-                               (inherit config)
-                               (rules '()))))))
-(define %signing-key
+===== Network and SSH =====
-  ;; Fill this with your local signing key (/etc/guix/signing-key.pub).
-  "...")
-(define %system
+Do not configure the primary network with ''static-networking-service-type''.
-  (operating-system
+At every boot, vpsAdminOS creates ''/ifcfg.add'' from the current addresses and
-    (host-name "guix")
+the ''vpsadminos-networking'' service runs it. Add any custom networking
-    ;; Servers usually use UTC regardless of the location.
+services on top of this layer.
-    (timezone "Etc/UTC")
-    (locale "en_US.utf8")
-    (kernel %ct-dummy-kernel)
+For convenient first access, the default template permits SSH login as
-    (bootloader %ct-bootloader)
+''root''. Once your keys work, you can harden access as described in
+[[manuals:server:ssh]].
-    (firmware '())
+===== Deploying with guix deploy =====
-    (initrd-modules '())
-    (packages (cons* nss-certs
+If you manage several Guix VPSes, you can keep their configurations on one
-                     %base-packages))
+coordinator Guix system and deploy them with
+[[https://guix.gnu.org/manual/en/html_node/Invoking-guix-deploy.html|guix deploy]].
+The complete configuration below is a starting point for one VPS. You maintain
+only ''deploy.scm''; the container details continue to come from the maintained
+''/etc/config/vpsadminos.scm'' module.
-    (essential-services
+The coordinator needs the SSH key ''/root/.ssh/id_ed25519'', and you must add
-     (modify-services
+its public part to ''root'' on the target VPS before the first deployment. Test
-         (operating-system-default-essential-services this-operating-system)
+key-only login first. Run ''cat /etc/ssh/ssh_host_ed25519_key.pub'' on the target
-       (delete firmware-service-type)
+VPS and verify the resulting key fingerprint by following the
-       (delete (service-kind %linux-bare-metal-service))))
+[[manuals:server:ssh|SSH guide]]. The configuration needs the whole line
+beginning with ''ssh-ed25519'', not just the fingerprint.
-    (file-systems %ct-file-systems)
+Save this configuration as ''/etc/config/deploy.scm'' on the coordinator and
+replace the target VPS address and host key:
-    (services
+<code scheme>
-     (cons* (service openssh-service-type
+;; Load the maintained vpsAdminOS container integration.
-                     (openssh-configuration
+(add-to-load-path "/etc/config")
-                      (openssh openssh-sans-x)
+(use-modules (gnu)
-                      (permit-root-login #t)
+             (gnu machine)
-                      ;; Only keys are allowed.
+             (gnu machine ssh)
-                      (password-authentication? #f)))
+             (gnu services base))
-            (simple-service 'extra-authorized-keys guix-service-type
+(use-service-modules ssh)
-                            (guix-extension
-                             (authorized-keys
-                              (list (plain-file "signing-key" %signing-key)))))
-            %ct-services))))
-;;; Set this to the SSH key of the machine.
+(let* ((platform-system
-(define %host-key
+        (module-ref (resolve-interface '(vpsadminos))
-  "ssh-ed25519 ...")
+                    '%ct-operating-system-base))
+       ;; These files belong to the machine from which you run guix deploy.
+       (controller-signing-key
+        (local-file "/etc/guix/signing-key.pub"))
+       (root-ssh-key
+        (local-file "/root/.ssh/id_ed25519.pub"))
+       ;; Build the service list before assigning the delayed services field.
+       (user-services
+        (cons
+         (simple-service 'controller-signing-key
+                         guix-service-type
+                         (guix-extension
+                          (authorized-keys
+                           (list controller-signing-key))))
+         (modify-services
+             (operating-system-user-services platform-system)
+           (openssh-service-type config =>
+             (openssh-configuration
+              (inherit config)
+              (permit-root-login 'prohibit-password)
+              (password-authentication? #f)
+              (authorized-keys
+               `(("root" ,root-ssh-key))))))))
+       (system
+        (operating-system
+          (inherit platform-system)
+          (host-name "guix-target")
+          (timezone "Etc/UTC")
+          (locale "en_US.utf8")
+          (services user-services)))
+       (target-machine
+        (machine
+          (operating-system system)
+          (environment managed-host-environment-type)
+          (configuration
+           (machine-ssh-configuration
+            ;; Replace the address and host key with those of your target VPS.
+            (host-name "192.0.2.3")
+            (system "x86_64-linux")
+            (user "root")
+            (identity "/root/.ssh/id_ed25519")
+            (host-key "ssh-ed25519 REPLACE_WITH_TARGET_HOST_KEY")
+            (authorize? #t)
+            (allow-downgrades? #f)
+            ;; vpsAdminOS supplies the kernel and exposes a dummy /dev/null root.
+            ;; Guix's bare-metal file-system/initrd checks cannot inspect it.
+            (safety-checks? #f))))))
+  (list target-machine))
+</code>
-(define %machine
+First load the configuration without deploying it with ''guix time-machine -C
-  (machine
+/run/current-system/channels.scm -- deploy -L /etc/config
-   (operating-system %system)
+/etc/config/deploy.scm --dry-run''. Then run the same command without
-   (environment managed-host-environment-type)
+''--dry-run''. The first deployment automatically authorizes the coordinator's
-   (configuration (machine-ssh-configuration
+signing key on the target, and the declaration keeps it authorized in the new
-                   ;; Put the IP or host name here.
+generation.
-                   (host-name "...")
-                   (system "x86_64-linux")
-                   (host-key %host-key)
-                   (allow-downgrades? #t)
-                   (safety-checks? #f)))))
-(list %machine)
+The configuration deliberately allows only key-based ''root'' login and
+verifies the target host key. The container-specific ''safety-checks? #f''
+disables Guix checks for physical file systems and initrd modules: vpsAdminOS
+supplies the kernel and its integration module exposes a dummy ''/dev/null''
+root which current Guix cannot inspect. Downgrade protection stays enabled.
+If deployment fails, fix its cause instead of enabling
+''allow-downgrades?''.
-</code>
+===== Generations and recovery =====
+List generations with ''guix system list-generations''. Verify the new system
+before deleting older generations. The
+[[https://guix.gnu.org/manual/en/html_node/Invoking-guix-system.html|Guix manual]]
+describes rollback and generation management.
+If a new configuration does not boot or you lose SSH access, follow the
+[[manuals:vps:console|remote console guide]]. The
+[[manuals:vps:start_menu|vpsAdminOS start menu guide]] explains how to restore
+an older Guix generation. Fix the configuration and reconfigure again.
-If you will go via the guix deploy route, you should likely delete the /etc/config directory to prevent any confusion.

Knowledge base

User Tools

Site Tools

Differences

Page Tools