Author: sandervanderburg Date: Wed Jan 19 16:16:23 2011 New Revision: 25631 URL: https://svn.nixos.org/websvn/nix/?rev=25631&sc=1
Log: Initial version of the manual Added: disnix/disnixos/trunk/doc/ disnix/disnixos/trunk/doc/Makefile.am disnix/disnixos/trunk/doc/manual/ disnix/disnixos/trunk/doc/manual/Makefile.am disnix/disnixos/trunk/doc/manual/disnix-backdoor-client.xml disnix/disnixos/trunk/doc/manual/disnixos-deploy-network.xml disnix/disnixos/trunk/doc/manual/disnixos-env.xml disnix/disnixos/trunk/doc/manual/disnixos-geninfra.xml disnix/disnixos/trunk/doc/manual/disnixos-genservices.xml disnix/disnixos/trunk/doc/manual/disnixos-vm-env.xml disnix/disnixos/trunk/doc/manual/index.xml disnix/disnixos/trunk/doc/manual/installation.xml disnix/disnixos/trunk/doc/manual/introduction.xml disnix/disnixos/trunk/doc/manual/style.css disnix/disnixos/trunk/doc/manual/usage.xml Modified: disnix/disnixos/trunk/Makefile.am disnix/disnixos/trunk/configure.ac disnix/disnixos/trunk/release.nix disnix/disnixos/trunk/scripts/disnixos-geninfra.in Modified: disnix/disnixos/trunk/Makefile.am ============================================================================== --- disnix/disnixos/trunk/Makefile.am Wed Jan 19 14:07:51 2011 (r25630) +++ disnix/disnixos/trunk/Makefile.am Wed Jan 19 16:16:23 2011 (r25631) @@ -1 +1 @@ -SUBDIRS = scripts data +SUBDIRS = doc scripts data Modified: disnix/disnixos/trunk/configure.ac ============================================================================== --- disnix/disnixos/trunk/configure.ac Wed Jan 19 14:07:51 2011 (r25630) +++ disnix/disnixos/trunk/configure.ac Wed Jan 19 16:16:23 2011 (r25631) @@ -16,6 +16,20 @@ AC_PROG_INSTALL PKG_PROG_PKG_CONFIG NEED_PROG(socat, socat) +AC_PATH_PROG(xmllint, xmllint, false) +AC_PATH_PROG(xsltproc, xsltproc, false) +AC_PATH_PROG(dblatex, dblatex) + +# Checks for Docbook stuff +AC_ARG_WITH(docbook-rng, AC_HELP_STRING([--with-docbook-rng=PATH], + [path of the DocBook RelaxNG schema]), + docbookrng=$withval, docbookrng=/docbook-rng-missing) +AC_SUBST(docbookrng) + +AC_ARG_WITH(docbook-xsl, AC_HELP_STRING([--with-docbook-xsl=PATH], + [path of the DocBook XSL stylesheets]), + docbookxsl=$withval, docbookxsl=/docbook-xsl-missing) +AC_SUBST(docbookxsl) # Checks for Disnix libraries DISNIX_REQUIRED=0.2 @@ -26,6 +40,8 @@ # Output AC_CONFIG_FILES([ Makefile +doc/Makefile +doc/manual/Makefile scripts/Makefile data/Makefile data/generate-infrastructure.nix Added: disnix/disnixos/trunk/doc/Makefile.am ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/Makefile.am Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1 @@ +SUBDIRS = manual Added: disnix/disnixos/trunk/doc/manual/Makefile.am ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/Makefile.am Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1,66 @@ +XMLLINT = $(xmllint) +XSLTPROC = $(xsltproc) \ + --param section.autolabel 1 \ + --param section.label.includes.component.label 1 \ + --param html.stylesheet \'style.css\' \ + --param make.valid.html 1 \ + --param xref.with.number.and.title 1 \ + --param toc.section.depth 3 \ + --param admon.style \'\' \ + --param callout.graphics.extension \'.gif\' \ + --param contrib.inline.enabled 0 + +dblatex_opts = \ + -P doc.collab.show=0 \ + -P latex.output.revhistory=0 + +#man1_MANS = disnix-backdoor-client.1 disnixos-deploy-network.1 disnixos-env.1 disnixos-geninfra.1 \ +# disnixos-genservices.1 disnixos-gentests.1 disnixos-vm-env.1 + +MANUAL_SRCS = index.xml introduction.xml installation.xml images style.css \ + disnixos-env.xml disnixos-vm-env.xml disnix-backdoor-client.xml disnixos-deploy-network.xml \ + disnixos-geninfra.xml disnixos-genservices.xml \ + $(man1_MANS:.1=.xml) + +version.txt: + echo -n $(VERSION) > version.txt + +# Note: RelaxNG validation requires xmllint >= 2.7.4. +manual.is-valid: $(MANUAL_SRCS) version.txt + $(XMLLINT) --noout --nonet --xinclude --noxincludenode --relaxng $(docbookrng)/docbook.rng $< + touch $@ + +man $(MANS): $(MANUAL_SRCS) manual.is-valid + $(XSLTPROC) --nonet --xinclude $(docbookxsl)/manpages/docbook.xsl index.xml + +index.html: $(MANUAL_SRCS) manual.is-valid images + $(XSLTPROC) --nonet --xinclude --output index.html \ + $(docbookxsl)/html/docbook.xsl index.xml + +index.pdf: $(MANUAL_SRCS) manual.is-valid images + if test "$(dblatex)" != ""; then \ + $(dblatex) $(dblatex_opts) index.xml; \ + else \ + echo "Please install dblatex and rerun configure."; \ + exit 1; \ + fi + +images: + mkdir images + mkdir images/callouts + cp $(docbookxsl)/images/callouts/*.gif images/callouts + chmod -R +w images + +all-local: index.html + +install-data-local: index.html + $(INSTALL) -d $(DESTDIR)$(docdir)/manual + $(INSTALL_DATA) index.html $(DESTDIR)$(docdir)/manual + $(INSTALL_DATA) style.css $(DESTDIR)$(docdir)/manual + cp -r images $(DESTDIR)$(docdir)/manual/images + +KEEP = index.html manual.is-valid version.txt $(MANS) + +EXTRA_DIST = $(MANUAL_SRCS) $(FIGURES) $(KEEP) + +DISTCLEANFILES = $(KEEP) Added: disnix/disnixos/trunk/doc/manual/disnix-backdoor-client.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/disnix-backdoor-client.xml Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1,288 @@ +<refentry xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xmlns:xi="http://www.w3.org/2001/XInclude"; + xml:id="sec-disnix-backdoor-client"> + + <refmeta> + <refentrytitle>disnix-backdoor-client</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">DisnixOS</refmiscinfo> + <refmiscinfo class="version"><xi:include href="version.txt" parse="text" /></refmiscinfo> + </refmeta> + + <refnamediv> + <refname>disnix-backdoor-client</refname> + <refpurpose>Provides access to the disnix-service through a socket with public access</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>disnix-backdoor-client</command> + <arg choice="req"><option>--target</option> <replaceable>socat_address</replaceable></arg> + <arg choice="req"><replaceable>operation</replaceable></arg> + <arg><replaceable>options</replaceable></arg> + <arg><replaceable>Nix_store_path</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsection> + <title>Description</title> + + <para> + The command <command>disnix-backdoor-client</command> provides remote access to a <command>disnix-service</command> instance running + on a machine in the network by using a insecure socket with public access. This tool is designed for use with + <command>disnixos-vm-env</command> to automatically deploy a system in a network of virtual machines. + </para> + <para> + In most cases this command is not used directly, but is used by specifying the <option>--interface</option> option + for a Disnix command-line utility (such as <command>disnix-env</command>) or by setting the <replaceable>DISNIX_CLIENT_INTERFACE</replaceable> + environment variable. By using one of those properties, the Disnix tools will use the given interface instead + of the standard <command>disnix-client</command> which only provides loopback access. + </para> + </refsection> + + <refsection> + <title>Operations</title> + + <variablelist> + <varlistentry> + <term><option>--import</option></term> + <listitem> + <para> + Imports a given closure into the Nix store of the target machine. Optionally, + it transfers the closure from this machine to the target machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--export</option></term> + <listitem> + <para> + Exports the closure of a given Nix store path of the target machine into a file, + and optionally downloads it. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--print-invalid</option></term> + <listitem> + <para> + Prints all the paths that are not valid in the Nix store of the target machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--realise</option></term> + <listitem> + <para> + Realises the given store derivation on the target machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--set</option></term> + <listitem> + <para> + Creates a Disnix profile only containing the given derivation on the target machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--query-installed</option></term> + <listitem> + <para> + Queries all the installed services on the given target machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--query-requisites</option></term> + <listitem> + <para> + Queries all the requisites (intra-dependencies) of the given services on the target machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--collect-garbage</option></term> + <listitem> + <para> + Collects garbage on the given target machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--activate</option></term> + <listitem> + <para> + Activates the given service on the target machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--deactivate</option></term> + <listitem> + <para> + Deactivates the given service on the target machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--lock</option></term> + <listitem> + <para> + Acquires a lock on a Disnix profile of the target machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--unlock</option></term> + <listitem> + <para> + Release the lock on a Disnix profile of the target machine. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + + <refsection> + <title>Options</title> + + <variablelist> + <varlistentry> + <term><option>-t</option>, <option>--target</option></term> + <listitem> + <para> + Specifies a socat address for a socket connecting to a target machine. + Refer to the <command>socat</command> manual page for more details about + socat addresses. For example, <replaceable>TCP:hostname:port</replaceable> + can be used to connect to a machine through a TCP socket. + <replaceable>UNIX-CONNECT:/path/to/socket</replaceable> can be used + to connect to a machine through a Unix domain socket. + </para> + </listitem> + </varlistentry> + </variablelist> + + <refsection> + <title>Import operation</title> + + <variablelist> + <varlistentry> + <term><option>--localfile</option></term> + <listitem> + <para> + Specifies that the given closure is stored locally, + so that it will be transfered to the target machine first. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--remotefile</option></term> + <listitem> + <para> + Specifies that the given closure is stored remotely, + so that it does not have to be transfered to the target machine. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + + <refsection> + <title>Export operation</title> + + <variablelist> + <varlistentry> + <term><option>--localfile</option></term> + <listitem> + <para> + Specifies that the exported closure should be stored locally. + This option does not download the closure. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--remotefile</option></term> + <listitem> + <para> + Specifies that the exported closure should be stored remotely. + This option downloads the closure from the target machine. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + + <refsection> + <title>Set operation/Query installed operation</title> + + <variablelist> + <varlistentry> + <term><option>-p</option>, <option>--profile</option></term> + <listitem> + <para> + Specifies the name of the profile that should be used. Defaults to: default + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + + <refsection> + <title>Collect garbage operation</title> + + <variablelist> + <varlistentry> + <term><option>-d</option>, <option>--delete-old</option></term> + <listitem> + <para> + Specifies that also the older generations of the profiles have to be deleted. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + + <refsection> + <title>Activation/Deactivation operation</title> + + <variablelist> + <varlistentry> + <term><option>--type</option></term> + <listitem> + <para> + Specifies the activation module that should be used, such as + <command>echo</command> or <command>process</command>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--arguments</option></term> + <listitem> + <para> + Specifies the arguments passed to the activation module, + which is a string with key=value pairs. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + + <refsection> + <title>Lock/Unlock operation</title> + + <variablelist> + <varlistentry> + <term><option>-p</option>, <option>--profile</option></term> + <listitem> + <para> + Specifies the name of the profile that should be used. Defaults to: default. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + </refsection> +</refentry> \ No newline at end of file Added: disnix/disnixos/trunk/doc/manual/disnixos-deploy-network.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/disnixos-deploy-network.xml Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1,114 @@ +<refentry xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xmlns:xi="http://www.w3.org/2001/XInclude"; + xml:id="sec-disnixos-deploy-network"> + + <refmeta> + <refentrytitle>disnixos-deploy-network</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">DisnixOS</refmiscinfo> + <refmiscinfo class="version"><xi:include href="version.txt" parse="text" /></refmiscinfo> + </refmeta> + + <refnamediv> + <refname>disnixos-deploy-network</refname> + <refpurpose>Installs or updates the infrastructure of a distributed system</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>disnixos-deploy-network</command> + <arg><replaceable>options</replaceable></arg> + <arg choice="plain"><replaceable>network_expr</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsection> + <title>Description</title> + + <para> + The command <command>disnixos-deploy-network</command> is used to install or upgrade the NixOS + configurations of machines in a network through the Disnix service. + + </para> + <para> + This command is similar to the NixOS command <command>nixos-deploy-network</command>, except + that it uses the Disnix interface as communication layer (instead of SSH directly) and it also + notifies running services of an upgrade, so that they can optionally block/queue connections. + </para> + </refsection> + + <refsection> + <title>Options</title> + + <variablelist> + <varlistentry> + <term><option>--target-property</option></term> + <listitem> + <para> + The target property of an infrastructure model, that specifies how to connect + to the remote Disnix interface. (Defaults to hostname) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--interface</option></term> + <listitem> + <para> + Path to executable that communicates with a Disnix interface. Defaults to + <command>disnix-ssh-client</command>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-p</option>, <option>--profile</option></term> + <listitem> + <para> + Name of the profile that is used for this system. Defaults to: default + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--show-trace</option></term> + <listitem> + <para> + Shows a trace of the output. + </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><option>DISNIX_CLIENT_INTERFACE</option></term> + <listitem> + <para> + Sets the client interface (which defaults to + <command>disnix-ssh-client</command>) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>DISNIX_TARGET_PROPERTY</option></term> + <listitem> + <para> + Sets the target property of an infrastructure model, + that specifies how to connect to the remote Disnix interface. (Defaults to hostname) + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> +</refentry> Added: disnix/disnixos/trunk/doc/manual/disnixos-env.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/disnixos-env.xml Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1,156 @@ +<refentry xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xmlns:xi="http://www.w3.org/2001/XInclude"; + xml:id="sec-disnixos-env"> + + <refmeta> + <refentrytitle>disnixos-env</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">DisnixOS</refmiscinfo> + <refmiscinfo class="version"><xi:include href="version.txt" parse="text" /></refmiscinfo> + </refmeta> + + <refnamediv> + <refname>disnixos-env</refname> + <refpurpose>Installs or updates the services and infrastructure of a distributed system</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>disnixos-env</command> + <arg choice="plain"><option>-s</option> <replaceable>services_expr</replaceable></arg> + <arg choice="plain"><option>-n</option> <replaceable>network_expr</replaceable></arg> + <arg choice="plain"><option>-d</option> <replaceable>distribution_expr</replaceable></arg> + <arg><replaceable>options</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsection> + <title>Description</title> + + <para> + The command <command>disnixos-env</command> is used to install or upgrade the services and infrastructure of distributed + system in a given environment. + This command requires three Nix expressions as input parameters; A services model capturing + the components of a distributed system and its inter-dependencies; A network model capturing + the NixOS configurations of machines in the network and its properties and a distribution model which maps services to machines. + </para> + <para> + By invoking this command it will first build, distribute and activate all the NixOS configurations of the + machines in the network. + Then it will build all the services that are defined in the distribution + model from source code including all its dependencies. If all the services are successfully built, + the closures of the services are transferred to the target machines in the network. Finally, the + services are activated by traversing the inter-dependency graph of all the services. + In case of a failure a rollback is performed to bring the system back in its previous configuration. + </para> + <para> + When there is already a distributed system configuration deployed, an upgrade is performed. In this + phase only the changed parts of the system are deactivated and activated. In this process we + also deal with the inter-dependencies so that no services fails due to a missing inter-dependency. + </para> + <para> + This command is essentially a composition of the <command>disnixos-deploy-network</command> command (which + deploys the infrastructure) and the <command>disnix-env</command> (which deploys the services of which + the system is composed). + </para> + </refsection> + + <refsection> + <title>Options</title> + + <variablelist> + <varlistentry> + <term><option>-s</option>, <option>--services</option></term> + <listitem> + <para> + Services Nix expression which describes all components of the distributed system + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-n</option>, <option>--network</option></term> + <listitem> + <para> + Network Nix expression which captures NixOS configurations of machines in the network + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-d</option>, <option>--distribution</option></term> + <listitem> + <para> + Distribution Nix expression which maps services to machines in the network + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--target-property</option></term> + <listitem> + <para> + The target property of an infrastructure model, that specifies how to connect + to the remote Disnix interface. (Defaults to hostname) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--interface</option></term> + <listitem> + <para> + Path to executable that communicates with a Disnix interface. Defaults to + <command>disnix-ssh-client</command>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-p</option>, <option>--profile</option></term> + <listitem> + <para> + Name of the profile that is used for this system. Defaults to: default + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--show-trace</option></term> + <listitem> + <para> + Shows a trace of the output. + </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><option>DISNIX_CLIENT_INTERFACE</option></term> + <listitem> + <para> + Sets the client interface (which defaults to + <command>disnix-ssh-client</command>) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>DISNIX_TARGET_PROPERTY</option></term> + <listitem> + <para> + Sets the target property of an infrastructure model, + that specifies how to connect to the remote Disnix interface. (Defaults to hostname) + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> +</refentry> Added: disnix/disnixos/trunk/doc/manual/disnixos-geninfra.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/disnixos-geninfra.xml Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1,74 @@ +<refentry xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xmlns:xi="http://www.w3.org/2001/XInclude"; + xml:id="sec-disnixos-geninfra"> + + <refmeta> + <refentrytitle>disnixos-geninfra</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">DisnixOS</refmiscinfo> + <refmiscinfo class="version"><xi:include href="version.txt" parse="text" /></refmiscinfo> + </refmeta> + + <refnamediv> + <refname>disnixos-geninfra</refname> + <refpurpose>Generate an infrastructure model from a network model</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>disnixos-geninfra</command> + <arg><replaceable>options</replaceable></arg> + <arg choice="plain"><replaceable>network_expr</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsection> + <title>Description</title> + + <para> + The command <command>disnixos-geninfra</command> generates an infrastructure model + from a network model so that properties of the machines can be used by the + basic Disnix toolset. + </para> + </refsection> + + <refsection> + <title>Options</title> + + <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 socket. + </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>--show-trace</option></term> + <listitem> + <para> + Shows a trace of the output. + </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> +</refentry> Added: disnix/disnixos/trunk/doc/manual/disnixos-genservices.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/disnixos-genservices.xml Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1,68 @@ +<refentry xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xmlns:xi="http://www.w3.org/2001/XInclude"; + xml:id="sec-disnixos-genservices"> + + <refmeta> + <refentrytitle>disnixos-genservices</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">DisnixOS</refmiscinfo> + <refmiscinfo class="version"><xi:include href="version.txt" parse="text" /></refmiscinfo> + </refmeta> + + <refnamediv> + <refname>disnixos-genservices</refname> + <refpurpose>Generate a services model from a network model</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>disnixos-genservices</command> + <arg><replaceable>options</replaceable></arg> + <arg choice="plain"><replaceable>network_expr</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsection> + <title>Description</title> + + <para> + The command <command>disnixos-genservices</command> generates a services model + from a network model so that <command>disnix-manifest</command> can build + a network of NixOS configurations and <command>disnix-distribute</command> + and <command>disnix-activate</command> can distribute and activate the + configurations. + </para> + </refsection> + + <refsection> + <title>Options</title> + + <variablelist> + <varlistentry> + <term><option>--no-out-link</option></term> + <listitem> + <para> + Do not create a 'result' symlink. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--show-trace</option></term> + <listitem> + <para> + Shows a trace of the output. + </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> +</refentry> Added: disnix/disnixos/trunk/doc/manual/disnixos-vm-env.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/disnixos-vm-env.xml Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1,93 @@ +<refentry xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xmlns:xi="http://www.w3.org/2001/XInclude"; + xml:id="sec-disnixos-vm-env"> + + <refmeta> + <refentrytitle>disnixos-vm-env</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">DisnixOS</refmiscinfo> + <refmiscinfo class="version"><xi:include href="version.txt" parse="text" /></refmiscinfo> + </refmeta> + + <refnamediv> + <refname>disnixos-vm-env</refname> + <refpurpose>Deploys and runs a distributed system in a network of Virtual Machines</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>disnixos-vm-env</command> + <arg choice="plain"><option>-s</option> <replaceable>services_expr</replaceable></arg> + <arg choice="plain"><option>-n</option> <replaceable>network_expr</replaceable></arg> + <arg choice="plain"><option>-d</option> <replaceable>distribution_expr</replaceable></arg> + <arg><replaceable>options</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsection> + <title>Description</title> + + <para> + The command <command>disnixos-vm-env</command> is used to generate and launch a network of + virtual machines, closely matching the machine configurations defined in the network model. + This command requires three Nix expressions as input parameters; A services model capturing + the components of a distributed system and its inter-dependencies; A network model capturing + the NixOS configurations of machines in the network and its properties and a distribution model which maps services to machines. + </para> + <para> + By invoking this command it will first build a network of virtual machines, closely matching the + NixOS configurations in the network model. + Then it will build all the services that are defined in the distribution + model from source code including all its dependencies. Finally, it launches the virtual machines + and deploys the system into the virtual network. + </para> + </refsection> + + <refsection> + <title>Options</title> + + <variablelist> + <varlistentry> + <term><option>-s</option>, <option>--services</option></term> + <listitem> + <para> + Services Nix expression which describes all components of the distributed system + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-n</option>, <option>--network</option></term> + <listitem> + <para> + Network Nix expression which captures NixOS configurations of machines in the network + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-d</option>, <option>--distribution</option></term> + <listitem> + <para> + Distribution Nix expression which maps services to machines in the network + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--show-trace</option></term> + <listitem> + <para> + Shows a trace of the output. + </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> +</refentry> Added: disnix/disnixos/trunk/doc/manual/index.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/index.xml Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1,54 @@ +<book xmlns="http://docbook.org/ns/docbook"; + xmlns:xi="http://www.w3.org/2001/XInclude";> + + <info> + <title>DisnixOS User's Guide</title> + + <subtitle>Draft (Version <xi:include href="version.txt" parse="text" />)</subtitle> + + <author> + <personname> + <firstname>Sander</firstname> + <surname>van der Burg</surname> + </personname> + <affiliation> + <orgname>Delft University of Technology</orgname> + <orgdiv>Department of Software Technology</orgdiv> + </affiliation> + <contrib>Author</contrib> + </author> + + <copyright> + <year>2010</year> + <year>2011</year> + <holder>Sander van der Burg</holder> + </copyright> + + <date>January 2011</date> + </info> + + <xi:include href="introduction.xml" /> + <xi:include href="installation.xml" /> + <xi:include href="usage.xml" /> + + <appendix> + <title>Command Reference</title> + + <section> + <title>Main commands</title> + + <xi:include href="disnixos-env.xml" /> + <xi:include href="disnixos-vm-env.xml" /> + </section> + + <section> + <title>Utilities</title> + + <xi:include href="disnix-backdoor-client.xml" /> + <xi:include href="disnixos-deploy-network.xml" /> + <xi:include href="disnixos-geninfra.xml" /> + <xi:include href="disnixos-genservices.xml" /> + <!--<xi:include href="disnixos-gentests.xml" />--> + </section> + </appendix> +</book> Added: disnix/disnixos/trunk/doc/manual/installation.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/installation.xml Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1,114 @@ +<chapter xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xml:id="chap-installation"> + + <title>Installation</title> + + <para> + This chapter explains how DisnixOS can be installed. Except for the basic + <link xlink:href="http://nixos.org/disnix";>Disnix</link> + toolset, only the coordinator machine needs the DisnixOS + exentension tools. + </para> + + <section> + <title>Compiling DisnixOS from source</title> + + <para> + This section explains how to compile DisnixOS from source code. + Usually, this is only needed in special circumstances such as for + development, or trying a new platform. A more convenient way to install + DisnixOS is to use the Nix package manager. + </para> + + <section> + <title>Prerequisites</title> + <para> + In order to build DisnixOS from source code, the following dependencies are required: + Since it is an extension to Disnix, the core Disnix toolset must be installed. Have a look for + installation instructions in the Disnix manual. + Moreover, for network communications, DisnixOS uses + <link xlink:href="http://www.dest-unreach.org/socat";>socat</link>, + which must also be present on the system. + </para> + </section> + + <section> + <title>Compiling DisnixOS</title> + + <para> + After unpacking or checking out the DisnixOS sources, it can be + compiled by executing the following commands: + +<screen> +$ ./configure <replaceable>options...</replaceable> +$ make +$ make install +</screen> + </para> + + <para> + When building from the Subversion repository, these should be + preceded by the command: + +<screen> +$ ./bootstrap +</screen> + </para> + + <para> + The installation path can be specified by passing the + <option>--prefix=<replaceable>prefix</replaceable></option> to + <command>configure</command>. The default installation directory is + <filename>/usr/local</filename>. You can change this to any location + you like. You must have write permission to the + <replaceable>prefix</replaceable> path. + </para> + </section> + </section> + + <section> + <title>Installing by using the Nix package manager</title> + + <para> + The easiest way to use DisnixOS is by installing the DisnixOS package with + the Nix package manager from the + <link xlink:href="http://nixos.org/nixpkgs";>Nixpkgs</link> + repository by typing: + +<screen> +$ nix-env -i disnixos +</screen> + + Another way is downloading the DisnixOS source distribution + and to compile it manually. Moreover, it is also a good thing to have + to basic Disnix toolset in your environment. This can be done by typing: + </para> + +<screen> +$ nix-env -i disnix +</screen> + + <para> + A copy of + <link xlink:href="http://nixos.org/nixpkgs";>Nixpkgs</link> is required + and an environment variable <code>NIXPKGS_ALL</code> must point to the path where + it is installed, so that Disnix is able to find it. On NixOS a copy is + already present and this environment variable has already been configured. + On other systems this variable can be configured by adding the following lines to your + <filename>~/.bash_profile</filename> configuration (or another configuration + file, if you use a different shell): + </para> + +<screen> +$ cat >> ~/.bash_profile <<EOF +# Begin Nixpkgs addition + +NIXPKGS_ALL=/path/to/nixpkgs/pkgs/top-level/all-packages.nix +export NIXPKGS_ALL + +# End Nixpkgs addition +EOF +</screen> + </section> +</chapter> Added: disnix/disnixos/trunk/doc/manual/introduction.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/introduction.xml Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1,66 @@ +<chapter xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xml:id="chap-introduction"> + + <title>Introduction</title> + + <para> + Disnix is a toolset used to perform distributed deployment tasks + and is built on top of Nix; a package manager which has some distinct + features compared to conventional package + managers to make deployment safe and reliable. + </para> + + <para> + The purpose of Disnix is to manage the deployment of distributable + components (or <emphasis>services</emphasis>) in a network of machines. + Disnix, however, does not manage the deployment of the infrastructure itself. Normally, + a system administrator must manually install machines in the network by + following the installation steps of the operating system. Moreover, a system administrator + or developer must also manually write an infrastructure model, matching the + actual configuration of the network in order to correctly deploy a service-oriented + system. + </para> + + <para> + This DisnixOS extension provides complementary infrastructure management tools for Disnix + built on top of + <link xlink:href="http://nixos.org/nixos";>NixOS</link>, + a GNU/Linux distribution built around the Nix package manager. NixOS is a distribution + in which complete system configurations can be built from declarative specifications and + also allows atomic upgrades and rollbacks of complete system architectures. + </para> + + <section> + <title>Features</title> + + <simplesect> + <title>Infrastructure deployment</title> + <para> + DisnixOS allows you to write a network of NixOS configurations in a model and + to automatically deploy the system configurations in a network of machines through + the Disnix interface. + </para> + </simplesect> + + <simplesect> + <title>Infrastructure virtualisation</title> + <para> + DisnixOS uses the virtualisation features of NixOS to build a network of virtual machines + closely matching the real network and automatically deploys the service-oriented system, + so that it can be easily tested by developers. + </para> + </simplesect> + + <simplesect> + <title>Automated testing of a service-oriented system</title> + <para> + DisnixOS uses the virtualisation test techniques (also used for the NixOS + testsuite) to automatically script the deployment and testcases in a distributed + environment, so that a service-oriented system can be automatically tested, and run on + <link xlink:href="http://nixos.org/hydra";>Hydra</link>, + a continuous build and integration server built on top of Nix. + </para> + </simplesect> + </section> +</chapter> Added: disnix/disnixos/trunk/doc/manual/style.css ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/style.css Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1,29 @@ +body +{ + font-family: arial, lucida, helvetica, sans-serif; + font-size: 100%; +} + +h1 +{ + color: #0055aa; + font-size: 170%; +} + +h2 +{ + font-size: 150%; +} + +h3 +{ + font-size: 125%; +} + +pre.screen, pre.programlisting +{ + border-style: solid; + border-width: 1px; + background-color: #dddddd; + padding: 0.5em; +} Added: disnix/disnixos/trunk/doc/manual/usage.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/usage.xml Wed Jan 19 16:16:23 2011 (r25631) @@ -0,0 +1,85 @@ +<chapter xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xml:id="chap-usage"> + + <title>Usage</title> + + <para> + DisnixOS offers some additional features to the basic Disnix toolset, which are shown in this section. + </para> + + <section> + <title>Deploying the infrastructure</title> + <para> + To deploy the NixOS configurations of machines in the network, the following instruction can be used: + </para> + +<screen> +$ disnixos-deploy-network network.nix +</screen> + + </section> + + <section> + <title>Deploying the services and infrastructure at once</title> + + <para> + In order to automatically deploy NixOS configurations in a network machines and the services of + which a distributed system is composed, the following instruction can be used: + </para> + +<screen> +$ disnixos-env -s services.nix -n network.nix -d distribution.nix +</screen> + + <para> + This command is essentially a combination of the <command>nixos-deploy-network</command> (which + deploys the infrastructure and + <command>disnix-env</command> (which deploys the services) commands. + </para> + </section> + + <section> + <title>Deploying a system in a virtual network</title> + + <para> + You can also deploy a system in a network of virtual machines, which is useful for testing: + </para> + +<screen> +$ disnixos-vm-env -s services.nix -n network.nix -d distribution.nix +</screen> + <para> + The <command>disnixos-vm-env</command> command is almost similar to the <command>disnix-env</command> command, + except that it generates and launches a network of virtual machine instances. Moreover, this command + cannot be used to upgrade a system. + </para> + </section> + + <section> + <title>Generating an infrastructure model</title> + + <para> + DisnixOS used a network model instead of an infrastructure model, which the basic Disnix toolset uses. + Esentially, the semantics of these models are quite similar. The <command>disnixos-geninfra</command> + can be used to generate an infrastructure model from the network model: + </para> + +<screen> +$ disnixos-geninfra network.nix +</screen> + + <para> + The output of the tool is the path to the generated infrastructure model. This file can be used by tools in the + basic Disnix toolset. For example: + </para> + +<screen> +$ disnix-collect-garbage $(disnixos-geninfra network.nix) +</screen> + + <para> + The above command runs the Disnix garbage collector on machines defined in the network model. + </para> + </section> +</chapter> Modified: disnix/disnixos/trunk/release.nix ============================================================================== --- disnix/disnixos/trunk/release.nix Wed Jan 19 14:07:51 2011 (r25630) +++ disnix/disnixos/trunk/release.nix Wed Jan 19 16:16:23 2011 (r25631) @@ -16,7 +16,36 @@ src = disnixos; inherit officialRelease; - buildInputs = [ socat pkgconfig disnix ]; + buildInputs = [ socat pkgconfig libxml2 libxslt disnix dblatex tetex nukeReferences ]; + + # Add documentation in the tarball + configureFlags = '' + --with-docbook-rng=${docbook5}/xml/rng/docbook + --with-docbook-xsl=${docbook5_xsl}/xml/xsl/docbook + ''; + + preConfigure = '' + # TeX needs a writable font cache. + export VARTEXFONTS=$TMPDIR/texfonts + ''; + + preDist = '' + make -C doc/manual install prefix=$out + + make -C doc/manual index.pdf prefix=$out + cp doc/manual/index.pdf $out/index.pdf + + # The PDF containes filenames of included graphics (see + # http://www.tug.org/pipermail/pdftex/2007-August/007290.html). + # This causes a retained dependency on dblatex, which Hydra + # doesn't like (the output of the tarball job is distributed + # to Windows and Macs, so there should be no Linux binaries + # in the closure). + nuke-refs $out/index.pdf + + echo "doc-pdf manual $out/index.pdf" >> $out/nix-support/hydra-build-products + echo "doc manual $out/share/doc/disnix/manual" >> $out/nix-support/hydra-build-products + ''; }; build = Modified: disnix/disnixos/trunk/scripts/disnixos-geninfra.in ============================================================================== --- disnix/disnixos/trunk/scripts/disnixos-geninfra.in Wed Jan 19 14:07:51 2011 (r25630) +++ disnix/disnixos/trunk/scripts/disnixos-geninfra.in Wed Jan 19 16:16:23 2011 (r25631) @@ -24,7 +24,7 @@ echo "Options:" echo echo "--no-out-link Do not create a 'result' symlink" - echo "--use-backdoor Indicates that the backdoor must be enabled so that the VMs can be accessed through a UNIX domain socket" + echo "--use-backdoor Indicates that the backdoor must be enabled so that the VMs can be accessed through a socket" echo "--show-trace Shows a trace of the output" echo "-h,--help Shows the usage of this command" } _______________________________________________ nix-commits mailing list [email protected] http://mail.cs.uu.nl/mailman/listinfo/nix-commits
