DoDWAN   Documentation Download About

Using DoDWAN: a step by step tutorial

Preamble

DoDWAN implements a content-based epidemic dissemination model. This means that content disseminates among DoDWAN nodes epidemic-wise, but each node can however determine what kind of content it is willing to receive from other nodes.

Content is sent in the network by being published, and content is received selectively from the network according to subscriptions.

This short tutorial shows how DoDWAN can be used on a couple of Linux hosts to share content between these hosts.

In the following we assume that:

  1. you have at least two Linux hosts (host1and host2) at your disposal;
  2. these hosts belong to the same wired or wireless LAN;
  3. multicast traffic is enabled on these hosts.

We also assume that DoDWAN has been installed on each of these hosts. If that is not the case yet, please refer to the installation procedure.

Starting DoDWAN nodes

Start DoDWAN on each Linux device you plan to use:

host1$ dodwan.sh start

host2$ dodwan.sh start

If you're wondering if DoDWAN is running on a host, just check its status. For example on host1:

host1$ dodwan.sh status

If you're curious about what's happening once DoDWAN is running on a host, you can have a look at the log file it produces. By default log files are saved in directory /dev/shm/${USER}/dodwan/var/node/${HOSTNAME}/log, and a new log file is created every time DoDWAN is (re)started on a host.

The command below allows you to display the log events produced by the current execution on host1:

host1$ tail -f /dev/shm/${USER}/dodwan/var/node/${HOSTNAME}/log/*
       (Use Ctrl-C to terminate)

Publishing content (on host1)

Publishing content is straightforward::

host1$ echo "Let us pretend this is jazz music" > /tmp/file1.mp3
host1$ dodwan.sh publish type=music,style=jazz /tmp/file1.mp3

With this command host1 publishes a message whose payload is the content of file.mp3. This message includes a descriptor that characterizes its content, based on a sequence of attributes expressed as name=value pairs. In that case the descriptor indicates that the payload if of type=music, and this music is of style=jazz.

Note that in this example there is no indication about what user --or what host-- is the destination of this content. This is because the epidemic dissemination model is inherently appropriate to push content toward whoever --or whatever-- is interested.

When a message is published on a DoDWAN node, it is first saved in a local cache maintained by this node. It will only be transferred to other nodes when these nodes indicate that they are interested in this type of content.

Receiving content (on host2)

By default, a DoDWAN node is not willing to receive any content from any other node. In other words, its interest profile is empty.

In order to update the interest profile of a host, you must set a subscription on this host. A subscription is identified by a key, that can be used to remove the subscription after a while. It defines an interest pattern, and optionally an action to perform when content matching this pattern is received.

host2$ mkdir /tmp/myMusic
host2$ dodwan.sh subscribe myMusicPrefs "type=music,style=(jazz|classical)" -d /tmp/myMusic

In this example a subscription is set on host2. This subscription is identified by key myMusicPrefs. Its pattern indicates that host2is willing to receive any message whose descriptor contains attribute type=music AND attribute style=jazz OR style=classical. As you can see a pattern is basically a sequence of name=value pairs, just like a descriptor, except that the value field can contain regular expressions. The action to be performed when host2 receives content that matches this pattern is that the payload of the message should be saved in directory /tmp/myMusic.

Since the content published earlier by host1 matches the new interest profile of host2, this content should be transferred between both hosts as soon as the subscription is set. You can observe the result of this transfer by having a look at directory /tmp/myMusic on host2:

host2$ ls /tmp/myMusic
host1_file1.mp3

Note that the name of the file created on host2 is slightly different from that of the original file: a prefix has been appended in the file name, indicating which DoDWAN node has published this content.

By running the command below in a terminal, you'll be able to see new files appear in directory /tmp/myMusic:

host2$ watch -n 1 ls /tmp/myMusic

You can now publish other files on host1, and see if they are received by host2:

host1$ echo "Let us pretend this is classical music" > /tmp/file2.mp3
host1$ dodwan.sh publish type=music,style=classical /tmp/file2.mp3
host1$ echo "Let us pretend this is Rock\'n Roll music" > /tmp/file3.mp3
host1$ dodwan.sh publish type=music,style=rocknroll /tmp/file2.mp3

You should observe that file2 is received by host2, and deposited in /tmp/myMusic, but file3 is not. This is because, according to the subscription set on host2, this host is willing to receive jazz or classical music, but not Rock'n roll music.

Altruistic behavior

With the subscription set on host2, this host can so far only receive and store in its local cache content that matches the pattern defined in subscription myMusicPrefs. In other words host2 can only receive content it --or rather its user-- is interested in.

But a DoDWAN node can also behave as an opportunistic carrier for content it is not directly interested in, but that it is however willing to receive, store, and later forward to other nodes:

host2$ dodwan.sh subscribe anyMusic "type=music"

With this new subscription set on host2, this host can receive any kind of music. Note that this subscription does not replace the first one: it comes as an addition to myMusicPrefs. Besides, in this additional subscription there is no indication of an action to perform when content matching its pattern is received. This content will therefore be simply stored in the local cache.

With the combination of both subscriptions, host2 is now willing to receive any music file. This content will in any case be stored in the local cache, but jazz or classical music will additionally be deposited in directory /tmp/myMusic, as requested by myMusicPrefs. Any music content stored by host2 in its cache can be transferred to other interested nodes, hence the notion of altruistic behavior: host2 becomes an altruistic carrier for any kind of music content, even though its user only wishes to listen to jazz or classical music.

When subscription patterns overlap partially (as is the case with myMusicPrefs and anyMusic that both pertain to music), this does not mean that the same content will be received several times by a DoDWAN node. DoDWAN ensures that content is delivered once and once only to a node, even if several subscriptions on that node pertain to that content.

Content persistency

By default the local cache maintained by each DoDWAN node is saved in the filesystem. If you wish to have a look, this should be in /dev/shm/${USER}/dodwan/var/node/${HOSTNAME}/cache. Please do not delete files manually from this directory while DoDWAN is running.

When a node is stopped for a while, and then started again, its cache is re-initialized based on what is stored in the filesystem, so the node does not have to reacquire from other nodes some content it has already acquired in the past.

Removing subscriptions

Assume host2 does not wish to have jazz and classical music deposited in /tmp/myMusic anymore. Subscription myMusicPrefs can easily be removed:

host2$ dodwan.sh unsubscribe myMusicPrefs

With myMusicPrefs removed, host2 will continue to receive music files (because of subscription anyMusic), but these files will not be deposited in /tmp/myMusic).

In order not to receive any music on host2, subscription anyMusic should be removed as well:

host2$ dodwan.sh unsubscribe anyMusic

Once both subscriptions have been removed on host2, this host may still contain in its local cache some music it has received earlier because of these subscriptions. This content is still available on host2, which can therefore transfer it to other interested nodes.

Stopping DoDWAN nodes (and flushing their cache)

host1$ dodwan.sh stop ; dodwan.sh clear

host2$ dodwan.sh stop ; dodwan.sh clear

Flushing the cache of a node is only necessary if you want to start a node with a "clean slate". By default DoDWAN maintains a persistent cache, so any content stored in the filesystem is still available when you re-start a DoDWAN node.