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.  DRL will
  62 reopen the logfile when it receives SIGHUP.
  63
  64 drl_loglevel specifies the verbosity of logging. 1 - Debug, 2 - Info, 3 -
  65 Critical.  You probably know if you want Debug...  Info logs detailed traffic
  66 rates and protocol state information for producing graphs.  Critical only logs
  67 errors.
  68
  69 drl_configfile specifies the location of the second, DRL-only configuration
  70 file that is used to configure identities (discussed below).
  71
  72 Optionally, the ulogd.conf file can contain:
  73
  74 create_htb <int>
  75 Whether or not ulogd should rebuild the htb hierarchy (when using FPS). 0 will
  76 not rebuild it, any other value will.  Set this to zero when the hierarchy is
  77 managed externally (for instance, by PlanetLab's node manager).  When this is
  78 set to 0, identities require htb_node and htb_parent properties in the drl xml
  79 config.
  80
  81 enforce_on <int>
  82 Whether or not to turn enforcement on by default at startup.  0 for off,
  83 anything else for on.  If unspecified, it defaults to 1.  Enforcement can be
  84 turned on/off at runtime with SIGUSR1.
  85
  86 netem_loss <int>
  87 netem_delay <int>
  88 netem_slice <int|ALL>
  89
  90 These specifiy an artifical packet loss rate (%) or delay (ms) and the slice
  91 xid or the string ALL if it should apply to all slices.  These are useful for
  92 experimentation.
  93
  94 The second file (whose location is determined by drl_configfile) is an XML
  95 file containing a series of DRL identity specifications. Sending the ulogd
  96 process SIGUSR2 will cause it to re-read this XML config file.  DRL supports
  97 two types of identities.  1) machine identities: A machine identity is
  98 responsible for limiting all traffic that leaves a machine, regardless of the
  99 traffic's sliver of origin.  2) set identities: A set identity is responsible
 100 for limiting the traffic from a set of slivers or other set identities.
 101
 102 The following is an example DRL configuration file:
 103
 104 <?xml version="1.0" encoding="UTF-8"?>
 105 <drl>
 106     <machine id="11" limit="10000" commfabric="MESH" branch="0" accounting="STANDARD" ewma="0.1">
 107         <peer>137.110.222.242</peer>
 108         <peer>137.110.222.243</peer>
 109     </machine>
 110     <set id="20" limit="15000" commfabric="GOSSIP" branch="1" accounting="SAMPLEHOLD" ewma="0.1">
 111         <peer>137.110.222.240</peer>
 112         <xid>1f9</xid>
 113     </set>
 114     <set id="21" limit="25000" commfabric="MESH" branch="0" accounting="STANDARD" ewma="0.1" loop_intervals="2" comm_intervals="4" independent="1">
 115         <peer>137.110.222.245</peer>
 116         <xid>1fa</xid>
 117         <guid>20</guid>
 118     </set>
 119 </drl>
 120
 121 This file creates one machine identity and two set identities.  The resulting
 122 hierarchy would look like this, where 1f9 and 1fa are sliver identifiers:
 123
 124         11
 125         |
 126         21
 127        /  \
 128       20  1fa
 129       |
 130      1f9
 131
 132 With each identity specifier, the following fields must be defined:
 133
 134 id is a globally unique identifier for the identity.
 135
 136 limit is the identity's rate limit (in kilobits per second).
 137
 138 commfabric specifies the way in which the identity communicates with its peers.
 139 Valid options are MESH and GOSSIP.  If GOSSIP is select, the branch field must
 140 be present and positive.
 141
 142 branch specifies the number of peers to which a message should be sent during
 143 each interval.  Note that this field is ignored when commfabric is MESH.
 144
 145 accounting specifies the packet accounting mechanism.  Options are STANDARD,
 146 SAMPLEHOLD, or SIMPLE (GRD only).  Assuming n is the number of flows: Standard
 147 is the most accurate - it tracks all currently active flows and keeps O(n)
 148 state.  Sample&hold uses O(1) state and probabilistically samples packets to
 149 achieve good accuracy.  Simple only tracks aggregate values and uses very
 150 little state.  Simple is perfect for GRD, but useless for FPS.
 151
 152 ewma determines the extent to which rate changes are smoothed using rate
 153 history information.  0.1 is generally a good value.
 154
 155 loop_intervals specifies the number of estimate intervals (defined in the ulogd
 156 config file) to wait between executions of the estimate, allocate, enforce loop
 157 For example, if the estimate interval is 500ms and an identity sets intervals
 158 to 2, the identity will be scheduled for updates once every second.  Assumes 1
 159 if omited.
 160
 161 comm_intervals is similar to loop_intervals, but it schedules communication
 162 with peers.  Assumes 1 if omitted.
 163
 164 htb_node & htb_parent specify which htb_node and htb_parent an identity should
 165 modify when the ulogd process is instructed not to rebuild the htb hierarchy
 166 (create_htb=0 in ulogd.conf).
 167
 168 Optionally, a set identity can be specified as independent, in which case it
 169 will not be limited by any machine identities on the node.  Assumes 0 if
 170 omitted.
 171
 172 Each identity must also have one or more peers.  Peers are listed within <peer>
 173 tags inside the identity specifier.  In addition to peers, set identities must
 174 also have at least one <xid> or <guid> tag.  <xid> tags refer to slice ids for
 175 slices that are available at the local node.  <guid> tags refer to the globally
 176 unique id of another set identity.
 177
 178
 179
 180 A "real" example:
 181
 182 <?xml version="1.0" encoding="UTF-8"?>
 183 <drl>
 184     <set id="11" limit="10240" commfabric="GOSSIP" branch="2" accounting="STANDARD" ewma="0.1">
 185         <peer>137.110.222.241</peer>
 186         <peer>137.110.222.242</peer>
 187         <peer>137.110.222.243</peer>
 188         <peer>137.110.222.125</peer>
 189         <peer>137.110.222.126</peer>
 190         <peer>137.110.222.127</peer>
 191         <xid>207</xid>
 192     </set>
 193 </drl>
 194
 195 This creates one identity numbered 11 with a 10mbps limit.  It uses a gossip
 196 communication protocol to disseminate updates with a branching factor of two.
 197 It uses a standard flow table with an ewma smoothing value of 0.1.  The
 198 identity has six peers, and it limits only the traffic associated with the
 199 slide whose xid is 207.