docs/system/s390x/bootdevices.rst

   1 Boot devices on s390x
   2 =====================
   3
   4 Booting with bootindex parameter
   5 --------------------------------
   6
   7 For classical mainframe guests (i.e. LPAR or z/VM installations), you always
   8 have to explicitly specify the disk where you want to boot from (or "IPL" from,
   9 in s390x-speak -- IPL means "Initial Program Load"). In particular, there can
  10 also be only one boot device according to the architecture specification, thus
  11 specifying multiple boot devices is not possible (yet).
  12
  13 So for booting an s390x guest in QEMU, you should always mark the
  14 device where you want to boot from with the ``bootindex`` property, for
  15 example::
  16
  17  qemu-system-s390x -drive if=none,id=dr1,file=guest.qcow2 \
  18                    -device virtio-blk,drive=dr1,bootindex=1
  19
  20 For booting from a CD-ROM ISO image (which needs to include El-Torito boot
  21 information in order to be bootable), it is recommended to specify a ``scsi-cd``
  22 device, for example like this::
  23
  24  qemu-system-s390x -blockdev file,node-name=c1,filename=... \
  25                    -device virtio-scsi \
  26                    -device scsi-cd,drive=c1,bootindex=1
  27
  28 Note that you really have to use the ``bootindex`` property to select the
  29 boot device. The old-fashioned ``-boot order=...`` command of QEMU (and
  30 also ``-boot once=...``) is not supported on s390x.
  31
  32
  33 Booting without bootindex parameter
  34 -----------------------------------
  35
  36 The QEMU guest firmware (the so-called s390-ccw bios) has also some rudimentary
  37 support for scanning through the available block devices. So in case you did
  38 not specify a boot device with the ``bootindex`` property, there is still a
  39 chance that it finds a bootable device on its own and starts a guest operating
  40 system from it. However, this scanning algorithm is still very rough and may
  41 be incomplete, so that it might fail to detect a bootable device in many cases.
  42 It is really recommended to always specify the boot device with the
  43 ``bootindex`` property instead.
  44
  45 This also means that you should avoid the classical short-cut commands like
  46 ``-hda``, ``-cdrom`` or ``-drive if=virtio``, since it is not possible to
  47 specify the ``bootindex`` with these commands. Note that the convenience
  48 ``-cdrom`` option even does not give you a real (virtio-scsi) CD-ROM device on
  49 s390x. Due to technical limitations in the QEMU code base, you will get a
  50 virtio-blk device with this parameter instead, which might not be the right
  51 device type for installing a Linux distribution via ISO image. It is
  52 recommended to specify a CD-ROM device via ``-device scsi-cd`` (as mentioned
  53 above) instead.
  54
  55
  56 Booting from a network device
  57 -----------------------------
  58
  59 Beside the normal guest firmware (which is loaded from the file ``s390-ccw.img``
  60 in the data directory of QEMU, or via the ``-bios`` option), QEMU ships with
  61 a small TFTP network bootloader firmware for virtio-net-ccw devices, too. This
  62 firmware is loaded from a file called ``s390-netboot.img`` in the QEMU data
  63 directory. In case you want to load it from a different filename instead,
  64 you can specify it via the ``-global s390-ipl.netboot_fw=filename``
  65 command line option.
  66
  67 The ``bootindex`` property is especially important for booting via the network.
  68 If you don't specify the the ``bootindex`` property here, the network bootloader
  69 firmware code won't get loaded into the guest memory so that the network boot
  70 will fail. For a successful network boot, try something like this::
  71
  72  qemu-system-s390x -netdev user,id=n1,tftp=...,bootfile=... \
  73                    -device virtio-net-ccw,netdev=n1,bootindex=1
  74
  75 The network bootloader firmware also has basic support for pxelinux.cfg-style
  76 configuration files. See the `PXELINUX Configuration page
  77 <https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration>`__
  78 for details how to set up the configuration file on your TFTP server.
  79 The supported configuration file entries are ``DEFAULT``, ``LABEL``,
  80 ``KERNEL``, ``INITRD`` and ``APPEND`` (see the `Syslinux Config file syntax
  81 <https://wiki.syslinux.org/wiki/index.php?title=Config>`__ for more
  82 information).