nixpkgs/nixos/doc/manual/manpages/nixos-build-vms.8

.Dd January 1, 1980
.Dt nixos-build-vms 8
.Os
.Sh NAME
.Nm nixos-build-vms
.Nd build a network of virtual machines from a network of NixOS configurations
.
.
.
.Sh SYNOPSIS
.Nm nixos-build-vms
.Op Fl -show-trace
.Op Fl -no-out-link
.Op Fl -help
.Op Fl -option Ar name value
.Pa network.nix
.
.
.
.Sh DESCRIPTION
.
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
.Pa bin/run-vms
shell script that is generated by this command. By default, a
.Pa result
symlink is produced that points to the generated virtual network.
.
.Pp
A network Nix expression has the following structure:
.Bd -literal -offset indent
{
  test1 = {pkgs, config, ...}:
    {
      services.openssh.enable = true;
      nixpkgs.localSystem.system = "i686-linux";
      deployment.targetHost = "test1.example.net";

      # Other NixOS options
    };

  test2 = {pkgs, config, ...}:
    {
      services.openssh.enable = true;
      services.httpd.enable = true;
      environment.systemPackages = [ pkgs.lynx ];
      nixpkgs.localSystem.system = "x86_64-linux";
      deployment.targetHost = "test2.example.net";

      # Other NixOS options
    };
}
.Ed
.
.Pp
Each attribute in the expression represents a machine in the network
.Ns (e.g.
.Va test1
and
.Va test2 Ns
) referring to a function defining a NixOS configuration. In each NixOS
configuration, two attributes have a special meaning. The
.Va deployment.targetHost
specifies the address (domain name or IP address) of the system which is used by
.Ic ssh
to perform remote deployment operations. The
.Va nixpkgs.localSystem.system
attribute can be used to specify an architecture for the target machine, such as
.Ql i686-linux
which builds a 32-bit NixOS configuration. Omitting this property will build the
configuration for the same architecture as the host system.
.
.
.
.Sh OPTIONS
.Bl -tag -width indent
.It Fl -show-trace
Shows a trace of the output.
.
.It Fl -no-out-link
Do not create a
.Pa result
symlink.
.
.It Fl h , -help
Shows the usage of this command to the user.
.
.It Fl -option Ar name Va value
Set the Nix configuration option
.Va name
to
.Va value Ns
\&. This overrides settings in the Nix configuration file (see
.Xr nix.conf 5 Ns
).
.El
.
.
.
.Sh AUTHORS
.An -nosplit
.An Eelco Dolstra
and
.An the Nixpkgs/NixOS contributors