drl/Manual.txt

   1 Kevin Webb (kcwebb@cs.ucsd.edu)
   2 2009 11 03
   3
   4 --DRL manual--
   5
   6 DRL employs two principal abstractions, limiters and identities.
   7
   8 The primary abstraction provided by DRL is an identity, which represents a
   9 global rate limit and the set of traffic whose enforcement is being coordinated
  10 by that limit.  At any given node, an identity structure consists of a rate
  11 limit, a flow accounting table, a list of neighboring nodes, and other
  12 accounting information.  Our implementation currently supports two types of
  13 identities.  "Machine" identities limit the outgoing rate of all traffic
  14 leaving a machine, regardless of the traffic's sender.  "Set" identities limit
  15 the outgoing rate of some subset of the traffic leaving a machine.  Sets can
  16 contain other sets as well as leaves (which correspond to slivers in
  17 PlanetLab).
  18
  19 A limiter is an entity which contains (and schedules) identities, attributes
  20 packets to identities, and sends and receives messages to other limiters on
  21 behalf of identities.  Typically, there will be only one limiter per node,
  22 and it will be responsible for one or more identities.
  23
  24 -Implementation and configuration-
  25
  26 ulogd_DRL is a plugin for ulogd, the Linux userspace packet logging daemon.
  27 Using DRL requires that two configuration files be configured appropriately.
  28 The first file is ulogd's configuration file.  Ulogd has a number of
  29 configuration options that are not relevant to DRL, and an explanation of those
  30 can be found in the ulogd documentation.  The DRL sections of the ulogd config
  31 file are as follows:
  32
  33 The ulogd_DRL.so plugin must be loaded.  This is accomplished with a line such
  34 as:
  35
  36 plugin="/usr/lib/ulogd/ulogd_DRL.so"
  37
  38 where /usr/lib/ulogd/ is the path of your ulogd plugin directory.  After the
  39 "plugin" line, the following parameters must be present:
  40
  41 [DRL]
  42 nodelimit=0
  43 policy=FPS
  44 estintms=500
  45 drl_logfile="/root/pl1-log"
  46 drl_loglevel 2
  47 drl_configfile="/root/config.xml"
  48
  49 nodelimit specifies a static limit on the amount of network traffic that can be
  50 sent by the node as a whole (megabits/sec).  NOTE: Set this to 0 for unlimited.
  51
  52 policy specifies the allocation and enforcement policy.  Valid options are GRD
  53 and FPS.
  54
  55 estintms is the estimate interval.  This specifies the time interval at which
  56 the limiter will schedule actions for its identities.  Lower values give better
  57 responsiveness but incur higher overhead.  NOTE: this is in milliseconds.
  58 Generally, 500ms works well for FPS.  GRD needs a faster interval, generally
  59 50-100ms.
  60
  61 drl_logfile specifies where the drl logfile should be written.
  62
  63 drl_loglevel specifies the verbosity of logging. 1 - Debug, 2 - Info, 3 -
  64 Critical.  You probably know if you want Debug...  Info logs detailed traffic
  65 rates and protocol state information for producing graphs.  Critical only logs
  66 errors.
  67
  68 drl_configfile specifies the location of the second, DRL-only configuration
  69 file that is used to configure identities (discussed below).
  70
  71 Optionally, the ulogd.conf file can contain:
  72
  73 enforce_on <int>
  74 Whether or not to turn enforcement on by default at startup.  0 for off,
  75 anything else for on.  If unspecified, it defaults to 1.  Enforcement can be
  76 turned on/off at runtime with SIGUSR1.
  77
  78 netem_loss <int>
  79 netem_delay <int>
  80 netem_slice <int|ALL>
  81
  82 These specifiy an artifical packet loss rate (%) or delay (ms) and the slice
  83 xid or the string ALL if it should apply to all slices.  These are useful for
  84 experimentation.
  85
  86
  87 The second file (whose location is determined by drl_configfile) is an XML
  88 file containing a series of DRL identity specifications. Sending the ulogd
  89 process SIGHUP will cause it to re-read this XML config file.  DRL supports
  90 two types of identities.  1) machine identities: A machine identity is
  91 responsible for limiting all traffic that leaves a machine, regardless of the
  92 traffic's sliver of origin.  2) set identities: A set identity is responsible
  93 for limiting the traffic from a set of slivers or other set identities.
  94
  95 The following is an example DRL configuration file:
  96
  97 <?xml version="1.0" encoding="UTF-8"?>
  98 <drl>
  99     <machine id="11" limit="10000" commfabric="MESH" branch="0" accounting="STANDARD" ewma="0.1">
 100         <peer>137.110.222.242</peer>
 101         <peer>137.110.222.243</peer>
 102     </machine>
 103     <set id="20" limit="15000" commfabric="GOSSIP" branch="1" accounting="SAMPLEHOLD" ewma="0.1">
 104         <peer>137.110.222.240</peer>
 105         <xid>1f9</xid>
 106     </set>
 107     <set id="21" limit="25000" commfabric="MESH" branch="0" accounting="STANDARD" ewma="0.1" loop_intervals="2" comm_intervals="4" independent="1">
 108         <peer>137.110.222.245</peer>
 109         <xid>1fa</xid>
 110         <guid>20</guid>
 111     </set>
 112 </drl>
 113
 114 This file creates one machine identity and two set identities.  The resulting
 115 hierarchy would look like this, where 1f9 and 1fa are sliver identifiers:
 116
 117         11
 118         |
 119         21
 120        /  \
 121       20  1fa
 122       |
 123      1f9
 124
 125 With each identity specifier, the following fields must be defined:
 126
 127 id is a globally unique identifier for the identity.
 128
 129 limit is the identity's rate limit (in kilobits per second).
 130
 131 commfabric specifies the way in which the identity communicates with its peers.
 132 Valid options are MESH and GOSSIP.  If GOSSIP is select, the branch field must
 133 be present and positive.
 134
 135 branch specifies the number of peers to which a message should be sent during
 136 each interval.  Note that this field is ignored when commfabric is MESH.
 137
 138 accounting specifies the packet accounting mechanism.  Options are STANDARD,
 139 SAMPLEHOLD, or SIMPLE (GRD only).  Assuming n is the number of flows: Standard
 140 is the most accurate - it tracks all currently active flows and keeps O(n)
 141 state.  Sample&hold uses O(1) state and probabilistically samples packets to
 142 achieve good accuracy.  Simple only tracks aggregate values and uses very
 143 little state.  Simple is perfect for GRD, but useless for FPS.
 144
 145 ewma determines the extent to which rate changes are smoothed using rate
 146 history information.  0.1 is generally a good value.
 147
 148 loop_intervals specifies the number of estimate intervals (defined in the ulogd
 149 config file) to wait between executions of the estimate, allocate, enforce loop
 150 For example, if the estimate interval is 500ms and an identity sets intervals
 151 to 2, the identity will be scheduled for updates once every second.  Assumes 1
 152 if omited.
 153
 154 comm_intervals is similar to loop_intervals, but it schedules communication
 155 with peers.  Assumes 1 if omitted.
 156
 157 Optionally, a set identity can be specified as independent, in which case it
 158 will not be limited by any machine identities on the node.  Assumes 0 if
 159 omitted.
 160
 161 Each identity must also have one or more peers.  Peers are listed within <peer>
 162 tags inside the identity specifier.  In addition to peers, set identities must
 163 also have at least one <xid> or <guid> tag.  <xid> tags refer to slice ids for
 164 slices that are available at the local node.  <guid> tags refer to the globally
 165 unique id of another set identity.
 166
 167
 168
 169 A "real" example:
 170
 171 <?xml version="1.0" encoding="UTF-8"?>
 172 <drl>
 173     <set id="11" limit="10240" commfabric="GOSSIP" branch="2" accounting="STANDARD" ewma="0.1">
 174         <peer>137.110.222.241</peer>
 175         <peer>137.110.222.242</peer>
 176         <peer>137.110.222.243</peer>
 177         <peer>137.110.222.125</peer>
 178         <peer>137.110.222.126</peer>
 179         <peer>137.110.222.127</peer>
 180         <xid>207</xid>
 181     </set>
 182 </drl>
 183
 184 This creates one identity numbered 11 with a 10mbps limit.  It uses a gossip communication protocol to disseminate updates with a branching factor of two.  It uses a standard flow table with an ewma smoothing value of 0.1.  The identity has six peers, and it limits only the traffic associated with the slide whose xid is 207.