mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-10-05 22:05:47 +00:00
bandwidth: Adjust documentation
Recent autotest/virt-test testing on f20 discovered an anomaly in how the bandwidth options are documented and used. This was discovered due to a bug fix in the /sbin/tc utility found in iproute-3.11.0.1 (on f20) in which overflow was actually caught and returned as an error. The fix was first introduced in iproute-3.10 (search on iproute2 commit 'a303853e'). The autotest/virt-test test for virsh domiftune was attempting to send the largest unsigned integer value (4294967295) for maximum value testing. The libvirt xml implementation was designed to manage values in kilobytes thus when this value was passed to /sbin/tc, it (now) properly rejected the 4294967295kbps value. Investigation of the problem discovered that formatdomain.html.in and formatnetwork.html.in described the elements and property types slightly differently, although they use the same code - virNetDevBandwidthParseRate() (shared by portgroups, domains, and networks xml parsers). Rather than have the descriptions in two places, this patch will combine and reword the description under formatnetwork.html.in and have formatdomain.html.in link to that description. This documentation faux pas was continued into the virsh man page where the bandwidth description for both 'attach-interface' and 'domiftune' did not indicate the format of each value, thus leading to the test using largest unsigned integer value assuming "bps" rather than "kbps", which ultimately was wrong.
This commit is contained in:
John Ferlan
parent
d716d942e2
commit
7eb37a0d65
@ -3750,37 +3750,10 @@ qemu-kvm -net nic,model=? /dev/null
|
||||
|
||||
<p>
|
||||
This part of interface XML provides setting quality of service. Incoming
|
||||
and outgoing traffic can be shaped independently. The
|
||||
<code>bandwidth</code> element can have at most one <code>inbound</code>
|
||||
and at most one <code>outbound</code> child elements. Leaving any of these
|
||||
children element out result in no QoS applied on that traffic direction.
|
||||
So, when you want to shape only domain's incoming traffic, use
|
||||
<code>inbound</code> only, and vice versa. Each of these elements have one
|
||||
mandatory attribute <code>average</code> (or <code>floor</code> as
|
||||
described below). <code>average</code> specifies average bit rate on
|
||||
the interface being shaped. Then there are two optional attributes:
|
||||
<code>peak</code>, which specifies maximum rate at which interface can send
|
||||
data, and <code>burst</code>, amount of bytes that can be burst at
|
||||
<code>peak</code> speed. Accepted values for attributes are integer
|
||||
numbers. The units for <code>average</code> and <code>peak</code> attributes
|
||||
are kilobytes per second, and for the <code>burst</code> just kilobytes.
|
||||
Note the limitation of implementation: the <code>peak</code> attribute in
|
||||
<code>outbound</code> element is ignored (as linux ingress filters don't
|
||||
know it yet). <span class="since">Since 0.9.4</span> The <code>inbound</code> can
|
||||
optionally have <code>floor</code> attribute. This is there for
|
||||
guaranteeing minimal throughput for shaped interfaces. This, however,
|
||||
requires that all traffic goes through one point where QoS decisions can
|
||||
take place. That's why this attribute works only for virtual networks for
|
||||
now (that is <code><interface type='network'/></code> with a
|
||||
forward type of route, nat, or no forward at all). Moreover, the
|
||||
virtual network the interface is connected to is required to have at least
|
||||
inbound QoS set (<code>average</code> at least). Moreover, with
|
||||
<code>floor</code> attribute users don't need to specify
|
||||
<code>average</code>. However, <code>peak</code> and <code>burst</code>
|
||||
attributes still require <code>average</code>. Currently, linux kernel
|
||||
doesn't allow ingress qdiscs to have any classes therefore
|
||||
<code>floor</code> can be applied only on <code>inbound</code> and not
|
||||
<code>outbound</code>. <span class="since">Since 1.0.1</span>
|
||||
and outgoing traffic can be shaped independently.
|
||||
The <code>bandwidth</code> element and its child elements are described
|
||||
in the <a href="formatnetwork.html#elementQoS">QoS</a> section of
|
||||
the Network XML.
|
||||
</p>
|
||||
|
||||
<h5><a name="elementVlanTag">Setting VLAN tag (on supported network types only)</a></h5>
|
||||
|
||||
@ -412,49 +412,111 @@
|
||||
|
||||
<p>
|
||||
The <code><bandwidth></code> element allows setting
|
||||
quality of service for a particular network.
|
||||
<span class="since">Since 0.9.4</span> The limits specified
|
||||
are applied to the aggregate of all traffic to/from all guest
|
||||
interfaces attached to that network, <b>not</b> to each guest
|
||||
interface individually. Setting <code>bandwidth</code> for a
|
||||
network is supported only for networks with
|
||||
a <code><forward></code> mode
|
||||
quality of service for a particular network
|
||||
(<span class="since">since 0.9.4</span>). Setting
|
||||
<code>bandwidth</code> for a network is supported only
|
||||
for networks with a <code><forward></code> mode
|
||||
of <code>route</code>, <code>nat</code>, or no mode at all
|
||||
(i.e. an "isolated" network). <code>bandwidth</code> setting
|
||||
(i.e. an "isolated" network). Setting <code>bandwidth</code>
|
||||
is <b>not</b> supported for forward modes
|
||||
of <code>bridge</code>, <code>passthrough</code>, <code>private</code>,
|
||||
or <code>hostdev</code>, and attempts to do this will lead to
|
||||
a failure to define the network (or to create a transient
|
||||
network).
|
||||
or <code>hostdev</code>. Attempts to do this will lead to
|
||||
a failure to define the network or to create a transient network.
|
||||
</p>
|
||||
<p>
|
||||
The <code><bandwidth></code> element can only be a
|
||||
subelement of a domain's <code><interface></code>, a
|
||||
subelement of a <code><network></code>, or a subelement of
|
||||
a <code><portgroup></code> in a <code><network></code>.
|
||||
</p>
|
||||
<p>
|
||||
As a subelement of a domain's <code><interface></code>,
|
||||
the bandwidth only applies to that one interface of the domain.
|
||||
As a subelement of a <code><network></code>, the bandwidth
|
||||
is a total aggregate bandwidth to/from all guest interfaces attached
|
||||
to that network, <b>not</b> to each guest interface individually.
|
||||
If a domain's <code><interface></code> has
|
||||
<code><bandwidth></code> element values higher
|
||||
than the aggregate for the entire network, then the aggregate
|
||||
bandwidth for the <code><network></code> takes precedence.
|
||||
This is because the two choke points are independent of each other
|
||||
where the domain's <code><interface></code> bandwidth control
|
||||
is applied on the interface's tap device, while the
|
||||
<code><network></code> bandwidth control is applied on the
|
||||
interface part of the bridge device created for that network.
|
||||
</p>
|
||||
<p>
|
||||
As a subelement of a
|
||||
<code><portgroup></code> in a <code><network></code>,
|
||||
if a domain's <code><interface></code> has a
|
||||
<code>portgroup</code> attribute in its
|
||||
<code><source></code> element <b>and</b> if the
|
||||
<code><interface></code>
|
||||
itself has no <code><bandwidth></code> element, then the
|
||||
<code><bandwidth></code> element of the portgroup will be
|
||||
applied individually to each guest interface defined to be a
|
||||
member of that portgroup. Any <code><bandwidth></code>
|
||||
element in the domain's <code><interface></code> definition
|
||||
will override the setting in the portgroup
|
||||
(<span class="since">since 1.0.1</span>).
|
||||
</p>
|
||||
<p>
|
||||
Incoming and outgoing traffic can be shaped independently. The
|
||||
<code>bandwidth</code> element can have at most
|
||||
one <code>inbound</code> and at most one <code>outbound</code>
|
||||
<code>bandwidth</code> element can have at most one
|
||||
<code>inbound</code> and at most one <code>outbound</code>
|
||||
child element. Leaving either of these children elements out
|
||||
results in no QoS applied for that traffic direction. So,
|
||||
when you want to shape only a network's incoming traffic, use
|
||||
when you want to shape only incoming traffic, use
|
||||
<code>inbound</code> only, and vice versa. Each of these
|
||||
elements have one mandatory attribute - <code>average</code>,
|
||||
which specifies the desired average bit rate for the interface
|
||||
being shaped (in kibibytes/second). There are also two
|
||||
optional attributes: <code>peak</code>, which specifies the
|
||||
maximum rate at which the bridge can send data (again in
|
||||
kibibytes/second), and <code>burst</code> - the amount of
|
||||
bytes that can be transmitted in a single burst at
|
||||
<code>peak</code> speed (in kibibytes). Accepted values for
|
||||
attributes are integer numbers. The allotted bandwidth is
|
||||
shared equally between domains connected to the network.
|
||||
elements have one mandatory attribute - <code>average</code> (or
|
||||
<code>floor</code> as described below). The attributes are as follows,
|
||||
where accepted values for each attribute is an integer number.
|
||||
</p>
|
||||
<dl>
|
||||
<dt><code>average</code></dt>
|
||||
<dd>
|
||||
Specifies the desired average bit rate for the interface
|
||||
being shaped (in kilobytes/second).
|
||||
</dd>
|
||||
<dt><code>peak</code></dt>
|
||||
<dd>
|
||||
Optional attribute which specifies the maximum rate at
|
||||
which the bridge can send data (in kilobytes/second).
|
||||
Note the limitation of implementation: this attribute in the
|
||||
<code>outbound</code> element is ignored (as Linux ingress
|
||||
filters don't know it yet).
|
||||
</dd>
|
||||
<dt><code>burst</code></dt>
|
||||
<dd>
|
||||
Optional attribute which specifies the amount of kilobytes that
|
||||
can be transmitted in a single burst at <code>peak</code> speed.
|
||||
</dd>
|
||||
<dt><code>floor</code></dt>
|
||||
<dd>
|
||||
Optional attribute available only for the <code>inbound</code>
|
||||
element. This attribute guarantees minimal throughput for
|
||||
shaped interfaces. This, however, requires that all traffic
|
||||
goes through one point where QoS decisions can take place, hence
|
||||
why this attribute works only for virtual networks for now
|
||||
(that is <code><interface type='network'/></code> with a
|
||||
forward type of route, nat, or no forward at all). Moreover, the
|
||||
virtual network the interface is connected to is required to have
|
||||
at least inbound QoS set (<code>average</code> at least). If
|
||||
using the <code>floor</code> attribute users don't need to specify
|
||||
<code>average</code>. However, <code>peak</code> and
|
||||
<code>burst</code> attributes still require <code>average</code>.
|
||||
Currently, the Linux kernel doesn't allow ingress qdiscs to have
|
||||
any classes therefore <code>floor</code> can be applied only
|
||||
on <code>inbound</code> and not <code>outbound</code>.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<p>
|
||||
A <code><portgroup></code> element can also include
|
||||
a <code><bandwidth></code> element. In that case, the
|
||||
specified bandwidth will be applied individually to each guest
|
||||
interface defined to be a member of that portgroup.
|
||||
Any <code><bandwidth></code> element in the guest's
|
||||
interface definition will override the setting in the
|
||||
portgroup.
|
||||
<span class="since">Since 1.0.1</span>
|
||||
Attributes <code>average</code>, <code>peak</code>, and
|
||||
<code>burst</code> are available
|
||||
<span class="since">since 0.9.4</span>, while the
|
||||
<code>floor</code> attribute is available
|
||||
<span class="since">since 1.0.1</span>.
|
||||
</p>
|
||||
|
||||
<h5><a name="elementVlanTag">Setting VLAN tag (on supported network types only)</a></h5>
|
||||
@ -561,7 +623,7 @@
|
||||
network), and each portgroup has a name, as well as various
|
||||
subelements associated with it. The currently supported
|
||||
subelements are <code><bandwidth></code>
|
||||
(documented <a href="formatdomain.html#elementQoS">here</a>)
|
||||
(described <a href="formatnetwork.html#elementQoS">here</a>)
|
||||
and <code><virtualport></code>
|
||||
(documented <a href="formatdomain.html#elementsNICSDirect">here</a>).
|
||||
If a domain interface definition specifies a portgroup (by
|
||||
|
||||
@ -681,7 +681,10 @@ or the MAC address.
|
||||
If no I<--inbound> or I<--outbound> is specified, this command will
|
||||
query and show the bandwidth settings. Otherwise, it will set the
|
||||
inbound or outbound bandwidth. I<average,peak,burst> is the same as
|
||||
in command I<attach-interface>.
|
||||
in command I<attach-interface>. Values for I<average> and I<peak> are
|
||||
expressed in kilobytes per second, while I<burst> is expressed in kilobytes
|
||||
in a single burst at -I<peak> speed as described in the Network XML
|
||||
documentation at L<http://libvirt.org/formatnetwork.html#elementQoS>.
|
||||
|
||||
If I<--live> is specified, affect a running guest.
|
||||
If I<--config> is specified, affect the next boot of a persistent guest.
|
||||
@ -2020,7 +2023,10 @@ of the network interface. I<script> allows to specify a path to a script
|
||||
handling a bridge instead of the default one. I<model> allows to specify the
|
||||
model type. I<inbound> and I<outbound> control the bandwidth of the interface.
|
||||
I<peak> and I<burst> are optional, so "average,peak", "average,,burst" and
|
||||
"average" are also legal.
|
||||
"average" are also legal. Values for I<average> and I<peak> are
|
||||
expressed in kilobytes per second, while I<burst> is expressed in kilobytes
|
||||
in a single burst at -I<peak> speed as described in the Network XML
|
||||
documentation at L<http://libvirt.org/formatnetwork.html#elementQoS>.
|
||||
|
||||
If I<--live> is specified, affect a running domain.
|
||||
If I<--config> is specified, affect the next startup of a persistent domain.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user