diff options
author | Eelco Dolstra <eelco.dolstra@logicblox.com> | 2013-10-13 16:20:49 +0200 |
---|---|---|
committer | Eelco Dolstra <eelco.dolstra@logicblox.com> | 2013-10-13 17:35:57 +0200 |
commit | 00f380dee5c395704b8b83c462d0d735ff0e810e (patch) | |
tree | 08a95538d8f89c791f2742d70f507396b891e53a /nixos/doc/manual | |
parent | ca3725bfc96ebc7c8c5580805998135039319265 (diff) | |
download | nixlib-00f380dee5c395704b8b83c462d0d735ff0e810e.tar nixlib-00f380dee5c395704b8b83c462d0d735ff0e810e.tar.gz nixlib-00f380dee5c395704b8b83c462d0d735ff0e810e.tar.bz2 nixlib-00f380dee5c395704b8b83c462d0d735ff0e810e.tar.lz nixlib-00f380dee5c395704b8b83c462d0d735ff0e810e.tar.xz nixlib-00f380dee5c395704b8b83c462d0d735ff0e810e.tar.zst nixlib-00f380dee5c395704b8b83c462d0d735ff0e810e.zip |
Document nixos-generate-config
Diffstat (limited to 'nixos/doc/manual')
-rw-r--r-- | nixos/doc/manual/man-nixos-generate-config.xml | 191 | ||||
-rw-r--r-- | nixos/doc/manual/man-pages.xml | 11 |
2 files changed, 196 insertions, 6 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 000000000000..ff69d8d91701 --- /dev/null +++ b/nixos/doc/manual/man-nixos-generate-config.xml @@ -0,0 +1,191 @@ +<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> + +</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 = + [ <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> diff --git a/nixos/doc/manual/man-pages.xml b/nixos/doc/manual/man-pages.xml index 7840e1b897b0..5178d595fda6 100644 --- a/nixos/doc/manual/man-pages.xml +++ b/nixos/doc/manual/man-pages.xml @@ -15,17 +15,16 @@ </author> <copyright> - <year>2007</year> - <year>2008</year> - <year>2009</year> + <year>2007-2013</year> <holder>Eelco Dolstra</holder> </copyright> - + </info> - + <xi:include href="man-configuration.xml" /> <xi:include href="man-nixos-rebuild.xml" /> + <xi:include href="man-nixos-generate-config.xml" /> <xi:include href="man-nixos-option.xml" /> <xi:include href="man-nixos-build-vms.xml" /> - + </reference> |