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