1 files changed, 138 insertions, 0 deletions
diff --git a/nixos/doc/manual/man-nixos-build-vms.xml b/nixos/doc/manual/man-nixos-build-vms.xml
new file mode 100644
index 00000000000..fa7c8c0c6d7
--- /dev/null
+++ b/nixos/doc/manual/man-nixos-build-vms.xml
@@ -0,0 +1,138 @@
+<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>