You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

man-nixos-rebuild.xml 17KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575
  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. <refnamediv>
  11. <refname><command>nixos-rebuild</command></refname>
  12. <refpurpose>reconfigure a NixOS machine</refpurpose>
  13. </refnamediv>
  14. <refsynopsisdiv>
  15. <cmdsynopsis>
  16. <command>nixos-rebuild</command><group choice='req'>
  17. <arg choice='plain'>
  18. <option>switch</option>
  19. </arg>
  20. <arg choice='plain'>
  21. <option>boot</option>
  22. </arg>
  23. <arg choice='plain'>
  24. <option>test</option>
  25. </arg>
  26. <arg choice='plain'>
  27. <option>build</option>
  28. </arg>
  29. <arg choice='plain'>
  30. <option>dry-build</option>
  31. </arg>
  32. <arg choice='plain'>
  33. <option>dry-activate</option>
  34. </arg>
  35. <arg choice='plain'>
  36. <option>edit</option>
  37. </arg>
  38. <arg choice='plain'>
  39. <option>build-vm</option>
  40. </arg>
  41. <arg choice='plain'>
  42. <option>build-vm-with-bootloader</option>
  43. </arg>
  44. </group>
  45. <sbr />
  46. <arg>
  47. <option>--upgrade</option>
  48. </arg>
  49. <arg>
  50. <option>--install-bootloader</option>
  51. </arg>
  52. <arg>
  53. <option>--no-build-nix</option>
  54. </arg>
  55. <arg>
  56. <option>--fast</option>
  57. </arg>
  58. <arg>
  59. <option>--rollback</option>
  60. </arg>
  61. <arg>
  62. <option>--builders</option> <replaceable>builder-spec</replaceable>
  63. </arg>
  64. <sbr />
  65. <arg>
  66. <group choice='req'>
  67. <arg choice='plain'>
  68. <option>--profile-name</option>
  69. </arg>
  70. <arg choice='plain'>
  71. <option>-p</option>
  72. </arg>
  73. </group> <replaceable>name</replaceable>
  74. </arg>
  75. <sbr />
  76. <arg>
  77. <option>--show-trace</option>
  78. </arg>
  79. <arg>
  80. <option>-I</option>
  81. <replaceable>path</replaceable>
  82. </arg>
  83. <arg>
  84. <group choice='req'>
  85. <arg choice='plain'><option>--verbose</option></arg>
  86. <arg choice='plain'><option>-v</option></arg>
  87. </group>
  88. </arg>
  89. <arg>
  90. <group choice='req'>
  91. <arg choice='plain'><option>--max-jobs</option></arg>
  92. <arg choice='plain'><option>-j</option></arg>
  93. </group>
  94. <replaceable>number</replaceable>
  95. </arg>
  96. <arg>
  97. <group choice='req'>
  98. <arg choice='plain'><option>--keep-failed</option></arg>
  99. <arg choice='plain'><option>-K</option></arg>
  100. </group>
  101. </arg>
  102. <arg>
  103. <group choice='req'>
  104. <arg choice='plain'><option>--keep-going</option></arg>
  105. <arg choice='plain'><option>-k</option></arg>
  106. </group>
  107. </arg>
  108. </cmdsynopsis>
  109. </refsynopsisdiv>
  110. <refsection>
  111. <title>Description</title>
  112. <para>
  113. This command updates the system so that it corresponds to the configuration
  114. specified in <filename>/etc/nixos/configuration.nix</filename>. Thus, every
  115. time you modify <filename>/etc/nixos/configuration.nix</filename> or any
  116. NixOS module, you must run <command>nixos-rebuild</command> to make the
  117. changes take effect. It builds the new system in
  118. <filename>/nix/store</filename>, runs its activation script, and stop and
  119. (re)starts any system services if needed. Please note that user services need
  120. to be started manually as they aren't detected by the activation script at the moment.
  121. </para>
  122. <para>
  123. This command has one required argument, which specifies the desired
  124. operation. It must be one of the following:
  125. <variablelist>
  126. <varlistentry>
  127. <term>
  128. <option>switch</option>
  129. </term>
  130. <listitem>
  131. <para>
  132. Build and activate the new configuration, and make it the boot default.
  133. That is, the configuration is added to the GRUB boot menu as the default
  134. menu entry, so that subsequent reboots will boot the system into the new
  135. configuration. Previous configurations activated with
  136. <command>nixos-rebuild switch</command> or <command>nixos-rebuild
  137. boot</command> remain available in the GRUB menu.
  138. </para>
  139. </listitem>
  140. </varlistentry>
  141. <varlistentry>
  142. <term>
  143. <option>boot</option>
  144. </term>
  145. <listitem>
  146. <para>
  147. Build the new configuration and make it the boot default (as with
  148. <command>nixos-rebuild switch</command>), but do not activate it. That
  149. is, the system continues to run the previous configuration until the
  150. next reboot.
  151. </para>
  152. </listitem>
  153. </varlistentry>
  154. <varlistentry>
  155. <term>
  156. <option>test</option>
  157. </term>
  158. <listitem>
  159. <para>
  160. Build and activate the new configuration, but do not add it to the GRUB
  161. boot menu. Thus, if you reboot the system (or if it crashes), you will
  162. automatically revert to the default configuration (i.e. the
  163. configuration resulting from the last call to <command>nixos-rebuild
  164. switch</command> or <command>nixos-rebuild boot</command>).
  165. </para>
  166. </listitem>
  167. </varlistentry>
  168. <varlistentry>
  169. <term>
  170. <option>build</option>
  171. </term>
  172. <listitem>
  173. <para>
  174. Build the new configuration, but neither activate it nor add it to the
  175. GRUB boot menu. It leaves a symlink named <filename>result</filename> in
  176. the current directory, which points to the output of the top-level
  177. “system” derivation. This is essentially the same as doing
  178. <screen>
  179. <prompt>$ </prompt>nix-build /path/to/nixpkgs/nixos -A system
  180. </screen>
  181. Note that you do not need to be <literal>root</literal> to run
  182. <command>nixos-rebuild build</command>.
  183. </para>
  184. </listitem>
  185. </varlistentry>
  186. <varlistentry>
  187. <term>
  188. <option>dry-build</option>
  189. </term>
  190. <listitem>
  191. <para>
  192. Show what store paths would be built or downloaded by any of the
  193. operations above, but otherwise do nothing.
  194. </para>
  195. </listitem>
  196. </varlistentry>
  197. <varlistentry>
  198. <term>
  199. <option>dry-activate</option>
  200. </term>
  201. <listitem>
  202. <para>
  203. Build the new configuration, but instead of activating it, show what
  204. changes would be performed by the activation (i.e. by
  205. <command>nixos-rebuild test</command>). For instance, this command will
  206. print which systemd units would be restarted. The list of changes is not
  207. guaranteed to be complete.
  208. </para>
  209. </listitem>
  210. </varlistentry>
  211. <varlistentry>
  212. <term>
  213. <option>edit</option>
  214. </term>
  215. <listitem>
  216. <para>
  217. Opens <filename>configuration.nix</filename> in the default editor.
  218. </para>
  219. </listitem>
  220. </varlistentry>
  221. <varlistentry>
  222. <term>
  223. <option>build-vm</option>
  224. </term>
  225. <listitem>
  226. <para>
  227. Build a script that starts a NixOS virtual machine with the desired
  228. configuration. It leaves a symlink <filename>result</filename> in the
  229. current directory that points (under
  230. <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>)
  231. at the script that starts the VM. Thus, to test a NixOS configuration in
  232. a virtual machine, you should do the following:
  233. <screen>
  234. <prompt>$ </prompt>nixos-rebuild build-vm
  235. <prompt>$ </prompt>./result/bin/run-*-vm
  236. </screen>
  237. </para>
  238. <para>
  239. The VM is implemented using the <literal>qemu</literal> package. For
  240. best performance, you should load the <literal>kvm-intel</literal> or
  241. <literal>kvm-amd</literal> kernel modules to get hardware
  242. virtualisation.
  243. </para>
  244. <para>
  245. The VM mounts the Nix store of the host through the 9P file system. The
  246. host Nix store is read-only, so Nix commands that modify the Nix store
  247. will not work in the VM. This includes commands such as
  248. <command>nixos-rebuild</command>; to change the VM’s configuration,
  249. you must halt the VM and re-run the commands above.
  250. </para>
  251. <para>
  252. The VM has its own <literal>ext3</literal> root file system, which is
  253. automatically created when the VM is first started, and is persistent
  254. across reboots of the VM. It is stored in
  255. <literal>./<replaceable>hostname</replaceable>.qcow2</literal>.
  256. <!-- The entire file system hierarchy of the host is available in
  257. the VM under <filename>/hostfs</filename>.-->
  258. </para>
  259. </listitem>
  260. </varlistentry>
  261. <varlistentry>
  262. <term>
  263. <option>build-vm-with-bootloader</option>
  264. </term>
  265. <listitem>
  266. <para>
  267. Like <option>build-vm</option>, but boots using the regular boot loader
  268. of your configuration (e.g., GRUB 1 or 2), rather than booting directly
  269. into the kernel and initial ramdisk of the system. This allows you to
  270. test whether the boot loader works correctly. However, it does not
  271. guarantee that your NixOS configuration will boot successfully on the
  272. host hardware (i.e., after running <command>nixos-rebuild
  273. switch</command>), because the hardware and boot loader configuration in
  274. the VM are different. The boot loader is installed on an automatically
  275. generated virtual disk containing a <filename>/boot</filename>
  276. partition, which is mounted read-only in the VM.
  277. </para>
  278. </listitem>
  279. </varlistentry>
  280. </variablelist>
  281. </para>
  282. </refsection>
  283. <refsection>
  284. <title>Options</title>
  285. <para>
  286. This command accepts the following options:
  287. </para>
  288. <variablelist>
  289. <varlistentry>
  290. <term>
  291. <option>--upgrade</option>
  292. </term>
  293. <listitem>
  294. <para>
  295. Fetch the latest version of NixOS from the NixOS channel.
  296. </para>
  297. </listitem>
  298. </varlistentry>
  299. <varlistentry>
  300. <term>
  301. <option>--install-bootloader</option>
  302. </term>
  303. <listitem>
  304. <para>
  305. Causes the boot loader to be (re)installed on the device specified by the
  306. relevant configuration options.
  307. </para>
  308. </listitem>
  309. </varlistentry>
  310. <varlistentry>
  311. <term>
  312. <option>--no-build-nix</option>
  313. </term>
  314. <listitem>
  315. <para>
  316. Normally, <command>nixos-rebuild</command> first builds the
  317. <varname>nixUnstable</varname> attribute in Nixpkgs, and uses the
  318. resulting instance of the Nix package manager to build the new system
  319. configuration. This is necessary if the NixOS modules use features not
  320. provided by the currently installed version of Nix. This option disables
  321. building a new Nix.
  322. </para>
  323. </listitem>
  324. </varlistentry>
  325. <varlistentry>
  326. <term>
  327. <option>--fast</option>
  328. </term>
  329. <listitem>
  330. <para>
  331. Equivalent to <option>--no-build-nix</option>
  332. <option>--show-trace</option>. This option is useful if you call
  333. <command>nixos-rebuild</command> frequently (e.g. if you’re hacking on
  334. a NixOS module).
  335. </para>
  336. </listitem>
  337. </varlistentry>
  338. <varlistentry>
  339. <term>
  340. <option>--rollback</option>
  341. </term>
  342. <listitem>
  343. <para>
  344. Instead of building a new configuration as specified by
  345. <filename>/etc/nixos/configuration.nix</filename>, roll back to the
  346. previous configuration. (The previous configuration is defined as the one
  347. before the “current” generation of the Nix profile
  348. <filename>/nix/var/nix/profiles/system</filename>.)
  349. </para>
  350. </listitem>
  351. </varlistentry>
  352. <varlistentry>
  353. <term>
  354. <option>--builders</option> <replaceable>builder-spec</replaceable>
  355. </term>
  356. <listitem>
  357. <para>
  358. Allow ad-hoc remote builders for building the new system. This requires
  359. the user executing <command>nixos-rebuild</command> (usually root) to be
  360. configured as a trusted user in the Nix daemon. This can be achieved by
  361. using the <literal>nix.trustedUsers</literal> NixOS option. Examples
  362. values for that option are described in the <literal>Remote builds
  363. chapter</literal> in the Nix manual, (i.e. <command>--builders
  364. "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string
  365. existing builders specified in <filename>/etc/nix/machines</filename> can
  366. be ignored: <command>--builders ""</command> for example when they are
  367. not reachable due to network connectivity.
  368. </para>
  369. </listitem>
  370. </varlistentry>
  371. <varlistentry>
  372. <term>
  373. <option>--profile-name</option>
  374. </term>
  375. <term>
  376. <option>-p</option>
  377. </term>
  378. <listitem>
  379. <para>
  380. Instead of using the Nix profile
  381. <filename>/nix/var/nix/profiles/system</filename> to keep track of the
  382. current and previous system configurations, use
  383. <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>.
  384. When you use GRUB 2, for every system profile created with this flag,
  385. NixOS will create a submenu named “NixOS - Profile
  386. '<replaceable>name</replaceable>'” in GRUB’s boot menu, containing
  387. the current and previous configurations of this profile.
  388. </para>
  389. <para>
  390. For instance, if you want to test a configuration file named
  391. <filename>test.nix</filename> without affecting the default system
  392. profile, you would do:
  393. <screen>
  394. <prompt>$ </prompt>nixos-rebuild switch -p test -I nixos-config=./test.nix
  395. </screen>
  396. The new configuration will appear in the GRUB 2 submenu “NixOS -
  397. Profile 'test'”.
  398. </para>
  399. </listitem>
  400. </varlistentry>
  401. <varlistentry>
  402. <term>
  403. <option>--build-host</option>
  404. </term>
  405. <listitem>
  406. <para>
  407. Instead of building the new configuration locally, use the specified host
  408. to perform the build. The host needs to be accessible with ssh, and must
  409. be able to perform Nix builds. If the option
  410. <option>--target-host</option> is not set, the build will be copied back
  411. to the local machine when done.
  412. </para>
  413. <para>
  414. Note that, if <option>--no-build-nix</option> is not specified, Nix will
  415. be built both locally and remotely. This is because the configuration
  416. will always be evaluated locally even though the building might be
  417. performed remotely.
  418. </para>
  419. <para>
  420. You can include a remote user name in the host name
  421. (<replaceable>user@host</replaceable>). You can also set ssh options by
  422. defining the <envar>NIX_SSHOPTS</envar> environment variable.
  423. </para>
  424. </listitem>
  425. </varlistentry>
  426. <varlistentry>
  427. <term>
  428. <option>--target-host</option>
  429. </term>
  430. <listitem>
  431. <para>
  432. Specifies the NixOS target host. By setting this to something other than
  433. <replaceable>localhost</replaceable>, the system activation will happen
  434. on the remote host instead of the local machine. The remote host needs to
  435. be accessible over ssh, and for the commands <option>switch</option>,
  436. <option>boot</option> and <option>test</option> you need root access.
  437. </para>
  438. <para>
  439. If <option>--build-host</option> is not explicitly specified,
  440. <option>--build-host</option> will implicitly be set to the same value as
  441. <option>--target-host</option>. So, if you only specify
  442. <option>--target-host</option> both building and activation will take
  443. place remotely (and no build artifacts will be copied to the local
  444. machine).
  445. </para>
  446. <para>
  447. You can include a remote user name in the host name
  448. (<replaceable>user@host</replaceable>). You can also set ssh options by
  449. defining the <envar>NIX_SSHOPTS</envar> environment variable.
  450. </para>
  451. </listitem>
  452. </varlistentry>
  453. </variablelist>
  454. <para>
  455. In addition, <command>nixos-rebuild</command> accepts various Nix-related
  456. flags, including <option>--max-jobs</option> / <option>-j</option>,
  457. <option>--show-trace</option>, <option>--keep-failed</option>,
  458. <option>--keep-going</option> and <option>--verbose</option> /
  459. <option>-v</option>. See the Nix manual for details.
  460. </para>
  461. </refsection>
  462. <refsection>
  463. <title>Environment</title>
  464. <variablelist>
  465. <varlistentry>
  466. <term>
  467. <envar>NIXOS_CONFIG</envar>
  468. </term>
  469. <listitem>
  470. <para>
  471. Path to the main NixOS configuration module. Defaults to
  472. <filename>/etc/nixos/configuration.nix</filename>.
  473. </para>
  474. </listitem>
  475. </varlistentry>
  476. <varlistentry>
  477. <term>
  478. <envar>NIX_SSHOPTS</envar>
  479. </term>
  480. <listitem>
  481. <para>
  482. Additional options to be passed to <command>ssh</command> on the command
  483. line.
  484. </para>
  485. </listitem>
  486. </varlistentry>
  487. </variablelist>
  488. </refsection>
  489. <refsection>
  490. <title>Files</title>
  491. <variablelist>
  492. <varlistentry>
  493. <term>
  494. <filename>/run/current-system</filename>
  495. </term>
  496. <listitem>
  497. <para>
  498. A symlink to the currently active system configuration in the Nix store.
  499. </para>
  500. </listitem>
  501. </varlistentry>
  502. <varlistentry>
  503. <term>
  504. <filename>/nix/var/nix/profiles/system</filename>
  505. </term>
  506. <listitem>
  507. <para>
  508. The Nix profile that contains the current and previous system
  509. configurations. Used to generate the GRUB boot menu.
  510. </para>
  511. </listitem>
  512. </varlistentry>
  513. </variablelist>
  514. </refsection>
  515. <refsection>
  516. <title>Bugs</title>
  517. <para>
  518. This command should be renamed to something more descriptive.
  519. </para>
  520. </refsection>
  521. </refentry>