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