libvirt virtual networking documentation misleading

Bug #1103870 reported by Sascha Picchiantano
8
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Ubuntu Server Guide
Fix Released
Undecided
Doug Smythies
ufw
Invalid
Undecided
Unassigned

Bug Description

The 12.10 server documentation for Virtualiziation > libvirt -> virtual networking is a little confusing in regards to bridged networking.

The article says that you need to create a linux bridge and links to the netwokring -> bridging article. However, the libvirt and KVM packages in the 12.10 repository install a new bridge (virbr0) by default. The article does not mention this default bridge anywhere and does not describe why it is being installed and what it should be used for. Instead, the article says you need to create your own bridge. This is confusing.

The documentation should reflect that the kvm package installs a bridge for you, where to find it's configuration and how to use it.

Link: https://help.ubuntu.com/12.10/serverguide/libvirt.html#virtual-networking

Related branches

affects: ubuntu-docs (Ubuntu) → serverguide
Revision history for this message
Doug Smythies (dsmythies) wrote :

The article is referring to bridging as required "To enable external hosts to directly access services on virtual machines".
Is this not different, and in addition to, what is done by default?

Revision history for this message
Sascha Picchiantano (sascha-picchiantano) wrote : Re: [Bug 1103870] Re: libvirt virtual networking documentation misleading

No. The default bridge installed by libvirt is enabling NAT and DNS
services for virtual machines. There is actually no need to set up
additional bridges. An additional bridge could be set up if you don't
want/need NAT or want to do it yourself, but then again, libvirt has
everything built in to setup bridges. I think - since Ubuntu is using
libvirt - the documentation should reflect on how to use libvirt to setup
and control bridges (through virsh, for example).

Anyhow, the way it is currently described in the documentation is
confusing.

Revision history for this message
Doug Smythies (dsmythies) wrote :

Yes, the default does what you said, but it does not allow "external hosts to directly access services on virtual machines". Such a need is different, and in addition to, what is done by default. For example, with the default setup I can not SSH into the VM from an external client.

I'm not disagreeing that some improvement/clarity can be added to the paragraph.

Also, I agree that some documentation on how to use libvirt to make it so that external hosts can access services on virtual machines would be really good (and actually I could use such documentation myself, right now.)

Revision history for this message
Sascha Picchiantano (sascha-picchiantano) wrote :

Doug, the default does in fact let you have inbound connections. All you would have to do is add some iptables rules that take care of it.

The default is nothing more than a linux bridge with dnsmasq and iptables, configured by libvirt. you can use brutil, iptables and dnsmasq config to change it's configuration (which will be overriden on next boot) or you use virsh to control all aspects of it (which will then be persistant across boots). now that I have learnt more in the meantime since opening thi "bug", I tend to just destroy the default bridge and set up new ones from scratch.

that default thingy is no magic. it's all standard. and hence there should be more documentation about it. although ofcourse we could all argue since this is libvirt/kvm defaults, one could look up the documentation for that.

Revision history for this message
Doug Smythies (dsmythies) wrote :

Yes, you can add iptables rules for inbound connections. However, iptables can not help when you want the host and its guest VM's to be able to be accessed from the lan for the same port. For example if the host and its guest VM's are all running web servers on port 80. In that case some additional bridge work is required on top of the default (which I have not tried to figure out how to do it yet).

On my vmware ubuntu server running VM running on my Windows Laptop, the bridge is set up such that it appears on my LAN and all LAN client can access it. The VM even gets its IP address from my DHCP server.

There is always a trade off between adding detail to the serverguide and referring the reader to references for further detail.

Anyway, If I have time before the document string freeze for 13.04, maybe I can do something here.

Revision history for this message
Sascha Picchiantano (sascha-picchiantano) wrote :

To be able to reach multiple VMs on the same port, you would have to make sure your LAN routes the private IP addresses used by the VMs to your KVM box (e.g. 192.168.1.0/24 is what you use for your VMs, and your VM host is 10.10.10.1, then your LAN router would have to route 192.168.1.0/24 to 10.10.10.1). Then turn off NAT for the VMs.

That's all there is to it. This could be done with the default bridge (because it's just a normal bridge like any other bridge), but you would have to disable NAT for it (can be done with virsh).

Better way though would be to destroy/delete the default bridge and set up your own bridge from scratch, with a confiuration that fits your needs. By doing this, you can very easily create the same kind of setup you have with your vmware box.

This is exactly the stuff that is missing from the documentation. Neither does the documentation explain how the default bridge is set up (iptables, NAT, dnsmasq), nor does it explain that the default bridge is actually part of KVM and not part of Ubuntu, nor does it explain how to configure the default bridge or use another bridge. Especially new users are completely left in the dark.

By the way, this leads to another shortcoming: Once you get over the default bridge and set up your own and you want to have some sort of network security for your VMs, you will quickly realize that the Ubuntu Firewall (ufw) really doesn't play well with KVM at all. But that's a different topic.

Revision history for this message
Doug Smythies (dsmythies) wrote :

No, you don't have to make sure the LAN routers route to the VM's, but rather you make the VM's IP addresses be on the same sub-net as the host. For example if the host address is 10.10.10.1, with a sub-net mask 255.255.255.0, the VM's would be assigned, or obtain via DHCP, IP addresses on the 10.10.10.0 sub-net.

Anyway, I made some simple edits and have a merge proposal pending. The edits are much less than what was desired here, but there are only a couple of days left before the 13.04 documentation string freeze, and there is still much to do.

Changed in serverguide:
assignee: nobody → Doug Smythies (dsmythies)
status: New → Fix Committed
Revision history for this message
Sascha Picchiantano (sascha-picchiantano) wrote :

Thanks Doug, appreciate the effort. My english is not good enough to write technical documentation, else I would offer my help.

Changed in serverguide:
status: Fix Committed → Fix Released
Revision history for this message
Doug Smythies (dsmythies) wrote :

In serverguide the fix (such as it is) is released. This bug never was about UFW, so I am setting that to invalid, so as to get this one off the books.

Changed in ufw:
status: New → Invalid
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers