nixpkgs/doc/manual/man-nixos-build-vms.xml

<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-deploy-network</command>
    <arg><option>--use-backdoor</option></arg>
    <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>This command also provides the <option>--use-backdoor</option> option,
which spawns UNIX domain sockets in the current working directory by using the
<command>socat</command> command. This allows
users to remotely script a generated virtual machine.</para>

<para>A network Nix expression has the following structure:

<screen>
{
  test1 = {pkgs, config, ...}:
    {
      services.openssh.enable = true;
      nixpkgs.system = "i686-linux";
      deployment.hostname = "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.hostname = "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.hostname</varname> specifies the hostname
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>--use-backdoor</option></term>
    <listitem>
      <para>Indicates that the backdoor must be enabled so that the VMs can be
      accessed through a UNIX domain socket. The UNIX domain sockets are
      created in the current working directory.</para>
    </listitem>
  </varlistentry>

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


<refsection><title>Environment variables</title>

<variablelist>

  <varlistentry>
    <term><envar>NIXOS</envar></term>
    <listitem>
      <para>Path to the NixOS source tree.  Defaults to
      <filename>/etc/nixos/nixos</filename>.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><envar>NIXPKGS_ALL</envar></term>
    <listitem>
      <para>Path to the Nixpkgs source tree.  Defaults to
      <filename>/etc/nixos/nixpkgs</filename>.</para>
    </listitem>
  </varlistentry>
</variablelist>

</refsection>

</refentry>