docs/uci_qos.txt

   1 Quality of Service (qos-scripts) configuration
   2 ==============================================
   3
   4 This is the documentation for the UCI configuration file '/etc/config/qos'.
   5
   6 *WARNING*: 'luci-app-qos' won't start until you enable the 'qos' Initscript within the System-->Startup tab as well as enable qos under Network-->QoS
   7
   8
   9 == Sections
  10
  11 A minimal QoS configuration usually consists of:
  12 * one _interface_ section
  13 * some _rules_ allocating packets to at least two buckets
  14 * _configuration_ of the buckets.
  15
  16 === Interface
  17
  18 Each Interface can have its own buffer. The 'interface' section declares global characteristics of the connection on which the specified interface is communicating. The following options are defined within this section:
  19
  20 ----
  21 config interface dsl
  22         option enabled      1
  23         option classgroup  "Default"
  24         option overhead     1
  25         option upload       512
  26         option download     4096
  27 ----
  28
  29 | Name | Type | Required | Default | Description
  30 | 'enabled' | boolean | yes | '1' | Enable/Disable QoS
  31 | 'classgroup' | string | yes | 'Default' | Specify 'classgroup' used for this interface (see description of 'classgroup' below)
  32 | 'overhead' | boolean | yes | '1' | decrease upload and download ratio to prevent link saturation
  33 | 'download' | integer | yes | '4096' | Download limit in 'kilobits/second'
  34 | 'upload' | integer | yes | '512' | Upload limit in 'kilobits/second'
  35
  36 === Rules
  37
  38 Each 'classify' section defines one group of packets and which target (i.e. bucket) this group belongs to. All the packets share the bucket specified.
  39
  40 | Name | Type | Required | Default | Description
  41 | 'target' | bucket | yes | _(none)_ | The four defaults are: 'Priority, Express, Normal' and 'Bulk'
  42 | 'proto' | string | no | '0' | Packets matching this protocol belong to the bucket defined in target
  43 | 'srchost' | string | no | _(none)_ | Packets matching this source host(s) (single IP or in CIDR notation) belong to the bucket defined in target
  44 | 'dsthost' | string | no | _(none)_ | Packets matching this destination host(s) (single IP or in CIDR notation) belong to the bucket defined in target
  45 | 'ports' | integer | no | _(none)_ | Packets matching this, belong to the bucket defined in target
  46 | 'srcports' | integer | no | _(none)_ | Packets matching this, belong to the bucket defined in target
  47 | 'dstports' | integer | no | _(none)_ | Packets matching this, belong to the bucket defined in target
  48 | 'portrange' | integer | no | _(none)_ | Packets matching this, belong to the bucket defined in target
  49 | 'pktsize' | integer | no | _(none)_ | Packets matching this, belong to the bucket defined in target
  50 | 'tcpflags' | string | no | _(none)_ | Packets matching this, belong to the bucket defined in target
  51 | 'mark' | string | no | _(none)_ | Packets matching this, belong to the bucket defined in target
  52 | 'connbytes' | int | no | _(none)_ | Packets matching this, belong to the bucket defined in target
  53 | 'tos' | string | no | _(none)_ | Packets matching this, belong to the bucket defined in target
  54 | 'dscp' | string | no | _(none)_ | Packets matching this, belong to the bucket defined in target
  55 | 'direction' | string | no | _(none)_ | Packets matching this traffic direction ('in' or 'out') belong to the bucket defined in target
  56
  57 === Classgroup
  58
  59 As we can have more then one interface, we can have more then one classgroup.
  60
  61 ----
  62 config classgroup "Default"
  63         option classes      "Priority Express Normal Bulk"
  64         option default      "Normal"
  65 ----
  66
  67 | Name | Type | Required | Default | Description
  68 | 'classes' | bucket names | yes | _(none)_ | Specifies the list of  names of _classes_
  69 | 'default' | bucket name | yes | _(none)_ | Defines which _class_ is considered default
  70
  71
  72 === Classes
  73
  74 Each Bucket has its own configuration.
  75
  76 Example:
  77 ----
  78 config class "Normal"
  79         option packetsize  1500
  80         option packetdelay 100
  81         option avgrate     10
  82         option priority    5
  83 ----
  84
  85 | Name | Type | Required | Default | Description
  86 | 'packetsize' | integer | yes | _(none)_ | in bytes
  87 | 'packetdelay' | integer | yes | _(none)_ | in ms
  88 | 'maxsize' | integer | yes | _(none)_ | in bytes
  89 | 'avgrate' | integer | yes | _(none)_ | Average rate for this class, value in % of bandwidth (this value uses for calculate vaues 'Nx' of ''tc ... hfsc rt m1 N1 d N2 m2 N3'')
  90 | 'limitrate' | integer | no  | 100 | Defines to how much percent of the available bandwidth this class is capped to, value in %
  91 | 'maxsize' | integer | yes | _(none)_ | in bytes
  92 | 'priority' | integer | yes | _(none)_ | in %
  93
  94 === Classes (For Advanced Users)
  95
  96 Below is unverified technical breakdown of each /etc/config/qos class parameters.
  97
  98 ----
  99 ### Params:
 100 #
 101 # maxsize:
 102 #       limits packet size in iptables rule
 103 #
 104 # avgrate: (note: sum(avgrates) ~ 100)
 105 #       rt m1 = avgrate / sum (avgrate) * max_bandwidth
 106 #       rt m2 = avgrate * max_bandwidth / 100
 107 #       ls m1 = rt m1
 108 #
 109 # packetsize & packetdelay: (only works if avgrate is present)
 110 #       rt d = max( packetdelay, 'time required for packetsize to transfer' ) (smaller ps -> smaller d)
 111 #       ls d = rt d
 112 #
 113 # priority:
 114 #       ls m2 = priority / sum (priority) * max_bandwidth
 115 #
 116 # limitrate:
 117 #       ul rate = limitrate * max_bandwidth / 100
 118 ----
 119
 120 == Quick start guide
 121
 122 * Install the qos-scripts package:
 123
 124 ----
 125 opkg install qos-scripts
 126 ----
 127
 128 * Basic configuration using UCI command line:
 129
 130 ----
 131 uci set qos.wan.upload=1000            # Upload speed in kBits/s
 132 uci set qos.wan.download=16000         # Download speed in kBits/s
 133 uci set qos.wan.enabled=1
 134 uci commit qos
 135 ----
 136
 137 * Start it and look for error output and test):
 138
 139 ----
 140 /etc/init.d/qos start
 141 ----
 142
 143 * Make script run at every boot up:
 144
 145 ----
 146 /etc/init.d/qos enable
 147 ----
 148
 149 == Troubleshooting
 150
 151 * Look at the generated traffic control qdisc settings by running:
 152
 153 ----
 154 tc qdisc
 155 ----
 156
 157 The default (ie no-QoS-applied) values for any interface look like this:
 158
 159 ----
 160 qdisc fq_codel 0: dev eth0 root refcnt 2 limit 1024p flows 1024 quantum 300 target 5.0ms interval 100.0ms ecn
 161 ----
 162
 163 ... Any interface with only a single qdisc line printed, showing the same settings as this line (this one is for _dev eth0_), indicates no QoS on that interface.
 164
 165 Network interfaces with QoS enabled will have multiple qdisc lines printed, each corresponding to a QoS class, etc.
 166
 167 * If the printed qdisc settings don't seem to be correct, you can preview the _tc_ commands generated from the OpenWRT _/etc/config/qos_ by running:
 168
 169 ----
 170 /usr/lib/qos/generate.sh interface wan
 171 ----
 172
 173 (Replace 'wan' with the UCI interface name you're debugging, as given in the _/etc/config/qos_ file.)
 174
 175 This should print a series of _insmod_ and _tc_ commands used to set up the QoS subsystem. You can debug any errors caused by running these commands by running:
 176
 177 ----
 178 /usr/lib/qos/generate.sh interface wan | sh -x
 179 ----
 180
 181 The output of _/usr/lib/qos/generate.sh_ is normally executed automatically as part of _/etc/hotplug.d/iface/10-qos_.