Mercurial Mercurial > code > sail > DTN2-BPQ / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/manual/tutorial-1.html
changeset 0 2b3e5ec03512 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/tutorial-1.html	Thu Apr 21 14:57:45 2011 +0100
@@ -0,0 +1,297 @@
+<html>
+<head>
+<title> DTN2 Manual: Starting dtnd and sending a ping </title>
+<link rel="stylesheet" type="text/css" href="manual.css" />
+</head>
+<body>
+<h1>Starting dtnd and sending a ping
+</h1>
+
+<p>
+In this tutorial, you'll learn how to configure and start an instance
+of dtnd, then make it answer a ping.
+
+<h2> Configuration </h2>
+
+<p>
+In this section, we'll prepare an appropriate <tt>dtn.conf</tt>
+file for our instance of dtnd.
+
+<h3> Directories </h3>
+
+<p>
+First, you need to choose a directory that will hold the files dtnd
+needs. For the purposes of this tutorial, we'll assume your username
+is <tt>fred</tt> and that you want dtnd to write into
+<tt>/home/fred/dtn</tt>.
+
+<p> Make the <tt>/home/fred/dtn</tt> directory, then copy the example
+<tt>dtn.conf</tt> file from <tt>DTN2/daemon/dtn.conf</tt> to
+<tt>/home/fred/dtn/dtn.conf</tt>. Edit the <tt>dtn.conf</tt> file. For
+this tutorial, we'll use the simplest database to configure,
+BerkeleyDB. Leave the <i>storage set type berkeleydb</i> line alone.
+Set the <i>payloaddir</i> to <tt>/home/fred/dtn/bundles</tt> and set
+the <i>dbdir</i> to <tt>/home/fred/dtn/db</tt>.
+
+<p> The <i>dbdir</i> directory is where persistent objects that DTN2 uses to
+manage its internal state live. This database will remain fairly small. It
+needs to be preserved between invocations of the DTN2 daemon, because
+the data in it lets DTN2 know the status of registrations with
+clients, and bundles which are in flight in the network. One of the
+"disruptions" that a DTN is tolerant of is the failure of a node.
+Using the data in the database, a new DTN2 daemon can carry on the
+work the previous one was doing. But note that if the contents of the
+database are lost, it is as if this node never existed, and there will
+be repercussions in the DTN (like retransmissions of bundles) as a
+result.
+
+<p> The <i>payload</i> directory is where bundles which are in-flight
+live. In general, the bundles in this directory are ones which this
+DTN2 instance has custody of. That means that if they disappear out of
+this directory, they will be lost forever, since there are no other
+authoritative copies of the bundle in the network. DTN2 and the DTN
+protocols are designed to maintain the files in this directory without
+leaving old ones lying around. If you see an old file there, it's
+likely due to a bug. Please help us get to the bottom of what's causing it.
+Unlike packets, which are typically quite small (from 50 to 64,000
+bytes), a single bundle can be very large (over 2 gigabytes).
+On a server dedicated to
+running DTN2, your payload directory should have access to the largest
+partition on your server. As an analogy, on a mail server the mail
+spool is usually on /var, and has access to the majority of the extra
+disk space on a machine. The same should be true for the payload
+directory.
+
+<h3>Using TCL in the Config File</h3>
+
+<p> You don't need to make any changes in the <i>local_eid</i>, but
+scroll down and take a look at it anyway. In the defualt
+configuration, it looks like this: <i>route local_eid
+"dtn://[info hostname].dtn"</i>. Note the square
+brackets. To understand what's happening here, you need to know that
+this configuration file is not simply a file of settings for dtnd, but
+an actual <a href="http://www.tcl.tk">TCL</a> script. It is interpreted by
+the TCL interpreter that is built in to dtnd. In TCL, square brackets
+mean "interpret this first, and replace the brackets with the result".
+So before dtnd sees a <i>route local_eid ...</i> command, TCL
+processes the <i>info hostname</i> command. As you might be able to
+guess by now, the entire line results in the <i>local_eid</i> being
+set to a custom string based on your hostname.
+
+<p> This is the only place in this particular configuration file where
+we will use TCL features like the square brackets. However, you should
+remember that all the power of TCL is available to you as you write
+your own configuration files, should you desire it. For an example of
+this, see <a href="configuration.html#rotate">the example showing how
+to rotate logs</a> from within dtnd.
+
+<p> So the local EID is set, but what is it? From the
+<a href="arch.html">Architecture</a> section, you should recall
+that nodes in the DTN are identified by EIDs. The local EID
+is simply the way our DTN node will refer to itself. Without this
+setting, it would not recognize bundles intended for it, and might
+just pass them on ad infinitum! People who have configured Internet
+email systems like Postfix or Sendmail might recognize this setting,
+as mail routers need to know their own name for the same reason.
+
+<p>
+And EID is a string that is used throughout the DTN to identify
+an endpoint. That leaves you considerable latitude on how to set
+it. We recommend for now that you set it according to the
+machine name where the DTN node is running, as the example does.
+
+<p>
+At this time, one dtnd can have only one local EID. This
+limitation might disappear in future versions if it proves to be a
+problem.
+
+<h3> Interfaces </h3>
+
+<p>
+Take a look at the <i>interface add</i> commands a few lines
+down. The command <i>interface add tcp0 tcp</i> adds a
+TCP convergence layer named <i>tcp0</i> to the server. This
+means that the daemon will start listening on port 4556 for incoming
+connections from other servers in the DTN.
+
+<p>Usually DTN nodes that are communicating via
+TCP listen on port 4556, based on the IANA port assignment.
+If you have another application on the same server listening on
+port 4556, you'll need to choose a different port for your dtnd
+to use. 
+
+<p> The <i>interface add</i> command can take convergence layer
+specific arguments to customize the behavior of the interface.
+For the purposes of this tutorial,
+we will be using the defaults. For more information on these arguments
+see the reference pages on the <a href="configuration.html#cls">various
+convergence layers</a>.
+
+<p> In some security contexts, and with some virtual interface
+configurations, it is desirable to have dtnd listen only on a certain
+interface, for instance "listen to internal connections only".
+You can do this by adding <i>local_addr=desired-ip</i> to the end of
+the <i>interface add</i> command. The default <i>local_addr</i>
+is 0.0.0.0, meaning "listen on all interfaces".
+For this tutorial, we will allow dtnd to listen on all
+interfaces, so leave the <i>interface add</i> command as it is.
+
+<p> Note that we are adding an interface of type TCP. There are other
+ways that DTN nodes can communicate, including via UDP, raw
+ethernet frames, and across a filesystem
+(where some external activity, like a messenger with a USB keychain
+drive, is responsible for moving the files). A server that is
+using multiple convergence layers
+has other <i>interface add</i> lines in the configuration file.
+
+<p>
+In fact, below the <i>interface add</i> line for the TCP convergence
+layer is one for the UDP covergence layer. Because we are setting up
+a standalone server in this tutorial, neither <i>udp0</i> nor
+<i>tcp0</i> will end up getting used to move bundles at this point.
+
+<h3> Links and Routes </h3>
+
+<p>
+Because in this tutorial, we are setting up a standalone dtnd,
+we will not need any <tt>link</tt> or <tt>route</tt> statements.
+You'll end up with a Disruption Tolerant Network made up of
+only one daemon. Not much to brag about, but out of simple
+beginnings come great things!
+
+<h2> Initializing the Database </h2>
+
+<p>
+Before dtnd can use the database to keep track of runtime state,
+it needs to initialize it. This is a simple matter of starting
+the daemon once with the <tt>--init-db</tt> argument. You'll
+also want to give it the location of the configuration file, so
+that dtnd can find the correct database directory. Put that together
+and you have:
+
+<blockquote><pre>$ <font color=blue>daemon/dtnd -c /home/fred/dtn/dtn.conf --init-db </font>
+[1178218919.248562 /dtnd notice] random seed is 248552
+[1178218919.248660 /dtnd notice] DTN daemon starting up... (pid 3268)
+[1178218919.263195 /dtnd notice] initializing persistent data store
+[1178218919.263343 /dtn/storage notice] creating new database directory /var/tmp/dtn/db
+[1178218921.130742 /dtnd notice] closing persistent data store
+</pre>
+</blockquote>
+
+<h2> Running the Daemon </h2>
+
+<p>
+For now, you start dtnd from the commandline, like any other
+Unix command. By default, the TCL interpreter takes input from
+standard in, so you will need to leave it running in the foreground. While
+you are learning the ins and outs of dtnd, it is best to run it
+this way, so that you can interact with it. Use the <tt>-c</tt>
+argument to tell it where to find the configuration file.
+For information on other arguments you can give dtnd, see
+the <a href="man/dtnd.html">dtnd man page</a>.
+
+<p>
+Once you start dtnd with a command like <tt>DTN2/daemon/dtnd -c
+/home/fred/dtn/dtn.conf</tt>, it will put out some messages, then
+give you the <tt>dtn%</tt> prompt. This means the server is up
+and running, awaiting commands from you. Things you type at the
+prompt are interpreted by the same TCL interpreter that just parsed
+the configuration file. In a way, you can consider the configuration
+file a list of commands that will be issued for you
+each time you start the server.
+
+<p>
+Here's an example of starting up the server:
+
+<blockquote><pre>$ <font color=blue>daemon/dtnd -c /home/fred/dtn/dtn.conf</font>
+[1178218965.919630 /dtnd notice] random seed is 919621
+[1178218965.919725 /dtnd notice] DTN daemon starting up... (pid 3271)
+[1178218965.943359 /dtn/bundle/daemon notice] loading bundles from data store
+zabar dtn% 
+</pre></blockquote>
+
+<p>
+You get a bit more info if you start up with the '-l info argument':
+
+<blockquote><pre>$ <font color=blue>daemon/dtnd -c /home/fred/dtn/dtn.conf -l info</font>
+[1178219015.034268 /dtnd notice] random seed is 34259
+[1178219015.034621 /dtnd notice] DTN daemon starting up... (pid 3272)
+[1178219015.046752 /dtnd info] parsing configuration file daemon/dtn.conf...
+[1178219015.047142 /dtnd info] dtnd parsing configuration...
+[1178219015.047716 /dtn/interface/table info] adding interface tcp0 (tcp)
+[1178219015.048082 /dtn/interface/table info] adding interface udp0 (udp)
+[1178219015.048606 /dtnd info] dtnd configuration parsing complete
+[1178219015.048853 /dtn/storage info] initializing db name=DTN (not shared), dir=/var/tmp/dtn/db
+[1178219015.054478 /dtn/storage info] datastore /var/tmp/dtn/db was cleanly shut down
+[1178219015.057959 /dtn/bundle/daemon info] REGISTRATION_ADDED 0 dtn://zabar.research.intel-research.net.dtn
+[1178219015.058144 /dtn/bundle/daemon info] REGISTRATION_ADDED 2 dtn://zabar.research.intel-research.net.dtn/ping
+[1178219015.058309 /dtn/bundle/daemon notice] loading bundles from data store
+[1178219015.557741 /dtnd info] starting console on 127.0.0.1:5050
+zabar dtn% 
+</pre></blockquote>
+
+<p>
+Use the online help system to learn what you can do from here. Type
+<b>help</b>. For help on a specific command, type <b>help
+<i>command</i></b>. For now, though, you don't need to use any
+commands. Just let dtnd run in its own window. When we start talking
+to dtnd with an application you'll see log messages in the window
+where dtnd is running.
+
+<h2> Pinging the daemon </h2>
+
+<p>
+A Disruption Tolerant Network is made up of a number of
+servers whose job is to move bundles through the system.
+But where do the bundles come from? They come from applications.
+In the future, you can expect to see applications to move
+scientific data, web pages, e-mail, and other data that
+needs to traverse a network region prone to disruption.
+For now though, the best way to see your new DTN (consisting
+of just your one server) operate is to send a ping bundle into
+to it, and see what comes back out!
+
+<p>
+To ping your server, run the <tt>dtnping</tt> command. It lives
+in the <tt>DTN2/apps/dtnping</tt> directory. You'll need to give it
+one argument, which is the EID address of the endpoint that you
+want to ping. Since there is only one server in your DTN, the
+choice should be simple. You need to use the local EID
+that you set in the configuration file. If you'd like to
+check what dtnd thinks it's local EID name is, use the
+<tt>registration list</tt> command in the window where dtnd is running.
+The first registration is always the server registering it's own
+EID with itself, so that it can handle administrative bundles, like
+the ping bundle we are about to send.
+
+<p>
+Alternatively, <tt>dtnping</tt> contains a convenience shortcut
+whereby the string 'localhost' is interpreted as the local EID
+of the daemon.
+
+<p>
+Here's an example of how to ping a server who's local EID
+is <i>dtn://dtn-a.dtn</i>:
+
+<blockquote><pre>$ <font color=blue>./dtnping localhost</font>
+source_eid [dtn://zabar.research.intel-research.net.dtn/ping.3310]
+dtn_register succeeded, regid 10
+PING [dtn://zabar.research.intel-research.net.dtn/ping]...
+20 bytes from [dtn://zabar.research.intel-research.net.dtn/ping]: 'dtnping!' seqno=0, time=212 ms
+20 bytes from [dtn://zabar.research.intel-research.net.dtn/ping]: 'dtnping!' seqno=1, time=297 ms
+<font color=blue>Ctrl-C</font></pre></blockquote>
+
+<h2> What next? </h2>
+
+<p>
+You've set up a standalone dtnd and pinged it. From here, you
+can explore two directions. In the <a href="tutorial-2.html">
+DTN2 applications</a> tutorial, you can learn how to use the other
+applications that come with DTN2 to interact with your new little
+DTN. In the <a href="tutorial-3.html">building a bigger DTN</a>
+tutorial, you can see how to use links to make several nodes work
+together as part of a bigger DTN.
+
+</body>
+</html>
+
DTN2-BPQ