Commit 0c601b12 authored by pennae's avatar pennae Committed by pennae
Browse files

nixos/manual: translate manpages to mdoc

since we want to move away from docbook and having docbook manpages
around is going to block further progress we have to translate the
current nixos manpages from docbook it *something* else. mdoc seems the
most appropriate choice since markdown can't represent all the things
manpages can differentiate with even more extensions. if we ever need
html manpages we can render them using troff, like many of the online
manpage viewers, or rewrite them again. since we haven't had html
manpages for any of these in many years that seems unlikely to happen.

unlike most of the recent markdown conversions this comes with a lot of
minor rendering changes, mostly in spacing. docbook-xslt creates manual
pages in a very different dialect than mdoc (which is used here).
parent b73b082c
Loading
Loading
Loading
Loading
+7 −2
Original line number Diff line number Diff line
@@ -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 \
+0 −138
Original line number Diff line number Diff line
<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>
+0 −154
Original line number Diff line number Diff line
<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>
+0 −214
Original line number Diff line number Diff line
<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 =
    [ &lt;nixos/modules/installer/scan/not-detected.nix&gt;
    ];

  boot.initrd.availableKernelModules = [ "ehci_hcd" "ahci" ];
  boot.kernelModules = [ "kvm-intel" ];
  boot.extraModulePackages = [ ];

  fileSystems."/" =
    { device = "/dev/disk/by-label/nixos";
      fsType = "ext3";
      options = [ "rw" "data=ordered" "relatime" ];
    };

  fileSystems."/boot" =
    { device = "/dev/sda1";
      fsType = "ext3";
      options = [ "rw" "errors=continue" "user_xattr" "acl" "barrier=1" "data=writeback" "relatime" ];
    };

  swapDevices =
    [ { device = "/dev/sda2"; }
    ];

  nix.maxJobs = 8;
}
</programlisting>
   It will also create a basic
   <filename>/mnt/etc/nixos/configuration.nix</filename>, which you should edit
   to customise the logical configuration of your system. This file includes
   the result of the hardware scan as follows:
<programlisting>
  imports = [ ./hardware-configuration.nix ];
</programlisting>
  </para>
  <para>
   After installation, if your hardware configuration changes, you can run:
<screen>
<prompt>$ </prompt>nixos-generate-config
</screen>
   to update <filename>/etc/nixos/hardware-configuration.nix</filename>. Your
   <filename>/etc/nixos/configuration.nix</filename> will
   <emphasis>not</emphasis> be overwritten.
  </para>
 </refsection>
</refentry>
+0 −357

File deleted.

Preview size limit exceeded, changes collapsed.

Loading