diff options
| -rw-r--r-- | nixos/doc/manual/default.nix | 9 | ||||
| -rw-r--r-- | nixos/doc/manual/man-nixos-build-vms.xml | 138 | ||||
| -rw-r--r-- | nixos/doc/manual/man-nixos-enter.xml | 154 | ||||
| -rw-r--r-- | nixos/doc/manual/man-nixos-generate-config.xml | 214 | ||||
| -rw-r--r-- | nixos/doc/manual/man-nixos-install.xml | 357 | ||||
| -rw-r--r-- | nixos/doc/manual/man-nixos-option.xml | 134 | ||||
| -rw-r--r-- | nixos/doc/manual/man-nixos-rebuild.xml | 781 | ||||
| -rw-r--r-- | nixos/doc/manual/man-nixos-version.xml | 158 | ||||
| -rw-r--r-- | nixos/doc/manual/man-pages.xml | 7 | ||||
| -rw-r--r-- | nixos/doc/manual/manpages/README.md | 55 | ||||
| -rw-r--r-- | nixos/doc/manual/manpages/nixos-build-vms.8 | 109 | ||||
| -rw-r--r-- | nixos/doc/manual/manpages/nixos-enter.8 | 76 | ||||
| -rw-r--r-- | nixos/doc/manual/manpages/nixos-generate-config.8 | 169 | ||||
| -rw-r--r-- | nixos/doc/manual/manpages/nixos-install.8 | 195 | ||||
| -rw-r--r-- | nixos/doc/manual/manpages/nixos-option.8 | 93 | ||||
| -rw-r--r-- | nixos/doc/manual/manpages/nixos-rebuild.8 | 456 | ||||
| -rw-r--r-- | nixos/doc/manual/manpages/nixos-version.8 | 90 |
17 files changed, 1250 insertions, 1945 deletions
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 913058746b35c..264a8bcef27c2 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -254,12 +254,17 @@ in rec { # Generate the NixOS manpages. manpages = runCommand "nixos-manpages" { inherit sources; - nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ]; + nativeBuildInputs = [ + buildPackages.libxml2.bin + buildPackages.libxslt.bin + buildPackages.installShellFiles + ]; allowedReferences = ["out"]; } '' # Generate manpages. - mkdir -p $out/share/man + mkdir -p $out/share/man/man8 + installManPage ${./manpages}/* xsltproc --nonet \ --maxdepth 6000 \ --param man.output.in.separate.dir 1 \ diff --git a/nixos/doc/manual/man-nixos-build-vms.xml b/nixos/doc/manual/man-nixos-build-vms.xml deleted file mode 100644 index fa7c8c0c6d799..0000000000000 --- a/nixos/doc/manual/man-nixos-build-vms.xml +++ /dev/null @@ -1,138 +0,0 @@ -<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-build-vms</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-build-vms</command></refname> - <refpurpose>build a network of virtual machines from a network of NixOS configurations</refpurpose> - </refnamediv> - <refsynopsisdiv> - <cmdsynopsis> - <command>nixos-build-vms</command> - <arg> - <option>--show-trace</option> - </arg> - - <arg> - <option>--no-out-link</option> - </arg> - - <arg> - <option>--help</option> - </arg> - - <arg> - <option>--option</option> - <replaceable>name</replaceable> - <replaceable>value</replaceable> - </arg> - - <arg choice="plain"> - <replaceable>network.nix</replaceable> - </arg> - </cmdsynopsis> - </refsynopsisdiv> - <refsection> - <title>Description</title> - <para> - This command builds a network of QEMU-KVM virtual machines of a Nix - expression specifying a network of NixOS machines. The virtual network can - be started by executing the <filename>bin/run-vms</filename> shell script - that is generated by this command. By default, a <filename>result</filename> - symlink is produced that points to the generated virtual network. - </para> - <para> - A network Nix expression has the following structure: -<screen> -{ - test1 = {pkgs, config, ...}: - { - services.openssh.enable = true; - nixpkgs.localSystem.system = "i686-linux"; - deployment.targetHost = "test1.example.net"; - - # Other NixOS options - }; - - test2 = {pkgs, config, ...}: - { - services.openssh.enable = true; - services.httpd.enable = true; - environment.systemPackages = [ pkgs.lynx ]; - nixpkgs.localSystem.system = "x86_64-linux"; - deployment.targetHost = "test2.example.net"; - - # Other NixOS options - }; -} -</screen> - Each attribute in the expression represents a machine in the network (e.g. - <varname>test1</varname> and <varname>test2</varname>) referring to a - function defining a NixOS configuration. In each NixOS configuration, two - attributes have a special meaning. The - <varname>deployment.targetHost</varname> specifies the address (domain name - or IP address) of the system which is used by <command>ssh</command> to - perform remote deployment operations. The - <varname>nixpkgs.localSystem.system</varname> attribute can be used to - specify an architecture for the target machine, such as - <varname>i686-linux</varname> which builds a 32-bit NixOS configuration. - Omitting this property will build the configuration for the same - architecture as the host system. - </para> - </refsection> - <refsection> - <title>Options</title> - <para> - This command accepts the following options: - </para> - <variablelist> - <varlistentry> - <term> - <option>--show-trace</option> - </term> - <listitem> - <para> - Shows a trace of the output. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--no-out-link</option> - </term> - <listitem> - <para> - Do not create a 'result' symlink. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-h</option>, <option>--help</option> - </term> - <listitem> - <para> - Shows the usage of this command to the user. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable> - </term> - <listitem> - <para>Set the Nix configuration option - <replaceable>name</replaceable> to <replaceable>value</replaceable>. - This overrides settings in the Nix configuration file (see - <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - </para> - </listitem> - </varlistentry> - </variablelist> - </refsection> -</refentry> diff --git a/nixos/doc/manual/man-nixos-enter.xml b/nixos/doc/manual/man-nixos-enter.xml deleted file mode 100644 index 41f0e6b975159..0000000000000 --- a/nixos/doc/manual/man-nixos-enter.xml +++ /dev/null @@ -1,154 +0,0 @@ -<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-enter</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-enter</command></refname> - <refpurpose>run a command in a NixOS chroot environment</refpurpose> - </refnamediv> - <refsynopsisdiv> - <cmdsynopsis> - <command>nixos-enter</command> - <arg> - <arg choice='plain'> - <option>--root</option> - </arg> - <replaceable>root</replaceable> - </arg> - - <arg> - <arg choice='plain'> - <option>--system</option> - </arg> - <replaceable>system</replaceable> - </arg> - - <arg> - <arg choice='plain'> - <option>-c</option> - </arg> - <replaceable>shell-command</replaceable> - </arg> - - <arg> - <arg choice='plain'> - <option>--silent</option> - </arg> - </arg> - - <arg> - <arg choice='plain'> - <option>--help</option> - </arg> - </arg> - - <arg> - <arg choice='plain'> - <option>--</option> - </arg> - <replaceable>arguments</replaceable> - </arg> - </cmdsynopsis> - </refsynopsisdiv> - <refsection> - <title>Description</title> - <para> - This command runs a command in a NixOS chroot environment, that is, in a - filesystem hierarchy previously prepared using - <command>nixos-install</command>. - </para> - </refsection> - <refsection> - <title>Options</title> - <para> - This command accepts the following options: - </para> - <variablelist> - <varlistentry> - <term> - <option>--root</option> - </term> - <listitem> - <para> - The path to the NixOS system you want to enter. It defaults to - <filename>/mnt</filename>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--system</option> - </term> - <listitem> - <para> - The NixOS system configuration to use. It defaults to - <filename>/nix/var/nix/profiles/system</filename>. You can enter a - previous NixOS configuration by specifying a path such as - <filename>/nix/var/nix/profiles/system-106-link</filename>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--command</option> - </term> - <term> - <option>-c</option> - </term> - <listitem> - <para> - The bash command to execute. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--silent</option> - </term> - <listitem> - <para> - Suppresses all output from the activation script of the target system. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--</option> - </term> - <listitem> - <para> - Interpret the remaining arguments as the program name and arguments to be - invoked. The program is not executed in a shell. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsection> - <refsection> - <title>Examples</title> - <para> - Start an interactive shell in the NixOS installation in - <filename>/mnt</filename>: - </para> -<screen> -<prompt># </prompt>nixos-enter --root /mnt -</screen> - <para> - Run a shell command: - </para> -<screen> -<prompt># </prompt>nixos-enter -c 'ls -l /; cat /proc/mounts' -</screen> - <para> - Run a non-shell command: - </para> -<screen> -# nixos-enter -- cat /proc/mounts -</screen> - </refsection> -</refentry> diff --git a/nixos/doc/manual/man-nixos-generate-config.xml b/nixos/doc/manual/man-nixos-generate-config.xml deleted file mode 100644 index 9ac3b918ff693..0000000000000 --- a/nixos/doc/manual/man-nixos-generate-config.xml +++ /dev/null @@ -1,214 +0,0 @@ -<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> diff --git a/nixos/doc/manual/man-nixos-install.xml b/nixos/doc/manual/man-nixos-install.xml deleted file mode 100644 index eb6680b65677e..0000000000000 --- a/nixos/doc/manual/man-nixos-install.xml +++ /dev/null @@ -1,357 +0,0 @@ -<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-install</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-install</command></refname> - <refpurpose>install bootloader and NixOS</refpurpose> - </refnamediv> - <refsynopsisdiv> - <cmdsynopsis> - <command>nixos-install</command> - <arg> - <group choice='req'> - <arg choice='plain'> - <option>--verbose</option> - </arg> - <arg choice='plain'> - <option>-v</option> - </arg> - </group> - </arg> - <arg> - <arg choice='plain'> - <option>-I</option> - </arg> - <replaceable>path</replaceable> - </arg> - - <arg> - <arg choice='plain'> - <option>--root</option> - </arg> - <replaceable>root</replaceable> - </arg> - - <arg> - <arg choice='plain'> - <option>--system</option> - </arg> - <replaceable>path</replaceable> - </arg> - - <arg> - <option>--flake</option> <replaceable>flake-uri</replaceable> - </arg> - - <arg> - <group choice='req'> - <arg choice='plain'><option>--impure</option></arg> - </group> - </arg> - - <arg> - <arg choice='plain'> - <option>--channel</option> - </arg> - <replaceable>channel</replaceable> - </arg> - - <arg> - <arg choice='plain'> - <option>--no-channel-copy</option> - </arg> - </arg> - - <arg> - <group choice='req'> - <arg choice='plain'> - <option>--no-root-password</option> - </arg> - <arg choice='plain'> - <option>--no-root-passwd</option> - </arg> - </group> - </arg> - - <arg> - <arg choice='plain'> - <option>--no-bootloader</option> - </arg> - </arg> - - <arg> - <group choice='req'> - <arg choice='plain'> - <option>--max-jobs</option> - </arg> - - <arg choice='plain'> - <option>-j</option> - </arg> - </group> <replaceable>number</replaceable> - </arg> - - <arg> - <option>--cores</option> <replaceable>number</replaceable> - </arg> - - <arg> - <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable> - </arg> - - <arg> - <arg choice='plain'> - <option>--show-trace</option> - </arg> - </arg> - - <arg> - <arg choice='plain'> - <option>--keep-going</option> - </arg> - </arg> - - <arg> - <arg choice='plain'> - <option>--help</option> - </arg> - </arg> - </cmdsynopsis> - </refsynopsisdiv> - <refsection> - <title>Description</title> - <para> - This command installs NixOS in the file system mounted on - <filename>/mnt</filename>, based on the NixOS configuration specified in - <filename>/mnt/etc/nixos/configuration.nix</filename>. It performs the - following steps: - <itemizedlist> - <listitem> - <para> - It copies Nix and its dependencies to - <filename>/mnt/nix/store</filename>. - </para> - </listitem> - <listitem> - <para> - It runs Nix in <filename>/mnt</filename> to build the NixOS configuration - specified in <filename>/mnt/etc/nixos/configuration.nix</filename>. - </para> - </listitem> - <listitem> - <para> - It installs the current channel <quote>nixos</quote> in the target channel - profile (unless <option>--no-channel-copy</option> is specified). - </para> - </listitem> - <listitem> - <para> - It installs the GRUB boot loader on the device specified in the option - <option>boot.loader.grub.device</option> (unless - <option>--no-bootloader</option> is specified), and generates a GRUB - configuration file that boots into the NixOS configuration just - installed. - </para> - </listitem> - <listitem> - <para> - It prompts you for a password for the root account (unless - <option>--no-root-password</option> is specified). - </para> - </listitem> - </itemizedlist> - </para> - <para> - This command is idempotent: if it is interrupted or fails due to a temporary - problem (e.g. a network issue), you can safely re-run it. - </para> - </refsection> - <refsection> - <title>Options</title> - <para> - This command accepts the following options: - </para> - <variablelist> - <varlistentry> - <term><option>--verbose</option> / <option>-v</option></term> - <listitem> - <para>Increases the level of verbosity of diagnostic messages - printed on standard error. For each Nix operation, the information - printed on standard output is well-defined; any diagnostic - information is printed on standard error, never on standard - output.</para> - <para>Please note that this option may be specified repeatedly.</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--root</option> - </term> - <listitem> - <para> - Defaults to <filename>/mnt</filename>. If this option is given, treat the - directory <replaceable>root</replaceable> as the root of the NixOS - installation. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--system</option> - </term> - <listitem> - <para> - If this option is provided, <command>nixos-install</command> will install - the specified closure rather than attempt to build one from - <filename>/mnt/etc/nixos/configuration.nix</filename>. - </para> - <para> - The closure must be an appropriately configured NixOS system, with boot - loader and partition configuration that fits the target host. Such a - closure is typically obtained with a command such as <command>nix-build - -I nixos-config=./configuration.nix '<nixpkgs/nixos>' -A system - --no-out-link</command> - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--flake</option> <replaceable>flake-uri</replaceable>#<replaceable>name</replaceable> - </term> - <listitem> - <para> - Build the NixOS system from the specified flake. - The flake must contain an output named - <literal>nixosConfigurations.<replaceable>name</replaceable></literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--channel</option> - </term> - <listitem> - <para> - If this option is provided, do not copy the current - <quote>nixos</quote> channel to the target host. Instead, use the - specified derivation. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-I</option> - </term> - <listitem> - <para> - Add a path to the Nix expression search path. This option may be given - multiple times. See the NIX_PATH environment variable for information on - the semantics of the Nix search path. Paths added through - <replaceable>-I</replaceable> take precedence over NIX_PATH. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--max-jobs</option> - </term> - <term> - <option>-j</option> - </term> - <listitem> - <para> - Sets the maximum number of build jobs that Nix will perform in parallel - to the specified number. The default is <literal>1</literal>. A higher - value is useful on SMP systems or to exploit I/O latency. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--cores</option> - </term> - <listitem> - <para> - Sets the value of the <envar>NIX_BUILD_CORES</envar> environment variable - in the invocation of builders. Builders can use this variable at their - discretion to control the maximum amount of parallelism. For instance, in - Nixpkgs, if the derivation attribute - <varname>enableParallelBuilding</varname> is set to - <literal>true</literal>, the builder passes the - <option>-j<replaceable>N</replaceable></option> flag to GNU Make. The - value <literal>0</literal> means that the builder should use all - available CPU cores in the system. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable> - </term> - <listitem> - <para> - Set the Nix configuration option <replaceable>name</replaceable> to - <replaceable>value</replaceable>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--show-trace</option> - </term> - <listitem> - <para> - Causes Nix to print out a stack trace in case of Nix expression - evaluation errors. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--keep-going</option> - </term> - <listitem> - <para> - Causes Nix to continue building derivations as far as possible - in the face of failed builds. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>--help</option> - </term> - <listitem> - <para> - Synonym for <command>man nixos-install</command>. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsection> - <refsection> - <title>Examples</title> - <para> - A typical NixOS installation is done by creating and mounting a file system - on <filename>/mnt</filename>, generating a NixOS configuration in - <filename>/mnt/etc/nixos/configuration.nix</filename>, and running - <command>nixos-install</command>. For instance, if we want to install NixOS - on an <literal>ext4</literal> file system created in - <filename>/dev/sda1</filename>: -<screen> -<prompt>$ </prompt>mkfs.ext4 /dev/sda1 -<prompt>$ </prompt>mount /dev/sda1 /mnt -<prompt>$ </prompt>nixos-generate-config --root /mnt -<prompt>$ </prompt># edit /mnt/etc/nixos/configuration.nix -<prompt>$ </prompt>nixos-install -<prompt>$ </prompt>reboot -</screen> - </para> - </refsection> -</refentry> diff --git a/nixos/doc/manual/man-nixos-option.xml b/nixos/doc/manual/man-nixos-option.xml deleted file mode 100644 index b921386d0df01..0000000000000 --- a/nixos/doc/manual/man-nixos-option.xml +++ /dev/null @@ -1,134 +0,0 @@ -<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-option</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-option</command></refname> - <refpurpose>inspect a NixOS configuration</refpurpose> - </refnamediv> - <refsynopsisdiv> - <cmdsynopsis> - <command>nixos-option</command> - - <arg> - <group choice='req'> - <arg choice='plain'><option>-r</option></arg> - <arg choice='plain'><option>--recursive</option></arg> - </group> - </arg> - - <arg> - <option>-I</option> <replaceable>path</replaceable> - </arg> - - <arg> - <replaceable>option.name</replaceable> - </arg> - </cmdsynopsis> - </refsynopsisdiv> - <refsection> - <title>Description</title> - <para> - This command evaluates the configuration specified in - <filename>/etc/nixos/configuration.nix</filename> and returns the properties - of the option name given as argument. - </para> - <para> - When the option name is not an option, the command prints the list of - attributes contained in the attribute set. - </para> - </refsection> - <refsection> - <title>Options</title> - <para> - This command accepts the following options: - </para> - <variablelist> - <varlistentry> - <term><option>-r</option></term> - <term><option>--recursive</option></term> - <listitem> - <para> - Print all the values at or below the specified path recursively. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-I</option> <replaceable>path</replaceable> - </term> - <listitem> - <para> - This option is passed to the underlying - <command>nix-instantiate</command> invocation. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsection> - <refsection> - <title>Environment</title> - <variablelist> - <varlistentry> - <term> - <envar>NIXOS_CONFIG</envar> - </term> - <listitem> - <para> - Path to the main NixOS configuration module. Defaults to - <filename>/etc/nixos/configuration.nix</filename>. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsection> - <refsection> - <title>Examples</title> - <para> - Investigate option values: -<screen><prompt>$ </prompt>nixos-option boot.loader -This attribute set contains: -generationsDir -grub -initScript - -<prompt>$ </prompt>nixos-option boot.loader.grub.enable -Value: -true - -Default: -true - -Description: -Whether to enable the GNU GRUB boot loader. - -Declared by: - "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix" - -Defined by: - "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix" -</screen> - </para> - </refsection> - <refsection> - <title>Bugs</title> - <para> - The author listed in the following section is wrong. If there is any other - bug, please report to Nicolas Pierron. - </para> - </refsection> - <refsection> - <title>See also</title> - <para> - <citerefentry> - <refentrytitle>configuration.nix</refentrytitle> - <manvolnum>5</manvolnum> - </citerefentry> - </para> - </refsection> -</refentry> diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml deleted file mode 100644 index bf0f4aafa1429..0000000000000 --- a/nixos/doc/manual/man-nixos-rebuild.xml +++ /dev/null @@ -1,781 +0,0 @@ -<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-rebuild</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-rebuild</command></refname> - <refpurpose>reconfigure a NixOS machine</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>nixos-rebuild</command><group choice='req'> - <arg choice='plain'> - <option>switch</option> - </arg> - - <arg choice='plain'> - <option>boot</option> - </arg> - - <arg choice='plain'> - <option>test</option> - </arg> - - <arg choice='plain'> - <option>build</option> - </arg> - - <arg choice='plain'> - <option>dry-build</option> - </arg> - - <arg choice='plain'> - <option>dry-activate</option> - </arg> - - <arg choice='plain'> - <option>edit</option> - </arg> - - <arg choice='plain'> - <option>build-vm</option> - </arg> - - <arg choice='plain'> - <option>build-vm-with-bootloader</option> - </arg> - </group> - <sbr /> - - <arg> - <group choice='req'> - <arg choice='plain'> - <option>--upgrade</option> - </arg> - <arg choice='plain'> - <option>--upgrade-all</option> - </arg> - </group> - </arg> - - <arg> - <option>--install-bootloader</option> - </arg> - - <arg> - <option>--no-build-nix</option> - </arg> - - <arg> - <option>--fast</option> - </arg> - - <arg> - <option>--rollback</option> - </arg> - - <arg> - <option>--builders</option> <replaceable>builder-spec</replaceable> - </arg> - - <sbr/> - - <arg> - <option>--flake</option> <replaceable>flake-uri</replaceable> - </arg> - - <arg> - <option>--no-flake</option> - </arg> - - <arg> - <option>--override-input</option> <replaceable>input-name</replaceable> <replaceable>flake-uri</replaceable> - </arg> - - <sbr /> - - <arg> - <group choice='req'> - <arg choice='plain'> - <option>--profile-name</option> - </arg> - - <arg choice='plain'> - <option>-p</option> - </arg> - </group> <replaceable>name</replaceable> - </arg> - - <arg> - <group choice='req'> - <arg choice='plain'> - <option>--specialisation</option> - </arg> - - <arg choice='plain'> - <option>-c</option> - </arg> - </group> <replaceable>name</replaceable> - </arg> - - <sbr /> - - <arg> - <option>--build-host</option> <replaceable>host</replaceable> - </arg> - - <arg> - <option>--target-host</option> <replaceable>host</replaceable> - </arg> - - <arg> - <option>--use-remote-sudo</option> - </arg> - - <sbr /> - - <arg> - <option>--show-trace</option> - </arg> - <arg> - <option>-I</option> - <replaceable>NIX_PATH</replaceable> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--verbose</option></arg> - <arg choice='plain'><option>-v</option></arg> - </group> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--impure</option></arg> - </group> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--max-jobs</option></arg> - <arg choice='plain'><option>-j</option></arg> - </group> - <replaceable>number</replaceable> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--keep-failed</option></arg> - <arg choice='plain'><option>-K</option></arg> - </group> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--keep-going</option></arg> - <arg choice='plain'><option>-k</option></arg> - </group> - </arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsection> - <title>Description</title> - - <para> - This command updates the system so that it corresponds to the - configuration specified in - <filename>/etc/nixos/configuration.nix</filename> or - <filename>/etc/nixos/flake.nix</filename>. Thus, every time you - modify the configuration or any other NixOS module, you must run - <command>nixos-rebuild</command> to make the changes take - effect. It builds the new system in - <filename>/nix/store</filename>, runs its activation script, and - stop and (re)starts any system services if needed. Please note that - user services need to be started manually as they aren't detected - by the activation script at the moment. - </para> - - <para> - This command has one required argument, which specifies the desired - operation. It must be one of the following: - - <variablelist> - <varlistentry> - <term> - <option>switch</option> - </term> - <listitem> - <para> - Build and activate the new configuration, and make it the boot default. - That is, the configuration is added to the GRUB boot menu as the default - menu entry, so that subsequent reboots will boot the system into the new - configuration. Previous configurations activated with - <command>nixos-rebuild switch</command> or <command>nixos-rebuild - boot</command> remain available in the GRUB menu. - </para> - <para> - Note that if you are using specializations, running just - <command>nixos-rebuild switch</command> will switch you back to the - unspecialized, base system - in that case, you might want to use this - instead: -<screen> -<prompt>$ </prompt>nixos-rebuild switch --specialisation your-specialisation-name -</screen> - This command will build all specialisations and make them bootable just - like regular <command>nixos-rebuild switch</command> does - the only - thing different is that it will switch to given specialisation instead - of the base system; it can be also used to switch from the base system - into a specialised one, or to switch between specialisations. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>boot</option> - </term> - <listitem> - <para> - Build the new configuration and make it the boot default (as with - <command>nixos-rebuild switch</command>), but do not activate it. That - is, the system continues to run the previous configuration until the - next reboot. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>test</option> - </term> - <listitem> - <para> - Build and activate the new configuration, but do not add it to the GRUB - boot menu. Thus, if you reboot the system (or if it crashes), you will - automatically revert to the default configuration (i.e. the - configuration resulting from the last call to <command>nixos-rebuild - switch</command> or <command>nixos-rebuild boot</command>). - </para> - <para> - Note that if you are using specialisations, running just - <command>nixos-rebuild test</command> will activate the unspecialised, - base system - in that case, you might want to use this instead: -<screen> -<prompt>$ </prompt>nixos-rebuild test --specialisation your-specialisation-name -</screen> - This command can be also used to switch from the base system into a - specialised one, or to switch between specialisations. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>build</option> - </term> - <listitem> - <para> - Build the new configuration, but neither activate it nor add it to the - GRUB boot menu. It leaves a symlink named <filename>result</filename> in - the current directory, which points to the output of the top-level - “system” derivation. This is essentially the same as doing -<screen> -<prompt>$ </prompt>nix-build /path/to/nixpkgs/nixos -A system -</screen> - Note that you do not need to be <literal>root</literal> to run - <command>nixos-rebuild build</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>dry-build</option> - </term> - <listitem> - <para> - Show what store paths would be built or downloaded by any of the - operations above, but otherwise do nothing. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>dry-activate</option> - </term> - <listitem> - <para> - Build the new configuration, but instead of activating it, show what - changes would be performed by the activation (i.e. by - <command>nixos-rebuild test</command>). For instance, this command will - print which systemd units would be restarted. The list of changes is not - guaranteed to be complete. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>edit</option> - </term> - <listitem> - <para> - Opens <filename>configuration.nix</filename> in the default editor. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>build-vm</option> - </term> - <listitem> - <para> - Build a script that starts a NixOS virtual machine with the desired - configuration. It leaves a symlink <filename>result</filename> in the - current directory that points (under - <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>) - at the script that starts the VM. Thus, to test a NixOS configuration in - a virtual machine, you should do the following: -<screen> -<prompt>$ </prompt>nixos-rebuild build-vm -<prompt>$ </prompt>./result/bin/run-*-vm -</screen> - </para> - - <para> - The VM is implemented using the <literal>qemu</literal> package. For - best performance, you should load the <literal>kvm-intel</literal> or - <literal>kvm-amd</literal> kernel modules to get hardware - virtualisation. - </para> - - <para> - The VM mounts the Nix store of the host through the 9P file system. The - host Nix store is read-only, so Nix commands that modify the Nix store - will not work in the VM. This includes commands such as - <command>nixos-rebuild</command>; to change the VM’s configuration, - you must halt the VM and re-run the commands above. - </para> - - <para> - The VM has its own <literal>ext3</literal> root file system, which is - automatically created when the VM is first started, and is persistent - across reboots of the VM. It is stored in - <literal>./<replaceable>hostname</replaceable>.qcow2</literal>. -<!-- The entire file system hierarchy of the host is available in - the VM under <filename>/hostfs</filename>.--> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>build-vm-with-bootloader</option> - </term> - <listitem> - <para> - Like <option>build-vm</option>, but boots using the regular boot loader - of your configuration (e.g., GRUB 1 or 2), rather than booting directly - into the kernel and initial ramdisk of the system. This allows you to - test whether the boot loader works correctly. However, it does not - guarantee that your NixOS configuration will boot successfully on the - host hardware (i.e., after running <command>nixos-rebuild - switch</command>), because the hardware and boot loader configuration in - the VM are different. The boot loader is installed on an automatically - generated virtual disk containing a <filename>/boot</filename> - partition. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsection> - - <refsection> - <title>Options</title> - <para> - This command accepts the following options: - </para> - - <variablelist> - <varlistentry> - <term> - <option>--upgrade</option> - </term> - <term> - <option>--upgrade-all</option> - </term> - <listitem> - <para> - Update the root user's channel named <literal>nixos</literal> - before rebuilding the system. - </para> - <para> - In addition to the <literal>nixos</literal> channel, the root - user's channels which have a file named - <literal>.update-on-nixos-rebuild</literal> in their base - directory will also be updated. - </para> - <para> - Passing <option>--upgrade-all</option> updates all of the root - user's channels. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--install-bootloader</option> - </term> - <listitem> - <para> - Causes the boot loader to be (re)installed on the device specified by the - relevant configuration options. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--no-build-nix</option> - </term> - <listitem> - <para> - Normally, <command>nixos-rebuild</command> first builds the - <varname>nixUnstable</varname> attribute in Nixpkgs, and uses the - resulting instance of the Nix package manager to build the new system - configuration. This is necessary if the NixOS modules use features not - provided by the currently installed version of Nix. This option disables - building a new Nix. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--fast</option> - </term> - <listitem> - <para> - Equivalent to <option>--no-build-nix</option>. This option is - useful if you call <command>nixos-rebuild</command> frequently - (e.g. if you’re hacking on a NixOS module). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--rollback</option> - </term> - <listitem> - <para> - Instead of building a new configuration as specified by - <filename>/etc/nixos/configuration.nix</filename>, roll back to the - previous configuration. (The previous configuration is defined as the one - before the “current” generation of the Nix profile - <filename>/nix/var/nix/profiles/system</filename>.) - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--builders</option> <replaceable>builder-spec</replaceable> - </term> - <listitem> - <para> - Allow ad-hoc remote builders for building the new system. This requires - the user executing <command>nixos-rebuild</command> (usually root) to be - configured as a trusted user in the Nix daemon. This can be achieved by - using the <literal>nix.settings.trusted-users</literal> NixOS option. Examples - values for that option are described in the <literal>Remote builds - chapter</literal> in the Nix manual, (i.e. <command>--builders - "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string - existing builders specified in <filename>/etc/nix/machines</filename> can - be ignored: <command>--builders ""</command> for example when they are - not reachable due to network connectivity. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--profile-name</option> - </term> - <term> - <option>-p</option> - </term> - <listitem> - <para> - Instead of using the Nix profile - <filename>/nix/var/nix/profiles/system</filename> to keep track of the - current and previous system configurations, use - <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>. - When you use GRUB 2, for every system profile created with this flag, - NixOS will create a submenu named “NixOS - Profile - '<replaceable>name</replaceable>'” in GRUB’s boot menu, containing - the current and previous configurations of this profile. - </para> - <para> - For instance, if you want to test a configuration file named - <filename>test.nix</filename> without affecting the default system - profile, you would do: -<screen> -<prompt>$ </prompt>nixos-rebuild switch -p test -I nixos-config=./test.nix -</screen> - The new configuration will appear in the GRUB 2 submenu “NixOS - - Profile 'test'”. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--specialisation</option> - </term> - <term> - <option>-c</option> - </term> - <listitem> - <para> - Activates given specialisation; when not specified, switching and testing - will activate the base, unspecialised system. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--build-host</option> - </term> - <listitem> - <para> - Instead of building the new configuration locally, use the specified host - to perform the build. The host needs to be accessible with ssh, and must - be able to perform Nix builds. If the option - <option>--target-host</option> is not set, the build will be copied back - to the local machine when done. - </para> - <para> - Note that, if <option>--no-build-nix</option> is not specified, Nix will - be built both locally and remotely. This is because the configuration - will always be evaluated locally even though the building might be - performed remotely. - </para> - <para> - You can include a remote user name in the host name - (<replaceable>user@host</replaceable>). You can also set ssh options by - defining the <envar>NIX_SSHOPTS</envar> environment variable. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--target-host</option> - </term> - <listitem> - <para> - Specifies the NixOS target host. By setting this to something other than - an empty string, the system activation will happen - on the remote host instead of the local machine. The remote host needs to - be accessible over ssh, and for the commands <option>switch</option>, - <option>boot</option> and <option>test</option> you need root access. - </para> - - <para> - If <option>--build-host</option> is not explicitly specified or empty, - building will take place locally. - </para> - - <para> - You can include a remote user name in the host name - (<replaceable>user@host</replaceable>). You can also set ssh options by - defining the <envar>NIX_SSHOPTS</envar> environment variable. - </para> - - <para> - Note that <command>nixos-rebuild</command> honors the - <literal>nixpkgs.crossSystem</literal> setting of the given configuration - but disregards the true architecture of the target host. Hence the - <literal>nixpkgs.crossSystem</literal> setting has to match the target - platform or else activation will fail. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--use-substitutes</option> - </term> - <listitem> - <para> - When set, nixos-rebuild will add <option>--use-substitutes</option> - to each invocation of nix-copy-closure. This will only affect the - behavior of nixos-rebuild if <option>--target-host</option> or - <option>--build-host</option> is also set. This is useful when - the target-host connection to cache.nixos.org is faster than the - connection between hosts. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--use-remote-sudo</option> - </term> - <listitem> - <para> - When set, nixos-rebuild prefixes remote commands that run on - the <option>--build-host</option> and <option>--target-host</option> - systems with <command>sudo</command>. Setting this option allows - deploying as a non-root user. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--flake</option> <replaceable>flake-uri</replaceable><optional>#<replaceable>name</replaceable></optional> - </term> - <listitem> - <para> - Build the NixOS system from the specified flake. It defaults to - the directory containing the target of the symlink - <filename>/etc/nixos/flake.nix</filename>, if it exists. The - flake must contain an output named - <literal>nixosConfigurations.<replaceable>name</replaceable></literal>. If - <replaceable>name</replaceable> is omitted, it default to the - current host name. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--no-flake</option> - </term> - <listitem> - <para> - Do not imply <option>--flake</option> if - <filename>/etc/nixos/flake.nix</filename> exists. With this - option, it is possible to build non-flake NixOS configurations - even if the current NixOS systems uses flakes. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - In addition, <command>nixos-rebuild</command> accepts various Nix-related - flags, including <option>--max-jobs</option> / <option>-j</option>, <option>-I</option>, - <option>--show-trace</option>, <option>--keep-failed</option>, - <option>--keep-going</option>, <option>--impure</option>, and <option>--verbose</option> / - <option>-v</option>. See the Nix manual for details. - </para> - </refsection> - - <refsection> - <title>Environment</title> - - <variablelist> - <varlistentry> - <term> - <envar>NIXOS_CONFIG</envar> - </term> - <listitem> - <para> - Path to the main NixOS configuration module. Defaults to - <filename>/etc/nixos/configuration.nix</filename>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <envar>NIX_PATH</envar> - </term> - <listitem> - <para> - A colon-separated list of directories used to look up Nix expressions enclosed in angle brackets (e.g <nixpkgs>). Example - <screen> - nixpkgs=./my-nixpkgs - </screen> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <envar>NIX_SSHOPTS</envar> - </term> - <listitem> - <para> - Additional options to be passed to <command>ssh</command> on the command - line. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsection> - - <refsection> - <title>Files</title> - - <variablelist> - - <varlistentry> - <term> - <filename>/etc/nixos/flake.nix</filename> - </term> - <listitem> - <para> - If this file exists, then <command>nixos-rebuild</command> will - use it as if the <option>--flake</option> option was given. This - file may be a symlink to a <filename>flake.nix</filename> in an - actual flake; thus <filename>/etc/nixos</filename> need not be a - flake. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <filename>/run/current-system</filename> - </term> - <listitem> - <para> - A symlink to the currently active system configuration in the Nix store. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <filename>/nix/var/nix/profiles/system</filename> - </term> - <listitem> - <para> - The Nix profile that contains the current and previous system - configurations. Used to generate the GRUB boot menu. - </para> - </listitem> - </varlistentry> - - </variablelist> - </refsection> - - <refsection> - <title>Bugs</title> - <para> - This command should be renamed to something more descriptive. - </para> - </refsection> -</refentry> diff --git a/nixos/doc/manual/man-nixos-version.xml b/nixos/doc/manual/man-nixos-version.xml deleted file mode 100644 index 507c5035ed8d1..0000000000000 --- a/nixos/doc/manual/man-nixos-version.xml +++ /dev/null @@ -1,158 +0,0 @@ -<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-version</command> - </refentrytitle><manvolnum>8</manvolnum> - <refmiscinfo class="source">NixOS</refmiscinfo> - </refmeta> - <refnamediv> - <refname><command>nixos-version</command></refname> - <refpurpose>show the NixOS version</refpurpose> - </refnamediv> - <refsynopsisdiv> - <cmdsynopsis> - <command>nixos-version</command> - <arg> - <option>--hash</option> - </arg> - - <arg> - <option>--revision</option> - </arg> - - <arg> - <option>--configuration-revision</option> - </arg> - - <arg> - <option>--json</option> - </arg> - - </cmdsynopsis> - </refsynopsisdiv> - - <refsection> - <title>Description</title> - <para> - This command shows the version of the currently active NixOS configuration. - For example: -<screen><prompt>$ </prompt>nixos-version -16.03.1011.6317da4 (Emu) -</screen> - The version consists of the following elements: - <variablelist> - <varlistentry> - <term> - <literal>16.03</literal> - </term> - <listitem> - <para> - The NixOS release, indicating the year and month in which it was - released (e.g. March 2016). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>1011</literal> - </term> - <listitem> - <para> - The number of commits in the Nixpkgs Git repository between the start of - the release branch and the commit from which this version was built. - This ensures that NixOS versions are monotonically increasing. It is - <literal>git</literal> when the current NixOS configuration was built - from a checkout of the Nixpkgs Git repository rather than from a NixOS - channel. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>6317da4</literal> - </term> - <listitem> - <para> - The first 7 characters of the commit in the Nixpkgs Git repository from - which this version was built. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>Emu</literal> - </term> - <listitem> - <para> - The code name of the NixOS release. The first letter of the code name - indicates that this is the N'th stable NixOS release; for example, Emu - is the fifth release. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsection> - - <refsection> - <title>Options</title> - - <para> - This command accepts the following options: - </para> - - <variablelist> - - <varlistentry> - <term> - <option>--hash</option> - </term> - <term> - <option>--revision</option> - </term> - <listitem> - <para> - Show the full SHA1 hash of the Git commit from which this configuration - was built, e.g. -<screen><prompt>$ </prompt>nixos-version --hash -6317da40006f6bc2480c6781999c52d88dde2acf -</screen> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--configuration-revision</option> - </term> - <listitem> - <para> - Show the configuration revision if available. This could be the full SHA1 - hash of the Git commit of the system flake, if you add - <screen>{ system.configurationRevision = self.rev or "dirty"; }</screen> - to the <screen>modules</screen> array of your flake.nix system configuration e.g. -<screen><prompt>$ </prompt>nixos-version --configuration-revision -aa314ebd1592f6cdd53cb5bba8bcae97d9323de8 -</screen> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>--json</option> - </term> - <listitem> - <para> - Print a JSON representation of the versions of NixOS and the - top-level configuration flake. - </para> - </listitem> - </varlistentry> - - </variablelist> - - </refsection> - -</refentry> diff --git a/nixos/doc/manual/man-pages.xml b/nixos/doc/manual/man-pages.xml index 58f73521e94fd..0186221bddce9 100644 --- a/nixos/doc/manual/man-pages.xml +++ b/nixos/doc/manual/man-pages.xml @@ -15,11 +15,4 @@ </copyright> </info> <xi:include href="man-configuration.xml" /> - <xi:include href="man-nixos-build-vms.xml" /> - <xi:include href="man-nixos-generate-config.xml" /> - <xi:include href="man-nixos-install.xml" /> - <xi:include href="man-nixos-enter.xml" /> - <xi:include href="man-nixos-option.xml" /> - <xi:include href="man-nixos-rebuild.xml" /> - <xi:include href="man-nixos-version.xml" /> </reference> diff --git a/nixos/doc/manual/manpages/README.md b/nixos/doc/manual/manpages/README.md new file mode 100644 index 0000000000000..ed2682e5332d6 --- /dev/null +++ b/nixos/doc/manual/manpages/README.md @@ -0,0 +1,55 @@ +# NixOS manpages + +This is the collection of NixOS manpages, excluding `configuration.nix(5)`. + +Man pages are written in [`mdoc(7)` format](https://mandoc.bsd.lv/man/mdoc.7.html) and should be portable between mandoc and groff for rendering (though minor differences may occur, mandoc and groff seem to have slightly different spacing rules.) + +Being written in `mdoc` these manpages use semantic markup. This file provides a guideline on where to apply which of the semantic elements of `mdoc`. + +### Command lines and arguments + +In any manpage, commands, flags and arguments to the *current* executable should be marked according to their semantics. Commands, flags and arguments passed to *other* executables should not be marked like this and should instead be considered as code examples and marked with `Ql`. + + - Use `Fl` to mark flag arguments, `Ar` for their arguments. + - Repeating arguments should be marked by adding ellipses (`...`). + - Use `Cm` to mark literal string arguments, e.g. the `boot` command argument passed to `nixos-rebuild`. + - Optional flags or arguments should be marked with `Op`. This includes optional repeating arguments. + - Required flags or arguments should not be marked. + - Mutually exclusive groups of arguments should be enclosed in curly brackets, preferrably created with `Bro`/`Brc` blocks. + +When an argument is used in an example it should be marked up with `Ar` again to differentiate it from a constant. For example, a command with a `--host name` flag that calls ssh to retrieve the host's local time would signify this thusly: +``` +This will run +.Ic ssh Ar name Ic time +to retrieve the remote time. +``` + +### Paths, NixOS options, environment variables + +Constant paths should be marked with `Pa`, NixOS options with `Va`, and environment variables with `Ev`. + +Generated paths, e.g. `result/bin/run-hostname-vm` (where `hostname` is a variable or arguments) should be marked as `Ql` inline literals with their variable components marked appropriately. + + - Taking `hostname` from an argument become `.Ql result/bin/run- Ns Ar hostname Ns -vm` + - Taking `hostname` from a variable otherwise defined becomes `.Ql result/bin/run- Ns Va hostname Ns -vm` + +### Code examples and other commands + +In free text names and complete invocations of other commands (e.g. `ssh` or `tar -xvf src.tar`) should be marked with `Ic`, fragments of command lines should be marked with `Ql`. + +Larger code blocks or those that cannot be shown inline should use indented literal display block markup for their contents, i.e. +``` +.Bd -literal -offset indent +... +.Ed +``` +Contents of code blocks may be marked up further, e.g. if they refer to arguments that will be subsituted into them: +``` +.Bd -literal -offset indent +{ + options.hostname = "\c +.Ar hostname Ns \c +"; +} +.Ed +``` diff --git a/nixos/doc/manual/manpages/nixos-build-vms.8 b/nixos/doc/manual/manpages/nixos-build-vms.8 new file mode 100644 index 0000000000000..abf06b5dd5962 --- /dev/null +++ b/nixos/doc/manual/manpages/nixos-build-vms.8 @@ -0,0 +1,109 @@ +.Dd January 1, 1980 +.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from +.\" doc-default-operating-system. mandoc doesn't have this register set by default, +.\" so we can use it as a groff/mandoc switch. +.ie ddoc-default-operating-system .Dt nixos-build-vms \&8 "NixOS System Manager's Manual" +.el .Dt nixos-build-vms 8 +.Os NixOS +.Sh NAME +.Nm nixos-build-vms +.Nd build a network of virtual machines from a network of NixOS configurations +. +. +. +.Sh SYNOPSIS +.Nm nixos-build-vms +.Op Fl -show-trace +.Op Fl -no-out-link +.Op Fl -help +.Op Fl -option Ar name value +.Pa network.nix +. +. +. +.Sh DESCRIPTION +. +This command builds a network of QEMU\-KVM virtual machines of a Nix expression +specifying a network of NixOS machines. The virtual network can be started by +executing the +.Pa bin/run-vms +shell script that is generated by this command. By default, a +.Pa result +symlink is produced that points to the generated virtual network. +. +.Pp +A network Nix expression has the following structure: +.Bd -literal -offset indent +{ + test1 = {pkgs, config, ...}: + { + services.openssh.enable = true; + nixpkgs.localSystem.system = "i686-linux"; + deployment.targetHost = "test1.example.net"; + + # Other NixOS options + }; + + test2 = {pkgs, config, ...}: + { + services.openssh.enable = true; + services.httpd.enable = true; + environment.systemPackages = [ pkgs.lynx ]; + nixpkgs.localSystem.system = "x86_64-linux"; + deployment.targetHost = "test2.example.net"; + + # Other NixOS options + }; +} +.Ed +. +.Pp +Each attribute in the expression represents a machine in the network +.Ns (e.g. +.Va test1 +and +.Va test2 Ns +) referring to a function defining a NixOS configuration. In each NixOS +configuration, two attributes have a special meaning. The +.Va deployment.targetHost +specifies the address (domain name or IP address) of the system which is used by +.Ic ssh +to perform remote deployment operations. The +.Va nixpkgs.localSystem.system +attribute can be used to specify an architecture for the target machine, such as +.Ql i686-linux +which builds a 32-bit NixOS configuration. Omitting this property will build the +configuration for the same architecture as the host system. +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl -show-trace +Shows a trace of the output. +. +.It Fl -no-out-link +Do not create a +.Pa result +symlink. +. +.It Fl h , -help +Shows the usage of this command to the user. +. +.It Fl -option Ar name Va value +Set the Nix configuration option +.Va name +to +.Va value Ns +\&. This overrides settings in the Nix configuration file (see +.Xr nix.conf 5 Ns +). +.El +. +. +. +.Sh AUTHORS +.An -nosplit +.An Eelco Dolstra +and +.An the Nixpkgs/NixOS contributors diff --git a/nixos/doc/manual/manpages/nixos-enter.8 b/nixos/doc/manual/manpages/nixos-enter.8 new file mode 100644 index 0000000000000..bc8df31e5f2d8 --- /dev/null +++ b/nixos/doc/manual/manpages/nixos-enter.8 @@ -0,0 +1,76 @@ +.Dd January 1, 1980 +.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from +.\" doc-default-operating-system. mandoc doesn't have this register set by default, +.\" so we can use it as a groff/mandoc switch. +.ie ddoc-default-operating-system .Dt nixos-enter \&8 "NixOS System Manager's Manual" +.el .Dt nixos-enter 8 +.Os NixOS +.Sh NAME +.Nm nixos-enter +.Nd run a command in a NixOS chroot environment +. +. +. +.Sh SYNOPSIS +.Nm nixos-enter +.Op Fl -root Ar root +.Op Fl -system Ar system +.Op Fl -command | c Ar shell-command +.Op Fl -silent +.Op Fl -help +.Op Fl - Ar arguments ... +. +. +. +.Sh DESCRIPTION +This command runs a command in a NixOS chroot environment, that is, in a filesystem hierarchy previously prepared using +.Xr nixos-install 8 . +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl -root Ar root +The path to the NixOS system you want to enter. It defaults to +.Pa /mnt Ns +\&. +.It Fl -system Ar system +The NixOS system configuration to use. It defaults to +.Pa /nix/var/nix/profiles/system Ns +\&. You can enter a previous NixOS configuration by specifying a path such as +.Pa /nix/var/nix/profiles/system-106-link Ns +\&. +. +.It Fl -command Ar shell-command , Fl c Ar shell-command +The bash command to execute. +. +.It Fl -silent +Suppresses all output from the activation script of the target system. +. +.It Fl - +Interpret the remaining arguments as the program name and arguments to be invoked. +The program is not executed in a shell. +.El +. +. +. +.Sh EXAMPLES +.Bl -tag -width indent +.It Ic nixos-enter --root /mnt +Start an interactive shell in the NixOS installation in +.Pa /mnt Ns . +. +.It Ic nixos-enter -c 'ls -l /; cat /proc/mounts' +Run a shell command. +. +.It Ic nixos-enter -- cat /proc/mounts +Run a non-shell command. +.El +. +. +. +.Sh AUTHORS +.An -nosplit +.An Eelco Dolstra +and +.An the Nixpkgs/NixOS contributors diff --git a/nixos/doc/manual/manpages/nixos-generate-config.8 b/nixos/doc/manual/manpages/nixos-generate-config.8 new file mode 100644 index 0000000000000..8b9bb4d42483b --- /dev/null +++ b/nixos/doc/manual/manpages/nixos-generate-config.8 @@ -0,0 +1,169 @@ +.Dd January 1, 1980 +.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from +.\" doc-default-operating-system. mandoc doesn't have this register set by default, +.\" so we can use it as a groff/mandoc switch. +.ie ddoc-default-operating-system .Dt nixos-generate-config \&8 "NixOS System Manager's Manual" +.el .Dt nixos-generate-config 8 +.Os NixOS +.Sh NAME +.Nm nixos-generate-config +.Nd generate NixOS configuration modules +. +. +. +.Sh SYNOPSIS +.Nm nixos-generate-config +.Op Fl -force +.Op Fl -root Ar root +.Op Fl -dir Ar dir +. +. +. +.Sh DESCRIPTION +This command writes two NixOS configuration modules: +.Bl -tag -width indent +.It Pa /etc/nixos/hardware-configuration.nix +This module sets NixOS configuration options based on your current hardware +configuration. In particular, it sets the +.Va fileSystem +option to reflect all currently mounted file systems, the +.Va swapDevices +option to reflect active swap devices, and the +.Va boot.initrd.* +options to ensure that the initial ramdisk contains any kernel modules necessary +for mounting the root file system. +.Pp +If this file already exists, it is overwritten. Thus, you should not modify it +manually. Rather, you should include it from your +.Pa /etc/nixos/configuration.nix Ns +, and re-run +.Nm +to update it whenever your hardware configuration changes. +. +.It Pa /etc/nixos/configuration.nix +This is the main NixOS system configuration module. If it already exists, it’s +left unchanged. Otherwise, +.Nm +will write a template for you to customise. +.El +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl -root Ar root +If this option is given, treat the directory +.Ar root +as the root of the file system. This means that configuration files will be written to +.Ql Ar root Ns /etc/nixos Ns +, and that any file systems outside of +.Ar root +are ignored for the purpose of generating the +.Va fileSystems +option. +. +.It Fl -dir Ar dir +If this option is given, write the configuration files to the directory +.Ar dir +instead of +.Pa /etc/nixos Ns +\&. +. +.It Fl -force +Overwrite +.Pa /etc/nixos/configuration.nix +if it already exists. +. +.It Fl -no-filesystems +Omit everything concerning file systems and swap devices from the hardware configuration. +. +.It Fl -show-hardware-config +Don't generate +.Pa configuration.nix +or +.Pa hardware-configuration.nix +and print the hardware configuration to stdout only. +.El +. +. +. +.Sh EXAMPLES +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 +.Pa /mnt +and +.Pa /mnt/boot Ns +, you would run: +.Bd -literal -offset indent +$ nixos-generate-config --root /mnt +.Ed +. +.Pp +The resulting file +.Pa /mnt/etc/nixos/hardware-configuration.nix +might look like this: +.Bd -literal -offset indent +# 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; +} +.Ed +. +.Pp +It will also create a basic +.Pa /mnt/etc/nixos/configuration.nix Ns +, which you should edit to customise the logical configuration of your system. \ +This file includes the result of the hardware scan as follows: +.Bd -literal -offset indent +imports = [ ./hardware-configuration.nix ]; +.Ed +. +.Pp +After installation, if your hardware configuration changes, you can run: +.Bd -literal -offset indent +$ nixos-generate-config +.Ed +. +.Pp +to update +.Pa /etc/nixos/hardware-configuration.nix Ns +\&. Your +.Pa /etc/nixos/configuration.nix +will +.Em not +be overwritten. +. +.Sh AUTHORS +.An -nosplit +.An Eelco Dolstra +and +.An the Nixpkgs/NixOS contributors diff --git a/nixos/doc/manual/manpages/nixos-install.8 b/nixos/doc/manual/manpages/nixos-install.8 new file mode 100644 index 0000000000000..dc0a5da275d88 --- /dev/null +++ b/nixos/doc/manual/manpages/nixos-install.8 @@ -0,0 +1,195 @@ +.Dd January 1, 1980 +.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from +.\" doc-default-operating-system. mandoc doesn't have this register set by default, +.\" so we can use it as a groff/mandoc switch. +.ie ddoc-default-operating-system .Dt nixos-install \&8 "NixOS System Manager's Manual" +.el .Dt nixos-install 8 +.Os NixOS +.Sh NAME +.Nm nixos-install +.Nd install bootloader and NixOS +. +. +. +.Sh SYNOPSIS +.Nm nixos-install +.Op Fl -verbose | v +.Op Fl I Ar path +.Op Fl -root Ar root +.Op Fl -system Ar path +.Op Fl -flake Ar flake-uri +.Op Fl -impure +.Op Fl -channel Ar channel +.Op Fl -no-channel-copy +.Op Fl -no-root-password | -no-root-passwd +.Op Fl -no-bootloader +.Op Fl -max-jobs | j Ar number +.Op Fl -cores Ar number +.Op Fl -option Ar name value +.Op Fl -show-trace +.Op Fl -keep-going +.Op Fl -help +. +. +. +.Sh DESCRIPTION +This command installs NixOS in the file system mounted on +.Pa /mnt Ns +, based on the NixOS configuration specified in +.Pa /mnt/etc/nixos/configuration.nix Ns +\&. It performs the following steps: +. +.Bl -enum +.It +It copies Nix and its dependencies to +.Pa /mnt/nix/store Ns +\&. +. +.It +It runs Nix in +.Pa /mnt +to build the NixOS configuration specified in +.Pa /mnt/etc/nixos/configuration.nix Ns +\&. +. +.It +It installs the current channel +.Dq nixos +in the target channel profile (unless +.Fl -no-channel-copy +is specified). +. +.It +It installs the GRUB boot loader on the device specified in the option +.Va boot.loader.grub.device +(unless +.Fl -no-bootloader +is specified), and generates a GRUB configuration file that boots into the NixOS +configuration just installed. +. +.It +It prompts you for a password for the root account (unless +.Fl -no-root-password +is specified). +.El +. +.Pp +This command is idempotent: if it is interrupted or fails due to a temporary +problem (e.g. a network issue), you can safely re-run it. +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl -verbose , v +Increases the level of verbosity of diagnostic messages printed on standard +error. For each Nix operation, the information printed on standard output is +well-defined; any diagnostic information is printed on standard error, never on +standard output. +.Pp +Please note that this option may be specified repeatedly. +. +.It Fl -root Ar root +Defaults to +.Pa /mnt Ns +\&. If this option is given, treat the directory +.Ar root +as the root of the NixOS installation. +. +.It Fl -system Ar path +If this option is provided, +.Nm +will install the specified closure rather than attempt to build one from +.Pa /mnt/etc/nixos/configuration.nix Ns +\&. +.Pp +The closure must be an appropriately configured NixOS system, with boot loader +and partition configuration that fits the target host. Such a closure is +typically obtained with a command such as +.Ic nix-build -I nixos-config=./configuration.nix '<nixpkgs/nixos>' -A system --no-out-link Ns +\&. +. +.It Fl -flake Ar flake-uri Ns # Ns Ar name +Build the NixOS system from the specified flake. The flake must contain an +output named +.Ql nixosConfigurations. Ns Ar name Ns +\&. +. +.It Fl -channel Ar channel +If this option is provided, do not copy the current +.Dq nixos +channel to the target host. Instead, use the specified derivation. +. +.It Fl I Ar Path +Add a path to the Nix expression search path. This option may be given multiple +times. See the +.Ev NIX_PATH +environment variable for information on the semantics of the Nix search path. Paths added through +.Fl I +take precedence over +.Ev NIX_PATH Ns +\&. +. +.It Fl -max-jobs , j Ar number +Sets the maximum number of build jobs that Nix will perform in parallel to the +specified number. The default is 1. A higher value is useful on SMP systems or +to exploit I/O latency. +. +.It Fl -cores Ar N +Sets the value of the +.Ev NIX_BUILD_CORES +environment variable in the invocation of builders. Builders can use this +variable at their discretion to control the maximum amount of parallelism. For +instance, in Nixpkgs, if the derivation attribute +.Va enableParallelBuilding +is set to true, the builder passes the +.Fl j Ns Va N +flag to GNU Make. The value 0 means that the builder should use all available CPU cores in the system. +. +.It Fl -option Ar name value +Set the Nix configuration option +.Ar name +to +.Ar value Ns +\&. +. +.It Fl -show-trace +Causes Nix to print out a stack trace in case of Nix expression evaluation errors. +. +.It Fl -keep-going +Causes Nix to continue building derivations as far as possible in the face of failed builds. +. +.It Fl -help +Synonym for +.Ic man nixos-install Ns +\&. +.El +. +. +. +.Sh EXAMPLES +A typical NixOS installation is done by creating and mounting a file system on +.Pa /mnt Ns +, generating a NixOS configuration in +.Pa /mnt/etc/nixos/configuration.nix Ns +, and running +.Nm Ns +\&. For instance, if we want to install NixOS on an ext4 file system created in +.Pa /dev/sda1 Ns +: +.Bd -literal -offset indent +$ mkfs.ext4 /dev/sda1 +$ mount /dev/sda1 /mnt +$ nixos-generate-config --root /mnt +$ # edit /mnt/etc/nixos/configuration.nix +$ nixos-install +$ reboot +.Ed +. +. +. +.Sh AUTHORS +.An -nosplit +.An Eelco Dolstra +and +.An the Nixpkgs/NixOS contributors diff --git a/nixos/doc/manual/manpages/nixos-option.8 b/nixos/doc/manual/manpages/nixos-option.8 new file mode 100644 index 0000000000000..79cc113cfaf2d --- /dev/null +++ b/nixos/doc/manual/manpages/nixos-option.8 @@ -0,0 +1,93 @@ +.Dd January 1, 1980 +.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from +.\" doc-default-operating-system. mandoc doesn't have this register set by default, +.\" so we can use it as a groff/mandoc switch. +.ie ddoc-default-operating-system .Dt nixos-option \&8 "NixOS System Manager's Manual" +.el .Dt nixos-option 8 +.Os NixOS +.Sh NAME +.Nm nixos-option +.Nd inspect a NixOS configuration +. +. +. +.Sh SYNOPSIS +.Nm +.Op Fl r | -recursive +.Op Fl I Ar path +.Ar option.name +. +. +. +.Sh DESCRIPTION +This command evaluates the configuration specified in +.Pa /etc/nixos/configuration.nix +and returns the properties of the option name given as argument. +. +.Pp +When the option name is not an option, the command prints the list of attributes +contained in the attribute set. +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl r , -recursive +Print all the values at or below the specified path recursively. +. +.It Fl I Ar path +This option is passed to the underlying +.Xr nix-instantiate 1 +invocation. +.El +. +. +. +.Sh ENVIRONMENT +.Bl -tag -width indent +.It Ev NIXOS_CONFIG +Path to the main NixOS configuration module. Defaults to +.Pa /etc/nixos/configuration.nix Ns +\&. +.El +. +. +. +.Sh EXAMPLES +Investigate option values: +.Bd -literal -offset indent +$ nixos-option boot.loader +This attribute set contains: +generationsDir +grub +initScript + +$ nixos-option boot.loader.grub.enable +Value: +true + +Default: +true + +Description: +Whether to enable the GNU GRUB boot loader. + +Declared by: + "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix" + +Defined by: + "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix" +.Ed +. +. +. +.Sh SEE ALSO +.Xr configuration.nix 5 +. +. +. +.Sh AUTHORS +.An -nosplit +.An Nicolas Pierron +and +.An the Nixpkgs/NixOS contributors diff --git a/nixos/doc/manual/manpages/nixos-rebuild.8 b/nixos/doc/manual/manpages/nixos-rebuild.8 new file mode 100644 index 0000000000000..8ff59d6da9cfb --- /dev/null +++ b/nixos/doc/manual/manpages/nixos-rebuild.8 @@ -0,0 +1,456 @@ +.Dd January 1, 1980 +.\" nixpkgs groff will use Nixpkgs the OS in the title by default, taking it from +.\" doc-default-operating-system. mandoc doesn't have this register set by default, +.\" so we can use it as a groff/mandoc switch. +.ie ddoc-default-operating-system .Dt nixos-rebuild \&8 "NixOS System Manager's Manual" +.el .Dt nixos-rebuild 8 +.Os NixOS +.Sh NAME +.Nm nixos-rebuild +.Nd reconfigure a NixOS machine +. +. +. +.Sh SYNOPSIS +.Nm +.Bro +.Cm switch | boot | test | build | dry-build | dry-activate | edit | build-vm | build-vm-with-bootloader +.Brc +.br +.Op Fl -upgrade | -upgrade-all +.Op Fl -install-bootloader +.Op Fl -no-build-nix +.Op Fl -fast +.Op Fl -rollback +.Op Fl -builders Ar builder-spec +.br +.Op Fl -flake Ar flake-uri +.Op Fl -no-flake +.Op Fl -override-input Ar input-name flake-uri +.br +.Op Fl -profile-name | p Ar name +.Op Fl -specialisation | c Ar name +.br +.Op Fl -build-host Va host +.Op Fl -target-host Va host +.Op Fl -use-remote-sudo +.br +.Op Fl -show-trace +.Op Fl I Va NIX_PATH +.Op Fl -verbose | v +.Op Fl -impure +.Op Fl -max-jobs | j Va number +.Op Fl -keep-failed | K +.Op Fl -keep-going | k +. +. +. +.Sh DESCRIPTION +This command updates the system so that it corresponds to the +configuration specified in +.Pa /etc/nixos/configuration.nix +or +.Pa /etc/nixos/flake.nix Ns +\&. Thus, every time you modify the configuration or any other NixOS module, you +must run +.Nm +to make the changes take effect. It builds the new system in +.Pa /nix/store Ns +, runs its activation script, and stop and (re)starts any system services if +needed. Please note that user services need to be started manually as they +aren't detected by the activation script at the moment. +. +.Pp +This command has one required argument, which specifies the desired +operation. It must be one of the following: +.Bl -tag -width indent +.It Cm switch +Build and activate the new configuration, and make it the boot default. That +is, the configuration is added to the GRUB boot menu as the default +menu entry, so that subsequent reboots will boot the system into the new +configuration. Previous configurations activated with +.Ic nixos-rebuild switch +or +.Ic nixos-rebuild boot +remain available in the GRUB menu. +.Pp +Note that if you are using specializations, running just +.Ic nixos-rebuild switch +will switch you back to the unspecialized, base system \(em in that case, you +might want to use this instead: +.Bd -literal -offset indent +$ nixos-rebuild switch --specialisation your-specialisation-name +.Ed +.Pp +This command will build all specialisations and make them bootable just +like regular +.Ic nixos-rebuild switch +does \(em the only thing different is that it will switch to given +specialisation instead of the base system; it can be also used to switch from +the base system into a specialised one, or to switch between specialisations. +. +.It Cm boot +Build the new configuration and make it the boot default (as with +.Ic nixos-rebuild switch Ns +), but do not activate it. That is, the system continues to run the previous +configuration until the next reboot. +. +.It Cm test +Build and activate the new configuration, but do not add it to the GRUB +boot menu. Thus, if you reboot the system (or if it crashes), you will +automatically revert to the default configuration (i.e. the +configuration resulting from the last call to +.Ic nixos-rebuild switch +or +.Ic nixos-rebuild boot Ns +). +.Pp +Note that if you are using specialisations, running just +.Ic nixos-rebuild test +will activate the unspecialised, base system \(em in that case, you might want +to use this instead: +.Bd -literal -offset indent +$ nixos-rebuild test --specialisation your-specialisation-name +.Ed +.Pp +This command can be also used to switch from the base system into a +specialised one, or to switch between specialisations. +. +.It Cm build +Build the new configuration, but neither activate it nor add it to the +GRUB boot menu. It leaves a symlink named +.Pa result +in the current directory, which points to the output of the top-level +.Dq system +derivation. This is essentially the same as doing +.Bd -literal -offset indent +$ nix-build /path/to/nixpkgs/nixos -A system +.Ed +.Pp +Note that you do not need to be root to run +.Ic nixos-rebuild build Ns +\&. +. +.It Cm dry-build +Show what store paths would be built or downloaded by any of the +operations above, but otherwise do nothing. +. +.It Cm dry-activate +Build the new configuration, but instead of activating it, show what +changes would be performed by the activation (i.e. by +.Ic nixos-rebuild test Ns +). For instance, this command will print which systemd units would be restarted. +The list of changes is not guaranteed to be complete. +. +.It Cm edit +Opens +.Pa configuration.nix +in the default editor. +. +.It Cm build-vm +Build a script that starts a NixOS virtual machine with the desired +configuration. It leaves a symlink +.Pa result +in the current directory that points (under +.Ql result/bin/run\- Ns Va hostname Ns \-vm Ns +) +at the script that starts the VM. Thus, to test a NixOS configuration in +a virtual machine, you should do the following: +.Bd -literal -offset indent +$ nixos-rebuild build-vm +$ ./result/bin/run-*-vm +.Ed +.Pp +The VM is implemented using the +.Ql qemu +package. For best performance, you should load the +.Ql kvm-intel +or +.Ql kvm-amd +kernel modules to get hardware virtualisation. +.Pp +The VM mounts the Nix store of the host through the 9P file system. The +host Nix store is read-only, so Nix commands that modify the Nix store +will not work in the VM. This includes commands such as +.Nm Ns +; to change the VM’s configuration, you must halt the VM and re-run the commands +above. +.Pp +The VM has its own ext3 root file system, which is automatically created when +the VM is first started, and is persistent across reboots of the VM. It is +stored in +.Ql ./ Ns Va hostname Ns .qcow2 Ns +\&. +.\" The entire file system hierarchy of the host is available in +.\" the VM under +.\" .Pa /hostfs Ns +.\" . +. +.It Cm build-vm-with-bootloader +Like +.Cm build-vm Ns +, but boots using the regular boot loader of your configuration (e.g. GRUB 1 or +2), rather than booting directly into the kernel and initial ramdisk of the +system. This allows you to test whether the boot loader works correctly. \ +However, it does not guarantee that your NixOS configuration will boot +successfully on the host hardware (i.e., after running +.Ic nixos-rebuild switch Ns +), because the hardware and boot loader configuration in the VM are different. +The boot loader is installed on an automatically generated virtual disk +containing a +.Pa /boot +partition. +.El +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl -upgrade , -upgrade-all +Update the root user's channel named +.Ql nixos +before rebuilding the system. +.Pp +In addition to the +.Ql nixos +channel, the root user's channels which have a file named +.Ql .update-on-nixos-rebuild +in their base directory will also be updated. +.Pp +Passing +.Fl -upgrade-all +updates all of the root user's channels. +. +.It Fl -install-bootloader +Causes the boot loader to be (re)installed on the device specified by the +relevant configuration options. +. +.It Fl -no-build-nix +Normally, +.Nm +first builds the +.Ql nixUnstable +attribute in Nixpkgs, and uses the resulting instance of the Nix package manager +to build the new system configuration. This is necessary if the NixOS modules +use features not provided by the currently installed version of Nix. This option +disables building a new Nix. +. +.It Fl -fast +Equivalent to +.Fl -no-build-nix Ns +\&. This option is useful if you call +.Nm +frequently (e.g. if you’re hacking on a NixOS module). +. +.It Fl -rollback +Instead of building a new configuration as specified by +.Pa /etc/nixos/configuration.nix Ns +, roll back to the previous configuration. (The previous configuration is +defined as the one before the “current” generation of the Nix profile +.Pa /nix/var/nix/profiles/system Ns +\&.) +. +.It Fl -builders Ar builder-spec +Allow ad-hoc remote builders for building the new system. This requires +the user executing +.Nm +(usually root) to be configured as a trusted user in the Nix daemon. This can be +achieved by using the +.Va nix.settings.trusted-users +NixOS option. Examples values for that option are described in the +.Dq Remote builds +chapter in the Nix manual, (i.e. +.Ql --builders \(dqssh://bigbrother x86_64-linux\(dq Ns +). By specifying an empty string existing builders specified in +.Pa /etc/nix/machines +can be ignored: +.Ql --builders \(dq\(dq +for example when they are not reachable due to network connectivity. +. +.It Fl -profile-name Ar name , Fl p Ar name +Instead of using the Nix profile +.Pa /nix/var/nix/profiles/system +to keep track of the current and previous system configurations, use +.Pa /nix/var/nix/profiles/system-profiles/ Ns Va name Ns +\&. When you use GRUB 2, for every system profile created with this flag, NixOS +will create a submenu named +.Dq NixOS - Profile Va name +in GRUB’s boot menu, containing the current and previous configurations of this profile. +.Pp +For instance, if you want to test a configuration file named +.Pa test.nix +without affecting the default system profile, you would do: +.Bd -literal -offset indent +$ nixos-rebuild switch -p test -I nixos-config=./test.nix +.Ed +.Pp +The new configuration will appear in the GRUB 2 submenu +.Dq NixOS - Profile 'test' Ns +\&. +. +.It Fl -specialisation Ar name , Fl c Ar name +Activates given specialisation; when not specified, switching and testing +will activate the base, unspecialised system. +. +.It Fl -build-host Ar host +Instead of building the new configuration locally, use the specified host +to perform the build. The host needs to be accessible with +.Ic ssh Ns , +and must be able to perform Nix builds. If the option +.Fl -target-host +is not set, the build will be copied back to the local machine when done. +.Pp +Note that, if +.Fl -no-build-nix +is not specified, Nix will be built both locally and remotely. This is because +the configuration will always be evaluated locally even though the building +might be performed remotely. +.Pp +You can include a remote user name in the host name +.Ns ( Va user@host Ns +). You can also set ssh options by defining the +.Ev NIX_SSHOPTS +environment variable. +. +.It Fl -target-host Ar host +Specifies the NixOS target host. By setting this to something other than an +empty string, the system activation will happen on the remote host instead of +the local machine. The remote host needs to be accessible over +.Ic ssh Ns , +and for the commands +.Cm switch Ns +, +.Cm boot +and +.Cm test +you need root access. +.Pp +If +.Fl -build-host +is not explicitly specified or empty, building will take place locally. +.Pp +You can include a remote user name in the host name +.Ns ( Va user@host Ns +). You can also set ssh options by defining the +.Ev NIX_SSHOPTS +environment variable. +.Pp +Note that +.Nm +honors the +.Va nixpkgs.crossSystem +setting of the given configuration but disregards the true architecture of the +target host. Hence the +.Va nixpkgs.crossSystem +setting has to match the target platform or else activation will fail. +. +.It Fl -use-substitutes +When set, nixos-rebuild will add +.Fl -use-substitutes +to each invocation of nix-copy-closure. This will only affect the behavior of +nixos-rebuild if +.Fl -target-host +or +.Fl -build-host +is also set. This is useful when the target-host connection to cache.nixos.org +is faster than the connection between hosts. +. +.It Fl -use-remote-sudo +When set, nixos-rebuild prefixes remote commands that run on the +.Fl -build-host +and +.Fl -target-host +systems with +.Ic sudo Ns +\&. Setting this option allows deploying as a non-root user. +. +.It Fl -flake Va flake-uri Ns Op Va #name +Build the NixOS system from the specified flake. It defaults to the directory +containing the target of the symlink +.Pa /etc/nixos/flake.nix Ns +, if it exists. The flake must contain an output named +.Ql nixosConfigurations. Ns Va name Ns +\&. If +.Va name +is omitted, it default to the current host name. +. +.It Fl -no-flake +Do not imply +.Fl -flake +if +.Pa /etc/nixos/flake.nix +exists. With this option, it is possible to build non-flake NixOS configurations +even if the current NixOS systems uses flakes. +.El +.Pp +In addition, +.Nm +accepts various Nix-related flags, including +.Fl -max-jobs Ns , +.Fl j Ns , +.Fl I Ns , +.Fl -show-trace Ns , +.Fl -keep-failed Ns , +.Fl -keep-going Ns , +.Fl -impure Ns , +.Fl -verbose Ns , and +.Fl v Ns +\&. See the Nix manual for details. +. +. +. +.Sh ENVIRONMENT +.Bl -tag -width indent +.It Ev NIXOS_CONFIG +Path to the main NixOS configuration module. Defaults to +.Pa /etc/nixos/configuration.nix Ns +\&. +. +.It Ev NIX_PATH +A colon-separated list of directories used to look up Nix expressions enclosed +in angle brackets (e.g. <nixpkgs>). Example: +.Bd -literal -offset indent +nixpkgs=./my-nixpkgs +.Ed +. +.It Ev NIX_SSHOPTS +Additional options to be passed to +.Ic ssh +on the command line. +.El +. +. +. +.Sh FILES +.Bl -tag -width indent +.It Pa /etc/nixos/flake.nix +If this file exists, then +.Nm +will use it as if the +.Fl -flake +option was given. This file may be a symlink to a +.Pa flake.nix +in an actual flake; thus +.Pa /etc/nixos +need not be a flake. +. +.It Pa /run/current-system +A symlink to the currently active system configuration in the Nix store. +. +.It Pa /nix/var/nix/profiles/system +The Nix profile that contains the current and previous system +configurations. Used to generate the GRUB boot menu. +.El +. +. +. +.Sh BUGS +This command should be renamed to something more descriptive. +. +. +. +.Sh AUTHORS +.An -nosplit +.An Eelco Dolstra +and +.An the Nixpkgs/NixOS contributors diff --git a/nixos/doc/manual/manpages/nixos-version.8 b/nixos/doc/manual/manpages/nixos-version.8 new file mode 100644 index 0000000000000..980ee8b1f49e9 --- /dev/null +++ b/nixos/doc/manual/manpages/nixos-version.8 @@ -0,0 +1,90 @@ +.Dd January 1, 1980 +.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from +.\" doc-default-operating-system. mandoc doesn't have this register set by default, +.\" so we can use it as a groff/mandoc switch. +.ie ddoc-default-operating-system .Dt nixos-version \&8 "NixOS System Manager's Manual" +.el .Dt nixos-version 8 +.Os NixOS +.Sh NAME +.Nm nixos-version +.Nd show the NixOS version +. +. +. +.Sh SYNOPSIS +.Nm nixos-version +.Op Fl -hash +.Op Fl -revision +.Op Fl -configuration-revision +.Op Fl -json +. +. +. +.Sh DESCRIPTION +This command shows the version of the currently active NixOS configuration. For example: +.Bd -literal -offset indent +$ nixos-version +16.03.1011.6317da4 (Emu) +.Ed +. +.Pp +The version consists of the following elements: +.Bl -tag -width indent +.It Ql 16.03 +The NixOS release, indicating the year and month in which it was released +(e.g. March 2016). +.It Ql 1011 +The number of commits in the Nixpkgs Git repository between the start of the +release branch and the commit from which this version was built. This ensures +that NixOS versions are monotonically increasing. It is +.Ql git +when the current NixOS configuration was built from a checkout of the Nixpkgs +Git repository rather than from a NixOS channel. +.It Ql 6317da4 +The first 7 characters of the commit in the Nixpkgs Git repository from which +this version was built. +.It Ql Emu +The code name of the NixOS release. The first letter of the code name indicates +that this is the N'th stable NixOS release; for example, Emu is the fifth +release. +.El +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl -hash , -revision +Show the full SHA1 hash of the Git commit from which this configuration was +built, e.g. +.Bd -literal -offset indent +$ nixos-version --hash +6317da40006f6bc2480c6781999c52d88dde2acf +.Ed +. +.It Fl -configuration-revision +Show the configuration revision if available. This could be the full SHA1 hash +of the Git commit of the system flake, if you add +.Bd -literal -offset indent +{ system.configurationRevision = self.rev or "dirty"; } +.Ed +.Pp +to the +.Ql modules +array of your flake.nix system configuration e.g. +.Bd -literal -offset indent +$ nixos-version --configuration-revision +aa314ebd1592f6cdd53cb5bba8bcae97d9323de8 +.Ed +. +.It Fl -json +Print a JSON representation of the versions of NixOS and the top-level +configuration flake. +.El +. +. +. +.Sh AUTHORS +.An -nosplit +.An Eelco Dolstra +and +.An the Nixpkgs/NixOS contributors |