1Managing device boot order with bootindex properties 2==================================================== 3 4QEMU can tell QEMU-aware guest firmware (like the x86 PC BIOS) 5which order it should look for a bootable OS on which devices. 6A simple way to set this order is to use the ``-boot order=`` option, 7but you can also do this more flexibly, by setting a ``bootindex`` 8property on the individual block or net devices you specify 9on the QEMU command line. 10 11The ``bootindex`` properties are used to determine the order in which 12firmware will consider devices for booting the guest OS. If the 13``bootindex`` property is not set for a device, it gets the lowest 14boot priority. There is no particular order in which devices with no 15``bootindex`` property set will be considered for booting, but they 16will still be bootable. 17 18Some guest machine types (for instance the s390x machines) do 19not support ``-boot order=``; on those machines you must always 20use ``bootindex`` properties. 21 22There is no way to set a ``bootindex`` property if you are using 23a short-form option like ``-hda`` or ``-cdrom``, so to use 24``bootindex`` properties you will need to expand out those options 25into long-form ``-drive`` and ``-device`` option pairs. 26 27Example 28------- 29 30Let's assume we have a QEMU machine with two NICs (virtio, e1000) and two 31disks (IDE, virtio): 32 33.. parsed-literal:: 34 35 |qemu_system| -drive file=disk1.img,if=none,id=disk1 \\ 36 -device ide-hd,drive=disk1,bootindex=4 \\ 37 -drive file=disk2.img,if=none,id=disk2 \\ 38 -device virtio-blk-pci,drive=disk2,bootindex=3 \\ 39 -netdev type=user,id=net0 \\ 40 -device virtio-net-pci,netdev=net0,bootindex=2 \\ 41 -netdev type=user,id=net1 \\ 42 -device e1000,netdev=net1,bootindex=1 43 44Given the command above, firmware should try to boot from the e1000 NIC 45first. If this fails, it should try the virtio NIC next; if this fails 46too, it should try the virtio disk, and then the IDE disk. 47 48Limitations 49----------- 50 51Some firmware has limitations on which devices can be considered for 52booting. For instance, the x86 PC BIOS boot specification allows only one 53disk to be bootable. If boot from disk fails for some reason, the x86 BIOS 54won't retry booting from other disk. It can still try to boot from 55floppy or net, though. In the case of s390x BIOS, the BIOS will try up to 568 total devices, any number of which may be disks. 57 58Sometimes, firmware cannot map the device path QEMU wants firmware to 59boot from to a boot method. It doesn't happen for devices the firmware 60can natively boot from, but if firmware relies on an option ROM for 61booting, and the same option ROM is used for booting from more then one 62device, the firmware may not be able to ask the option ROM to boot from 63a particular device reliably. For instance with the PC BIOS, if a SCSI HBA 64has three bootable devices target1, target3, target5 connected to it, 65the option ROM will have a boot method for each of them, but it is not 66possible to map from boot method back to a specific target. This is a 67shortcoming of the PC BIOS boot specification. 68 69Mixing bootindex and boot order parameters 70------------------------------------------ 71 72Note that it does not make sense to use the bootindex property together 73with the ``-boot order=...`` (or ``-boot once=...``) parameter. The guest 74firmware implementations normally either support the one or the other, 75but not both parameters at the same time. Mixing them will result in 76undefined behavior, and thus the guest firmware will likely not boot 77from the expected devices. 78