<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>
$ 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>
    ];

  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>
$ 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>