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