drl/Manual.txt

   1 --DRL manual--
   2
   3 DRL employs two principal abstractions, limiters and identities.
   4
   5 An identity is a group of nodes that are cooperating to enforce a rate limit.
   6 At any given node, an identity structure consists of a rate limit, a flow
   7 accounting table, a list of neighboring nodes, and other accounting
   8 information.  Our implementation currently supports two types of identities.
   9 "Machine" identities limit the outgoing rate of all traffic leaving a machine,
  10 regardless of the traffic's sender.  "Set" identities limit the outgoing rate
  11 of some subset of the traffic leaving a machine.  Sets can contain other sets
  12 as well as leaves (which correspond to slivers in PlanetLab).
  13
  14 A limiter is an entity which contains (and schedules) identities, attributes
  15 packets to identities, and sends and receives messages to other limiters on
  16 behalf of identities.  Typically, there will be only one limiter per node,
  17 and it will be responsible for one or more identities.
  18
  19 -Implementation and configuration-
  20
  21 ulogd_DRL is a plugin for ulogd, the Linux userspace packet logging daemon.
  22 Using DRL requires that two configuration files be configured appropriately.
  23 The first file is ulogd's configuration file.  Ulogd has a number of
  24 configuration options that are not relevant to DRL, and an explanation of those
  25 can be found in the ulogd documentation.  The DRL sections of the ulogd config
  26 file are as follows:
  27
  28 The ulogd_DRL.so plugin must be loaded.  This is accomplished with a line such
  29 as:
  30
  31 plugin="/usr/lib/ulogd/ulogd_DRL.so"
  32
  33 where /usr/lib/ulogd/ is the path of your ulogd plugin directory.  After the
  34 "plugin" line, the following parameters must be present:
  35
  36 [DRL]
  37 nodelimit=0
  38 policy=FPS
  39 estintms=500
  40 drl_logfile="/root/pl1-log"
  41 drl_loglevel 2
  42 drl_configfile="/root/config.xml"
  43
  44 nodelimit specifies a static limit on the amount of network traffic that can be
  45 sent by the node (megabits/sec).  NOTE: Set this to 0 for unlimited.
  46
  47 policy specifies the enforcement policy.  Valid options are GRD and FPS.  GRD
  48 is currently broken, so use FPS for now.
  49
  50 estintms is the estimate interval.  This specifies the time interval at which
  51 DRL can schedule identity updates.  Lower values give better responsiveness but
  52 incur higher overhead.  NOTE: this is in milliseconds.
  53
  54 drl_logfile specifies where the drl logfile should be written.
  55
  56 drl_loglevel specifies the verbosity of logging. 1 - Debug, 2 - Warn,
  57 3 - Critical
  58
  59 drl_configfile specifies the location of the second, DRL-only configuration
  60 file.
  61
  62 The second file (whose location is determined by drl_configfile) is an XML file
  63 containing a series of DRL identity specifications.  DRL supports two types of
  64 identities.  1) machine identities: A machine identity is responsible for
  65 limiting all traffic that leaves a machine, regardless of the traffic's sliver
  66 of origin.  2) set identities: A set identity is responsible for limiting the
  67 traffic from a set of slivers or other set identities.
  68
  69 The following is an example DRL configuration file:
  70
  71 <?xml version="1.0" encoding="UTF-8"?>
  72 <drl>
  73     <machine id="11" limit="10" commfabric="MESH" branch="0" accounting="STANDARD" ewma="0.1" intervals="2">
  74         <peer>137.110.222.242</peer>
  75         <peer>137.110.222.243</peer>
  76     </machine>
  77     <set id="20" limit="15" commfabric="GOSSIP" branch="1" accounting="STANDARD" ewma="0.1" intervals="3">
  78         <peer>137.110.222.240</peer>
  79         <xid>1f9</xid>
  80     </set>
  81     <set id="21" limit="25" commfabric="MESH" branch="0" accounting="STANDARD" ewma="0.1" intervals="1">
  82         <peer>137.110.222.245</peer>
  83         <xid>1fa</xid>
  84         <guid>20</guid>
  85     </set>
  86 </drl>
  87
  88 This file creates one machine identity and two set identities.  The resulting
  89 hierarchy would look like this, where 1f9 and 1fa are slivers:
  90
  91         11
  92         |
  93         21
  94        /  \
  95       20  1fa
  96       |
  97      1f9
  98
  99 With each identity specifier, the following fields must be defined:
 100
 101 id is a globally unique identifier for the identity.
 102
 103 limit is the identity's rate limit (in megabits per second).
 104
 105 commfabric specifies the way in which the identity communicates with its peers.
 106 Valid options are MESH and GOSSIP.  If GOSSIP is select, the branch field must
 107 be present and positive.
 108
 109 branch specifies the number of peers to which a message should be sent during
 110 each estimate interval.  Note that this field is ignored when commfabric is
 111 MESH.
 112
 113 accounting specifies the packet accounting mechanism.  Just leave this as
 114 STANDARD for now, or bad things might happen. :)
 115
 116 ewma determines the extent to which rate changes are smoothed using rate
 117 history information.  0.1 is generally a good value.
 118
 119 intervals specifies the number of estimate intervals (defined in the ulogd
 120 config file) to wait between updates.  For example, if the estimate interval is
 121 500ms and an identity sets intervals to 2, the identity will be scheduled for
 122 updates once every second.
 123
 124 Each identity must also have one or more peers.  Peers are listed within <peer>
 125 tags inside the identity specifier.  In addition to peers, set identities must
 126 also have at least one <xid> or <guid> tag.  <xid> tags refer to slice ids for
 127 slices that are available at the local node.  <guid> tags refer to the globally
 128 unique id of another set identity.