Changes between Version 6 and Version 7 of ReferenceGuide

Timestamp:

Oct 18, 2012 11:55:56 AM (12 years ago)

Author:

Ted Faber

Comment:

--

ReferenceGuide

@@ -3 +3 @@
 = Reference Guide =
 
-This document describes the details of the commands and data structures that make up the containers system.  The [UserGuide User Guide /Tutotial] provides useful context about the workflows and goals of the system that inform these technical details.
+This document describes the details of the commands and data structures that make up the containers system.  The [UsersGuide User Guide /Tutotial] provides useful context about the workflows and goals of the system that inform these technical details.
 
 == containerize.py ==
@@ -71 +71 @@
 More detailed examples are available in [UsersGuide the tutorial]
 
-
+== container_image.py ==
+
+The {{{container_image.py}}} command draws a picture of the topology of an experiment.  This is helpful in keeping track of how virtual nodes are connected.  {{{containerize.py}}} calls this internally and stores the output in the [ReferenceGuide#Per-ExperimentDirectory per-experiment directory] (unless {{{--no-image}}} is used.
+
+A researcher may call {{{container_image.py}}} directly to generate an image later or to generate one with the partitioning drawn.
+
+The simplest way to call {{{container_image.py}}} is:
+
+{{{
+/share/containers/container_image.py topology.xml output.png
+}}}
+
+The first parameter is a [http://fedd.deterlab.net/wiki.TopDl topdl] description, for example the one in the [ReferenceGuide#Per-ExperimentDirectory per-experiment directory].  The second parameter is the output file for the image.  When drawing an experiment that has been containerized, the {{{--experiment}}} option is very useful.
+
+Options include:
+
+ {{{--experiment=}}}''project''/''experiment''::
+    Draw the experiment in ''project''/''experiment'', if it exists.  Note that this is just DETER experiment and DETER project.  Omit any sub-group.
+ {{{--topo=}}}''filename''::
+    Draw the topology in ''filename'' 
+ {{{--attr-prefix=}}}''prefix''
+    Prefix for containers attributes.  Deprecated.
+ {{{--partitions}}}::
+    Draw labeled boxes around nodes that share a physical node.
+ {{{--out=}}}''filename''::
+    Save the image in ''filename''
+
+If neither {{{--topo}}} nor {{{--experiment}}} is given, the first positional parameter is the topdl topology to draw.  If {{{--out}}} is not given the next positional parameter (the first if {{{--topo}}} nor {{{--experiment}}} is given) is the output file.
+
+A common invocation looks like:
+
+{{{
+/share/containers/container_image.py --experiment SAFER/testbed-containers ~/drawing.png
+}}}
+
+
+== Per-experiment Directory ==
 
 == Site Configuration File ==
@@ -120 +156 @@
 These have no way to log in or work as conventional machines.  Process tree rooted in the startcommand is created, so a service will run with its own view of the network.  It does not have an address on the control net.
 
-Because of a bug in their internal routing, multi-homed processes do not respond correctly 
+Because of a bug in their internal routing, multi-homed processes do not respond correctly for requests on some interfaces.  A ViewOS process does not recognize its other addresses when a packe arrives on a different interface.  A picture makes this clearer:
+
+[[Image(viewos.png)]]
+
+Container A can ping Interface X (10.0.0.1) of the ViewOS container successfully, but if Container A tries to ping Interface Y (10.0.1.2) the ViewOS container will not reply (in fact it will send ARP requests on Interface Y looking for its own address).
+
+ViewOS processes are best used as lightweight forwarders for this reason.
+
+=== Physical Nodes ===
+
+Physical nodes can be incorporated into experiments, but should only use modern versions of Ubuntu, to allow the container system to run their start commands correctly and to initialize their routing tables.
 
 === Interconnections: VDE switches and local networking ===