diff options
author | Sander van der Burg <s.vanderburg@tudelft.nl> | 2010-12-07 16:33:18 +0000 |
---|---|---|
committer | Sander van der Burg <s.vanderburg@tudelft.nl> | 2010-12-07 16:33:18 +0000 |
commit | 9df8293d63edb2bedacf453e63432fdb07269bdd (patch) | |
tree | 3b243387c9c006967331f159e5b0478e3c8e6832 /doc/manual/man-nixos-build-vms.xml | |
parent | 2e38d8cd317b0d88d569b197648cb5cb65292328 (diff) | |
download | nixpkgs-9df8293d63edb2bedacf453e63432fdb07269bdd.tar nixpkgs-9df8293d63edb2bedacf453e63432fdb07269bdd.tar.gz nixpkgs-9df8293d63edb2bedacf453e63432fdb07269bdd.tar.bz2 nixpkgs-9df8293d63edb2bedacf453e63432fdb07269bdd.tar.lz nixpkgs-9df8293d63edb2bedacf453e63432fdb07269bdd.tar.xz nixpkgs-9df8293d63edb2bedacf453e63432fdb07269bdd.tar.zst nixpkgs-9df8293d63edb2bedacf453e63432fdb07269bdd.zip |
Wrote manual pages for the nixos-deploy-network and nixos-build-vms commands
svn path=/nixos/trunk/; revision=25030
Diffstat (limited to 'doc/manual/man-nixos-build-vms.xml')
-rw-r--r-- | doc/manual/man-nixos-build-vms.xml | 147 |
1 files changed, 147 insertions, 0 deletions
diff --git a/doc/manual/man-nixos-build-vms.xml b/doc/manual/man-nixos-build-vms.xml new file mode 100644 index 00000000000..3bbf9defb11 --- /dev/null +++ b/doc/manual/man-nixos-build-vms.xml @@ -0,0 +1,147 @@ +<refentry xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude"> + +<refmeta> + <refentrytitle><command>nixos-build-vms</command></refentrytitle> + <manvolnum>8</manvolnum> + <refmiscinfo class="source">NixOS</refmiscinfo> + <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> +</refmeta> + +<refnamediv> + <refname><command>nixos-build-vms</command></refname> + <refpurpose>build a network of virtual machines from a network of NixOS configurations</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>nixos-deploy-network</command> + <arg><option>--use-backdoor</option></arg> + <arg><option>--show-trace</option></arg> + <arg><option>--no-out-link</option></arg> + <arg><option>--help</option></arg> + <arg choice="plain"><replaceable>network.nix</replaceable></arg> + </cmdsynopsis> +</refsynopsisdiv> + +<refsection><title>Description</title> + +<para>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 <filename>bin/run-vms</filename> shell script that is generated by +this command. By default, a <filename>result</filename> symlink is produced that +points to the generated virtual network. +</para> + +<para>This command also provides the <option>--use-backdoor</option> option, +which spawns UNIX domain sockets in the current working directory by using the +<command>socat</command> command. This allows +users to remotely script a generated virtual machine.</para> + +<para>A network Nix expression has the following structure: + +<screen> +{ + test1 = {pkgs, config, ...}: + { + services.openssh.enable = true; + nixpkgs.system = "i686-linux"; + deployment.hostname = "test1.example.net"; + + # Other NixOS options + }; + + test2 = {pkgs, config, ...}: + { + services.openssh.enable = true; + services.httpd.enable = true; + environment.systemPackages = [ pkgs.lynx ]; + nixpkgs.system = "x86_64-linux"; + deployment.hostname = "test2.example.net"; + + # Other NixOS options + }; +} +</screen> + +Each attribute in the expression represents a machine in the network +(e.g. <varname>test1</varname> and <varname>test2</varname>) +referring to a function defining a NixOS configuration. +In each NixOS configuration, two attributes have a special meaning. +The <varname>deployment.hostname</varname> specifies the hostname +of the system which is used by <command>ssh</command> to perform +remote deployment operations. The <varname>nixpkgs.system</varname> +attribute can be used to specify an architecture for the target machine, +such as <varname>i686-linux</varname> which builds a 32-bit NixOS +configuration. Omitting this property will build the configuration +for the same architecture as the host system. +</para> + +</refsection> + +<refsection><title>Options</title> + +<para>This command accepts the following options:</para> + +<variablelist> + + <varlistentry> + <term><option>--use-backdoor</option></term> + <listitem> + <para>Indicates that the backdoor must be enabled so that the VMs can be + accessed through a UNIX domain socket. The UNIX domain sockets are + created in the current working directory.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--show-trace</option></term> + <listitem> + <para>Shows a trace of the output.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-out-link</option></term> + <listitem> + <para>Do not create a 'result' symlink.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-h</option>, <option>--help</option></term> + <listitem> + <para>Shows the usage of this command to the user.</para> + </listitem> + </varlistentry> + +</variablelist> + +</refsection> + + +<refsection><title>Environment variables</title> + +<variablelist> + + <varlistentry> + <term><envar>NIXOS</envar></term> + <listitem> + <para>Path to the NixOS source tree. Defaults to + <filename>/etc/nixos/nixos</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>NIXPKGS_ALL</envar></term> + <listitem> + <para>Path to the Nixpkgs source tree. Defaults to + <filename>/etc/nixos/nixpkgs</filename>.</para> + </listitem> + </varlistentry> +</variablelist> + +</refsection> + +</refentry> |