1 files changed, 110 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..f37677629d0
--- /dev/null
+++ b/nixos/doc/manual/man-nixos-build-vms.xml
@@ -0,0 +1,110 @@
+<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 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.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.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.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>
+
+</variablelist>
+
+</refsection>
+
+
+</refentry>