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