 Welcome, welcome in the room. So this session, we're having Thomas. Thomas will talk about KMU parameters jungle. Thomas, the stage is yours. Thank you. So hello and welcome to my talk. My name is Thomas Hoot. I'm working for Red Hat and I'm a QMU developer since more than five years now already. So, working with QMU since a couple of years already, of course, the first question is, is there a need for a guide through the QMU parameter jungle? I'd say, yes, QMU is a very big project. It supports a lot of guest devices. It supports a lot of host backends. It's been in development since approximately 15 years now. So there's a lot of legacy code in there and of course a lot of legacy command line parameters. And if you just have a look at the help output of QMU, it already has more than 450 lines of code, 450 lines. And especially I regularly see people asking on the mailing list and on IRC about how do I start QMU to get this and that done. And so I thought it would be a good idea to maybe explain some things. One thing in advance, if you just want an easier way to run a virtual machine, try to use libvert, word manager, OpenStack or any other upper layer tools. Instead, they can make your life much easier. But if you're interested in running QMU directly, this is hopefully the right talk for you here. So generally know how, I hope everybody knows what QMU is, is anybody in the room here who does not have a clue about QMU at all? Okay, that looks good. Whoever tried to run QMU directly already? Okay, and whoever wanted, how do I use these parameters to get the things done that I wanted to do? Okay, so pretty much everybody who tried to run QMU also had some problems, is that already? Okay, so let's get started with some general know-how. First thing to notice is that QMU does not distinguish between single dash parameters and double dash parameters like most other GNU tools are doing it. So dash help is exactly the same as dash dash help. Then you've got to be aware that QMU is running the guest with a set of default devices. So each normal guest has a network interface card, for example, a VGA card. And sometimes there are cases you do not want this. You'd rather want to start with a blank board instead. And in this case, you should use the dash no defaults option. And this will disable almost all of the default devices. And there's also a way to suppress just certain default devices. For example, dash VGA non or dash net non to disable the VGA card or the network interface card. Getting help about the command line. Of course, there's a man page and we also have a pretty long HTML help text. For QMU, which explains most of the thing. But if you're just sitting at the shell and want to get some help about the parameters, you of course can run it with dash help to get a rough list. But the important thing to know is that you can also run a lot of parameters with string help too. So for example, if you run QMU with dash xl help, it will print your list of available accelerators like KVM, XAM, Hexam in the recent QMU releases. And this is especially helpful for the dash device parameter. Dash device is the parameter that you use to add an additional device to the gas. So additional hardware like network card. And so if you run dash device hub, QMU will print out a nice list of available devices for the gas. And if you've chosen one of the devices that you want to add, you can also run a dash device parameter with the device name comma help and it will print you out a list of parameters that you can use to configure the device. So here's an example for the E1000. The E1000 is a network card. And I run QMU with dash device E1000 comma hub and I get a nice list of parameters that I can use to configure the network card here. So for example, a PCI slot address or I can set the MAC address of the network card. And once I've picked the parameters that I want to set, I can run QMU with dash device E1000 MAC equals the MAC address comma address equals the PCI slot and function. Any questions? So the question was that address here should be an int 32. Actually, that's a good question. Yeah, maybe it's just, I never noticed this. Yeah, you're right, it should be an integer but actually you can really set PCI slot and a function number. So it's slot dot function number in this case. I've got to look it up. That's a good question. Thanks. Next thing that you should really be aware of is that a QMU device consists of two parts. So at one side there's the emulated guest hardware like the network card itself and the other part is the host backend. So the hardware in the guest has somehow to interact with the outside and this is the host backend. For example, an E1000 network card could be attached to a tap host network via a bridge to the outside. I explicitly say it here because a lot of people get this wrong. They just think I want to run QMU and I want a network card so there must be one parameter that gives me everything. But that's often not the case especially if you want to have full control over the system. If you want to do it correctly you've got to normally specify both dash device to configure the guest side and another parameter to configure the host side. And this leads us to the next slide. You also get to be aware that there are different classes of QMU parameters. So the first class you could say that the convenience parameters and these convenience parameters often give you both in one parameter. So for example, dash CD-ROM and then you can give an ESO file image name will add a CD-ROM device hardware to the guest side but it will also configure the host backend and then the host backend in this case is just a block layer module that reads the ESO image on your host. Then there are the architected options and these give you now the full control over the QMU internals and here normally you have to specify both sides separately. So for example, to configure a CD-ROM drive you would say dash device IDE CD for configuring the guest hardware and to configure the host backend you would use block depth raw and then you can also specify the ESO image on your host somewhere. Yeah, there's a question. I mentioned that a minute ago. Oh, the question is whether this dash block depth is a typo or whether it's on purpose. So QMU does not distinguish between single dash and double dash. So in this case I was just lazy because the line got very long and I do not want to reach it into the jungle leaves here. But yes, it's a little bit ugly that QMU doesn't distinguish this but once you introduced it you have to stay compatible with all the versions so you do not want to switch. Yeah, third category are simply legacy options. So as I mentioned, QMU is a very, very old project, it was 15 years already. So there are a lot of options that have been introduced in the past but simply do not match the current internals of QMU anymore. But the QMU project normally tries to stay as compatible as possible with all the releases. So there are a lot of old options around. And for example, for the CD-ROM example you could for example use dash drive IF for interface equals IDE comma media equals CD-ROM and then you can also specify the iso file name on your host. So that was just the introduction. Now let's look into the different classes of devices a little bit closer. Let's start with character devices and character devices, you configure the host back end with the dash card of parameter and you can list the available host back ends with dash card of help. So for example, I can map a character device to a file on my host, I can map it to a socket, standard IO pipe, GTY, there are lots of more options if you're interested, just have a look at the QMU documentation. So for example, to redirect a serial port of the guest to a file on the host, you could run QMU. In this case, I started with no defaults because I want to avoid that QMU configures a default serial port and I also do not want a VGA card in this case, I explain why. And then you say dash card of file and you have to give it an ID, identification string in this case, C1 and this path equals the file name, I say I tell QMU which file to use on the host file system. The guest hardware is configured with dash device, either serial is a serial port on the isa bus and then I say comma card of equals and here's now the ID to tell QMU which character backend should be used to connect the serial port to. And actually if you run this command with a recent version of QMU, you will even see something in the file already because the recent version of QMU, they ship with a guest firmware that can redirect its output to the serial port if no VGA card is available. So since I started QMU with no defaults here, you would see the output of the, it's called CBIOS in the text which is quite neat. So for character devices there are also some legacy or you could also say convenience options. Sometimes you cannot really distinguish between legacy and convenience because, yeah, because the old options are often way more easier or way easier to use than the options that give you full control. So some people say they are legacy, some people say they are much easier to use, we should keep them forever. And in this case, there's for example dash serial and dash parallel for configuring serial and parallel ports and these also give you, or these also configure both the host backend and the guest hardware in one go. And I sometimes use dash serial because it's really convenient. For example, you can use it if you want to emulate an embedded power PC or ARM board which outputs its, or which prints its output through serial part and you have to run it with no defaults for some reason. You can use dash serial mon, called standard IO and this is a special mode that multiplexes the QM, the so-called QMU HMP monitor with the serial output. And you can then toggle between the serial output and the monitor with the keyboard shortcut control AC. I'll try to show it. So this is the command line here. I'm using embedded power PC board, run it with no graphics because I'm a console guy, I do not want to fancy GTK window. For some reason I want to run it with no defaults and then I say serial mon standard IO. And here it is. So you see the serial output of the guest. In this case it's the U-boot firmware. And I'm talking here to the U-boot. Can for example run the help text and I get the U-boot help. And at one point in time I say, oh I want to talk to QMU instead. So I press control A, C, and you end up in the QMU monitor. If you want to type help again, you get the help output of the QMU monitor instead. And there you can do things like a system reset for example and you see my power PC guest just started again. So of course I can also quit the system. Okay, that's all for character devices. Let's have a look at network devices. So modern network devices should be configured with the so-called dash net def command to configure the host back end side. And just as with the character devices you first have to give a type and an identification string. And the type can be for example a user for a fully emulated network stack. Which is quite nice because it does not require any privileges or a special bridge set up on the host. But it's a completely network address translated network. So by default you cannot reach the guest from the outsides. You have to do things like port forwarding. And of course if your TCP traffic has problems with network address translation then it's also not that good. So for having more control over the network you normally want to use the TAP device which gives you real network access via a bridge. And there are also some other options like for example socket which can be used to tunnel all the network traffic to another instance of QMU. If you just want to hook up to virtual machines for example. The example looks somewhat similar to the character devices here. So I specified a host back end. In this case a user network with an ID and one. And since the user back end is a fully emulated network QMU also provides an emulated DHCP server here. And you can for example configure the DHCP server with a parameter like DHCP start and then the starting address of the IP addresses that should be assigned to the guest. The guest hardware is configured with flash device again. In this case I'm not using the E1000 network card. I'm using the word I own network card. And I use comma net def equals and here the ID of the back end to tell QMU which host back end it should connect the guest hardware to. Of course there's also a legacy network command and this is the dash net command. And the dash net command can be used to configure both the guest hardware and the host back end. And but not in one line you have to specify twice. So with dash net nick for network and interface card comma model equals the type for example here when E1000 you configure the guest hardware and the host back end part looks similar to the dash net def on the previous slide. So the dash net user configures user back end for this. The thing is that you also have to connect these two parameters together and this is done via the so called VLAN equals number option. In this case I said VLAN equals zero which uses the VLAN is number zero. Zero is default so you can omit VLAN equals zero if you just want to use that one. You just have to specify it if you want to use another number. Now the confusing part. VLAN is not what you think of when you hear the term VLAN. Normally VLAN is network traffic encapsulated in some other network packets not in QMU speak. In QMU land a VLAN is you could think of a emulated hub. So just replace the term VLAN with hub in your mind and then it's pretty much what you get. You see the dash net option is quite confusing so I recommend to use dash net def if possible. You just have to be aware that there's still one case where you need dash net and this is if you want to run and normally just try to use dash net def instead. So to really give you a vision of what I'm talking about I've drawn some nice pictures here. So dash net def gives you a real one-to-one connection between your guest hardware and your host backend. For example here I'm one to run a guest with two network cards and that's also with two host backends and the first one is an E1000 device connected to a user net def so connected via the ID and the second one is a virtual net connected to a tap host backend with N2 and in this case you really get straight connection between your E1000 and the user and the virtual net to the tap just that's normally what you want. Now if you try to do the same and I often see that on IRC and on the mailing list if you try to use the net command like you can also see it in some very old examples in the internet on some third party pages. People often try to use dash net, nick, model, something, dash net user and then the second network connection they just do it again, dash net, nick, model in this case word IO, dash net, tap and in this case I omitted the VLAN equals number option on purpose because this was what people often get wrong. In this case you get a hub in between so everything is connected to an emulated hub so the traffic of the E1000 network card is also visible on the word IO network, word IO network card for example and of course it's somehow working because people normally do not look very close at the traffic yet but it's not what you really want normally unless you really want to sniff the network traffic on one interface to see what's happening on the other interface. If you really want to use dash net you have to use VLAN equals number parameter or try to avoid it and use dash net def immediately. Yes, that's a question. Yes, there's also a way to connect net def to a QMU hub but actually if you just want to sniff the traffic there's even, oh sorry the question was if I want to sniff the network traffic on one of the interfaces with the dash net def command you can do that. There's also a way to connect net def to a hub since a couple of weeks at least but actually there's a better way to sniff network traffic. QMU can sniff the network traffic for you. There's an option to dump the network traffic into a file in the same file layout as used by Wireshark and TCP dump and then you can just let QMU dump the traffic into the file and look at it afterwards with Wireshark for example. So let's have a look at the third category, block devices. Modern block devices should be configured maybe you guessed it already with the dash block def parameter. Now I see a couple of people looking strange so block def is quite new. Block def is only there since a year or two I think since QMU 2.9 or something like that but that's the way to go. So in this example I want to stop my guess with a QCO2 image. So QCO2 is the native image format of QMU which is the preferred one of course and as you already see I specify your block def twice so the block layer of QMU is quite complex and you can stack the different block layer drivers on top of each other. So this works like this so I specify a block def file driver which connects to a raw file on my host. In this file, in this case the IMG.QCO I give it a node name so this is pretty much the same as the ID equals something as you've seen in the previous examples but with block def it's node name equals F1 in this case and the file driver just gives me a raw access to the file on top of that I have to specify a driver that handles the layout of the file so this could be QCO2, VMDK, something like that. So I specify another block def driver in this case QCO2, give it another node name and I say connect to the raw driver that I specified just before and then I can connect my guest hardware in this case an IDE hard disk and say drive equals the QCO2 driver and this way I connected to the QCO image. If that's too much to type there's also a short way where you can specify everything in one line so in this case you immediately start with the QCO2 driver give it a node name and then you can say file.driver equals file so this is the raw driver in the same line and file.filename equals mg.QCO and also connected to the IDE hard HD guest hardware and you see already this is quite complex but this gives you the full control over the QMU block layer stack so if you've seen the presentation of Kashyap this morning you maybe also got already the sense that the QMU block layer is quite mighty and this is an example for what is possible with the block layer today so the IDE hard disk guest hardware in this case is connected to a raw block driver which again connects to a so-called quorum block driver and the quorum block driver can query multiple other sources for example one is in QCO2 which is then connected to another block debug driver and finally the block debug driver is connected to a file on your local host but QMU cannot only connect to files on your local host so this QCO2 driver has a backing chain for example to another QCO2 driver which connects via HTTP I think it's using Curl on the inside so it can also access files that are somewhere on an HTTP server for example and this way you can really set up complex trees in your QMU command line parameter jungle the question is what the quorum driver is I think actually I've never used it so I think it just queries multiple sources and uses the... or maybe Stefan can answer that one so the question is what does quorum do it can do a few things and the main feature is replication so say you have three NFS servers and if one of them goes down your VM could keep running because what the quorum driver does is it will actually read from all three of them it will compare and make sure that the disk image is still consistent and then it has rules for repairing does that mean it's still high available? so as also mentioned here at the bottom the slide has been taken from another talk from KVM Forum 2014 by Max Reitz and Kevin Wolff so if you are interested in the QMU block layer I can recommend that talk and also there are some other talks for example from Markus Ambruster a year earlier something like that I've got some references on the last slide for that of course block layer is complex so there's also a legacy option and this is dash drive and since dash block depth is still quite new you see dash drive still in a lot of examples on the internet you can use dash drive to configure both the guest hardware and the host backend in one line for example to set up an IDE drive you would say dash drive if for interface equals IDE format equals raw could also be Qco in this case just give a raw file and then file equals filename on your host there's also a special case here where you say if equals none and this was used to only configure the host backend side and this was mainly used before the new dash block depth command was introduced into QMU so if you are using a recent QMU try to use block depth instead if you are using an older version of QMU you're likely got to use the dash drive with if equals none dash drive is quite complex and does not really match the internals of QMU that much anymore so be aware that parts of dash drive might be removed in the future don't do not use it in new scripts and code anymore in Apple layers if possible and of course there are also some convenience or even more legacy options for example if you just want to use a hard disk image on your local file as any kind of or in this case it's an IDE on the x86 platform guest disk you can use dash HDA for example dash FDA is used for floppy drives and dash CD-ROM for CD-ROM drives you had a couple of these already in the past slides and there are many more of them so this is all I wanted to say in a short amount of time here and you could of course talk forever about QMU parameters I think just a couple of points I wanted to for you to take away so if you run QMU try to be aware that there are always two parts the emulated guest hardware and host backends and if you want to run if you want to have full control over both parts you also got to specify each part separately by using the dash Cardiff, dash NetDev and dash BlockDev commands together with the dash device and in scripts and other code that should be future proof please avoid to use dash Net and dash Drive since these are really legacy and might get removed in the future we do not have concrete plans for doing that yet but the discussion pops up every couple of months you could say so the comment is that LibWord for example also still uses dash Drive and did not switch to dash BlockDev yet so it won't happen very soon that we really can get rid of dash Drive but I think people are working on that so that's all I wanted to say thanks for your attention and questions I think you were first so the question was that the legacy and the convenience options sometimes had to distinguish and whether we or how we remove or when we yeah so options that we intend to remove they are clearly marked as deprecated so if you run QMU with such an option it normally prints out a line at the start if this option is deprecated please use something different instead and we've got a chapter in the QMU documentation where we list all the deprecated devices so some options like dash Drive for example they are considered somehow as legacy but they are not deprecated yet so they won't get removed very soon yet I just wanted to say that you should be aware of it maybe two or three years they could be marked as deprecated and a year later maybe they are removed or something like that yes please yeah there is a configuration file but the question was we have so many options why don't we use configuration files you can use configuration files but they are not for some reasons they are not that popular actually you cannot do everything with the configuration file as far as I know not every command line parameter really works from the configuration file and people are not using it that much actually so the comment was that some hosting providers apparently are using the config options and only a percentage of the configuration of the command line parameters are really working right from the configuration file yeah that is also true so the comment was that people who want to use configuration files they just use slip word yes please so the question was for the parameters that use these IDs or node names are there any limitations in length or characters actually I have never tried I don't know I guess there are some limitations but apparently people did not try to hit them yet sorry yes please very true so the question was I mentioned this possibility to dump the network traffic that QMU can also dump the network traffic and the question was what about the host backends like vhost user that somehow bypass the QMU networking stack and you are right for these backends you cannot dump the traffic this way so this only works for the normal case where the network traffic is fully handled by QMU okay time's up if you have more questions just catch me outside thanks