From e0d69c92a89eeeaeb7ce857377d3418756b8998b Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Wed, 9 Dec 2009 15:05:13 +0000 Subject: [PATCH] * Added a manpage for nixos-rebuild. svn path=/nixos/trunk/; revision=18855 --- doc/manual/man-nixos-rebuild.xml | 307 +++++++++++++++++++++++++++++++ doc/manual/man-pages.xml | 1 + 2 files changed, 308 insertions(+) create mode 100644 doc/manual/man-nixos-rebuild.xml diff --git a/doc/manual/man-nixos-rebuild.xml b/doc/manual/man-nixos-rebuild.xml new file mode 100644 index 000000000000..0bdc925efd9e --- /dev/null +++ b/doc/manual/man-nixos-rebuild.xml @@ -0,0 +1,307 @@ + + + + nixos-rebuild + 8 + NixOS + + + + + nixos-rebuild + reconfigure a NixOS machine + + + + + nixos-rebuild + + + + + + + + + + + + + + + + + + + + +Description + +This command updates the system so that it corresponds to the +configuration specified in +/etc/nixos/configuration.nix. Thus, every time +you modify /etc/nixos/configuration.nix or any +NixOS module, you must run nixos-rebuild to make +the changes take effect. It builds the new system in +/nix/store, runs its activation script, and stop +and (re)starts any system services if needed. + +This command has one required argument, which specifies the +desired operation. It must be one of the following: + + + + + + + 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 meny entry, so that subsequent reboots + will boot the system into the new configuration. Previous + configurations activated with nixos-rebuild + switch or nixos-rebuild boot remain + available in the GRUB menu. + + + + + + + Build the new configuration and make it the boot default + (as with nixos-rebuild switch), but do not + activate it. That is, the system continues to run the previous + configuration until the next reboot. + + + + + + + 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 nixos-rebuild switch or + nixos-rebuild boot). + + + + + + + Build the new configuration, but neither activate it nor + add it to the GRUB boot menu. It leaves a symlink named + result in the current directory, which + points to the output of the top-level “system” derivation. This + is essentially the same as doing + +$ nix-build /etc/nixos/nixos -A system + + Note that you do not need to be root to run + nixos-rebuild build. + + + + + + + Simply show what store paths would be built or downloaded + by any of the operations above. + + + + + + + Build a script that starts a NixOS virtual machine with + the desired configuration. It leaves a symlink + result in the current directory that points + (under + result/bin/run-hostname-vm) + at the script that starts the VM. Thus, to test a NixOS + configuration in a virtual machine, you should do the following: + +$ nixos-rebuild build-vm +$ ./result/bin/run-*-vm + + + The VM is implemented using the + qemu-kvm package. For best performance, you + should load the kvm-intel or + kvm-amd kernel modules. + + The VM mounts the Nix store of the host through the CIFS + filesystem. (qemu-kvm automatically starts a + Samba daemon for this purpose.) 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 + nixos-rebuild; to change the VM’s + configuration, you must halt the VM and re-run the commands + above. + + + The VM has its own ext3 root + filesystem, which is automatically created when the VM is first + started, and is persistent across reboots of the VM. It is + stored in ./hostname.qcow2. + The entire filesystem hierarchy of the host is available in the + VM under /hostfs. + + + + + + + + + + + +Options + +This command accepts the following options: + + + + + + + Causes the GRUB boot loader to be (re)installed on the + device specified by the + boot.loader.grub.device configuration + option. + + + + + + + Normally, nixos-rebuild calls + nix-pull to obtain the set of available + pre-built binaries in the Nixpkgs channel. This option causes + the call to nix-pull to be skipped. Note + that the result of previous invocations of + nix-pull may still be available in + /nix/var/nix/manifests, so to disable the + use of pre-built binaries, you should clear that directory in + addition to using . + + + + + + + Normally, nixos-rebuild first builds + the 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. + + + + + + + Equivalent to + . + This option is useful if you call + nixos-rebuild frequently (e.g. if you’re + hacking on a NixOS module). + + + + + + + Instead of building a new configuration as specified by + /etc/nixos/configuration.nix, roll back to + the previous configuration. (The previous configuration is + defined as the one before the “current” generation of the + profile /nix/var/nix/profiles/system.) + + + + + +In addition, nixos-rebuild accepts various +Nix-related flags, including / +, , +, and + / . See +the Nix manual for details. + + + + +Environment + + + + + NIXOS + + Path to the NixOS source tree. Defaults to + /etc/nixos/nixos. + + + + + NIXPKGS + + Path to the Nixpkgs source tree. Defaults to + /etc/nixos/nixpkgs. + + + + + NIXOS_CONFIG + + Path to the main NixOS configuration module. Defaults to + /etc/nixos/configuration.nix. + + + + + + + + +Files + + + + + /var/run/current-system + + A symlink to the currently active system configuration in + the Nix store. + + + + + /nix/var/nix/profiles/system + + The Nix profile that contains the current and previous + system configurations. Used to generate the GRUB boot + menu. + + + + + + + + +Bugs + +This command should be renamed to something more +descriptive. + + + + + + diff --git a/doc/manual/man-pages.xml b/doc/manual/man-pages.xml index ccd0ebfc6da4..e706574d8895 100644 --- a/doc/manual/man-pages.xml +++ b/doc/manual/man-pages.xml @@ -24,5 +24,6 @@ +