pyrox.dev
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
5<refmeta>
6 <refentrytitle><command>nixos-generate-config</command></refentrytitle>
7 <manvolnum>8</manvolnum>
8 <refmiscinfo class="source">NixOS</refmiscinfo>
9 <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
10</refmeta>
11
12<refnamediv>
13 <refname><command>nixos-generate-config</command></refname>
14 <refpurpose>generate NixOS configuration modules</refpurpose>
15</refnamediv>
16
17<refsynopsisdiv>
18 <cmdsynopsis>
19 <command>nixos-generate-config</command>
20 <arg><option>--force</option></arg>
21 <arg>
22 <arg choice='plain'><option>--root</option></arg>
23 <replaceable>root</replaceable>
24 </arg>
25 <arg>
26 <arg choice='plain'><option>--dir</option></arg>
27 <replaceable>dir</replaceable>
28 </arg>
29 </cmdsynopsis>
30</refsynopsisdiv>
31
32
33<refsection><title>Description</title>
34
35<para>This command writes two NixOS configuration modules:
36
37<variablelist>
38
39 <varlistentry>
40 <term><option>/etc/nixos/hardware-configuration.nix</option></term>
41 <listitem>
42 <para>This module sets NixOS configuration options based on your
43 current hardware configuration. In particular, it sets the
44 <option>fileSystem</option> option to reflect all currently
45 mounted file systems, the <option>swapDevices</option> option to
46 reflect active swap devices, and the
47 <option>boot.initrd.*</option> options to ensure that the
48 initial ramdisk contains any kernel modules necessary for
49 mounting the root file system.</para>
50
51 <para>If this file already exists, it is overwritten. Thus, you
52 should not modify it manually. Rather, you should include it
53 from your <filename>/etc/nixos/configuration.nix</filename>, and
54 re-run <command>nixos-generate-config</command> to update it
55 whenever your hardware configuration changes.</para>
56 </listitem>
57 </varlistentry>
58
59 <varlistentry>
60 <term><option>/etc/nixos/configuration.nix</option></term>
61 <listitem>
62 <para>This is the main NixOS system configuration module. If it
63 already exists, it’s left unchanged. Otherwise,
64 <command>nixos-generate-config</command> will write a template
65 for you to customise.</para>
66 </listitem>
67 </varlistentry>
68
69</variablelist>
70
71</para>
72
73</refsection>
74
75
76<refsection><title>Options</title>
77
78<para>This command accepts the following options:</para>
79
80<variablelist>
81
82 <varlistentry>
83 <term><option>--root</option></term>
84 <listitem>
85 <para>If this option is given, treat the directory
86 <replaceable>root</replaceable> as the root of the file system.
87 This means that configuration files will be written to
88 <filename><replaceable>root</replaceable>/etc/nixos</filename>,
89 and that any file systems outside of
90 <replaceable>root</replaceable> are ignored for the purpose of
91 generating the <option>fileSystems</option> option.</para>
92 </listitem>
93 </varlistentry>
94
95 <varlistentry>
96 <term><option>--dir</option></term>
97 <listitem>
98 <para>If this option is given, write the configuration files to
99 the directory <replaceable>dir</replaceable> instead of
100 <filename>/etc/nixos</filename>.</para>
101 </listitem>
102 </varlistentry>
103
104 <varlistentry>
105 <term><option>--force</option></term>
106 <listitem>
107 <para>Overwrite
108 <filename>/etc/nixos/configuration.nix</filename> if it already
109 exists.</para>
110 </listitem>
111 </varlistentry>
112
113 <varlistentry>
114 <term><option>--no-filesystems</option></term>
115 <listitem>
116 <para>Omit everything concerning file systems and swap devices
117 from the hardware configuration.</para>
118 </listitem>
119 </varlistentry>
120
121 <varlistentry>
122 <term><option>--show-hardware-config</option></term>
123 <listitem>
124 <para>Don't generate <filename>configuration.nix</filename> or
125 <filename>hardware-configuration.nix</filename> and print the
126 hardware configuration to stdout only.</para>
127 </listitem>
128 </varlistentry>
129
130</variablelist>
131
132</refsection>
133
134
135<refsection><title>Examples</title>
136
137<para>This command is typically used during NixOS installation to
138write initial configuration modules. For example, if you created and
139mounted the target file systems on <filename>/mnt</filename> and
140<filename>/mnt/boot</filename>, you would run:
141
142<screen>
143$ nixos-generate-config --root /mnt
144</screen>
145
146The resulting file
147<filename>/mnt/etc/nixos/hardware-configuration.nix</filename> might
148look like this:
149
150<programlisting>
151# Do not modify this file! It was generated by ‘nixos-generate-config’
152# and may be overwritten by future invocations. Please make changes
153# to /etc/nixos/configuration.nix instead.
154{ config, pkgs, ... }:
155
156{
157 imports =
158 [ <nixos/modules/installer/scan/not-detected.nix>
159 ];
160
161 boot.initrd.availableKernelModules = [ "ehci_hcd" "ahci" ];
162 boot.kernelModules = [ "kvm-intel" ];
163 boot.extraModulePackages = [ ];
164
165 fileSystems."/" =
166 { device = "/dev/disk/by-label/nixos";
167 fsType = "ext3";
168 options = [ "rw" "data=ordered" "relatime" ];
169 };
170
171 fileSystems."/boot" =
172 { device = "/dev/sda1";
173 fsType = "ext3";
174 options = [ "rw" "errors=continue" "user_xattr" "acl" "barrier=1" "data=writeback" "relatime" ];
175 };
176
177 swapDevices =
178 [ { device = "/dev/sda2"; }
179 ];
180
181 nix.maxJobs = 8;
182}
183</programlisting>
184
185It will also create a basic
186<filename>/mnt/etc/nixos/configuration.nix</filename>, which you
187should edit to customise the logical configuration of your system.
188This file includes the result of the hardware scan as follows:
189
190<programlisting>
191 imports = [ ./hardware-configuration.nix ];
192</programlisting>
193</para>
194
195<para>After installation, if your hardware configuration changes, you
196can run:
197
198<screen>
199$ nixos-generate-config
200</screen>
201
202to update <filename>/etc/nixos/hardware-configuration.nix</filename>.
203Your <filename>/etc/nixos/configuration.nix</filename> will
204<emphasis>not</emphasis> be overwritten.</para>
205
206</refsection>
207
208</refentry>