<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>