diff options
Diffstat (limited to 'nixos/doc/manual/man-nixos-rebuild.xml')
| -rw-r--r-- | nixos/doc/manual/man-nixos-rebuild.xml | 781 |
1 files changed, 0 insertions, 781 deletions
diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml deleted file mode 100644 index bf0f4aafa14..00000000000 --- a/nixos/doc/manual/man-nixos-rebuild.xml +++ /dev/null @@ -1,781 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refmeta> - <refentrytitle><command>nixos-rebuild</command> - </refentrytitle><manvolnum>8</manvolnum> - <refmiscinfo class="source">NixOS</refmiscinfo> -<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> - </refmeta> - - <refnamediv> - <refname><command>nixos-rebuild</command></refname> - <refpurpose>reconfigure a NixOS machine</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>nixos-rebuild</command><group choice='req'> - <arg choice='plain'> - <option>switch</option> - </arg> - - <arg choice='plain'> - <option>boot</option> - </arg> - - <arg choice='plain'> - <option>test</option> - </arg> - - <arg choice='plain'> - <option>build</option> - </arg> - - <arg choice='plain'> - <option>dry-build</option> - </arg> - - <arg choice='plain'> - <option>dry-activate</option> - </arg> - - <arg choice='plain'> - <option>edit</option> - </arg> - - <arg choice='plain'> - <option>build-vm</option> - </arg> - - <arg choice='plain'> - <option>build-vm-with-bootloader</option> - </arg> - </group> - <sbr /> - - <arg> - <group choice='req'> - <arg choice='plain'> - <option>--upgrade</option> - </arg> - <arg choice='plain'> - <option>--upgrade-all</option> - </arg> - </group> - </arg> - - <arg> - <option>--install-bootloader</option> - </arg> - - <arg> - <option>--no-build-nix</option> - </arg> - - <arg> - <option>--fast</option> - </arg> - - <arg> - <option>--rollback</option> - </arg> - - <arg> - <option>--builders</option> <replaceable>builder-spec</replaceable> - </arg> - - <sbr/> - - <arg> - <option>--flake</option> <replaceable>flake-uri</replaceable> - </arg> - - <arg> - <option>--no-flake</option> - </arg> - - <arg> - <option>--override-input</option> <replaceable>input-name</replaceable> <replaceable>flake-uri</replaceable> - </arg> - - <sbr /> - - <arg> - <group choice='req'> - <arg choice='plain'> - <option>--profile-name</option> - </arg> - - <arg choice='plain'> - <option>-p</option> - </arg> - </group> <replaceable>name</replaceable> - </arg> - - <arg> - <group choice='req'> - <arg choice='plain'> - <option>--specialisation</option> - </arg> - - <arg choice='plain'> - <option>-c</option> - </arg> - </group> <replaceable>name</replaceable> - </arg> - - <sbr /> - - <arg> - <option>--build-host</option> <replaceable>host</replaceable> - </arg> - - <arg> - <option>--target-host</option> <replaceable>host</replaceable> - </arg> - - <arg> - <option>--use-remote-sudo</option> - </arg> - - <sbr /> - - <arg> - <option>--show-trace</option> - </arg> - <arg> - <option>-I</option> - <replaceable>NIX_PATH</replaceable> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--verbose</option></arg> - <arg choice='plain'><option>-v</option></arg> - </group> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--impure</option></arg> - </group> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--max-jobs</option></arg> - <arg choice='plain'><option>-j</option></arg> - </group> - <replaceable>number</replaceable> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--keep-failed</option></arg> - <arg choice='plain'><option>-K</option></arg> - </group> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--keep-going</option></arg> - <arg choice='plain'><option>-k</option></arg> - </group> - </arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsection> - <title>Description</title> - - <para> - This command updates the system so that it corresponds to the - configuration specified in - <filename>/etc/nixos/configuration.nix</filename> or - <filename>/etc/nixos/flake.nix</filename>. Thus, every time you - modify the configuration or any other NixOS module, you must run - <command>nixos-rebuild</command> to make the changes take - effect. It builds the new system in - <filename>/nix/store</filename>, 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. - </para> - - <para> - This command has one required argument, which specifies the desired - operation. It must be one of the following: - - <variablelist> - <varlistentry> - <term> - <option>switch</option> - </term> - <listitem> - <para> - 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 - <command>nixos-rebuild switch</command> or <command>nixos-rebuild - boot</command> remain available in the GRUB menu. - </para> - <para> - Note that if you are using specializations, running just - <command>nixos-rebuild switch</command> will switch you back to the - unspecialized, base system - in that case, you might want to use this - instead: -<screen> -<prompt>$ </prompt>nixos-rebuild switch --specialisation your-specialisation-name -</screen> - This command will build all specialisations and make them bootable just - like regular <command>nixos-rebuild switch</command> does - 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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>boot</option> - </term> - <listitem> - <para> - Build the new configuration and make it the boot default (as with - <command>nixos-rebuild switch</command>), but do not activate it. That - is, the system continues to run the previous configuration until the - next reboot. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>test</option> - </term> - <listitem> - <para> - 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 <command>nixos-rebuild - switch</command> or <command>nixos-rebuild boot</command>). - </para> - <para> - Note that if you are using specialisations, running just - <command>nixos-rebuild test</command> will activate the unspecialised, - base system - in that case, you might want to use this instead: -<screen> -<prompt>$ </prompt>nixos-rebuild test --specialisation your-specialisation-name -</screen> - This command can be also used to switch from the base system into a - specialised one, or to switch between specialisations. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>build</option> - </term> - <listitem> - <para> - Build the new configuration, but neither activate it nor add it to the - GRUB boot menu. It leaves a symlink named <filename>result</filename> in - the current directory, which points to the output of the top-level - “system” derivation. This is essentially the same as doing -<screen> -<prompt>$ </prompt>nix-build /path/to/nixpkgs/nixos -A system -</screen> - Note that you do not need to be <literal>root</literal> to run - <command>nixos-rebuild build</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>dry-build</option> - </term> - <listitem> - <para> - Show what store paths would be built or downloaded by any of the - operations above, but otherwise do nothing. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>dry-activate</option> - </term> - <listitem> - <para> - Build the new configuration, but instead of activating it, show what - changes would be performed by the activation (i.e. by - <command>nixos-rebuild test</command>). For instance, this command will - print which systemd units would be restarted. The list of changes is not - guaranteed to be complete. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>edit</option> - </term> - <listitem> - <para> - Opens <filename>configuration.nix</filename> in the default editor. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>build-vm</option> - </term> - <listitem> - <para> - Build a script that starts a NixOS virtual machine with the desired - configuration. It leaves a symlink <filename>result</filename> in the - current directory that points (under - <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>) - at the script that starts the VM. Thus, to test a NixOS configuration in - a virtual machine, you should do the following: -<screen> -<prompt>$ </prompt>nixos-rebuild build-vm -<prompt>$ </prompt>./result/bin/run-*-vm -</screen> - </para> - - <para> - The VM is implemented using the <literal>qemu</literal> package. For - best performance, you should load the <literal>kvm-intel</literal> or - <literal>kvm-amd</literal> kernel modules to get hardware - virtualisation. - </para> - - <para> - 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 - <command>nixos-rebuild</command>; to change the VM’s configuration, - you must halt the VM and re-run the commands above. - </para> - - <para> - The VM has its own <literal>ext3</literal> 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 - <literal>./<replaceable>hostname</replaceable>.qcow2</literal>. -<!-- The entire file system hierarchy of the host is available in - the VM under <filename>/hostfs</filename>.--> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>build-vm-with-bootloader</option> - </term> - <listitem> - <para> - Like <option>build-vm</option>, 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 <command>nixos-rebuild - switch</command>), 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 <filename>/boot</filename> - partition. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsection> - - <refsection> - <title>Options</title> - <para> - This command accepts the following options: - </para> - - <variablelist> - <varlistentry> - <term> - <option>--upgrade</option> - </term> - <term> - <option>--upgrade-all</option> - </term> - <listitem> - <para> - Update the root user's channel named <literal>nixos</literal> - before rebuilding the system. - </para> - <para> - In addition to the <literal>nixos</literal> channel, the root - user's channels which have a file named - <literal>.update-on-nixos-rebuild</literal> in their base - directory will also be updated. - </para> - <para> - Passing <option>--upgrade-all</option> updates all of the root - user's channels. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--install-bootloader</option> - </term> - <listitem> - <para> - Causes the boot loader to be (re)installed on the device specified by the - relevant configuration options. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--no-build-nix</option> - </term> - <listitem> - <para> - Normally, <command>nixos-rebuild</command> first builds the - <varname>nixUnstable</varname> 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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--fast</option> - </term> - <listitem> - <para> - Equivalent to <option>--no-build-nix</option>. This option is - useful if you call <command>nixos-rebuild</command> frequently - (e.g. if you’re hacking on a NixOS module). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--rollback</option> - </term> - <listitem> - <para> - Instead of building a new configuration as specified by - <filename>/etc/nixos/configuration.nix</filename>, roll back to the - previous configuration. (The previous configuration is defined as the one - before the “current” generation of the Nix profile - <filename>/nix/var/nix/profiles/system</filename>.) - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--builders</option> <replaceable>builder-spec</replaceable> - </term> - <listitem> - <para> - Allow ad-hoc remote builders for building the new system. This requires - the user executing <command>nixos-rebuild</command> (usually root) to be - configured as a trusted user in the Nix daemon. This can be achieved by - using the <literal>nix.settings.trusted-users</literal> NixOS option. Examples - values for that option are described in the <literal>Remote builds - chapter</literal> in the Nix manual, (i.e. <command>--builders - "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string - existing builders specified in <filename>/etc/nix/machines</filename> can - be ignored: <command>--builders ""</command> for example when they are - not reachable due to network connectivity. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--profile-name</option> - </term> - <term> - <option>-p</option> - </term> - <listitem> - <para> - Instead of using the Nix profile - <filename>/nix/var/nix/profiles/system</filename> to keep track of the - current and previous system configurations, use - <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>. - When you use GRUB 2, for every system profile created with this flag, - NixOS will create a submenu named “NixOS - Profile - '<replaceable>name</replaceable>'” in GRUB’s boot menu, containing - the current and previous configurations of this profile. - </para> - <para> - For instance, if you want to test a configuration file named - <filename>test.nix</filename> without affecting the default system - profile, you would do: -<screen> -<prompt>$ </prompt>nixos-rebuild switch -p test -I nixos-config=./test.nix -</screen> - The new configuration will appear in the GRUB 2 submenu “NixOS - - Profile 'test'”. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--specialisation</option> - </term> - <term> - <option>-c</option> - </term> - <listitem> - <para> - Activates given specialisation; when not specified, switching and testing - will activate the base, unspecialised system. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--build-host</option> - </term> - <listitem> - <para> - Instead of building the new configuration locally, use the specified host - to perform the build. The host needs to be accessible with ssh, and must - be able to perform Nix builds. If the option - <option>--target-host</option> is not set, the build will be copied back - to the local machine when done. - </para> - <para> - Note that, if <option>--no-build-nix</option> 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. - </para> - <para> - You can include a remote user name in the host name - (<replaceable>user@host</replaceable>). You can also set ssh options by - defining the <envar>NIX_SSHOPTS</envar> environment variable. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--target-host</option> - </term> - <listitem> - <para> - 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 ssh, and for the commands <option>switch</option>, - <option>boot</option> and <option>test</option> you need root access. - </para> - - <para> - If <option>--build-host</option> is not explicitly specified or empty, - building will take place locally. - </para> - - <para> - You can include a remote user name in the host name - (<replaceable>user@host</replaceable>). You can also set ssh options by - defining the <envar>NIX_SSHOPTS</envar> environment variable. - </para> - - <para> - Note that <command>nixos-rebuild</command> honors the - <literal>nixpkgs.crossSystem</literal> setting of the given configuration - but disregards the true architecture of the target host. Hence the - <literal>nixpkgs.crossSystem</literal> setting has to match the target - platform or else activation will fail. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--use-substitutes</option> - </term> - <listitem> - <para> - When set, nixos-rebuild will add <option>--use-substitutes</option> - to each invocation of nix-copy-closure. This will only affect the - behavior of nixos-rebuild if <option>--target-host</option> or - <option>--build-host</option> is also set. This is useful when - the target-host connection to cache.nixos.org is faster than the - connection between hosts. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--use-remote-sudo</option> - </term> - <listitem> - <para> - When set, nixos-rebuild prefixes remote commands that run on - the <option>--build-host</option> and <option>--target-host</option> - systems with <command>sudo</command>. Setting this option allows - deploying as a non-root user. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--flake</option> <replaceable>flake-uri</replaceable><optional>#<replaceable>name</replaceable></optional> - </term> - <listitem> - <para> - Build the NixOS system from the specified flake. It defaults to - the directory containing the target of the symlink - <filename>/etc/nixos/flake.nix</filename>, if it exists. The - flake must contain an output named - <literal>nixosConfigurations.<replaceable>name</replaceable></literal>. If - <replaceable>name</replaceable> is omitted, it default to the - current host name. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--no-flake</option> - </term> - <listitem> - <para> - Do not imply <option>--flake</option> if - <filename>/etc/nixos/flake.nix</filename> exists. With this - option, it is possible to build non-flake NixOS configurations - even if the current NixOS systems uses flakes. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - In addition, <command>nixos-rebuild</command> accepts various Nix-related - flags, including <option>--max-jobs</option> / <option>-j</option>, <option>-I</option>, - <option>--show-trace</option>, <option>--keep-failed</option>, - <option>--keep-going</option>, <option>--impure</option>, and <option>--verbose</option> / - <option>-v</option>. See the Nix manual for details. - </para> - </refsection> - - <refsection> - <title>Environment</title> - - <variablelist> - <varlistentry> - <term> - <envar>NIXOS_CONFIG</envar> - </term> - <listitem> - <para> - Path to the main NixOS configuration module. Defaults to - <filename>/etc/nixos/configuration.nix</filename>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <envar>NIX_PATH</envar> - </term> - <listitem> - <para> - A colon-separated list of directories used to look up Nix expressions enclosed in angle brackets (e.g <nixpkgs>). Example - <screen> - nixpkgs=./my-nixpkgs - </screen> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <envar>NIX_SSHOPTS</envar> - </term> - <listitem> - <para> - Additional options to be passed to <command>ssh</command> on the command - line. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsection> - - <refsection> - <title>Files</title> - - <variablelist> - - <varlistentry> - <term> - <filename>/etc/nixos/flake.nix</filename> - </term> - <listitem> - <para> - If this file exists, then <command>nixos-rebuild</command> will - use it as if the <option>--flake</option> option was given. This - file may be a symlink to a <filename>flake.nix</filename> in an - actual flake; thus <filename>/etc/nixos</filename> need not be a - flake. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <filename>/run/current-system</filename> - </term> - <listitem> - <para> - A symlink to the currently active system configuration in the Nix store. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <filename>/nix/var/nix/profiles/system</filename> - </term> - <listitem> - <para> - The Nix profile that contains the current and previous system - configurations. Used to generate the GRUB boot menu. - </para> - </listitem> - </varlistentry> - - </variablelist> - </refsection> - - <refsection> - <title>Bugs</title> - <para> - This command should be renamed to something more descriptive. - </para> - </refsection> -</refentry> |