|
1 <html> |
|
2 <head> |
|
3 <title> DTN2 Manual: DTN2 Applications </title> |
|
4 <link rel="stylesheet" type="text/css" href="manual.css" /> |
|
5 </head> |
|
6 <body> |
|
7 <h1>DTN2 Applications |
|
8 </h1> |
|
9 |
|
10 <p> |
|
11 In this tutorial, you'll learn how to use the programs in |
|
12 the <tt>apps</tt> directory to send data of various kinds |
|
13 through your DTN. You'll get to see more things happening if you've |
|
14 followed the instructions in <a href="tutorial-3.html"> |
|
15 Building a Bigger DTN</a> first, but even with a standalone |
|
16 dtnd, you can send and receive bundles. |
|
17 |
|
18 <h2> dtnsend and dtnrecv </h2> |
|
19 |
|
20 <p> |
|
21 The most basic tools to send bundles through the DTN network |
|
22 are <a href="man_dtnsend.html">dtnsend</a> and <a href="man_dtnrecv.html">dtnrecv</a>. You can use |
|
23 <a href="man_dtnsend.html">dtnsend</a> to create a bundle and set various options |
|
24 in it. The bundle will move through the DTN until it gets |
|
25 to the destination node. You'll then use <a href="man_dtnrecv.html">dtnrecv</a> |
|
26 to retrieve the bundle out of the final dtnd. |
|
27 |
|
28 <p> |
|
29 First, take a look at the options <a href="man_dtnsend.html">dtnsend</a> takes: |
|
30 |
|
31 <blockquote><pre>$ <font color=blue>DTN2/apps/dtnsend/dtnsend -h</font> |
|
32 usage: dtnsend [opts] -s <source_eid> -d <dest_eid> -t |
|
33 <type> -p <payload> |
|
34 options: |
|
35 -s <eid|demux_string> source eid) |
|
36 -d <eid|demux_string> destination eid) |
|
37 -r <eid|demux_string> reply to eid) |
|
38 -t <f|t|m|d> payload type: file, tmpfile, message, or date |
|
39 -p <filename|string> payload data |
|
40 -e <time> expiration time in seconds (default: one hour) |
|
41 -i <regid> registration id for reply to |
|
42 -n <int> copies of the bundle to send |
|
43 -z <time> msecs to sleep between transmissions |
|
44 -c request custody transfer |
|
45 -C request custody transfer receipts |
|
46 -D request for end-to-end delivery receipt |
|
47 -X request for deletion receipt |
|
48 -R request for bundle reception receipts |
|
49 -F request for bundle forwarding receipts |
|
50 -w wait for bundle status reports |
|
51 -E <int> include extension block and specify type |
|
52 -P <int> flag value(s) to include in extension block |
|
53 -S <string> extension block content |
|
54 </pre></blockquote> |
|
55 |
|
56 <p> |
|
57 To use <a href="man_dtnsend.html">dtnsend</a>, you need to give it a source and |
|
58 destination. Then you tell it what kind of data to send, and |
|
59 where to find it. You may use other command line options to |
|
60 set some optional flags in the bundle. |
|
61 |
|
62 <p> |
|
63 First, let's send in a little test message that we will be |
|
64 able to see inside the daemon, and then will be able to fetch with |
|
65 <a href="man_dtnrecv.html">dtnrecv</a>. |
|
66 |
|
67 <blockquote><pre>$ <font color=blue>DTN2/apps/dtnsend/dtnsend |
|
68 -s dtn://dtn-a.dtn/me |
|
69 -d dtn://dtn-a.dtn/testing |
|
70 -t m -p "testing"</font></pre></blockquote> |
|
71 |
|
72 <p> You can use a command like that, but instead of using the example |
|
73 hostname <i>dtn-a</i>, use the local eid you configured in your |
|
74 dtn.conf file. |
|
75 |
|
76 <p> |
|
77 In the window where dtnd is running, type <a href="configuration.html#Getting a list of pending bundles">bundle list</a>. You should |
|
78 get something like this: |
|
79 |
|
80 <blockquote><pre>dtn% <font color=blue>bundle list</font> |
|
81 Currently Pending Bundles (1): |
|
82 0 : dtn://dtn-a.dtn/me -> dtn://dtn-a.dtn/testing length 7 |
|
83 </pre></blockquote> |
|
84 |
|
85 <p> |
|
86 There's a couple things to note here. First, see how the bundle is |
|
87 shown with length 7? That's what we'd expect, because we sent a |
|
88 payload from the command line of the letters "testing". The bundle |
|
89 consists of <b>exactly</b> those 7 letters. There's no terminating |
|
90 NUL character, nor a newline. Second, notice that our eids now have |
|
91 an extra string on them, in contast to the local eid we set in |
|
92 the configuration file in the first tutorial. It's easiest to think of |
|
93 these as the equivalent of TCP ports. For more details on how |
|
94 addressing works in the DTN world, see the <a href="arch.html"> |
|
95 architecture</a> section of the manual. |
|
96 |
|
97 <p> |
|
98 In another window, go take a look behind the scenes at the |
|
99 directory where you told dtnd to store the bundles in transit. You should |
|
100 find a file there named bundle_0.dat. It should be no surprise by |
|
101 now that this file is 7 bytes long, and contains the string |
|
102 "testing". Generally, you'll never need to do anything with the |
|
103 files in this directory. They are managed by dtnd for you. But |
|
104 it's always nice to have an idea what's going on, so now you know. |
|
105 |
|
106 <p> |
|
107 So now we've gotten a bundle into the system, and the bundle has |
|
108 made it's way across the DTN to its final destination. "Big deal", you |
|
109 say, "the final destination is the same place we put it in!". Ok, |
|
110 you've got a point. But later we'll try something fancier and |
|
111 with some imagination, you'll be able to pretend you've sent a |
|
112 bundle all the way to Mars. Before that though, we've got to get our |
|
113 bundle back out. And for that, we use <a href="man_dtnrecv.html">dtnrecv</a>. |
|
114 |
|
115 <p> |
|
116 The usage of <a href="man_dtnrecv.html">dtnrecv</a> is much easier to remember than |
|
117 that of <a href="man_dtnsend.html">dtnsend</a>. You only need to tell it the name of |
|
118 the endpoint who's bundles you want to pick up. Because |
|
119 <a href="man_dtnrecv.html">dtnrecv</a> cannot pick up bundles from across the DTN, but only |
|
120 on the local node, it's options are much simpler. |
|
121 |
|
122 <blockquote><pre>$ <font color=blue>DTN2/apps/dtnrecv/dtnrecv dtn://dtn-a.dtn/testing</font> |
|
123 dtnrecv (pid 29614) starting up |
|
124 find registration succeeded, regid 0 |
|
125 register succeeded, regid 13 |
|
126 looping forever to receive bundles |
|
127 dtn_recv [dtn://dtn-a.dtn/testing]... |
|
128 7 bytes from [dtn://dtn-a.dtn/me]: transit time=0 ms |
|
129 0000000 7465 7374 696e 67 | testing |
|
130 |
|
131 dtn_recv [dtn://dtn-a.dtn/testing]... |
|
132 <font color=blue>Ctrl-C</font></pre></blockquote> |
|
133 |
|
134 <p> |
|
135 As before, there's a couple of things to note here. First, notice |
|
136 how <a href="man_dtnrecv.html">dtnrecv</a> was able to figure out the local eid for the |
|
137 local dtnd, and them add the argument onto the end to make the |
|
138 complete eid. It did that by asking the local server what its |
|
139 local eid is. The second thing to notice is that the answer |
|
140 did indeed come back correctly. The 7 bytes we put into the DTN |
|
141 with <a href="man_dtnsend.html">dtnsend</a> came back out with <a href="man_dtnrecv.html">dtnrecv</a>. Finally, |
|
142 note that <a href="man_dtnrecv.html">dtnrecv</a> stayed running until we killed it with |
|
143 Ctrl-C. It was waiting for more bundles for that endpoint to arrive. |
|
144 |
|
145 <p> |
|
146 Turn your attention to the window where dtnd is running. Type |
|
147 "bundle list" again and notice that there are no currently |
|
148 pending bundles. Great! The server did it's job and held the |
|
149 bundle until an application registered and requested that |
|
150 bundles for that endpoint get delivered. This is a key difference |
|
151 between sending data with TCP or UDP and sending data over a DTN. |
|
152 In a DTN, every part of the network, from the link protocols up |
|
153 to the applications themselves need to recognize and tolerate |
|
154 delays and disruptions. Typically applications do this by |
|
155 operating asynchronously. Another way applications can operate |
|
156 is by arranging with the DTN bundle router to make a callback |
|
157 to the application when bundles arrive. |
|
158 <i>Stay tuned for a future |
|
159 tutorial showing how that works when I figure it out myself! -jra |
|
160 </i> |
|
161 |
|
162 <h3> Other payload types </h3> |
|
163 |
|
164 <p> In the example above, we used the "-t m" parameter to indicate we |
|
165 wanted to specify the bundle contents from the command line. But what |
|
166 if you wanted to send a movie through a DTN? You'd want to use "-t f" |
|
167 to indicate you are sending a file, then the argument following "-p" |
|
168 will be interpreted as a filename. dtnd will open that file and read |
|
169 it in to fill up the bundle. Be aware that dtnd needs to make a copy |
|
170 of your file and put it in the bundle directory, even if your file is |
|
171 quite big. Once dtnd has gotten another server someplace else in the |
|
172 DTN to take custody of the bundle, it will be deleted from the local |
|
173 server. (However, custody transfer is not currently implemented in DTN2.) |
|
174 |
|
175 <p> |
|
176 The final payload type is "d", for date. When you use this, |
|
177 you do not need -p. A payload consisting of the date is made up |
|
178 automatically for you. This is useful for testing, but not for much |
|
179 else. |
|
180 |
|
181 <h3> Getting a receipt, waiting for it to arrive </h3> |
|
182 |
|
183 <i>To fully understand this section, you should quit and restart your |
|
184 dtnd process, otherwise you will get unexpected results due to state |
|
185 that is not properly cleaned up from the above tests. -demmer</i> |
|
186 |
|
187 <p> |
|
188 If you add the -e and -w options to the <a href="man_dtnsend.html">dtnsend</a> command |
|
189 above, something different happens. The -e argument asks the |
|
190 far end DTN server (in this case, still our local server) to |
|
191 make up a receipt and send it via the DTN back to our reply |
|
192 address. Because we did not use the -r argument to explicitly |
|
193 set a reply address, the receipt will come to the source eid |
|
194 we specified with the -s option. The -w argument tells |
|
195 <a href="man_dtnsend.html">dtnsend</a> to wait for incoming messages to the reply |
|
196 endpoint. So, here's an example of it in action: |
|
197 |
|
198 <blockquote><pre>$ <font color=blue>DTN2/apps/dtnsend/dtnsend -e -w -s dtn://dtn-a.dtn/me |
|
199 -d dtn://dtn-a.dtn/testing |
|
200 -t m -p "testing"</font> |
|
201 got 67 byte report from [dtn://dtn-a.dtn]: time=18893.0 ms |
|
202 </pre></blockquote> |
|
203 |
|
204 <p> |
|
205 18.893 seconds?!? What kind of broken network could possibly take |
|
206 18.893 seconds to deliver a little 7 byte bundle? What's going on here? |
|
207 |
|
208 <p> |
|
209 Well, recall that this is a disruption tolerant network, and that |
|
210 the application on the other end may not have been running at the time |
|
211 we sent the message. In fact it was not. The 18 seconds was how long |
|
212 it took me to find another window and run <a href="man_dtnrecv.html">dtnrecv</a>. (So |
|
213 I type slow. Sue me.) The dtnd server couldn't create and send a |
|
214 receipt until it had delivered the bundle to the final destination, |
|
215 which in this case was the <a href="man_dtnrecv.html">dtnrecv</a> process that I started |
|
216 a few seconds after I ran <a href="man_dtnsend.html">dtnsend</a>. If I'd had my |
|
217 <a href="man_dtnrecv.html">dtnrecv</a> up and running before I ran <a href="man_dtnsend.html">dtnsend</a> the |
|
218 receipt would have arrived in just a few milliseconds. |
|
219 |
|
220 <h2>dtncp and dtncpd</h2> |
|
221 |
|
222 <p> |
|
223 What if you wanted to move a file to another node on the DTN? |
|
224 You've have to have someone logged into that machine ready to run |
|
225 <a href="man_dtnrecv.html">dtnrecv</a> on it. And of course, you can't log in to it, |
|
226 because the other bundle router is on the other side of Mars. |
|
227 And of course, you can't put your buddy there to run the command, |
|
228 because, well, it's on the other side of Mars. What to do? If |
|
229 there was a daemon there listening for bundles arriving on |
|
230 a certain endpoint, and you had a program that could package up |
|
231 local files and send them to the endpoint the far side was |
|
232 waiting on, you could move files! |
|
233 |
|
234 <p> |
|
235 That's exactly how <a href="man_dtncp.html">dtncp</a> and <a href="man_dtncpd.html">dtndcpd</a> work. |
|
236 <a href="man_dtncp.html">dtncp</a> is used to pick up a file from the local |
|
237 filesystem send it as a bundle. |
|
238 <a href="man_dtncpd.html">dtndcpd</a> is the daemon, which would stay running |
|
239 all the time. It registers with the local bundle router |
|
240 requesting a notification when a bundle comes in that was sent |
|
241 by <a href="man_dtncp.html">dtncp</a>. It copies the bundle into an "incoming files" |
|
242 directory. Voila, you've copied a file. |
|
243 |
|
244 <p> |
|
245 You need to run a <a href="man_dtncpd.html">dtndcpd</a> on every node in the |
|
246 network where you want to be able to copy files. If a node |
|
247 is only sending out files, it need not have a <a href="man_dtncpd.html">dtndcpd</a> |
|
248 running. |
|
249 |
|
250 <p> |
|
251 Note that <a href="man_dtncpd.html">dtndcpd</a> is not a general purpose file copy |
|
252 system like <tt>scp</tt>. It can only deposit files into a |
|
253 specific directory. It was written this way because it is an |
|
254 example application, and implementing the security-critical |
|
255 parts of a general file transfer utility were beyond the scope |
|
256 of the example. Likewise, there's no facility to run remote |
|
257 commands on the remote node. It would be possible to add |
|
258 some kind of flag to the bundle contents specifying whether |
|
259 or not to run the received file (and with which arguments). |
|
260 These are all possibilities for bundle applications you might |
|
261 choose to make in the future. |
|
262 |
|
263 <h3> An example </h3> |
|
264 |
|
265 <p> |
|
266 In one window, we get a directory ready for <a href="man_dtncpd.html">dtndcpd</a> |
|
267 to put files into, then start it. <a href="man_dtncpd.html">dtndcpd</a> registers |
|
268 on the endpoint <i>/dtncp/recv:*</i>, then waits for incoming |
|
269 files. |
|
270 |
|
271 <blockquote><pre>$ <font color=blue>mkdir /home/fred/dtn/incoming</font> |
|
272 $ <font color=blue>DTN2/apps/dtncpd/dtncpd /home/fred/dtn/incoming</font> |
|
273 opening connection to dtn router... |
|
274 local_eid [dtn://dtn-a.dtn/dtncp/recv:*] |
|
275 dtn_register succeeded, regid 0xa |
|
276 dtn_recv [dtn://dtn-a.dtn/dtncp/recv:*]... |
|
277 </pre></blockquote> |
|
278 |
|
279 <p> |
|
280 In another window, we copy a file: |
|
281 |
|
282 <blockquote><pre>$ <font color=blue>DTN2/apps/dtncp/dtncp /etc/motd dtn://dtn-a.dtn</font></pre></blockquote> |
|
283 |
|
284 <p> |
|
285 And in the first window, <a href="man_dtncpd.html">dtndcpd</a> says: |
|
286 |
|
287 <blockquote><pre>====================================== |
|
288 File Received at Sun Mar 6 01:03:24 2005 |
|
289 |
|
290 region : internet |
|
291 host : dtn-a |
|
292 path : |
|
293 file : motd |
|
294 size : 960 bytes |
|
295 loc : /home/fred/dtn/incoming/dtn-a//passwd</pre></blockquote> |
|
296 |
|
297 <p> |
|
298 You may also give <a href="man_dtncp.html">dtncp</a> a third argument, which will |
|
299 be the filename on the far side. The default, if you neglect |
|
300 to provide this argument, is to make the far side file have the |
|
301 same name as the local file. |
|
302 |
|
303 <h3> Wildcard endpoints </h3> |
|
304 |
|
305 <p> |
|
306 The DTN2 implementation treats <b>*</b> (asterisk) as a |
|
307 special character in endpoints. The asterisk denotes |
|
308 that any endpoint that matches the prefix before the asterix |
|
309 will match that endpoint. <a href="man_dtncpd.html">dtndcpd</a> uses a wildcard |
|
310 endpoint to be able to match the endpoints that <a href="man_dtncp.html">dtncp</a> |
|
311 makes by adding the desired remote filename onto the end of |
|
312 the first part of the endpoint string, <i>/dtncp/recv:</i>. |
|
313 |
|
314 </body> |
|
315 </html> |
|
316 |