diff options
Diffstat (limited to 'nixpkgs/pkgs/os-specific/linux/nixos-rebuild')
| -rw-r--r-- | nixpkgs/pkgs/os-specific/linux/nixos-rebuild/default.nix | 7 | ||||
| -rw-r--r-- | nixpkgs/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.8 | 452 |
2 files changed, 459 insertions, 0 deletions
diff --git a/nixpkgs/pkgs/os-specific/linux/nixos-rebuild/default.nix b/nixpkgs/pkgs/os-specific/linux/nixos-rebuild/default.nix index b0a00972eca2..b871c63e36d3 100644 --- a/nixpkgs/pkgs/os-specific/linux/nixos-rebuild/default.nix +++ b/nixpkgs/pkgs/os-specific/linux/nixos-rebuild/default.nix @@ -6,6 +6,7 @@ , nix , lib , nixosTests +, installShellFiles }: let fallback = import ./../../../../nixos/modules/installer/tools/nix-fallback-paths.nix; @@ -20,6 +21,12 @@ substituteAll { nix_i686_linux = fallback.i686-linux; nix_aarch64_linux = fallback.aarch64-linux; path = lib.makeBinPath [ coreutils gnused gnugrep ]; + nativeBuildInputs = [ + installShellFiles + ]; + postInstall = '' + installManPage ${./nixos-rebuild.8} + ''; # run some a simple installer tests to make sure nixos-rebuild still works for them passthru.tests = { diff --git a/nixpkgs/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.8 b/nixpkgs/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.8 new file mode 100644 index 000000000000..64bbbee411d7 --- /dev/null +++ b/nixpkgs/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.8 @@ -0,0 +1,452 @@ +.Dd January 1, 1980 +.Dt nixos-rebuild 8 +.Os +.Sh NAME +.Nm nixos-rebuild +.Nd reconfigure a NixOS machine +. +. +. +.Sh SYNOPSIS +.Nm +.Bro +.Cm switch | boot | test | build | dry-build | dry-activate | edit | build-vm | build-vm-with-bootloader +.Brc +.br +.Op Fl -upgrade | -upgrade-all +.Op Fl -install-bootloader +.Op Fl -no-build-nix +.Op Fl -fast +.Op Fl -rollback +.Op Fl -builders Ar builder-spec +.br +.Op Fl -flake Ar flake-uri +.Op Fl -no-flake +.Op Fl -override-input Ar input-name flake-uri +.br +.Op Fl -profile-name | p Ar name +.Op Fl -specialisation | c Ar name +.br +.Op Fl -build-host Va host +.Op Fl -target-host Va host +.Op Fl -use-remote-sudo +.br +.Op Fl -show-trace +.Op Fl I Va NIX_PATH +.Op Fl -verbose | v +.Op Fl -impure +.Op Fl -max-jobs | j Va number +.Op Fl -keep-failed | K +.Op Fl -keep-going | k +. +. +. +.Sh DESCRIPTION +This command updates the system so that it corresponds to the +configuration specified in +.Pa /etc/nixos/configuration.nix +or +.Pa /etc/nixos/flake.nix Ns +\&. Thus, every time you modify the configuration or any other NixOS module, you +must run +.Nm +to make the changes take effect. It builds the new system in +.Pa /nix/store Ns +, runs its activation script, and stop and (re)starts any system services if +needed. Please note that user services need to be started manually as they +aren't detected by the activation script at the moment. +. +.Pp +This command has one required argument, which specifies the desired +operation. It must be one of the following: +.Bl -tag -width indent +.It Cm switch +Build and activate the new configuration, and make it the boot default. That +is, the configuration is added to the GRUB boot menu as the default +menu entry, so that subsequent reboots will boot the system into the new +configuration. Previous configurations activated with +.Ic nixos-rebuild switch +or +.Ic nixos-rebuild boot +remain available in the GRUB menu. +.Pp +Note that if you are using specializations, running just +.Ic nixos-rebuild switch +will switch you back to the unspecialized, base system \(em in that case, you +might want to use this instead: +.Bd -literal -offset indent +$ nixos-rebuild switch --specialisation your-specialisation-name +.Ed +.Pp +This command will build all specialisations and make them bootable just +like regular +.Ic nixos-rebuild switch +does \(em the only thing different is that it will switch to given +specialisation instead of the base system; it can be also used to switch from +the base system into a specialised one, or to switch between specialisations. +. +.It Cm boot +Build the new configuration and make it the boot default (as with +.Ic nixos-rebuild switch Ns +), but do not activate it. That is, the system continues to run the previous +configuration until the next reboot. +. +.It Cm test +Build and activate the new configuration, but do not add it to the GRUB +boot menu. Thus, if you reboot the system (or if it crashes), you will +automatically revert to the default configuration (i.e. the +configuration resulting from the last call to +.Ic nixos-rebuild switch +or +.Ic nixos-rebuild boot Ns +). +.Pp +Note that if you are using specialisations, running just +.Ic nixos-rebuild test +will activate the unspecialised, base system \(em in that case, you might want +to use this instead: +.Bd -literal -offset indent +$ nixos-rebuild test --specialisation your-specialisation-name +.Ed +.Pp +This command can be also used to switch from the base system into a +specialised one, or to switch between specialisations. +. +.It Cm build +Build the new configuration, but neither activate it nor add it to the +GRUB boot menu. It leaves a symlink named +.Pa result +in the current directory, which points to the output of the top-level +.Dq system +derivation. This is essentially the same as doing +.Bd -literal -offset indent +$ nix-build /path/to/nixpkgs/nixos -A system +.Ed +.Pp +Note that you do not need to be root to run +.Ic nixos-rebuild build Ns +\&. +. +.It Cm dry-build +Show what store paths would be built or downloaded by any of the +operations above, but otherwise do nothing. +. +.It Cm dry-activate +Build the new configuration, but instead of activating it, show what +changes would be performed by the activation (i.e. by +.Ic nixos-rebuild test Ns +). For instance, this command will print which systemd units would be restarted. +The list of changes is not guaranteed to be complete. +. +.It Cm edit +Opens +.Pa configuration.nix +in the default editor. +. +.It Cm build-vm +Build a script that starts a NixOS virtual machine with the desired +configuration. It leaves a symlink +.Pa result +in the current directory that points (under +.Ql result/bin/run\- Ns Va hostname Ns \-vm Ns +) +at the script that starts the VM. Thus, to test a NixOS configuration in +a virtual machine, you should do the following: +.Bd -literal -offset indent +$ nixos-rebuild build-vm +$ ./result/bin/run-*-vm +.Ed +.Pp +The VM is implemented using the +.Ql qemu +package. For best performance, you should load the +.Ql kvm-intel +or +.Ql kvm-amd +kernel modules to get hardware virtualisation. +.Pp +The VM mounts the Nix store of the host through the 9P file system. The +host Nix store is read-only, so Nix commands that modify the Nix store +will not work in the VM. This includes commands such as +.Nm Ns +; to change the VM’s configuration, you must halt the VM and re-run the commands +above. +.Pp +The VM has its own ext3 root file system, which is automatically created when +the VM is first started, and is persistent across reboots of the VM. It is +stored in +.Ql ./ Ns Va hostname Ns .qcow2 Ns +\&. +.\" The entire file system hierarchy of the host is available in +.\" the VM under +.\" .Pa /hostfs Ns +.\" . +. +.It Cm build-vm-with-bootloader +Like +.Cm build-vm Ns +, but boots using the regular boot loader of your configuration (e.g. GRUB 1 or +2), rather than booting directly into the kernel and initial ramdisk of the +system. This allows you to test whether the boot loader works correctly. \ +However, it does not guarantee that your NixOS configuration will boot +successfully on the host hardware (i.e., after running +.Ic nixos-rebuild switch Ns +), because the hardware and boot loader configuration in the VM are different. +The boot loader is installed on an automatically generated virtual disk +containing a +.Pa /boot +partition. +.El +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl -upgrade , -upgrade-all +Update the root user's channel named +.Ql nixos +before rebuilding the system. +.Pp +In addition to the +.Ql nixos +channel, the root user's channels which have a file named +.Ql .update-on-nixos-rebuild +in their base directory will also be updated. +.Pp +Passing +.Fl -upgrade-all +updates all of the root user's channels. +. +.It Fl -install-bootloader +Causes the boot loader to be (re)installed on the device specified by the +relevant configuration options. +. +.It Fl -no-build-nix +Normally, +.Nm +first builds the +.Ql nixUnstable +attribute in Nixpkgs, and uses the resulting instance of the Nix package manager +to build the new system configuration. This is necessary if the NixOS modules +use features not provided by the currently installed version of Nix. This option +disables building a new Nix. +. +.It Fl -fast +Equivalent to +.Fl -no-build-nix Ns +\&. This option is useful if you call +.Nm +frequently (e.g. if you’re hacking on a NixOS module). +. +.It Fl -rollback +Instead of building a new configuration as specified by +.Pa /etc/nixos/configuration.nix Ns +, roll back to the previous configuration. (The previous configuration is +defined as the one before the “current” generation of the Nix profile +.Pa /nix/var/nix/profiles/system Ns +\&.) +. +.It Fl -builders Ar builder-spec +Allow ad-hoc remote builders for building the new system. This requires +the user executing +.Nm +(usually root) to be configured as a trusted user in the Nix daemon. This can be +achieved by using the +.Va nix.settings.trusted-users +NixOS option. Examples values for that option are described in the +.Dq Remote builds +chapter in the Nix manual, (i.e. +.Ql --builders \(dqssh://bigbrother x86_64-linux\(dq Ns +). By specifying an empty string existing builders specified in +.Pa /etc/nix/machines +can be ignored: +.Ql --builders \(dq\(dq +for example when they are not reachable due to network connectivity. +. +.It Fl -profile-name Ar name , Fl p Ar name +Instead of using the Nix profile +.Pa /nix/var/nix/profiles/system +to keep track of the current and previous system configurations, use +.Pa /nix/var/nix/profiles/system-profiles/ Ns Va name Ns +\&. When you use GRUB 2, for every system profile created with this flag, NixOS +will create a submenu named +.Dq NixOS - Profile Va name +in GRUB’s boot menu, containing the current and previous configurations of this profile. +.Pp +For instance, if you want to test a configuration file named +.Pa test.nix +without affecting the default system profile, you would do: +.Bd -literal -offset indent +$ nixos-rebuild switch -p test -I nixos-config=./test.nix +.Ed +.Pp +The new configuration will appear in the GRUB 2 submenu +.Dq NixOS - Profile 'test' Ns +\&. +. +.It Fl -specialisation Ar name , Fl c Ar name +Activates given specialisation; when not specified, switching and testing +will activate the base, unspecialised system. +. +.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 +.Ic ssh Ns , +and must be able to perform Nix builds. If the option +.Fl -target-host +is not set, the build will be copied back to the local machine when done. +.Pp +Note that, if +.Fl -no-build-nix +is not specified, Nix will be built both locally and remotely. This is because +the configuration will always be evaluated locally even though the building +might be performed remotely. +.Pp +You can include a remote user name in the host name +.Ns ( Va user@host Ns +). You can also set ssh options by defining the +.Ev NIX_SSHOPTS +environment variable. +. +.It Fl -target-host Ar host +Specifies the NixOS target host. By setting this to something other than an +empty string, the system activation will happen on the remote host instead of +the local machine. The remote host needs to be accessible over +.Ic ssh Ns , +and for the commands +.Cm switch Ns +, +.Cm boot +and +.Cm test +you need root access. +.Pp +If +.Fl -build-host +is not explicitly specified or empty, building will take place locally. +.Pp +You can include a remote user name in the host name +.Ns ( Va user@host Ns +). You can also set ssh options by defining the +.Ev NIX_SSHOPTS +environment variable. +.Pp +Note that +.Nm +honors the +.Va nixpkgs.crossSystem +setting of the given configuration but disregards the true architecture of the +target host. Hence the +.Va nixpkgs.crossSystem +setting has to match the target platform or else activation will fail. +. +.It Fl -use-substitutes +When set, nixos-rebuild will add +.Fl -use-substitutes +to each invocation of nix-copy-closure. This will only affect the behavior of +nixos-rebuild if +.Fl -target-host +or +.Fl -build-host +is also set. This is useful when the target-host connection to cache.nixos.org +is faster than the connection between hosts. +. +.It Fl -use-remote-sudo +When set, nixos-rebuild prefixes remote commands that run on the +.Fl -build-host +and +.Fl -target-host +systems with +.Ic sudo Ns +\&. Setting this option allows deploying as a non-root user. +. +.It Fl -flake Va flake-uri Ns Op Va #name +Build the NixOS system from the specified flake. It defaults to the directory +containing the target of the symlink +.Pa /etc/nixos/flake.nix Ns +, if it exists. The flake must contain an output named +.Ql nixosConfigurations. Ns Va name Ns +\&. If +.Va name +is omitted, it default to the current host name. +. +.It Fl -no-flake +Do not imply +.Fl -flake +if +.Pa /etc/nixos/flake.nix +exists. With this option, it is possible to build non-flake NixOS configurations +even if the current NixOS systems uses flakes. +.El +.Pp +In addition, +.Nm +accepts various Nix-related flags, including +.Fl -max-jobs Ns , +.Fl j Ns , +.Fl I Ns , +.Fl -show-trace Ns , +.Fl -keep-failed Ns , +.Fl -keep-going Ns , +.Fl -impure Ns , +.Fl -verbose Ns , and +.Fl v Ns +\&. See the Nix manual for details. +. +. +. +.Sh ENVIRONMENT +.Bl -tag -width indent +.It Ev NIXOS_CONFIG +Path to the main NixOS configuration module. Defaults to +.Pa /etc/nixos/configuration.nix Ns +\&. +. +.It Ev NIX_PATH +A colon-separated list of directories used to look up Nix expressions enclosed +in angle brackets (e.g. <nixpkgs>). Example: +.Bd -literal -offset indent +nixpkgs=./my-nixpkgs +.Ed +. +.It Ev NIX_SSHOPTS +Additional options to be passed to +.Ic ssh +on the command line. +.El +. +. +. +.Sh FILES +.Bl -tag -width indent +.It Pa /etc/nixos/flake.nix +If this file exists, then +.Nm +will use it as if the +.Fl -flake +option was given. This file may be a symlink to a +.Pa flake.nix +in an actual flake; thus +.Pa /etc/nixos +need not be a flake. +. +.It Pa /run/current-system +A symlink to the currently active system configuration in the Nix store. +. +.It Pa /nix/var/nix/profiles/system +The Nix profile that contains the current and previous system +configurations. Used to generate the GRUB boot menu. +.El +. +. +. +.Sh BUGS +This command should be renamed to something more descriptive. +. +. +. +.Sh AUTHORS +.An -nosplit +.An Eelco Dolstra +and +.An the Nixpkgs/NixOS contributors |