diff --git a/nixos/doc/manual/installation/building-images-via-nixos-rebuild-build-image.chapter.md b/nixos/doc/manual/installation/building-images-via-nixos-rebuild-build-image.chapter.md new file mode 100644 index 000000000000..378b1163a6e3 --- /dev/null +++ b/nixos/doc/manual/installation/building-images-via-nixos-rebuild-build-image.chapter.md @@ -0,0 +1,16 @@ +# Building Images with `nixos-rebuild build-image` {#sec-image-nixos-rebuild-build-image} + +Nixpkgs contains a variety of modules to build custom images for different virtualization platforms and cloud providers, such as e.g. `amazon-image.nix` and `proxmox-lxc.nix`. + +While those can be imported individually, `system.build.images` provides an attribute set mapping variant names to image derivations. Available variants are defined - end extendable - in `image.modules`, an attribute set mapping variant names to a list of NixOS modules. + +All of those images can be built via both, their `system.build.image` attribute, and the CLI `nixos-rebuild build-image`. To build i.e. an Amazon image from your existing NixOS configuration: + +```ShellSession +$ nixos-rebuild build-image --image-variant amazon +$ ls result +nixos-image-amazon-25.05pre-git-x86_64-linux.vhd nix-support +``` + +To get a list of all variants available, run `nixos-rebuild build-image` without arguments. + diff --git a/nixos/doc/manual/installation/building-nixos.chapter.md b/nixos/doc/manual/installation/building-nixos.chapter.md index 7b0b5ea1c447..2b4dba57c10f 100644 --- a/nixos/doc/manual/installation/building-nixos.chapter.md +++ b/nixos/doc/manual/installation/building-nixos.chapter.md @@ -1,7 +1,7 @@ # Building a NixOS (Live) ISO {#sec-building-image} Default live installer configurations are available inside `nixos/modules/installer/cd-dvd`. -For building other system images, [nixos-generators] is a good place to start looking at. +For building other system images, see [Building Images with `nixos-rebuild build-image`](#sec-image-nixos-rebuild-build-image). You have two options: @@ -14,8 +14,6 @@ on which they immediately depend in order to work correctly. However, if you are confident, you can opt to override those enforced values with `mkForce`. -[nixos-generators]: https://github.com/nix-community/nixos-generators - ## Practical Instructions {#sec-building-image-instructions} To build an ISO image for the channel `nixos-unstable`: @@ -30,7 +28,7 @@ $ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd To check the content of an ISO image, mount it like so: ```ShellSession -# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso +# mount -o loop -t iso9660 ./result/iso/nixos-image-25.05pre-git-x86_64-linux.iso /mnt/iso ``` ## Additional drivers or firmware {#sec-building-image-drivers} diff --git a/nixos/doc/manual/installation/installation.md b/nixos/doc/manual/installation/installation.md index f3b1773d865c..04bad5be1d46 100644 --- a/nixos/doc/manual/installation/installation.md +++ b/nixos/doc/manual/installation/installation.md @@ -8,5 +8,6 @@ installing.chapter.md changing-config.chapter.md upgrading.chapter.md building-nixos.chapter.md +building-images-via-nixos-rebuild-build-image.chapter.md building-images-via-systemd-repart.chapter.md ``` diff --git a/nixos/doc/manual/redirects.json b/nixos/doc/manual/redirects.json index f792750a1ea4..428dbdcc54c2 100644 --- a/nixos/doc/manual/redirects.json +++ b/nixos/doc/manual/redirects.json @@ -167,6 +167,9 @@ "sec-building-image-tech-notes": [ "index.html#sec-building-image-tech-notes" ], + "sec-image-nixos-rebuild-build-image": [ + "index.html#sec-image-nixos-rebuild-build-image" + ], "sec-image-repart": [ "index.html#sec-image-repart" ], diff --git a/nixos/doc/manual/release-notes/rl-2505.section.md b/nixos/doc/manual/release-notes/rl-2505.section.md index 1b33e663a98d..595b6af0e339 100644 --- a/nixos/doc/manual/release-notes/rl-2505.section.md +++ b/nixos/doc/manual/release-notes/rl-2505.section.md @@ -8,6 +8,10 @@ - `nixos-rebuild-ng`, a full rewrite of `nixos-rebuild` in Python, is available for testing. You can enable it by setting [system.rebuild.enableNg](options.html#opt-system.rebuild.enableNg) in your configuration (this will replace the old `nixos-rebuild`), or by adding `nixos-rebuild-ng` to your `environment.systemPackages` (in this case, it will live side-by-side with `nixos-rebuild` as `nixos-rebuild-ng`). It is expected that the next major version of NixOS (25.11) will enable `system.rebuild.enableNg` by default. +- A `nixos-rebuild build-image` sub-command has been added. + + It allows users to build platform-specific (disk) images from their NixOS configurations. `nixos-rebuild build-image` works similar to the popular [nix-community/nixos-generators](https://github.com/nix-community/nixos-generators) project. See new [section on image building in the nixpkgs manual](https://nixos.org/manual/nixpkgs/unstable/#sec-image-nixos-rebuild-build-image). + ## New Modules {#sec-release-25.05-new-modules} @@ -132,6 +136,32 @@ - `python3Packages.opentracing` has been removed due to being unmaintained upstream. [OpenTelemetry](https://opentelemetry.io/) is the recommended replacement. +- Default file names of images generated by several builders in `system.build` have been changed as outlined in the table below. + + Names are now known at evaluation time and customizable via the new options `image.baseName`, `image.extension`, `image.fileName` and `image.filePath` with the latter returning a path relative to the derivations out path (e.g. `iso/${image.fileName` for iso images). + + | `system.build` Option | Old Filename | New Filename | + |--------------------------+------------------------------------------------------------+-----------------------------------------------------------------| + | amazonImage | nixos-amazon-image-25.05pre-git-x86_64-linux.vhd | nixos-image-amazon-25.05pre-git-x86_64-linux.vhd | + | azureImage | disk.vhd | nixos-image-azure-25.05pre-git-x86_64-linux.vhd | + | digitalOceanImage | nixos.qcow2.gz | nixos-image-digital-ocean-25.05pre-git-x86_64-linux.qcow2.gz | + | googleComputeImage | nixos-image-25.05pre-git-x86_64-linux.raw.tar.gz | nixos-image-google-compute-25.05pre-git-x86_64-linux.raw.tar.gz | + | hypervImage | nixos-25.05pre-git-x86_64-linux.vhdx | nixos-image-hyperv-25.05pre-git-x86_64-linux.vhdx | + | isoImage (installer) | nixos-25.05pre-git-x86_64-linux.iso | nixos-image-25.05pre-git-x86_64-linux.iso | + | isoImage | nixos.iso | nixos-image-25.05pre-git-x86_64-linux.iso | + | kubevirtImage | nixos.qcow2 | nixos-image-kubevirt-25.05pre-git-x86_64-linux.qcow2 | + | linodeImage | nixos-image-25.05pre-git-x86_64-linux.img.gz | nixos-image-linode-25.05pre-git-x86_64-linux.img.gz | + | metadata (lxc-container) | nixos-system-x86_64-linux.tar.xz | nixos-image-lxc-metadata-25.05pre-git-x86_64-linux.tar.xz | + | OCIImage | nixos.qcow2 | nixos-image-oci-25.05pre-git-x86_64-linux.qcow2 | + | openstackImage (zfs) | nixos-openstack-image-25.05pre-git-x86_64-linux.root.qcow2 | nixos-image-openstack-zfs-25.05pre-git-x86_64-linux.root.qcow2 | + | openstackImage | nixos.qcow2 | nixos-image-openstack-25.05pre-git-x86_64-linux.qcow2 | + | sdImage | nixos-sd-image-25.05pre-git-x86_64-linux.img.zst | nixos-image-sd-card-25.05pre-git-x86_64-linux.img.zst | + | tarball (lxc-container) | nixos-system-x86_64-linux.tar.xz | nixos-image-lxc-25.05pre-git-x86_64-linux.tar.xz | + | tarball (proxmox-lxc) | nixos-system-x86_64-linux.tar.xz | nixos-image-lxc-proxmox-25.05pre-git-x86_64-linux.tar.xz | + | vagrantVirtualbox | nixos-25.05pre-git-x86_64-linux.ova | nixos-image-virtualbox-25.05pre-git-x86_64-linux.ova | + | virtualBoxOVA | virtualbox-vagrant.box | nixos-image-vagrant-virtualbox-25.05pre-git-x86_64-linux.ova | + | vmwareImage | nixos-25.05pre-git-x86_64-linux.vmdk | nixos-image-vmware-25.05pre-git-x86_64-linux.vmdk | + - the notmuch vim plugin now lives in a separate output of the `notmuch` package. Installing `notmuch` will not bring the notmuch vim package anymore, add `vimPlugins.notmuch-vim` to your (Neo)vim configuration if you want the diff --git a/nixos/maintainers/scripts/ec2/README.md b/nixos/maintainers/scripts/ec2/README.md index eb2c9088d5a2..575b13e88a1c 100644 --- a/nixos/maintainers/scripts/ec2/README.md +++ b/nixos/maintainers/scripts/ec2/README.md @@ -18,10 +18,10 @@ nix run nixpkgs#upload-ami -- --image-info ./result/nix-support/image-info.json ## How to build your own NixOS config into an AMI -I suggest looking at https://github.com/nix-community/nixos-generators for a user-friendly interface. +Use `nixos-rebuild build-image` as follows: ```bash -nixos-generate -c ./my-config.nix -f amazon +NIXOS_CONFIG="$(pwd)/my-config.nix" nixos-rebuild build-image --image-variant amazon export AWS_REGION=us-west-2 export AWS_PROFILE=my-profile diff --git a/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.8 b/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.8 index 25ae9efba1c7..a66f27892a1a 100644 --- a/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.8 +++ b/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.8 @@ -10,7 +10,7 @@ .Sh SYNOPSIS .Nm .Bro -.Cm switch | boot | test | build | dry-build | dry-activate | edit | repl | build-vm | build-vm-with-bootloader | list-generations Op Fl -json +.Cm switch | boot | test | build | dry-build | dry-activate | edit | repl | build-vm | build-vm-with-bootloader | build-image | list-generations Op Fl -json .Brc .br .Op Fl -upgrade | -upgrade-all @@ -34,6 +34,8 @@ .Op Fl -profile-name | p Ar name .Op Fl -specialisation | c Ar name .br +.Op Fl -image-variant Ar variant +.br .Op Fl -build-host Va host .Op Fl -target-host Va host .Op Fl -use-remote-sudo @@ -226,6 +228,16 @@ containing a .Pa /boot partition. . +.It Cm build-image +Build a disk-image variant, pre-configured for the given platform/provider. +Select a variant with the +.Fl --image-variant +option or run without any options to get a list of available variants. + +.Bd -literal -offset indent +$ nixos-rebuild build-image --image-variant proxmox +.Ed +. .It Cm list-generations Op Fl -json List the available generations in a similar manner to the boot loader menu. It shows the generation number, build date and time, NixOS version, @@ -323,6 +335,12 @@ The new configuration will appear in the GRUB 2 submenu Activates given specialisation; when not specified, switching and testing will activate the base, unspecialised system. . +.It Fl -image-variant Ar variant +Selects an image variant to build from +the +.Va config.system.build.images +attribute of the given configuration. A list of variants is printed if this option remains unset. +. .It Fl -build-host Ar host Instead of building the new configuration locally, use the specified host to perform the build. The host needs to be accessible with diff --git a/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.sh b/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.sh index 9e4fde59172c..864b20c25221 100755 --- a/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.sh +++ b/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.sh @@ -29,6 +29,7 @@ upgrade= upgrade_all= profile=/nix/var/nix/profiles/system specialisation= +imageVariant= buildHost= targetHost= remoteSudo= @@ -52,7 +53,7 @@ while [ "$#" -gt 0 ]; do --help) showSyntax ;; - switch|boot|test|build|edit|repl|dry-build|dry-run|dry-activate|build-vm|build-vm-with-bootloader|list-generations) + switch|boot|test|build|edit|repl|dry-build|dry-run|dry-activate|build-vm|build-vm-with-bootloader|build-image|list-generations) if [ "$i" = dry-run ]; then i=dry-build; fi if [ "$i" = list-generations ]; then buildNix= @@ -153,6 +154,14 @@ while [ "$#" -gt 0 ]; do specialisation="$1" shift 1 ;; + --image-variant) + if [ -z "$1" ]; then + log "$0: ‘--image-variant’ requires an argument" + exit 1 + fi + imageVariant="$1" + shift 1 + ;; --build-host) buildHost="$1" shift 1 @@ -819,6 +828,43 @@ if [ -z "$rollback" ]; then else pathToConfig="$(nixFlakeBuild "$flake#$flakeAttr.config.system.build.vmWithBootLoader" "${extraBuildFlags[@]}" "${lockFlags[@]}")" fi + elif [ "$action" = build-image ]; then + if [[ -z $buildingAttribute ]]; then + variants="$( + runCmd nix-instantiate --eval --strict --json --expr \ + "let + value = import \"$(realpath $buildFile)\"; + set = if builtins.isFunction value then value {} else value; + in builtins.mapAttrs (n: v: v.passthru.filePath) set.${attr:+$attr.}config.system.build.images" \ + "${extraBuildFlags[@]}" + )" + elif [[ -z $flake ]]; then + variants="$( + runCmd nix-instantiate --eval --strict --json --expr \ + "with import {}; builtins.mapAttrs (n: v: v.passthru.filePath) config.system.build.images" \ + "${extraBuildFlags[@]}" + )" + else + variants="$( + runCmd nix "${flakeFlags[@]}" eval --json \ + "$flake#$flakeAttr.config.system.build.images" \ + --apply "builtins.mapAttrs (n: v: v.passthru.filePath)" "${evalArgs[@]}" "${extraBuildFlags[@]}" + )" + fi + if ! echo "$variants" | jq -e --arg variant "$imageVariant" "keys | any(. == \$variant)" > /dev/null; then + echo -e "Please specify one of the following supported image variants via --image-variant:\n" >&2 + echo "$variants" | jq -r '. | keys | join ("\n")' + exit 1 + fi + imageName="$(echo "$variants" | jq -r --arg variant "$imageVariant" ".[\$variant]")" + + if [[ -z $buildingAttribute ]]; then + pathToConfig="$(nixBuild $buildFile -A "${attr:+$attr.}config.system.build.images.${imageVariant}" "${extraBuildFlags[@]}")" + elif [[ -z $flake ]]; then + pathToConfig="$(nixBuild '' -A config.system.build.images.${imageVariant} -k "${extraBuildFlags[@]}")" + else + pathToConfig="$(nixFlakeBuild "$flake#$flakeAttr.config.system.build.images.${imageVariant}" "${extraBuildFlags[@]}" "${lockFlags[@]}")" + fi else showSyntax fi @@ -913,3 +959,8 @@ if [[ "$action" = build-vm || "$action" = build-vm-with-bootloader ]]; then Done. The virtual machine can be started by running $(echo "${pathToConfig}/bin/"run-*-vm) EOF fi + +if [[ "$action" = build-image ]]; then + echo -n "Done. The disk image can be found in " >&2 + echo "${pathToConfig}/${imageName}" +fi