nixpkgs/nixos/doc/manual/man-nixos-generate-config.xml
Albert Safin 0eaf29433e nixos/doc: fix manpage format
Spaces inside <refname> cause stray double underscore in generated manual pages.

Fixes #70468
2019-10-05 15:55:49 +00:00

215 lines
6.3 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<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, its 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>