libdessert0.87-dev 0.87.2-1.1 / usr / share / doc / libdessert0.87-dev / html / main.html

This file is indexed.

/usr/share/doc/libdessert0.87-dev/html/main.html is in libdessert0.87-dev 0.87.2-1.1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>DES-SERT - A Simple and Extensible Routing Framework for Testbeds: DES-SERT</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.2 -->
<div class="navigation" id="top">
  <div class="tabs">
    <ul>
      <li class="current"><a href="main.html"><span>Main&nbsp;Page</span></a></li>
      <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div class="contents">
<h1>DES-SERT </h1><h3 class="version">0.87.1 </h3><h2><a class="anchor" id="intro_sec">
Introduction</a></h2>
<p>DES-SERT, the DES Simple and Extensible Routing-Framework for Testbeds, is a framework designed to assist researchers implementing routing protocols for testbeds.</p>
<p>DES-SERT enables the implementation of routing protocols on top of Ethernet via an underlay (Layer 2.5) in user space. It introduces an abstraction from OS specific issues and provides functionality and data structures to implement proactive, reactive, and hybrid routing protocols.</p>
<p>While generally usable in many application scenarios, it is primarily used in DES-Mesh (<a href="http://www.des-testbed.net/">http://www.des-testbed.net/</a>), the multi-transceiver wireless mesh network testbed part of the DES-Testbed at Freie Universitaet Berlin, Germany.</p>
<h2><a class="anchor" id="arch_sec">
DES-SERT Architecture</a></h2>
<p>DES-SERT introduces some concepts to implement routing protocols. When implementing a routing protocol with DES-SERT, you should be familiar with these concepts to structure and tailor your implementation.</p>
<h3><a class="anchor" id="messages_subsec">
DES-SERT Messages</a></h3>
<p>Every packet you send or receive on the mesh is represented as a DES-SERT message. From a programmers point of view, a DES-SERT message is just a C-structure:</p>
<div class="fragment"><pre class="fragment"> <span class="keyword">typedef</span> <span class="keyword">struct </span>__attribute__ ((__packed__)) <a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg</a> {
    <span class="keyword">struct     </span>ether_header l2h;
    <span class="keywordtype">char</span>       proto[<a class="code" href="group__global.html#ga1fa8816abb158565a7a23de9877e4249" title="length of protocol string used in dessert_msg">DESSERT_PROTO_STRLEN</a>];
    uint8_t    ver;
    uint8_t    flags;
    <span class="keyword">union </span>{
            uint32_t u32;
            <span class="keyword">struct </span>__attribute__ ((__packed__)) {
                uint8_t    ttl;
                uint8_t    u8;
                uint16_t   u16;
            };
    };
    uint16_t   hlen;
    uint16_t   plen;
 } <a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a>;
</pre></div><p>Every message sent via the underlay carries this structure as a packet header. All data in a "dessert_msg" is stored in network byte order. DES-SERT tries to care as automatically as possible of this structure. Nevertheless you will have to care at least about: "l2h.ether_dhost" and "ttl".</p>
<p>If you need to send some data along with every packet, e.g. some kind of metric or cost your routing protocol uses, you should try to fit this data into the "u8", "u16" and the upper 4 bits of the "flags" field. These fields will never be touched by DES-SERT except on initialization via "dessert_msg_new".</p>
<p>Because just a C-structure is not really usable as a packet, there are some utility functions around - please have a look around in "dessert.h" and the doxygen documentation. The most important ones are: "dessert_msg_new" and "dessert_msg_destroy", which do not simply allocate memory for a DES-SERT message, but for a whole packet of maximum size and initialize the structures for further packet construction/processing.</p>
<div class="fragment"><pre class="fragment">    <span class="keywordtype">int</span> <a class="code" href="group__msg.html#ga9a58534c56c6d5bba349178b00f5df2c" title="creates a new dessert_msg_t and initializes it.">dessert_msg_new</a>(<a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a> **msgout);

    <span class="keywordtype">void</span> <a class="code" href="group__msg.html#ga07a7fbeec245d9f997021e7c7aabffe5" title="free a dessert_msg">dessert_msg_destroy</a>(<a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a>* msg);
</pre></div><h3><a class="anchor" id="extensions_subsec">
DES-SERT Extensions</a></h3>
<p>A DES-SERT extension is some structure used to piggyback data on a DES-SERT message. It consists of a 8-bit user supplied type field (with some reserved values), an 8-bit length field and user supplied data of arbitrary length of 253 bytes at most.</p>
<p>It can be added to a message via <a class="el" href="group__msg.html#gac1fa7dd6d73701eea3a1b9a734b69093" title="add an extension record to a dessert_msg">dessert_msg_addext()</a>, retrieved via <a class="el" href="group__msg.html#ga36014dbdcc5597ada3d4b23e104f4bb0" title="get an specific or all extensions">dessert_msg_getext()</a> and removed via <a class="el" href="group__msg.html#ga68c273b9e1712604ae54b59f89b0712e" title="remove an extension record from a dessert_msg">dessert_msg_delext()</a>.</p>
<div class="fragment"><pre class="fragment">    <span class="keywordtype">int</span> <a class="code" href="group__msg.html#gac1fa7dd6d73701eea3a1b9a734b69093" title="add an extension record to a dessert_msg">dessert_msg_addext</a>(<a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a>* msg, <a class="code" href="structdessert__ext.html" title="a extension record to add to a dessert_msg">dessert_ext_t</a>** ext,
                        uint8_t type, <span class="keywordtype">size_t</span> len);

    <span class="keywordtype">int</span> <a class="code" href="group__msg.html#ga68c273b9e1712604ae54b59f89b0712e" title="remove an extension record from a dessert_msg">dessert_msg_delext</a>(<a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a> *msg, <a class="code" href="structdessert__ext.html" title="a extension record to add to a dessert_msg">dessert_ext_t</a> *ext);

    <span class="keywordtype">int</span> <a class="code" href="group__msg.html#ga36014dbdcc5597ada3d4b23e104f4bb0" title="get an specific or all extensions">dessert_msg_getext</a>(<span class="keyword">const</span> <a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a>* msg, <a class="code" href="structdessert__ext.html" title="a extension record to add to a dessert_msg">dessert_ext_t</a>** ext,
                        uint8_t type, <span class="keywordtype">int</span> index);
</pre></div><p>It is recommended not to put single data fields in extensions, but combine semantically related data in a struct and attach this struct as an extension because every extension carried introduces an 16-bit overhead to the packet.</p>
<h3><a class="anchor" id="pipelines_subsec">
Processing Pipelines</a></h3>
<p>Routing algorithms are often split up in several parts like packet validation, loop-detection or routing table lookup. To implement these as independent and clear as possible, DES-SERT enables you to split up your packet processing in as many parts as you like.</p>
<p>There are two separate processing pipelines - one for packets received from the kernel via a TUN or TAP interface and one for packets received via an interface used on the mesh network.</p>
<p>You can register callbacks to be added to one of these pipelines with "dessert_sysrxcb_add" or "dessert_meshrxcb_add". Both take an additional integer argument ("priority") specifying the order the callbacks should be called. Higher "priority" value results in being called later within the pipeline.</p>
<div class="fragment"><pre class="fragment">    <span class="keywordtype">int</span> <a class="code" href="group__sys.html#ga3e9b0a0ce49597c62e519f1721225803" title="adds a callback function to call if a packet should be injected into dessert via...">dessert_sysrxcb_add</a>(<a class="code" href="group__global.html#ga85d7968d07d0e597654c5930c64f37fd" title="Callback type to call if a packed should be injected into dessert via a tun/tap interface...">dessert_sysrxcb_t</a>* c, <span class="keywordtype">int</span> prio);

    <span class="keywordtype">int</span> <a class="code" href="group__mesh.html#gaec6c2bbd7b63aa29235a80f9ecc86a6c" title="Adds a callback function to the meshrx pipeline.">dessert_meshrxcb_add</a>(<a class="code" href="group__global.html#ga6936046e5222e0a9296780eab531cbd9" title="Callback type to call if a packed is received via a dessert mesh interface.">dessert_meshrxcb_t</a>* c, <span class="keywordtype">int</span> prio);
</pre></div><p>If a callback returns "DESSERT_MSG_KEEP" the packed will be processed by further callbacks, if it returns "DESSERT_MSG_DROP" the message will be dropped and no further callbacks will be called.</p>
<p>You do not need to care about the management of the buffers for incoming messages - DES-SERT does this for you. Nevertheless if you need to add extensions or enlarge the payload of a message, you need to tell DES-SERT to enlarge the buffer for you if the flag "DESSERT_FLAG_SPARSE" is set on the message. You can do this by returning "DESSERT_MSG_NEEDNOSPARSE" from within a callback. The callback will be called again with a larger buffer and no "DESSERT_FLAG_SPARSE" flag being set.</p>
<h3><a class="anchor" id="buffer_subsec">
Processing Buffer</a></h3>
<p>If you need to pass information along several callbacks, you can do this in the processing buffer passed to the the callbacks. This buffer contains some local processing flags ("lflags") set by the builtin callback "dessert_msg_ifaceflags_cb" (e.g. telling you about packet origin or if the packet is multicast) and 1KB of space for your callbacks to pass along arbitrary data.</p>
<p>This buffer might only be allocated after you explicitly request it - in this case the proc argument is NULL and you can return the value "DESSERT_MSG_NEEDMSGPROC" from within your callback. The callback will be called again with a valid processing buffer.</p>
<h2><a class="anchor" id="interfaces_sec">
Using Interfaces</a></h2>
<h3><a class="anchor" id="sysif_subsec">
Using a TUN/TAP interface</a></h3>
<p>First you have to choose whether to use a TUN or TAP interface. TUN interfaces are used to exchange IPv4 / IPv6 datagrams with the kernel network stack. TAP interfaces are used to exchange Ethernet frames with the kernel network stack. If you want to route Ethernet frames, you should choose a TAP interface. If you intend to implement a custom layer 2 to layer 3 mapping, you should use a TUN interface.</p>
<p>Currently, you can only initialize and use a single sys (TUN/TAP) interface. This is done by "dessert_sysif_init". You must then set up the interface config in the kernel yourself e.g. by calling "ifconfig".</p>
<div class="fragment"><pre class="fragment">    <span class="keywordtype">int</span> <a class="code" href="group__sys.html#ga47fac5a4a5b28a150ddf774f92814188" title="Initializes the tun/tap Interface dev for des-sert.">dessert_sysif_init</a>(<span class="keywordtype">char</span>* name, uint8_t flags);
</pre></div><p>In either case, frames you receive from a TUN/TAP interface will be passed along the callbacks added by "dessert_sysrxcb_add" to the processing pipeline. Each of them will be called with a pointer to an Ethernet frame. In case of a TUN interface, "ether_shost" and "ether_dhost" are set to "00:00:00:00:00:00", and ether_type reflects whether the packet received is IPv4 oder IPv6.</p>
<p>Packets are sent to the kernel network stack with "dessert_syssend". In case of a TUN Interface "ether_shost" and "ether_dhost" will be ignored.</p>
<div class="fragment"><pre class="fragment">    <span class="keywordtype">int</span> <a class="code" href="group__sys.html#gac134e7a61bdee1ae6d6a8c1114180f15" title="sends a packet via tun/tap interface to the kernel">dessert_syssend_msg</a>(<a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a> *msg);

    <span class="keywordtype">int</span> <a class="code" href="group__sys.html#ga4a69d48f1f2f8e1425d1ec8b3be3226c" title="sends a packet via tun/tap interface to the kernel">dessert_syssend</a>(<span class="keyword">const</span> <span class="keyword">struct</span> ether_header *eth, <span class="keywordtype">size_t</span> len);
</pre></div><h3><a class="anchor" id="meshif_subsec">
Using a Mesh Interface</a></h3>
<p>Mesh interfaces are used similar to the TUN/TAP interface with two major differences: You can have multiple mesh interfaces and they send and receive DES-SERT messages instead of Ethernet frames.</p>
<p>You add an mesh interface using "dessert_meshif_add" and can send to it by calling "dessert_meshsend". If the interface parameter is NULL, the packet will be transmitted over every interface (good for flooding).</p>
<div class="fragment"><pre class="fragment">    <span class="keywordtype">int</span> <a class="code" href="group__mesh.html#ga58e1c127ee23b780717c468f4643677e" title="Initializes given mesh interface, starts up the packet processor thread.">dessert_meshif_add</a>(<span class="keyword">const</span> <span class="keywordtype">char</span>* dev, uint8_t flags);


    <span class="keywordtype">int</span> <a class="code" href="group__mesh.html#ga4b6a065d39419e4a0baf353186a5482d" title="Sends a dessert message via the specified interface or all interfaces.">dessert_meshsend</a>(<span class="keyword">const</span> <a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a>* msgin,
                    <span class="keyword">const</span> <a class="code" href="structdessert__meshif.html" title="an interface used for dessert_msg frames">dessert_meshif_t</a> *iface);

    <span class="keywordtype">int</span> <a class="code" href="group__mesh.html#ga0b75a2f325b65d6c602e759f05d2da4b" title="Sends a dessert message via the interface which is identified by the given hardware...">dessert_meshsend_hwaddr</a>(<span class="keyword">const</span> <a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a>* msgin,
                    <span class="keyword">const</span> uint8_t hwaddr[ETHER_ADDR_LEN]);

    <span class="keywordtype">int</span> <a class="code" href="group__mesh.html#ga3e0576fe29eff23611fba86bbef1971f" title="Sends a dessert message via all interfaces, except via the specified interface.">dessert_meshsend_allbutone</a>(<span class="keyword">const</span> <a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a>* msgin,
                    <span class="keyword">const</span> <a class="code" href="structdessert__meshif.html" title="an interface used for dessert_msg frames">dessert_meshif_t</a> *iface);

    <span class="keywordtype">int</span> <a class="code" href="group__mesh.html#ga16f52ad209a9d5885c61f320da3e8118" title="Sends a dessert message fast via the specified interface or all interfaces.">dessert_meshsend_fast</a>(<a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a>* msg,
                    <span class="keyword">const</span> <a class="code" href="structdessert__meshif.html" title="an interface used for dessert_msg frames">dessert_meshif_t</a> *iface);

    <span class="keywordtype">int</span> <a class="code" href="group__mesh.html#gad7ff09f7d63c4ff2d9669f88fbe12f12" title="Sends a dessert message fast via the interface specified by the given hardware address...">dessert_meshsend_fast_hwaddr</a>(<a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a>* msg,
                    <span class="keyword">const</span> uint8_t hwaddr[ETHER_ADDR_LEN]);

    <span class="keywordtype">int</span> <a class="code" href="group__mesh.html#gaa93f48da25750346bc75ed224874b389" title="Sends a dessert message fast via all interfaces, except the specified interface.">dessert_meshsend_fast_allbutone</a>(<a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a>* msg,
                    <span class="keyword">const</span> <a class="code" href="structdessert__meshif.html" title="an interface used for dessert_msg frames">dessert_meshif_t</a> *iface);

    <span class="keywordtype">int</span> <a class="code" href="group__mesh.html#ga35180b7a994a3763a05790fd1a19ffc7" title="Sends a dessert message msg via the specified interface iface or all interfaces.">dessert_meshsend_raw</a>(<a class="code" href="structdessert__msg.html" title="A basic message send on des-sert layer2.5.">dessert_msg_t</a>* msg,
                    <span class="keyword">const</span> <a class="code" href="structdessert__meshif.html" title="an interface used for dessert_msg frames">dessert_meshif_t</a> *iface);
</pre></div><h2><a class="anchor" id="logging_sec">
Logging</a></h2>
<p>You can write log messages easily with a bunch of macros provided by DES-SERT ("dessert_debug", "dessert_info" ,"dessert_notice", "dessert_warn", "dessert_warning", "dessert_err", "dessert_crit", "dessert_alert" and "dessert_emerg"). Each of them can be used like "printf" and logs to Syslog, STDERR, file or a ringbuffer depending on your configuration.</p>
<p>DES-SERT also ships with a custom "assert" macro which acts like the original macro from the standard C library and uses the logging mechanism described above.</p>
<h2><a class="anchor" id="periodics_sec">
Periodics</a></h2>
<p>Periodics help you to perform maintenance or delayed tasks. A task consists of a callback, which will be called at the time you requested, and a void pointer the callback is passed. You can add these tasks by calling "dessert_periodic_add" or "dessert_periodic_add_delayed".</p>
<h2><a class="anchor" id="cli_sec">
CLI - Command Line Interface</a></h2>
<p>DES-SERT supports simple configuration and debugging of your routing protocol implementation by providing a Cisco like command line interface (cli) and a config file parser based upon it. This cli is realized through libcli (<a href="http://code.google.com/p/libcli/">http://code.google.com/p/libcli/</a>).</p>
<p>DES-SERT does some of the initialization of libcli. Therefore, it provides the main cli anchor "dessert_cli" and some anchors to add commands below "dessert_cli_.*". Because DES-SERT only loosely wraps libcli, you should make yourself familiar with libcli itself. This may be improved in further DES-SERT releases.</p>
<p>You can evaluate a config file by calling "cli_file" and start a thread enabling a telnet-interface for DES-SERT by calling "dessert_cli_run".</p>
<h2><a class="anchor" id="all_sec">
Putting it all together</a></h2>
<p>Now you have learned about the most important aspects of DES-SERT. To write your own routing protocol implementation, you need to know how to put all this together.</p>
<p>You should start with a main() program parsing the command line options and then calling "dessert_init()". This is needed to set up DES-SERT correctly. Afterwards you can register callbacks, read the config file and do what you like. If everything is set up, you call "dessert_run()" and let the event based framework do its job.</p>
<p>If you would like to see a complete protocol implementation sample, have a look at the "gossiping" directory.</p>
<h2><a class="anchor" id="feedback_sec">
Contact &amp; Feedback</a></h2>
<p>We love feedback - if you have patches, comments or questions, please contact us! Recent contact information is available on <a href="http://www.des-testbed.net/des-sert/">http://www.des-testbed.net/des-sert/</a> </p>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated by&nbsp;
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.2 </small></address>
</body>
</html>

APT Browse - Built by Thomas Orozco.