nixpkgs/nixos/doc/manual/man-nixos-install.xml
2019-09-18 22:13:35 +02:00

229 lines
7.2 KiB
XML

<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-install</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-install</command>
</refname><refpurpose>install bootloader and NixOS</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>nixos-install</command>
<arg>
<arg choice='plain'>
<option>-I</option>
</arg>
<replaceable>path</replaceable>
</arg>
<arg>
<arg choice='plain'>
<option>--root</option>
</arg>
<replaceable>root</replaceable>
</arg>
<arg>
<arg choice='plain'>
<option>--system</option>
</arg>
<replaceable>path</replaceable>
</arg>
<arg>
<arg choice='plain'>
<option>--no-channel-copy</option>
</arg>
</arg>
<arg>
<arg choice='plain'>
<option>--no-root-passwd</option>
</arg>
</arg>
<arg>
<arg choice='plain'>
<option>--no-bootloader</option>
</arg>
</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>
<option>--cores</option> <replaceable>number</replaceable>
</arg>
<arg>
<option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
</arg>
<arg>
<arg choice='plain'>
<option>--show-trace</option>
</arg>
</arg>
<arg>
<arg choice='plain'>
<option>--help</option>
</arg>
</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
This command installs NixOS in the file system mounted on <filename>/mnt</filename>, based on the NixOS configuration specified in <filename>/mnt/etc/nixos/configuration.nix</filename>. It performs the following steps:
<itemizedlist>
<listitem>
<para>
It copies Nix and its dependencies to <filename>/mnt/nix/store</filename>.
</para>
</listitem>
<listitem>
<para>
It runs Nix in <filename>/mnt</filename> to build the NixOS configuration specified in <filename>/mnt/etc/nixos/configuration.nix</filename>.
</para>
</listitem>
<listitem>
<para>
It installs the GRUB boot loader on the device specified in the option <option>boot.loader.grub.device</option> (unless <option>--no-bootloader</option> is specified), and generates a GRUB configuration file that boots into the NixOS configuration just installed.
</para>
</listitem>
<listitem>
<para>
It prompts you for a password for the root account (unless <option>--no-root-passwd</option> is specified).
</para>
</listitem>
</itemizedlist>
</para>
<para>
This command is idempotent: if it is interrupted or fails due to a temporary problem (e.g. a network issue), you can safely re-run it.
</para>
</refsection>
<refsection>
<title>Options</title>
<para>
This command accepts the following options:
</para>
<variablelist>
<varlistentry>
<term>
<option>--root</option>
</term>
<listitem>
<para>
Defaults to <filename>/mnt</filename>. If this option is given, treat the directory <replaceable>root</replaceable> as the root of the NixOS installation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--system</option>
</term>
<listitem>
<para>
If this option is provided, <command>nixos-install</command> will install the specified closure rather than attempt to build one from <filename>/mnt/etc/nixos/configuration.nix</filename>.
</para>
<para>
The closure must be an appropriately configured NixOS system, with boot loader and partition configuration that fits the target host. Such a closure is typically obtained with a command such as <command>nix-build -I nixos-config=./configuration.nix '&lt;nixos&gt;' -A system --no-out-link</command>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-I</option>
</term>
<listitem>
<para>
Add a path to the Nix expression search path. This option may be given multiple times. See the NIX_PATH environment variable for information on the semantics of the Nix search path. Paths added through <replaceable>-I</replaceable> take precedence over NIX_PATH.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--max-jobs</option>
</term>
<term>
<option>-j</option>
</term>
<listitem>
<para>
Sets the maximum number of build jobs that Nix will perform in parallel to the specified number. The default is <literal>1</literal>. A higher value is useful on SMP systems or to exploit I/O latency.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--cores</option>
</term>
<listitem>
<para>
Sets the value of the <envar>NIX_BUILD_CORES</envar> environment variable in the invocation of builders. Builders can use this variable at their discretion to control the maximum amount of parallelism. For instance, in Nixpkgs, if the derivation attribute <varname>enableParallelBuilding</varname> is set to <literal>true</literal>, the builder passes the <option>-j<replaceable>N</replaceable></option> flag to GNU Make. The value <literal>0</literal> means that the builder should use all available CPU cores in the system.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
</term>
<listitem>
<para>
Set the Nix configuration option <replaceable>name</replaceable> to <replaceable>value</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--show-trace</option>
</term>
<listitem>
<para>
Causes Nix to print out a stack trace in case of Nix expression evaluation errors.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--help</option>
</term>
<listitem>
<para>
Synonym for <command>man nixos-install</command>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsection>
<refsection>
<title>Examples</title>
<para>
A typical NixOS installation is done by creating and mounting a file system on <filename>/mnt</filename>, generating a NixOS configuration in <filename>/mnt/etc/nixos/configuration.nix</filename>, and running <command>nixos-install</command>. For instance, if we want to install NixOS on an <literal>ext4</literal> file system created in <filename>/dev/sda1</filename>:
<screen>
<prompt>$ </prompt>mkfs.ext4 /dev/sda1
<prompt>$ </prompt>mount /dev/sda1 /mnt
<prompt>$ </prompt>nixos-generate-config --root /mnt
<prompt>$ </prompt># edit /mnt/etc/nixos/configuration.nix
<prompt>$ </prompt>nixos-install
<prompt>$ </prompt>reboot
</screen>
</para>
</refsection>
</refentry>