Re: [libvirt] [PATCH v2] bandwidth: Adjust documentation

On 02/17/2014 05:45 PM, John Ferlan wrote: 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) 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. 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.)