Author: sandervanderburg
Date: Sat Sep 11 20:32:23 2010
New Revision: 23738
URL: https://svn.nixos.org/websvn/nix/?rev=23738&sc=1
Log:
Added models section and some minor documentation updates
Added:
disnix/disnix/trunk/doc/manual/browser.png (contents, props changed)
disnix/disnix/trunk/doc/manual/models.xml
disnix/disnix/trunk/doc/manual/stafftracker.dia (contents, props changed)
disnix/disnix/trunk/doc/manual/stafftracker.png (contents, props changed)
Modified:
disnix/disnix/trunk/doc/manual/Makefile.am
disnix/disnix/trunk/doc/manual/installation.xml
disnix/disnix/trunk/doc/manual/manual.xml
disnix/disnix/trunk/doc/manual/overview.xml
Modified: disnix/disnix/trunk/doc/manual/Makefile.am
==============================================================================
--- disnix/disnix/trunk/doc/manual/Makefile.am Sat Sep 11 17:16:42 2010
(r23737)
+++ disnix/disnix/trunk/doc/manual/Makefile.am Sat Sep 11 20:32:23 2010
(r23738)
@@ -13,16 +13,16 @@
-P doc.collab.show=0 \
-P latex.output.revhistory=0
-FIGURES = model.png
+FIGURES = model.png stafftracker.png
-MANUAL_SRCS = manual.xml introduction.xml overview.xml installation.xml
+MANUAL_SRCS = manual.xml introduction.xml overview.xml installation.xml
models.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 $<
+ $(XMLLINT) --noout --nonet --xinclude --noxincludenode --relaxng
$(docbookrng)/docbook.rng $<
touch $@
manual.html: $(MANUAL_SRCS) manual.is-valid
Added: disnix/disnix/trunk/doc/manual/browser.png
==============================================================================
Binary file. No diff available.
Modified: disnix/disnix/trunk/doc/manual/installation.xml
==============================================================================
--- disnix/disnix/trunk/doc/manual/installation.xml Sat Sep 11 17:16:42
2010 (r23737)
+++ disnix/disnix/trunk/doc/manual/installation.xml Sat Sep 11 20:32:23
2010 (r23738)
@@ -1,151 +1,213 @@
<chapter xmlns="http://docbook.org/ns/docbook";
xmlns:xlink="http://www.w3.org/1999/xlink";
- xml:id="chap-introduction">
+ xml:id="chap-installation">
-<title>Installation</title>
+ <title>Installation</title>
-<section>
-<title>Obtaining Disnix</title>
+ <section>
+ <title>Compiling Disnix from source</title>
-<para>
-The easiest way to use Disnix is by installing the Disnix package with
-the Nix package manager from the
-<link xlink:href="http://nixos.org/nixpkgs";>Nixpkgs</link>
-repository by typing:
+ <section>
+ <title>Prerequisites</title>
+ <para>
+ In order to build Disnix from source code, the
following dependencies are required:
+ Disnix uses XML for representing the lower
level data formats and
+ therefore requires
+ <link
xlink:href="http://www.xmlsoft.org";>libxml2</link>
+ and
+ <link
xlink:href="http://www.xmlsoft.org";>libxslt</link>
+ to parse and transform them.
+
+ The Disnix service that provides remote access
to deployment operations
+ is a D-Bus service and requires
+ <link
xlink:href="http://www.freedesktop.org/wiki/Software/DBusBindings";>dbus-glib</link>
+ (which itself depends on
+ <link
xlink:href="http://www.gtk.org";>GLib</link>
+ and
+ <link
xlink:href="http://www.freedesktop.org/wiki/Software/dbus";>D-Bus</link>
+ ).
+
+ Since Disnix is built on top of the
+ <link xlink:href="http://nixos.org/nix";>Nix
package manager</link> it also requires
+ Nix to be installed on the same machine.
+ </para>
+ </section>
+
+ <section>
+ <title>Compiling Disnix</title>
+
+ <para>
+ After unpacking or checking out the Disnix
sources, it can be
+ compiled by executing the following commands:
-<screen>
-$ nix-env -i disnix
-</screen>
-
-Another way is downloading the Disnix source distribution
-and to compile it manually.
-</para>
-
-</section>
-
-<section>
-<title>Prerequisites</title>
-
-<para>
-In order to build Disnix the following dependencies are required
-(only required if Disnix is built from source code):
-Disnix uses XML for representing the lower level data formats and
-therefore requires
-<link xlink:href="http://www.xmlsoft.org";>libxml2</link>
-and
-<link xlink:href="http://www.xmlsoft.org";>libxslt</link>
-to parse and transform them.
-
-The Disnix service that provides remote access to deployment operations
-is a D-Bus service and requires
-<link
xlink:href="http://www.freedesktop.org/wiki/Software/DBusBindings";>dbus-glib</link>
-(which itself depends on
-<link xlink:href="http://www.gtk.org";>GLib</link>
-and
-<link xlink:href="http://www.freedesktop.org/wiki/Software/dbus";>D-Bus</link>
-).
-</para>
-
-<para>
-In order to run a Disnix client, the
-<link xlink:href="http://nixos.org/nix";>Nix package manager</link>
-must be installed, a copy of
-<link xlink:href="http://nixos.org/nixpkgs";>Nixpkgs</link> is required
-and an environment variable NIXPKGS_ALL must point to the path where
-it is installed.
-</para>
-
-<para>
-By default, Disnix includes a SSH client and wrapper that can be used
-to execute remote deployment operations. If you want to use SSH as a
-communication protocol, a
-<link xlink:href="http://www.openssh.org";>OpenSSH</link>
-server must be running on each target machine and a client machine
-requires a OpenSSH client.
-</para>
-
-</section>
-
-<section>
-<title>Compiling Disnix</title>
-
-<para>
-After unpacking or checking out the Disnix sources, it can be
-compiled by executing the following commands:
-
-<screen>
+ <screen>
$ ./configure <replaceable>options...</replaceable>
$ make
$ make install
-</screen>
+ </screen>
+ </para>
-</para>
+ <para>
+ When building from the Subversion repository,
these should be
+ preceded by the command:
-<para>
-When building from the Subversion repository, these should be
-preceded by the command:
-
-<screen>
+ <screen>
$ ./bootstrap
-</screen>
+ </screen>
+ </para>
-</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 the coordinator machine</title>
+
+ <para>
+ The easiest way to use Disnix is by installing the
Disnix package with
+ the Nix package manager from the
+ <link
xlink:href="http://nixos.org/nixpkgs";>Nixpkgs</link>
+ repository by typing:
-<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>
-<title>Running a Disnix service on a target machine</title>
-</section>
-
-<para>
-In order to deploy a distributed system in a network of machines, every
-machine needs to be reachable by the coordinator, in order to perform
deployment
-steps remotely.
-The Disnix service is a service that provides access to these operations
-through a RPC protocol.
-</para>
-
-<para>
-The Disnix service consists of two parts. A core Disnix component which
actually performs
-the deployment operations and a wrapper which exposes the operations to remote
users
-through a RPC protocol (such as the SSH wrapper which is included in the
-Disnix distribution).
-</para>
-
-<para>
-The core Disnix service is a D-Bus service operating on the system bus,
-thus it requires the D-Bus system daemon running.
-Moreover, it also requires the Disnix service configuration file
-(which installed in PREFIX/etc/dbus-1/system.d) in the right location
-so that it is allowed to register itself on the system bus with the right
access permissions
-(on most systems this location is in /etc/dbus-1/system.d).
-</para>
-
-<para>
-Except for the core Disnix service, a protocol wrapper is required that
provides remote
-access to the core service operations through a RPC protocol. A SSH wrapper is
included
-which only requires a OpenSSH server running on the same machine. For other
protocols,
-you have to read the documentation that is included with the extension.
-</para>
-
-<para>
-By default, only users who are members of the group 'disnix' may access
operations
-of the core Disnix service. Thus in order to access the Disnix operations
remotely, either
-an account with the right permissions is required or the protocol wrapper
should perform
-the authentication to the core Disnix service. The OpenSSH wrapper, for
instance,
-uses the credentials of the calling user from the coordinator by default
-and therefore every target machine requires
-the user to be defined in /etc/passwd and the user should be member of
-the 'disnix' group.
-</para>
+ <screen>
+$ nix-env -i disnix
+ </screen>
+ Another way is downloading the Disnix source
distribution
+ and to compile it manually.
+ </para>
+
+ <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 this
+ variable is already defined).
+ </para>
+ </section>
+
+ <section>
+ <title>Installing a target machine</title>
+
+ <para>
+ In order to deploy a distributed system in a network of
machines, every
+ machine needs to be reachable by the coordinator, in
order to perform deployment
+ steps remotely.
+ The Disnix service is a service that provides access to
these operations
+ through a RPC protocol.
+ </para>
+
+ <para>
+ The Disnix service consists of two parts. A core Disnix
component which actually performs
+ the deployment operations and a wrapper which exposes
the operations to remote users
+ through a RPC protocol (such as the SSH wrapper which
is included in the
+ Disnix distribution).
+ </para>
+
+ <para>
+ By default, Disnix includes a SSH client and wrapper
that can be used
+ to execute remote deployment operations. If you want to
use SSH as a
+ communication protocol, a
+ <link xlink:href="http://www.openssh.org";>OpenSSH</link>
+ server must be running on each target machine and a
client machine
+ requires a OpenSSH client.
+ </para>
+
+ <section>
+ <title>Installing a target machine running NixOS</title>
+
+ <para>
+ To enable the Disnix core service on NixOS the
following property
+ must be defined in the
<code>/etc/nixos/configuration.nix</code> file:
+
+ <screen>
+services.disnix.enable = true;
+ </screen>
+
+ In order to use the OpenSSH wrapper, also the
OpenSSH service must
+ be activated in the
<code>/etc/nixos/configuration.nix</code> file:
+
+ <screen>
+services.openssh.enable = true;
+ </screen>
+ </para>
+ </section>
+
+ <section>
+ <title>Installing a target machine manually</title>
+
+ <para>
+ The core Disnix service is a D-Bus service
operating on the system bus,
+ thus it requires the D-Bus system daemon
running.
+ Moreover, it also requires the Disnix service
configuration file
+ (which installed in
<code>PREFIX/etc/dbus-1/system.d</code>) in the right location
+ so that it is allowed to register itself on the
system bus with the right access permissions
+ (on most systems this location is in
<code>/etc/dbus-1/system.d</code>).
+ </para>
+
+ <para>
+ The Disnix service also performs the activation
and deactivation of a service on the machine.
+ Since services can have many forms, such as a
MySQL database, web application or a UNIX process,
+ a Disnix activation scripts package must be
installed, which takes care of these steps for
+ each service type on the given machine. From
the Disnix website, a package for NixOS can
+ be downloaded called
<code>disnix-activation-scripts-nixos</code>, that will also work on
+ most Linux distribution with some configuration
options.
+ For other platforms these modules have to be
adapted so that they will work on that particular
+ type of machine.
+ </para>
+
+ <para>
+ Also the host system must configured to start
the Disnix D-Bus service automatically.
+ In most Linux distributions this can be done by
creating a <code>/etc/init.d/disnix</code>
+ script and configure your distribution so that
it will be launched on system startup.
+ A init.d script for Disnix could look like this:
+ </para>
+
+ <screen>
+#!/bin/bash
+
+source /etc/init.d/functions
+
+case "$1":
+ start)
+ loadproc disnix-service
--activation-scripts-dir=/path/to/activation/scripts
+ ;;
+
+ stop)
+ killproc disnix-service
+ ;;
+
+ restart)
+ $0 stop
+ $0 start
+ ;;
+esac
+ </screen>
+
+ <para>
+ Except for the core Disnix service, a protocol
wrapper is required that provides remote
+ access to the core service operations through a
RPC protocol. A SSH wrapper is included
+ which only requires a OpenSSH server running on
the same machine. For other protocols,
+ you have to read the documentation that is
included with the extension.
+ </para>
+
+ <para>
+ By default, only users who are members of the
group <code>disnix</code> may access operations
+ of the core Disnix service. Thus in order to
access the Disnix operations remotely, either
+ an account with the right permissions is
required or the protocol wrapper should perform
+ the authentication to the core Disnix service.
The OpenSSH wrapper, for instance,
+ uses the credentials of the calling user from
the coordinator by default
+ and therefore every target machine requires
+ the user to be defined in
<code>/etc/passwd</code> and the user should be member of
+ the <code>disnix</code> group.
+ </para>
+ </section>
+ </section>
</chapter>
Modified: disnix/disnix/trunk/doc/manual/manual.xml
==============================================================================
--- disnix/disnix/trunk/doc/manual/manual.xml Sat Sep 11 17:16:42 2010
(r23737)
+++ disnix/disnix/trunk/doc/manual/manual.xml Sat Sep 11 20:32:23 2010
(r23738)
@@ -30,5 +30,6 @@
<xi:include href="introduction.xml" />
<xi:include href="overview.xml" />
- <xi:include href="installation.xml" />
+ <xi:include href="installation.xml" />
+ <xi:include href="models.xml" />
</book>
Added: disnix/disnix/trunk/doc/manual/models.xml
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ disnix/disnix/trunk/doc/manual/models.xml Sat Sep 11 20:32:23 2010
(r23738)
@@ -0,0 +1,58 @@
+<chapter xmlns="http://docbook.org/ns/docbook";
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xml:id="chap-models">
+
+ <title>Writing Disnix models</title>
+
+ <para>
+ In this section we explain how to write models that Disnix can
use to
+ automatically deploy a distributed system into a network of
machines.
+ We use the <code>StaffTracker</code> system as an example for
this.
+ </para>
+
+ <section>
+ <title>Background</title>
+
+ <para>
+ This example is a system which is used to manage staff
of a
+ university. For each staff member, the system can track
+ its zipcode from the staff members' room number.
+ From the zipcode it can determine the address of the
+ building. From the IP address the system can determine
+ the current location from the staff member.
+ All the data repositories are stored in separate
databases.
+ Each data repository can be accessed by a web service.
+ </para>
+ </section>
+
+ <section>
+ <title>Architecture</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="stafftracker.png"
format="PNG"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ The picture above shows the architecture of the
+ <code>StaffTracker</code> system.
+ In the database layer, database components are shown,
+ which store records such as zipcodes and staff members.
+ In the web service layer, web service components are
+ shown, which provide access to the data in de databases
+ (the <code>GeolocationService</code> uses GeoIP to
track a location).
+ In the presentation layer, the <code>StaffTracker</code>
+ web application front-end is shown, which can be
+ used by end users to manage staff of a university.
+ </para>
+
+ <para>
+ All the components shown in the picture are
+ <emphasis>distributable</emphasis> components (or
services).
+ For instance, the <code>GeolocationService</code> can
+ be deployed on a different machine in the network as
+ the <code>StaffTracker</code> web application front-end.
+ </para>
+ </section>
+</chapter>
Modified: disnix/disnix/trunk/doc/manual/overview.xml
==============================================================================
--- disnix/disnix/trunk/doc/manual/overview.xml Sat Sep 11 17:16:42 2010
(r23737)
+++ disnix/disnix/trunk/doc/manual/overview.xml Sat Sep 11 20:32:23 2010
(r23738)
@@ -40,13 +40,11 @@
<para>
By writing instances of the specifications shown above and by running the
following command:
-</para>
-<para>
-<command>disnix-env -s services.nix -i infrastructure.nix -d
distribution.nix</command>
-</para>
+<screen>
+disnix-env -s services.nix -i infrastructure.nix -d distribution.nix
+</screen>
-<para>
All the services that are defined in the distribution model are built from
source code,
then transferred to the machines in the network and finally activated in the
right order.
By adapting one of the models and by running <command>disnix-env</command>
again,
Added: disnix/disnix/trunk/doc/manual/stafftracker.dia
==============================================================================
Binary file. No diff available.
Added: disnix/disnix/trunk/doc/manual/stafftracker.png
==============================================================================
Binary file. No diff available.
_______________________________________________
nix-commits mailing list
[email protected]
http://mail.cs.uu.nl/mailman/listinfo/nix-commits
