[libvirt] [PATCH v2] bandwidth: Adjust documentation

Laine Stump laine at laine.org
Tue Feb 18 10:58:44 UTC 2014


On 02/17/2014 05:45 PM, John Ferlan wrote:
>
>
>>>       <h5><a name="elementVlanTag">Setting VLAN tag (on supported network types only)</a></h5>
>>> diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in
>>> index 1ca1bec..d4c390a 100644
>>> --- a/docs/formatnetwork.html.in
>>> +++ b/docs/formatnetwork.html.in
>>> @@ -412,40 +412,81 @@
>>>
>>>         <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
>>> +        quality of service for a particular network
>>> +        (<span class="since">since 0.9.4</span>). For a <code>domain</code>
>>> +        object, the limits specified are applied to the domain traffic.
>> I'm quite sure about the 'domain traffic'. The <bandwidth/> under domain 
>> limits the particular <interface/> that has <bandwidth/>. Having 'domain 
>> traffic' written here may sound like if the domain traffic was 
>> aggregated and then shaped (which is done in network not in domain).
>> Maybe 'domain interface traffic'?
>>
> Right - I struggled with this one when trying to merge things. Using
> "domain interface traffic" does target a bit better. Of course the
> context is discussing network bandwidth, so I guess I just assumed - hah
> - that the reader would consider the domain traffic as the traffic for
> that interface.
>
> In the end, they both affect the same target interface; however, it
> wasn't quite clear which would take precedence.  If the interface had
> one set of values on it, then the domain was defined with a different
> set, then what happens?


That is a non-question, because there is no <bandwidth> subelement of a
<domain>! The <bandwidth> element can appear in 3 places:

1) as a subelement of a domain's <interface>. In this case, the
bandwidth applies to that one interface of that domain.

2) as a subelement of a <portgroup> in a <network>. In this case, if a
domain's <interface> has a "portgroup='xxx'" attribute in its <source>
element:

      <interface type='network'>
        <source network='testnet' portgroup='admin'/>
        ...

*and* if the <interface itself has no <bandwidth> element, then the
<bandwidth> element of the portgroup is applied to that interface.

3) as a subelement of a <network>. In this case, the bandwidth specified
is intended to be to total aggregate bandwidth of all guest interfaces
attached to that network.

So, as you can see, there is no concept of "the bandwidth of a domain".

The places where there may be a question of precendence:

1) if an <interface> has a <bandwidth> *and* it belongs to a portgroup
that has a <bandwidth>. In this case, we decided that the bandwidth
under the individual <interface> would take precedence, since at the
time anyone who had permission to edit the domain (and its <interface>)
also had permission to edit the network (and its <portgroup>); so
allowing the specific config for one interface to override the general
config for many interfaces was more useful.

2) if a <network> has a bandwidth defined for the aggregate of all
interfaces attached to that network, and one interface has bandwidth
defined that is higher than the aggregate for the entire network. In
this case, the aggregate bandwidth for the network takes precedence, not
because of anything we do, but just because the two choke points are
independent of each other (the <interface> bandwidth control happens on
the interface's tap device, and the <network> bandwidth control happens
on the interface part of the bridge device created for that network).


Did you maybe mean to say

  If the interface had one set of values on it, then the *NETWORK*
  was defined with a different set, then what happens?


? If so, then I believe (2) above explains in (rather obtusely, of
course, but I hope it's possible to decipher it)


>   Or vice versa - a domain with a set of values
> applied to an interface and then someone edits the network interface. It
> seems it would be the "last" set to be applied that would "win".

What is "interface" vs. "network interface"? I can't tell if you're
talking about the same thing with two slightly different names, or
incorrectly naming something in the <network> configuration.

But if you're talking about interface bandwidth vs. network aggregate
bandwidth, the way that it works is that both sets of rules are
installed, and the traffic for that guest's interface is shaped twice -
once as it goes in/out of the guest interface's tap device, then the
same traffic is shaped again (in aggregate with all other traffic for
the network) as it goes in/out of the interface that is a part of the
network's bridge device.

> Since this is an active topic for other recent patches, hopefully we can
> come up with a wording that will stick going forward.  I've copied Laine
> on this response just to bring it to his attention and get his take as
> well...
>

Although I understand the desire to eliminate nearly duplicated wording,
I'm a bit concerned about trying to combine two things that are almost
but not entirely the same, due to the potential of the combined
information being wrong in one of both cases, or at least becoming
unnecessarily confusing due to extra "exceptions" that are needed to
explain the differences. In spite of that, I'm fine with it being
combined - if people complain, we can always split it up again.

I can never really form a good opinion about documentation without
seeing it live on the web page and hearing how others interpret it, and
my burn-out level on documentation has lately led to my opinion either
being "yeah, that's okay", or "no, I don't like that, but I don't know
how to / don't have time to fix it" :-P

(The recent change to the information for <bandwidth> in the network
documentation was a side effect of me making a small change to
validation of network xml to disallow specifying <bandwidth> on network
types where we can't support setting aggregate bandwidth for the entire
network. While I was doing that, I noticed that the documentation about
<bandwidth> in formatnetwork.html.in was obtuse/incorrect, so I made
some changes to fix those things; I didn't think to look at the
documentation for <bandwidth> in the domain (<interface>) XML docs,
because I hadn't changed anything there.)




More information about the libvir-list mailing list