nixos/doc/manual/man-nixos-rebuild.xml

   1 <refentry xmlns="http://docbook.org/ns/docbook"
   2           xmlns:xlink="http://www.w3.org/1999/xlink"
   3           xmlns:xi="http://www.w3.org/2001/XInclude">
   4  <refmeta>
   5   <refentrytitle><command>nixos-rebuild</command>
   6   </refentrytitle><manvolnum>8</manvolnum>
   7   <refmiscinfo class="source">NixOS</refmiscinfo>
   8 <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
   9  </refmeta>
  10
  11  <refnamediv>
  12   <refname><command>nixos-rebuild</command></refname>
  13   <refpurpose>reconfigure a NixOS machine</refpurpose>
  14  </refnamediv>
  15
  16  <refsynopsisdiv>
  17   <cmdsynopsis>
  18    <command>nixos-rebuild</command><group choice='req'>
  19    <arg choice='plain'>
  20     <option>switch</option>
  21    </arg>
  22
  23    <arg choice='plain'>
  24     <option>boot</option>
  25    </arg>
  26
  27    <arg choice='plain'>
  28     <option>test</option>
  29    </arg>
  30
  31    <arg choice='plain'>
  32     <option>build</option>
  33    </arg>
  34
  35    <arg choice='plain'>
  36     <option>dry-build</option>
  37    </arg>
  38
  39    <arg choice='plain'>
  40     <option>dry-activate</option>
  41    </arg>
  42
  43    <arg choice='plain'>
  44     <option>edit</option>
  45    </arg>
  46
  47    <arg choice='plain'>
  48     <option>build-vm</option>
  49    </arg>
  50
  51    <arg choice='plain'>
  52     <option>build-vm-with-bootloader</option>
  53    </arg>
  54     </group>
  55     <sbr />
  56
  57     <arg>
  58       <group choice='req'>
  59         <arg choice='plain'>
  60           <option>--upgrade</option>
  61         </arg>
  62         <arg choice='plain'>
  63           <option>--upgrade-all</option>
  64         </arg>
  65       </group>
  66     </arg>
  67
  68    <arg>
  69     <option>--install-bootloader</option>
  70    </arg>
  71
  72    <arg>
  73     <option>--no-build-nix</option>
  74    </arg>
  75
  76    <arg>
  77     <option>--fast</option>
  78    </arg>
  79
  80    <arg>
  81     <option>--rollback</option>
  82    </arg>
  83
  84    <arg>
  85     <option>--builders</option> <replaceable>builder-spec</replaceable>
  86    </arg>
  87
  88    <sbr/>
  89
  90    <arg>
  91     <option>--flake</option> <replaceable>flake-uri</replaceable>
  92    </arg>
  93
  94    <arg>
  95     <option>--no-flake</option>
  96    </arg>
  97
  98    <arg>
  99     <option>--override-input</option> <replaceable>input-name</replaceable> <replaceable>flake-uri</replaceable>
 100    </arg>
 101
 102    <sbr />
 103
 104    <arg>
 105     <group choice='req'>
 106     <arg choice='plain'>
 107      <option>--profile-name</option>
 108     </arg>
 109
 110     <arg choice='plain'>
 111      <option>-p</option>
 112     </arg>
 113      </group> <replaceable>name</replaceable>
 114    </arg>
 115
 116    <sbr />
 117
 118    <arg>
 119     <option>--build-host</option> <replaceable>host</replaceable>
 120    </arg>
 121
 122    <arg>
 123     <option>--target-host</option> <replaceable>host</replaceable>
 124    </arg>
 125
 126    <arg>
 127     <option>--use-remote-sudo</option>
 128    </arg>
 129
 130    <sbr />
 131
 132    <arg>
 133     <option>--show-trace</option>
 134    </arg>
 135    <arg>
 136     <option>-I</option>
 137     <replaceable>path</replaceable>
 138    </arg>
 139    <arg>
 140     <group choice='req'>
 141      <arg choice='plain'><option>--verbose</option></arg>
 142      <arg choice='plain'><option>-v</option></arg>
 143     </group>
 144    </arg>
 145    <arg>
 146     <group choice='req'>
 147      <arg choice='plain'><option>--impure</option></arg>
 148     </group>
 149    </arg>
 150    <arg>
 151     <group choice='req'>
 152      <arg choice='plain'><option>--max-jobs</option></arg>
 153      <arg choice='plain'><option>-j</option></arg>
 154     </group>
 155     <replaceable>number</replaceable>
 156    </arg>
 157    <arg>
 158     <group choice='req'>
 159      <arg choice='plain'><option>--keep-failed</option></arg>
 160      <arg choice='plain'><option>-K</option></arg>
 161     </group>
 162    </arg>
 163    <arg>
 164     <group choice='req'>
 165      <arg choice='plain'><option>--keep-going</option></arg>
 166      <arg choice='plain'><option>-k</option></arg>
 167     </group>
 168    </arg>
 169   </cmdsynopsis>
 170  </refsynopsisdiv>
 171
 172  <refsection>
 173   <title>Description</title>
 174
 175   <para>
 176    This command updates the system so that it corresponds to the
 177    configuration specified in
 178    <filename>/etc/nixos/configuration.nix</filename> or
 179    <filename>/etc/nixos/flake.nix</filename>. Thus, every time you
 180    modify the configuration or any other NixOS module, you must run
 181    <command>nixos-rebuild</command> to make the changes take
 182    effect. It builds the new system in
 183    <filename>/nix/store</filename>, runs its activation script, and
 184    stop and (re)starts any system services if needed. Please note that
 185    user services need to be started manually as they aren't detected
 186    by the activation script at the moment.
 187   </para>
 188
 189   <para>
 190    This command has one required argument, which specifies the desired
 191    operation. It must be one of the following:
 192
 193    <variablelist>
 194     <varlistentry>
 195      <term>
 196       <option>switch</option>
 197      </term>
 198      <listitem>
 199       <para>
 200        Build and activate the new configuration, and make it the boot default.
 201        That is, the configuration is added to the GRUB boot menu as the default
 202        menu entry, so that subsequent reboots will boot the system into the new
 203        configuration. Previous configurations activated with
 204        <command>nixos-rebuild switch</command> or <command>nixos-rebuild
 205        boot</command> remain available in the GRUB menu.
 206       </para>
 207      </listitem>
 208     </varlistentry>
 209
 210     <varlistentry>
 211      <term>
 212       <option>boot</option>
 213      </term>
 214      <listitem>
 215       <para>
 216        Build the new configuration and make it the boot default (as with
 217        <command>nixos-rebuild switch</command>), but do not activate it. That
 218        is, the system continues to run the previous configuration until the
 219        next reboot.
 220       </para>
 221      </listitem>
 222     </varlistentry>
 223
 224     <varlistentry>
 225      <term>
 226       <option>test</option>
 227      </term>
 228      <listitem>
 229       <para>
 230        Build and activate the new configuration, but do not add it to the GRUB
 231        boot menu. Thus, if you reboot the system (or if it crashes), you will
 232        automatically revert to the default configuration (i.e. the
 233        configuration resulting from the last call to <command>nixos-rebuild
 234        switch</command> or <command>nixos-rebuild boot</command>).
 235       </para>
 236      </listitem>
 237     </varlistentry>
 238
 239     <varlistentry>
 240      <term>
 241       <option>build</option>
 242      </term>
 243      <listitem>
 244       <para>
 245        Build the new configuration, but neither activate it nor add it to the
 246        GRUB boot menu. It leaves a symlink named <filename>result</filename> in
 247        the current directory, which points to the output of the top-level
 248        “system” derivation. This is essentially the same as doing
 249 <screen>
 250 <prompt>$ </prompt>nix-build /path/to/nixpkgs/nixos -A system
 251 </screen>
 252        Note that you do not need to be <literal>root</literal> to run
 253        <command>nixos-rebuild build</command>.
 254       </para>
 255      </listitem>
 256     </varlistentry>
 257
 258     <varlistentry>
 259      <term>
 260       <option>dry-build</option>
 261      </term>
 262      <listitem>
 263       <para>
 264        Show what store paths would be built or downloaded by any of the
 265        operations above, but otherwise do nothing.
 266       </para>
 267      </listitem>
 268     </varlistentry>
 269
 270     <varlistentry>
 271      <term>
 272       <option>dry-activate</option>
 273      </term>
 274      <listitem>
 275       <para>
 276        Build the new configuration, but instead of activating it, show what
 277        changes would be performed by the activation (i.e. by
 278        <command>nixos-rebuild test</command>). For instance, this command will
 279        print which systemd units would be restarted. The list of changes is not
 280        guaranteed to be complete.
 281       </para>
 282      </listitem>
 283     </varlistentry>
 284
 285     <varlistentry>
 286      <term>
 287       <option>edit</option>
 288      </term>
 289      <listitem>
 290       <para>
 291        Opens <filename>configuration.nix</filename> in the default editor.
 292       </para>
 293      </listitem>
 294     </varlistentry>
 295
 296     <varlistentry>
 297      <term>
 298       <option>build-vm</option>
 299      </term>
 300      <listitem>
 301       <para>
 302        Build a script that starts a NixOS virtual machine with the desired
 303        configuration. It leaves a symlink <filename>result</filename> in the
 304        current directory that points (under
 305        <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>)
 306        at the script that starts the VM. Thus, to test a NixOS configuration in
 307        a virtual machine, you should do the following:
 308 <screen>
 309 <prompt>$ </prompt>nixos-rebuild build-vm
 310 <prompt>$ </prompt>./result/bin/run-*-vm
 311 </screen>
 312       </para>
 313
 314       <para>
 315        The VM is implemented using the <literal>qemu</literal> package. For
 316        best performance, you should load the <literal>kvm-intel</literal> or
 317        <literal>kvm-amd</literal> kernel modules to get hardware
 318        virtualisation.
 319       </para>
 320
 321       <para>
 322        The VM mounts the Nix store of the host through the 9P file system. The
 323        host Nix store is read-only, so Nix commands that modify the Nix store
 324        will not work in the VM. This includes commands such as
 325        <command>nixos-rebuild</command>; to change the VM’s configuration,
 326        you must halt the VM and re-run the commands above.
 327       </para>
 328
 329       <para>
 330        The VM has its own <literal>ext3</literal> root file system, which is
 331        automatically created when the VM is first started, and is persistent
 332        across reboots of the VM. It is stored in
 333        <literal>./<replaceable>hostname</replaceable>.qcow2</literal>.
 334 <!-- The entire file system hierarchy of the host is available in
 335       the VM under <filename>/hostfs</filename>.-->
 336       </para>
 337      </listitem>
 338     </varlistentry>
 339
 340     <varlistentry>
 341      <term>
 342       <option>build-vm-with-bootloader</option>
 343      </term>
 344      <listitem>
 345       <para>
 346        Like <option>build-vm</option>, but boots using the regular boot loader
 347        of your configuration (e.g., GRUB 1 or 2), rather than booting directly
 348        into the kernel and initial ramdisk of the system. This allows you to
 349        test whether the boot loader works correctly. However, it does not
 350        guarantee that your NixOS configuration will boot successfully on the
 351        host hardware (i.e., after running <command>nixos-rebuild
 352        switch</command>), because the hardware and boot loader configuration in
 353        the VM are different. The boot loader is installed on an automatically
 354        generated virtual disk containing a <filename>/boot</filename>
 355        partition.
 356       </para>
 357      </listitem>
 358     </varlistentry>
 359    </variablelist>
 360   </para>
 361  </refsection>
 362
 363  <refsection>
 364   <title>Options</title>
 365   <para>
 366    This command accepts the following options:
 367   </para>
 368
 369   <variablelist>
 370    <varlistentry>
 371     <term>
 372      <option>--upgrade</option>
 373     </term>
 374     <term>
 375      <option>--upgrade-all</option>
 376     </term>
 377     <listitem>
 378       <para>
 379         Update the root user's channel named <literal>nixos</literal>
 380         before rebuilding the system.
 381       </para>
 382       <para>
 383         In addition to the <literal>nixos</literal> channel, the root
 384         user's channels which have a file named
 385         <literal>.update-on-nixos-rebuild</literal> in their base
 386         directory will also be updated.
 387       </para>
 388       <para>
 389         Passing <option>--upgrade-all</option> updates all of the root
 390         user's channels.
 391      </para>
 392     </listitem>
 393    </varlistentry>
 394
 395    <varlistentry>
 396     <term>
 397      <option>--install-bootloader</option>
 398     </term>
 399     <listitem>
 400      <para>
 401       Causes the boot loader to be (re)installed on the device specified by the
 402       relevant configuration options.
 403      </para>
 404     </listitem>
 405    </varlistentry>
 406
 407    <varlistentry>
 408     <term>
 409      <option>--no-build-nix</option>
 410     </term>
 411     <listitem>
 412      <para>
 413       Normally, <command>nixos-rebuild</command> first builds the
 414       <varname>nixUnstable</varname> attribute in Nixpkgs, and uses the
 415       resulting instance of the Nix package manager to build the new system
 416       configuration. This is necessary if the NixOS modules use features not
 417       provided by the currently installed version of Nix. This option disables
 418       building a new Nix.
 419      </para>
 420     </listitem>
 421    </varlistentry>
 422
 423    <varlistentry>
 424     <term>
 425      <option>--fast</option>
 426     </term>
 427     <listitem>
 428      <para>
 429       Equivalent to <option>--no-build-nix</option>. This option is
 430       useful if you call <command>nixos-rebuild</command> frequently
 431       (e.g. if you’re hacking on a NixOS module).
 432      </para>
 433     </listitem>
 434    </varlistentry>
 435
 436    <varlistentry>
 437     <term>
 438      <option>--rollback</option>
 439     </term>
 440     <listitem>
 441      <para>
 442       Instead of building a new configuration as specified by
 443       <filename>/etc/nixos/configuration.nix</filename>, roll back to the
 444       previous configuration. (The previous configuration is defined as the one
 445       before the “current” generation of the Nix profile
 446       <filename>/nix/var/nix/profiles/system</filename>.)
 447      </para>
 448     </listitem>
 449    </varlistentry>
 450
 451    <varlistentry>
 452     <term>
 453      <option>--builders</option> <replaceable>builder-spec</replaceable>
 454     </term>
 455     <listitem>
 456      <para>
 457       Allow ad-hoc remote builders for building the new system. This requires
 458       the user executing <command>nixos-rebuild</command> (usually root) to be
 459       configured as a trusted user in the Nix daemon. This can be achieved by
 460       using the <literal>nix.settings.trusted-users</literal> NixOS option. Examples
 461       values for that option are described in the <literal>Remote builds
 462       chapter</literal> in the Nix manual, (i.e. <command>--builders
 463       "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string
 464       existing builders specified in <filename>/etc/nix/machines</filename> can
 465       be ignored: <command>--builders ""</command> for example when they are
 466       not reachable due to network connectivity.
 467      </para>
 468     </listitem>
 469    </varlistentry>
 470
 471    <varlistentry>
 472     <term>
 473      <option>--profile-name</option>
 474     </term>
 475     <term>
 476      <option>-p</option>
 477     </term>
 478     <listitem>
 479      <para>
 480       Instead of using the Nix profile
 481       <filename>/nix/var/nix/profiles/system</filename> to keep track of the
 482       current and previous system configurations, use
 483       <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>.
 484       When you use GRUB 2, for every system profile created with this flag,
 485       NixOS will create a submenu named “NixOS - Profile
 486       '<replaceable>name</replaceable>'” in GRUB’s boot menu, containing
 487       the current and previous configurations of this profile.
 488      </para>
 489      <para>
 490       For instance, if you want to test a configuration file named
 491       <filename>test.nix</filename> without affecting the default system
 492       profile, you would do:
 493 <screen>
 494 <prompt>$ </prompt>nixos-rebuild switch -p test -I nixos-config=./test.nix
 495 </screen>
 496       The new configuration will appear in the GRUB 2 submenu “NixOS -
 497       Profile 'test'”.
 498      </para>
 499     </listitem>
 500    </varlistentry>
 501
 502    <varlistentry>
 503     <term>
 504      <option>--build-host</option>
 505     </term>
 506     <listitem>
 507      <para>
 508       Instead of building the new configuration locally, use the specified host
 509       to perform the build. The host needs to be accessible with ssh, and must
 510       be able to perform Nix builds. If the option
 511       <option>--target-host</option> is not set, the build will be copied back
 512       to the local machine when done.
 513      </para>
 514      <para>
 515       Note that, if <option>--no-build-nix</option> is not specified, Nix will
 516       be built both locally and remotely. This is because the configuration
 517       will always be evaluated locally even though the building might be
 518       performed remotely.
 519      </para>
 520      <para>
 521       You can include a remote user name in the host name
 522       (<replaceable>user@host</replaceable>). You can also set ssh options by
 523       defining the <envar>NIX_SSHOPTS</envar> environment variable.
 524      </para>
 525     </listitem>
 526    </varlistentry>
 527
 528    <varlistentry>
 529     <term>
 530      <option>--target-host</option>
 531     </term>
 532     <listitem>
 533      <para>
 534       Specifies the NixOS target host. By setting this to something other than
 535       <replaceable>localhost</replaceable>, the system activation will happen
 536       on the remote host instead of the local machine. The remote host needs to
 537       be accessible over ssh, and for the commands <option>switch</option>,
 538       <option>boot</option> and <option>test</option> you need root access.
 539      </para>
 540
 541      <para>
 542       If <option>--build-host</option> is not explicitly specified, building
 543       will take place locally.
 544      </para>
 545
 546      <para>
 547       You can include a remote user name in the host name
 548       (<replaceable>user@host</replaceable>). You can also set ssh options by
 549       defining the <envar>NIX_SSHOPTS</envar> environment variable.
 550      </para>
 551
 552      <para>
 553       Note that <command>nixos-rebuild</command> honors the
 554       <literal>nixpkgs.crossSystem</literal> setting of the given configuration
 555       but disregards the true architecture of the target host. Hence the
 556       <literal>nixpkgs.crossSystem</literal> setting has to match the target
 557       platform or else activation will fail.
 558      </para>
 559     </listitem>
 560    </varlistentry>
 561
 562    <varlistentry>
 563     <term>
 564      <option>--use-substitutes</option>
 565     </term>
 566     <listitem>
 567      <para>
 568        When set, nixos-rebuild will add <option>--use-substitutes</option>
 569        to each invocation of nix-copy-closure. This will only affect the
 570        behavior of nixos-rebuild if <option>--target-host</option> or
 571        <option>--build-host</option> is also set. This is useful when
 572        the target-host connection to cache.nixos.org is faster than the
 573        connection between hosts.
 574      </para>
 575     </listitem>
 576    </varlistentry>
 577
 578    <varlistentry>
 579     <term>
 580      <option>--use-remote-sudo</option>
 581     </term>
 582     <listitem>
 583      <para>
 584       When set, nixos-rebuild prefixes remote commands that run on
 585       the <option>--build-host</option> and <option>--target-host</option>
 586       systems with <command>sudo</command>. Setting this option allows
 587       deploying as a non-root user.
 588      </para>
 589     </listitem>
 590    </varlistentry>
 591
 592    <varlistentry>
 593     <term>
 594      <option>--flake</option> <replaceable>flake-uri</replaceable><optional>#<replaceable>name</replaceable></optional>
 595     </term>
 596     <listitem>
 597      <para>
 598       Build the NixOS system from the specified flake. It defaults to
 599       the directory containing the target of the symlink
 600       <filename>/etc/nixos/flake.nix</filename>, if it exists. The
 601       flake must contain an output named
 602       <literal>nixosConfigurations.<replaceable>name</replaceable></literal>. If
 603       <replaceable>name</replaceable> is omitted, it default to the
 604       current host name.
 605      </para>
 606     </listitem>
 607    </varlistentry>
 608
 609    <varlistentry>
 610     <term>
 611      <option>--no-flake</option>
 612     </term>
 613     <listitem>
 614      <para>
 615       Do not imply <option>--flake</option> if
 616       <filename>/etc/nixos/flake.nix</filename> exists. With this
 617       option, it is possible to build non-flake NixOS configurations
 618       even if the current NixOS systems uses flakes.
 619      </para>
 620     </listitem>
 621    </varlistentry>
 622
 623   </variablelist>
 624
 625   <para>
 626    In addition, <command>nixos-rebuild</command> accepts various Nix-related
 627    flags, including <option>--max-jobs</option> / <option>-j</option>,
 628    <option>--show-trace</option>, <option>--keep-failed</option>,
 629    <option>--keep-going</option>, <option>--impure</option>, and <option>--verbose</option> /
 630    <option>-v</option>. See the Nix manual for details.
 631   </para>
 632  </refsection>
 633
 634  <refsection>
 635   <title>Environment</title>
 636
 637   <variablelist>
 638    <varlistentry>
 639     <term>
 640      <envar>NIXOS_CONFIG</envar>
 641     </term>
 642     <listitem>
 643      <para>
 644       Path to the main NixOS configuration module. Defaults to
 645       <filename>/etc/nixos/configuration.nix</filename>.
 646      </para>
 647     </listitem>
 648    </varlistentry>
 649
 650    <varlistentry>
 651     <term>
 652      <envar>NIX_SSHOPTS</envar>
 653     </term>
 654     <listitem>
 655      <para>
 656       Additional options to be passed to <command>ssh</command> on the command
 657       line.
 658      </para>
 659     </listitem>
 660    </varlistentry>
 661   </variablelist>
 662  </refsection>
 663
 664  <refsection>
 665   <title>Files</title>
 666
 667   <variablelist>
 668
 669    <varlistentry>
 670     <term>
 671      <filename>/etc/nixos/flake.nix</filename>
 672     </term>
 673     <listitem>
 674      <para>
 675       If this file exists, then <command>nixos-rebuild</command> will
 676       use it as if the <option>--flake</option> option was given. This
 677       file may be a symlink to a <filename>flake.nix</filename> in an
 678       actual flake; thus <filename>/etc/nixos</filename> need not be a
 679       flake.
 680      </para>
 681     </listitem>
 682    </varlistentry>
 683
 684    <varlistentry>
 685     <term>
 686      <filename>/run/current-system</filename>
 687     </term>
 688     <listitem>
 689      <para>
 690       A symlink to the currently active system configuration in the Nix store.
 691      </para>
 692     </listitem>
 693    </varlistentry>
 694
 695    <varlistentry>
 696     <term>
 697      <filename>/nix/var/nix/profiles/system</filename>
 698     </term>
 699     <listitem>
 700      <para>
 701       The Nix profile that contains the current and previous system
 702       configurations. Used to generate the GRUB boot menu.
 703      </para>
 704     </listitem>
 705    </varlistentry>
 706
 707   </variablelist>
 708  </refsection>
 709
 710  <refsection>
 711   <title>Bugs</title>
 712   <para>
 713    This command should be renamed to something more descriptive.
 714   </para>
 715  </refsection>
 716 </refentry>