path: root/nixos/doc/manual/man-nixos-generate-config.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-generate-config</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-generate-config</command></refname>
  <refpurpose>generate NixOS configuration modules</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <cmdsynopsis>
   <command>nixos-generate-config</command>
   <arg>
    <option>--force</option>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--root</option>
    </arg>
     <replaceable>root</replaceable>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--dir</option>
    </arg>
     <replaceable>dir</replaceable>
   </arg>
  </cmdsynopsis>
 </refsynopsisdiv>
 <refsection>
  <title>Description</title>
  <para>
   This command writes two NixOS configuration modules:
   <variablelist>
    <varlistentry>
     <term>
      <option>/etc/nixos/hardware-configuration.nix</option>
     </term>
     <listitem>
      <para>
       This module sets NixOS configuration options based on your current
       hardware configuration. In particular, it sets the
       <option>fileSystem</option> option to reflect all currently mounted file
       systems, the <option>swapDevices</option> option to reflect active swap
       devices, and the <option>boot.initrd.*</option> options to ensure that
       the initial ramdisk contains any kernel modules necessary for mounting
       the root file system.
      </para>
      <para>
       If this file already exists, it is overwritten. Thus, you should not
       modify it manually. Rather, you should include it from your
       <filename>/etc/nixos/configuration.nix</filename>, and re-run
       <command>nixos-generate-config</command> to update it whenever your
       hardware configuration changes.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <option>/etc/nixos/configuration.nix</option>
     </term>
     <listitem>
      <para>
       This is the main NixOS system configuration module. If it already
       exists, it’s left unchanged. Otherwise,
       <command>nixos-generate-config</command> will write a template for you
       to customise.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsection>
 <refsection>
  <title>Options</title>
  <para>
   This command accepts the following options:
  </para>
  <variablelist>
   <varlistentry>
    <term>
     <option>--root</option>
    </term>
    <listitem>
     <para>
      If this option is given, treat the directory
      <replaceable>root</replaceable> as the root of the file system. This
      means that configuration files will be written to
      <filename><replaceable>root</replaceable>/etc/nixos</filename>, and that
      any file systems outside of <replaceable>root</replaceable> are ignored
      for the purpose of generating the <option>fileSystems</option> option.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--dir</option>
    </term>
    <listitem>
     <para>
      If this option is given, write the configuration files to the directory
      <replaceable>dir</replaceable> instead of
      <filename>/etc/nixos</filename>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--force</option>
    </term>
    <listitem>
     <para>
      Overwrite <filename>/etc/nixos/configuration.nix</filename> if it already
      exists.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--no-filesystems</option>
    </term>
    <listitem>
     <para>
      Omit everything concerning file systems and swap devices from the
      hardware configuration.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--show-hardware-config</option>
    </term>
    <listitem>
     <para>
      Don't generate <filename>configuration.nix</filename> or
      <filename>hardware-configuration.nix</filename> and print the hardware
      configuration to stdout only.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsection>
 <refsection>
  <title>Examples</title>
  <para>
   This command is typically used during NixOS installation to write initial
   configuration modules. For example, if you created and mounted the target
   file systems on <filename>/mnt</filename> and
   <filename>/mnt/boot</filename>, you would run:
<screen>
<prompt>$ </prompt>nixos-generate-config --root /mnt
</screen>
   The resulting file
   <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> might look
   like this:
<programlisting>
# Do not modify this file!  It was generated by ‘nixos-generate-config’
# and may be overwritten by future invocations.  Please make changes
# to /etc/nixos/configuration.nix instead.
{ config, pkgs, ... }:

{
  imports =
    [ &lt;nixos/modules/installer/scan/not-detected.nix&gt;
    ];

  boot.initrd.availableKernelModules = [ "ehci_hcd" "ahci" ];
  boot.kernelModules = [ "kvm-intel" ];
  boot.extraModulePackages = [ ];

  fileSystems."/" =
    { device = "/dev/disk/by-label/nixos";
      fsType = "ext3";
      options = [ "rw" "data=ordered" "relatime" ];
    };

  fileSystems."/boot" =
    { device = "/dev/sda1";
      fsType = "ext3";
      options = [ "rw" "errors=continue" "user_xattr" "acl" "barrier=1" "data=writeback" "relatime" ];
    };

  swapDevices =
    [ { device = "/dev/sda2"; }
    ];

  nix.maxJobs = 8;
}
</programlisting>
   It will also create a basic
   <filename>/mnt/etc/nixos/configuration.nix</filename>, which you should edit
   to customise the logical configuration of your system. This file includes
   the result of the hardware scan as follows:
<programlisting>
  imports = [ ./hardware-configuration.nix ];
</programlisting>
  </para>
  <para>
   After installation, if your hardware configuration changes, you can run:
<screen>
<prompt>$ </prompt>nixos-generate-config
</screen>
   to update <filename>/etc/nixos/hardware-configuration.nix</filename>. Your
   <filename>/etc/nixos/configuration.nix</filename> will
   <emphasis>not</emphasis> be overwritten.
  </para>
 </refsection>
</refentry>