diff options
Diffstat (limited to 'nixos/doc/manual/man-nixos-generate-config.xml')
-rw-r--r-- | nixos/doc/manual/man-nixos-generate-config.xml | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/nixos/doc/manual/man-nixos-generate-config.xml b/nixos/doc/manual/man-nixos-generate-config.xml new file mode 100644 index 00000000000..9ac3b918ff6 --- /dev/null +++ b/nixos/doc/manual/man-nixos-generate-config.xml @@ -0,0 +1,214 @@ +<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 = + [ <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> +<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> |