docs/uci_qos.txt

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