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:
host1and host2) at your
disposal;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.
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)
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.
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.
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.
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.
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.
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.