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

   1 <refentry xmlns="http://docbook.org/ns/docbook"
   2           xmlns:xlink="http://www.w3.org/1999/xlink"
   3           xmlns:xi="http://www.w3.org/2001/XInclude">
   4  <refmeta>
   5   <refentrytitle><command>nixos-build-vms</command>
   6   </refentrytitle><manvolnum>8</manvolnum>
   7   <refmiscinfo class="source">NixOS</refmiscinfo>
   8 <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
   9  </refmeta>
  10  <refnamediv>
  11   <refname><command>nixos-build-vms</command></refname>
  12   <refpurpose>build a network of virtual machines from a network of NixOS configurations</refpurpose>
  13  </refnamediv>
  14  <refsynopsisdiv>
  15   <cmdsynopsis>
  16    <command>nixos-build-vms</command>
  17    <arg>
  18     <option>--show-trace</option>
  19    </arg>
  20
  21    <arg>
  22     <option>--no-out-link</option>
  23    </arg>
  24
  25    <arg>
  26     <option>--help</option>
  27   </arg>
  28
  29   <arg>
  30     <option>--option</option>
  31     <replaceable>name</replaceable>
  32     <replaceable>value</replaceable>
  33   </arg>
  34
  35    <arg choice="plain">
  36     <replaceable>network.nix</replaceable>
  37    </arg>
  38   </cmdsynopsis>
  39  </refsynopsisdiv>
  40  <refsection>
  41   <title>Description</title>
  42   <para>
  43    This command builds a network of QEMU-KVM virtual machines of a Nix
  44    expression specifying a network of NixOS machines. The virtual network can
  45    be started by executing the <filename>bin/run-vms</filename> shell script
  46    that is generated by this command. By default, a <filename>result</filename>
  47    symlink is produced that points to the generated virtual network.
  48   </para>
  49   <para>
  50    A network Nix expression has the following structure:
  51 <screen>
  52 {
  53   test1 = {pkgs, config, ...}:
  54     {
  55       services.openssh.enable = true;
  56       nixpkgs.localSystem.system = "i686-linux";
  57       deployment.targetHost = "test1.example.net";
  58
  59       # Other NixOS options
  60     };
  61
  62   test2 = {pkgs, config, ...}:
  63     {
  64       services.openssh.enable = true;
  65       services.httpd.enable = true;
  66       environment.systemPackages = [ pkgs.lynx ];
  67       nixpkgs.localSystem.system = "x86_64-linux";
  68       deployment.targetHost = "test2.example.net";
  69
  70       # Other NixOS options
  71     };
  72 }
  73 </screen>
  74    Each attribute in the expression represents a machine in the network (e.g.
  75    <varname>test1</varname> and <varname>test2</varname>) referring to a
  76    function defining a NixOS configuration. In each NixOS configuration, two
  77    attributes have a special meaning. The
  78    <varname>deployment.targetHost</varname> specifies the address (domain name
  79    or IP address) of the system which is used by <command>ssh</command> to
  80    perform remote deployment operations. The
  81    <varname>nixpkgs.localSystem.system</varname> attribute can be used to
  82    specify an architecture for the target machine, such as
  83    <varname>i686-linux</varname> which builds a 32-bit NixOS configuration.
  84    Omitting this property will build the configuration for the same
  85    architecture as the host system.
  86   </para>
  87  </refsection>
  88  <refsection>
  89   <title>Options</title>
  90   <para>
  91    This command accepts the following options:
  92   </para>
  93   <variablelist>
  94    <varlistentry>
  95     <term>
  96      <option>--show-trace</option>
  97     </term>
  98     <listitem>
  99      <para>
 100       Shows a trace of the output.
 101      </para>
 102     </listitem>
 103    </varlistentry>
 104    <varlistentry>
 105     <term>
 106      <option>--no-out-link</option>
 107     </term>
 108     <listitem>
 109      <para>
 110       Do not create a 'result' symlink.
 111      </para>
 112     </listitem>
 113    </varlistentry>
 114    <varlistentry>
 115     <term>
 116      <option>-h</option>, <option>--help</option>
 117     </term>
 118     <listitem>
 119      <para>
 120       Shows the usage of this command to the user.
 121      </para>
 122     </listitem>
 123    </varlistentry>
 124    <varlistentry>
 125     <term>
 126      <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
 127     </term>
 128     <listitem>
 129      <para>Set the Nix configuration option
 130       <replaceable>name</replaceable> to <replaceable>value</replaceable>.
 131       This overrides settings in the Nix configuration file (see
 132       <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 133      </para>
 134     </listitem>
 135    </varlistentry>
 136   </variablelist>
 137  </refsection>
 138 </refentry>