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