Wrote manual pages for the nixos-deploy-network and nixos-build-vms commands
svn path=/nixos/trunk/; revision=25030
This commit is contained in:
Sander van der Burg
parent
2e38d8cd31
commit
9df8293d63
147
doc/manual/man-nixos-build-vms.xml
Normal file
147
doc/manual/man-nixos-build-vms.xml
Normal file
@ -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>
|
||||
134
doc/manual/man-nixos-deploy-network.xml
Normal file
134
doc/manual/man-nixos-deploy-network.xml
Normal file
@ -0,0 +1,134 @@
|
||||
<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-deploy-network</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-deploy-network</command></refname>
|
||||
<refpurpose>deploy a network of NixOS configurations into a network of machines</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<cmdsynopsis>
|
||||
<command>nixos-deploy-network</command>
|
||||
<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 automatically deploys a network of NixOS
|
||||
configurations into a network of machines.
|
||||
First, it tries to build all the system derivations defined
|
||||
in the network expression. Then it efficiently transfers
|
||||
the closures to the machines in the network. Finally, the configurations
|
||||
are activated. In case of a failure, a rollback is performed,
|
||||
which brings all the updated configurations back into the previous
|
||||
state.</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>--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>
|
||||
@ -26,5 +26,6 @@
|
||||
<xi:include href="man-configuration.xml" />
|
||||
<xi:include href="man-nixos-rebuild.xml" />
|
||||
<xi:include href="man-nixos-option.xml" />
|
||||
|
||||
<xi:include href="man-nixos-deploy-network.xml" />
|
||||
<xi:include href="man-nixos-build-vms.xml" />
|
||||
</reference>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user