Nixos-rebuild: Difference between revisions

(2 intermediate revisions by 2 users not shown)

Line 1:

'''nixos-rebuild''' is the NixOS command used to apply changes made to the system configuration. It can also be used for a variety of other tasks related to managing the state of a NixOS system.

==~~=Basic functionality=~~==

== Usage ==

NixOS follows a "declarative configuration" approach, which means that the proper way to modify your system is to make changes to your system configuration (typically <code>/etc/nixos/configuration.nix</code>), and then ''rebuild'' your system with <code>nixos-rebuild</code>:

Line 22:

Line 24:

* <code>--upgrade</code>: Update the <code>nixos</code> channel of the root user before building the configuration.

=== Deploying on other machines ===

<code>nixos-rebuild</code> can also be used to build and deploy system configurations on remote hosts via SSH. To use a remote host to build your system and deploy it on the current host, use:

Line 45:

Line 48:

For a full list of sub-commands and options, see the <code>nixos-rebuild</code> man page.

==== Deploying on a different architecture ====

There is currently a regression within <code>nixos-rebuild</code> that causes the local <code>nixos-rebuild</code> to invoke the binaries for the target architecture on the local system. This will naturally fail, throwing an ''"Exec format error".''<ref>https://github.com/NixOS/nixpkgs/issues/166499</ref> This can be bypassed by running <code>nixos-rebuild</code> with the <code>--fast</code> flag.

===Rolling back to a specific generation===

As noted earlier, it possible to switch to the previous generation using the command <code>nixos-rebuild switch --rollback</code>

As of December 2024, <code>nixos-rebuild</code> doesn't have built-in functionality to switch to a generation earlier than the previous. However, there is an [https://github.com/NixOS/nixpkgs/pull/105910/files open pull request] that adds this functionality.

It is possible to manually simulate the behavior from this PR in the meantime. Run the following command to list your generations:

$ nixos-rebuild list-generations

Generation Build-date NixOS version Kernel Configuration Revision Specialisation

1054 current 2024-12-02 08:47:16 24.11.20241130.62c435d 6.12.1 *

1053 2024-12-02 08:44:23 24.11.20241130.62c435d 6.12.1 *

1052 2024-12-02 08:25:54 24.11.20241130.62c435d 6.12.1 *

...

</syntaxHighlight>

Run the command <code>/nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch</code> where <code>N</code> is the generation number you want to switch to.

You can manually see that <code>/nix/var/nix/profiles/</code> contains symlinks to the system closures associated with the listed generations by <code>nixos-rebuild list-generations</code> above:

$ ls -l /nix/var/nix/profiles/

lrwxrwxrwx - root root 2 12月 08:25 system-1052-link -> /nix/store/a5sh1kam9j42gcgca11ax5wg0iaiccab-nixos-system-onyx-24.11.20241130.62c435d

lrwxrwxrwx - root root 2 12月 08:44 system-1053-link -> /nix/store/nhba65kybj6y0gyd307mf9wj3089rf08-nixos-system-onyx-24.11.20241130.62c435d

lrwxrwxrwx - root root 2 12月 08:47 system-1054-link -> /nix/store/97wrfk1dmgbivw35wrkmrg0d0c1zhviw-nixos-system-onyx-24.11.20241130.62c435d

</syntaxHighlight>

===Specifying a different configuration location===

Line 68:

Line 102:

# nixos-rebuild switch --flake /etc/nixos#hostname

</syntaxHighlight>

{{Note|If your flake files are part of a Git repository, only tracked files are considered for building. Nix flakes deliberately ignores untracked files in the repository and do not copy them over to the Nix store. You need to stage untracked files first if they are relevant for your flake config. Otherwise, an error will be raised that the untracked file could not be found at the flake's Nix store path.}}

===Internals===

@@ Line 1: / Line 1: @@
+{{DISPLAYTITLE:nixos-rebuild}}{{Cleanup}}
 '''nixos-rebuild''' is the NixOS command used to apply changes made to the system configuration. It can also be used for a variety of other tasks related to managing the state of a NixOS system.
-===Basic functionality===
+== Usage ==
 NixOS follows a "declarative configuration" approach, which means that the proper way to modify your system is to make changes to your system configuration (typically <code>/etc/nixos/configuration.nix</code>), and then ''rebuild'' your system with <code>nixos-rebuild</code>:
@@ Line 22: / Line 24: @@
 * <code>--upgrade</code>: Update the <code>nixos</code> channel of the root user before building the configuration.
+=== Deploying on other machines ===
 <code>nixos-rebuild</code> can also be used to build and deploy system configurations on remote hosts via SSH. To use a remote host to build your system and deploy it on the current host, use:
 <syntaxHighlight lang=console>
@@ Line 45: / Line 48: @@
 For a full list of sub-commands and options, see the <code>nixos-rebuild</code> man page.
+==== Deploying on a different architecture ====
+There is currently a regression within <code>nixos-rebuild</code> that causes the local <code>nixos-rebuild</code> to invoke the binaries for the target architecture on the local system. This will naturally fail, throwing an ''"Exec format error".''<ref>https://github.com/NixOS/nixpkgs/issues/166499</ref> This can be bypassed by running <code>nixos-rebuild</code> with the <code>--fast</code> flag.
+===Rolling back to a specific generation===
+As noted earlier, it possible to switch to the previous generation using the command <code>nixos-rebuild switch --rollback</code>
+As of December 2024, <code>nixos-rebuild</code> doesn't have built-in functionality to switch to a generation earlier than the previous. However, there is an [https://github.com/NixOS/nixpkgs/pull/105910/files open pull request] that adds this functionality.
+It is possible to manually simulate the behavior from this PR in the meantime. Run the following command to list your generations:
+<syntaxHighlight lang=console>
+$ nixos-rebuild list-generations
+Generation    Build-date           NixOS version           Kernel  Configuration Revision  Specialisation
+current  2024-12-02 08:47:16  24.11.20241130.62c435d  6.12.1                          *
+          2024-12-02 08:44:23  24.11.20241130.62c435d  6.12.1                          *
+          2024-12-02 08:25:54  24.11.20241130.62c435d  6.12.1                          *
+...
+</syntaxHighlight>
+Run the command <code>/nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch</code> where <code>N</code> is the generation number you want to switch to.
+You can manually see that <code>/nix/var/nix/profiles/</code> contains symlinks to the system closures associated with the listed generations by <code>nixos-rebuild list-generations</code> above:
+<syntaxHighlight lang=console>
+$ ls -l /nix/var/nix/profiles/
+lrwxrwxrwx - root root  2 12月 08:25 system-1052-link -> /nix/store/a5sh1kam9j42gcgca11ax5wg0iaiccab-nixos-system-onyx-24.11.20241130.62c435d
+lrwxrwxrwx - root root  2 12月 08:44 system-1053-link -> /nix/store/nhba65kybj6y0gyd307mf9wj3089rf08-nixos-system-onyx-24.11.20241130.62c435d
+lrwxrwxrwx - root root  2 12月 08:47 system-1054-link -> /nix/store/97wrfk1dmgbivw35wrkmrg0d0c1zhviw-nixos-system-onyx-24.11.20241130.62c435d
+</syntaxHighlight>
 ===Specifying a different configuration location===
@@ Line 68: / Line 102: @@
 # nixos-rebuild switch --flake /etc/nixos#hostname
 </syntaxHighlight>
+{{Note|If your flake files are part of a Git repository, only tracked files are considered for building. Nix flakes deliberately ignores untracked files in the repository and do not copy them over to the Nix store. You need to stage untracked files first if they are relevant for your flake config. Otherwise, an error will be raised that the untracked file could not be found at the flake's Nix store path.}}
 ===Internals===