Author: sandervanderburg Date: Wed Jan 19 22:01:01 2011 New Revision: 25636 URL: https://svn.nixos.org/websvn/nix/?rev=25636&sc=1
Log: Some manual tweaks and additions Added: disnix/disnixos/trunk/doc/manual/background.xml disnix/disnixos/trunk/doc/manual/disnixos-gentests.xml Modified: disnix/disnixos/trunk/doc/manual/Makefile.am disnix/disnixos/trunk/doc/manual/disnix-backdoor-client.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/usage.xml disnix/disnixos/trunk/release.nix Modified: disnix/disnixos/trunk/doc/manual/Makefile.am ============================================================================== --- disnix/disnixos/trunk/doc/manual/Makefile.am Wed Jan 19 21:48:05 2011 (r25635) +++ disnix/disnixos/trunk/doc/manual/Makefile.am Wed Jan 19 22:01:01 2011 (r25636) @@ -14,12 +14,12 @@ -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 +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 \ +MANUAL_SRCS = index.xml introduction.xml background.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 \ + disnixos-geninfra.xml disnixos-genservices.xml disnixos-gentests.xml \ $(man1_MANS:.1=.xml) version.txt: Added: disnix/disnixos/trunk/doc/manual/background.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/background.xml Wed Jan 19 22:01:01 2011 (r25636) @@ -0,0 +1,167 @@ +<chapter xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xml:id="chap-background"> + + <title>Background</title> + + <para> + <link xlink:href="http://nixos.org/nixos";>NixOS</link> + is a GNU/Linux distribution, which uses the Nix package manager to manage + all packages, system components (such as the Linux kernel) and configuration files. + In NixOS, system configurations are derived from declarative specifications describing + properties of the system, such as kernel modules, partitions, services and + system packages. + </para> + + <example xml:id="ex-1-nixos-configuration"> + <title>A NixOS configuration running a OpenSSH server</title> +<programlisting> +{pkgs, ...}: <co xml:id='co-1-functionHeader' /> + +{ + boot = { <co xml:id='co-2-boot' /> + loader = { + grub = { + device = "/dev/sda"; + }; + }; + }; + + fileSystems = [ <co xml:id='co-3-filesystems' /> + { mountPoint = "/"; + device = "/dev/sda2"; + } + ]; + + swapDevices = [ + { device = "/dev/sda1"; } + ]; + + services = { <co xml:id='co-4-services' /> + openssh = { + enable = true; + }; + }; + + environment = { <co xml:id='co-5-environment' /> + systemPackages = [ + pkgs.mc + pkgs.subversion + pkgs.lynx + ]; + }; +} +</programlisting> + </example> + + <para> + <xref linkend="ex-1-nixos-configuration" /> shows a Nix expression describing the configuration + of a machine. + </para> + + <calloutlist> + <callout arearefs='co-1-functionHeader'> + <para> + This line states that the expression is a function, having + an argument called <varname>pkgs</varname>, which refers to + <link xlink:href="http://nixos.org/nixpkgs";>Nixpkgs</link>, + a collection of 2500 packages which can be deployed + by the Nix package manager. + </para> + </callout> + + <callout arearefs='co-2-boot'> + <para> + This section of the NixOS specifcation describes the settings + of the GRUB bootloader, such as that the partition containing + the MBR is <filename>/dev/sda</filename>. + </para> + </callout> + + <callout arearefs='co-3-filesystems'> + <para> + This section of the NixOS specifcation describes the settings + of hard drive partitions, such as the root partition and the + swap partition. + </para> + </callout> + + <callout arearefs='co-4-services'> + <para> + This section of the NixOS specifcation describes the services + running on the system, such as the OpenSSH server providing + remote SSH access. + </para> + </callout> + + <callout arearefs='co-5-environment'> + <para> + This section of the NixOS specifcation describes the system packages, + which can be used by all users on the machines, such as the + Lynx web browser and Midnight Commander. + </para> + </callout> + </calloutlist> + + <para> + The specification in <xref linkend="ex-1-nixos-configuration" /> can be stored in the + at <filename>/etc/nixos/configuration.nix</filename> and + the complete configuration can be built from source code and activated by running: + </para> + +<screen> +$ nixos-rebuild switch +</screen> + + <para> + NixOS configurations can also be used in an attributeset, describing a network + of machines: + </para> + + <example xml:id="ex-2-network"> + <title>A network of NixOS configurations</title> +<programlisting> +{ + test1 = import ../configurations/openssh.nix; <co xml:id='co-1-openssh' /> + test2 = import ../configurations/tomcat.nix; <co xml:id='co-2-tomcat' /> + test3 = import ../configurations/httpd.nix; +} +</programlisting> + </example> + + <para> + <xref linkend="ex-2-network" /> shows a network of NixOS configurations. Basically, this + expression is an attribute set in which each attribute refers to a NixOS configuration: + </para> + + <calloutlist> + <callout arearefs='co-1-openssh'> + <para> + This attribute declares that we have a machine with identifier + <varname>test1</varname>, having a configuration running a OpenSSH server, + described earlier in <xref linkend="ex-1-nixos-configuration" />. + </para> + </callout> + <callout arearefs='co-2-tomcat'> + <para> + This attribute declares that we have a machine with identifier + <varname>test2</varname>, having a configuration running an Apache Tomcat server. + </para> + </callout> + </calloutlist> + + <para> + By typing the following instruction on the command line, the network of machines are built + from source code, distributed to the target machines and finally activated: + </para> + +<screen> +$ nixos-deploy-network network.nix +</screen> + + <para> + Disnix is a toolset supporting the deployment of services. DisnixOS combines the latter feature + of using <command>nixos-deploy-network</command> to deploy networks of NixOS machines, + as addition to Disnix to provide infrastructure deployment. + </para> +</chapter> Modified: disnix/disnixos/trunk/doc/manual/disnix-backdoor-client.xml ============================================================================== --- disnix/disnixos/trunk/doc/manual/disnix-backdoor-client.xml Wed Jan 19 21:48:05 2011 (r25635) +++ disnix/disnixos/trunk/doc/manual/disnix-backdoor-client.xml Wed Jan 19 22:01:01 2011 (r25636) @@ -31,7 +31,7 @@ <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. + <link linkend="sec-disnixos-vm-env"><command>disnixos-vm-env</command></link> 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 Modified: disnix/disnixos/trunk/doc/manual/disnixos-env.xml ============================================================================== --- disnix/disnixos/trunk/doc/manual/disnixos-env.xml Wed Jan 19 21:48:05 2011 (r25635) +++ disnix/disnixos/trunk/doc/manual/disnixos-env.xml Wed Jan 19 22:01:01 2011 (r25636) @@ -50,8 +50,9 @@ 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 + This command is essentially a composition of the + <link linkend="sec-disnixos-deploy-network"><command>disnixos-deploy-network</command></link> + command (which deploys the infrastructure) and <command>disnix-env</command> (which deploys the services of which the system is composed). </para> </refsection> Modified: disnix/disnixos/trunk/doc/manual/disnixos-geninfra.xml ============================================================================== --- disnix/disnixos/trunk/doc/manual/disnixos-geninfra.xml Wed Jan 19 21:48:05 2011 (r25635) +++ disnix/disnixos/trunk/doc/manual/disnixos-geninfra.xml Wed Jan 19 22:01:01 2011 (r25636) @@ -28,7 +28,7 @@ <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 + from a network model, so that properties of the machines can be used by the basic Disnix toolset. </para> </refsection> Modified: disnix/disnixos/trunk/doc/manual/disnixos-genservices.xml ============================================================================== --- disnix/disnixos/trunk/doc/manual/disnixos-genservices.xml Wed Jan 19 21:48:05 2011 (r25635) +++ disnix/disnixos/trunk/doc/manual/disnixos-genservices.xml Wed Jan 19 22:01:01 2011 (r25636) @@ -28,7 +28,7 @@ <para> The command <command>disnixos-genservices</command> generates a services model - from a network model so that <command>disnix-manifest</command> can build + from a network model, referring to actual system derivations 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. Added: disnix/disnixos/trunk/doc/manual/disnixos-gentests.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/disnixos/trunk/doc/manual/disnixos-gentests.xml Wed Jan 19 22:01:01 2011 (r25636) @@ -0,0 +1,67 @@ +<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-gentests"> + + <refmeta> + <refentrytitle>disnixos-gentests</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">DisnixOS</refmiscinfo> + <refmiscinfo class="version"><xi:include href="version.txt" parse="text" /></refmiscinfo> + </refmeta> + + <refnamediv> + <refname>disnixos-gentests</refname> + <refpurpose>Generate initalialization steps of the test suite</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>disnixos-gentests</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-gentests</command> generates a part + of the testsuite that starts the backdoors on the machines in the + network and deploys the services in the network of machines, + by invoking <command>disnix-activate</command>. + </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> Modified: disnix/disnixos/trunk/doc/manual/disnixos-vm-env.xml ============================================================================== --- disnix/disnixos/trunk/doc/manual/disnixos-vm-env.xml Wed Jan 19 21:48:05 2011 (r25635) +++ disnix/disnixos/trunk/doc/manual/disnixos-vm-env.xml Wed Jan 19 22:01:01 2011 (r25636) @@ -36,7 +36,7 @@ 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 + 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 Modified: disnix/disnixos/trunk/doc/manual/index.xml ============================================================================== --- disnix/disnixos/trunk/doc/manual/index.xml Wed Jan 19 21:48:05 2011 (r25635) +++ disnix/disnixos/trunk/doc/manual/index.xml Wed Jan 19 22:01:01 2011 (r25636) @@ -28,6 +28,7 @@ </info> <xi:include href="introduction.xml" /> + <xi:include href="background.xml" /> <xi:include href="installation.xml" /> <xi:include href="usage.xml" /> @@ -48,7 +49,7 @@ <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" />--> + <xi:include href="disnixos-gentests.xml" /> </section> </appendix> </book> Modified: disnix/disnixos/trunk/doc/manual/installation.xml ============================================================================== --- disnix/disnixos/trunk/doc/manual/installation.xml Wed Jan 19 21:48:05 2011 (r25635) +++ disnix/disnixos/trunk/doc/manual/installation.xml Wed Jan 19 22:01:01 2011 (r25636) @@ -25,9 +25,11 @@ <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 + Since it is an extension to + <link xlink:href="http://nixos.org/disnix";>Disnix</link>, + the core Disnix toolset must be installed. Have a look for installation instructions in the Disnix manual. - Moreover, for network communications, DisnixOS uses + Moreover, for network communication, DisnixOS uses <link xlink:href="http://www.dest-unreach.org/socat";>socat</link>, which must also be present on the system. </para> @@ -68,7 +70,7 @@ </section> <section> - <title>Installing by using the Nix package manager</title> + <title>Installing DisnixOS by using the Nix package manager</title> <para> The easiest way to use DisnixOS is by installing the DisnixOS package with @@ -93,7 +95,7 @@ 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 + it is installed, so that Disnix is able to find it. In 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 Modified: disnix/disnixos/trunk/doc/manual/introduction.xml ============================================================================== --- disnix/disnixos/trunk/doc/manual/introduction.xml Wed Jan 19 21:48:05 2011 (r25635) +++ disnix/disnixos/trunk/doc/manual/introduction.xml Wed Jan 19 22:01:01 2011 (r25636) @@ -19,7 +19,7 @@ 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. + system, which is sometimes a lot of work and error prone. </para> <para> @@ -28,7 +28,7 @@ <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. + also allows atomic upgrades and rollbacks of complete system configurations. </para> <section> @@ -47,16 +47,16 @@ <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. + closely matching the actual network and automatically deploys the service-oriented system + in the virtual network, 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 + DisnixOS uses the virtualisation test techniques, 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. Modified: disnix/disnixos/trunk/doc/manual/usage.xml ============================================================================== --- disnix/disnixos/trunk/doc/manual/usage.xml Wed Jan 19 21:48:05 2011 (r25635) +++ disnix/disnixos/trunk/doc/manual/usage.xml Wed Jan 19 22:01:01 2011 (r25636) @@ -18,6 +18,10 @@ $ disnixos-deploy-network network.nix </screen> + <para> + By executing the command above, all the system configurations are built from the NixOS specifications, + then distributed to the machines in the network and finally activated. + </para> </section> <section> @@ -34,7 +38,7 @@ <para> This command is essentially a combination of the <command>nixos-deploy-network</command> (which - deploys the infrastructure and + deploys the infrastructure) and <command>disnix-env</command> (which deploys the services) commands. </para> </section> @@ -43,7 +47,8 @@ <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: + You can also deploy a system in a network of virtual machines, which is useful for testing. + This can be done by executing the following instruction: </para> <screen> @@ -60,7 +65,7 @@ <title>Generating an infrastructure model</title> <para> - DisnixOS used a network model instead of an infrastructure model, which the basic Disnix toolset uses. + DisnixOS uses 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> Modified: disnix/disnixos/trunk/release.nix ============================================================================== --- disnix/disnixos/trunk/release.nix Wed Jan 19 21:48:05 2011 (r25635) +++ disnix/disnixos/trunk/release.nix Wed Jan 19 22:01:01 2011 (r25636) @@ -44,7 +44,7 @@ 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 + echo "doc manual $out/share/doc/disnixos/manual" >> $out/nix-support/hydra-build-products ''; }; _______________________________________________ nix-commits mailing list [email protected] http://mail.cs.uu.nl/mailman/listinfo/nix-commits
