Boot Action Reference

The boot action is used to cause the device to boot using the deployed files. Depending on the parameters in the job definition, this could be by executing a command on the dispatcher (for example /usr/bin/qemu-system-x86_64) or by connecting to the device over serial or ssh. Depending on the power state of the device and the device configuration, the device may be powered up or reset to provoke the boot.

Every boot action must specify a method which is used to determine how to boot the deployed files on the device. Depending on the method, other parameters will be required.

Boot actions which result in a POSIX type login or shell must specify a list of expected prompts which will be matched against the output to determine the endpoint of the boot process. There are no default prompts, the test writer is responsible for providing a list of all possible prompts.

See also

prompts

auto_login

Some systems require the test job to specify a username and optionally a password to login. These values must be specified in the test job submission. If the system boots directly to a prompt without needing a login, the auto_login details can be omitted from the test job submission.

Note

The test job submission uses auto_login with underscore.

login_prompt

The prompt to match when the system requires a login. This prompt needs to be unique across the entire boot sequence, so typically includes : and should be quoted. If the hostname of the device is included in the prompt, this can be included in the login_prompt:

auto_login:
  login_prompt: 'login:'
  username: root

Note

If login_prompt is not matched during boot LAVA will send control characters to the shell “thinking” that the kernel alert happened which may result in incorrect login but after it recognizes the Login incorrect message it will automatically try to log in using provided credentials.

username

Whenever a login_prompt is specified, a username will also be required. The username should either be root or a user with sudo access without needing a password.

password_prompt

If the login requires a password as well as a username, the password_prompt must be specified:

auto_login:
  login_prompt: 'login:'
  username: root
  password_prompt: 'Password:'
  password: rootme

Note

If password_prompt is not matched during login or password is required but not provided LAVA will recognize the Login timed out message, stop the execution of the job and log the error.

password

Whenever a password_prompt is specified, a password will also be required.

login_commands

A list of arbitrary login_commands can be run after the initial login and before setting the shell prompt. This is typically used to make a regular user become root with su. For example:

auto_login:
  login_prompt: 'login:'
  username: user
  password_prompt: 'Password:'
  password: pass
  login_commands:
    - sudo su

Note

No interactive input such as a password can be provided with the list of login_commands.

prompts

After login (or directly from boot if no login is required), LAVA needs to match the first prompt offered by the booted system. The full list of possible prompts must be specified by the test writer in the test job submission.

Each prompt needs to be unique across the entire boot sequence, so typically includes : and needs to be quoted. If the hostname of the device is included in the prompt, this can be included in the prompt:

Caution

Take care with the specified prompts. Prompt strings which do not include enough characters can match early, resulting in a failed login. Prompt strings which include extraneous characters may fail to match for all test jobs. Avoid prompt elements which are user-specific, e.g. $ indicates an unprivileged user in some shells and # indicates the superuser. ~ indicates the home directory in some shells. In general, the prompt string should include and usually end with a colon : or a colon and space.

- boot:
    prompts:
      - 'root@debian:'

When using the lxc protocol, the hostname element of the prompt will vary:

- boot:
    prompts:
      - 'root@(.*):'

When using a ramdisk, the prompt is likely to need to contain brackets which will need to be escaped:

- boot:
    prompts:
    # escape the brackets to ensure that the prompt does not match
    # kernel debug lines which may mention initramfs
    - '\(initramfs\)'

connection-namespace

When using namespaces in job definition, you can reuse the existing serial connection from another namespace via connection-namespace parameter. Example:

actions:
- deploy:
    namespace: boot1
# ...
- boot:
    namespace: boot1
# ...
- test:
    namespace: boot1
# ...
- boot:
    namespace: boot2
    connection-namespace: boot1
# ...
- test:
    namespace: boot2
# ...

commands

One of the key definitions in the device type template for each device is the list(s) of boot commands that the device needs. These are sets of specific commands that will be run to boot the device to start a test. The definitions will typically include placeholders which LAVA will substitute with dynamic data as necessary. For example, the full path to a tftp kernel image will be expanded to include a job-specific temporary directory when a job is started.

As a simple example from a U-Boot template:

- setenv autoload no
- setenv initrd_high '0xffffffff'
- setenv fdt_high '0xffffffff'
- setenv loadkernel 'tftp {KERNEL_ADDR} {KERNEL}'
- setenv loadinitrd 'tftp {RAMDISK_ADDR} {RAMDISK}; setenv initrd_size ${filesize}'
- setenv loadfdt 'tftp {DTB_ADDR} {DTB}'
- setenv bootcmd 'run loadkernel; run loadinitrd; run loadfdt; {BOOTX}'
- boot

Note

In some cases, the boot commands list in the template may not provide all of the commands used; lines will also be generated from other data in the template. For example: the command setenv kernel_addr_r '0x82000000' might be generated from the load addresses which match the type of kernel being deployed.

When a test is started, the appropriate list of commands will be selected. LAVA then substitutes the placeholders in the list to generate a complete command list. The final parsed and expanded boot commands used for a test are reported in the logs for that test job, e.g.:

Parsed boot commands: setenv autoload no; setenv initrd_high '0xffffffff';
setenv fdt_high '0xffffffff'; setenv kernel_addr_r '0x82000000'; setenv
initrd_addr_r '0x83000000'; setenv fdt_addr_r '0x88000000'; setenv loadkernel
'tftp ${kernel_addr_r} 158349/tftp-deploy-Fo78o6/vmlinuz'; setenv loadinitrd
'tftp ${initrd_addr_r} 158349/tftp-deploy-Fo78o6/ramdisk.cpio.gz.uboot; setenv
initrd_size ${filesize}'; setenv loadfdt 'tftp ${fdt_addr_r}
158349/tftp-deploy-Fo78o6/am335x-boneblack.dtb'; setenv bootargs
'console=ttyO0,115200n8 root=/dev/ram0  ip=dhcp'; setenv bootcmd 'dhcp; setenv
serverip 10.3.1.1; run loadkernel; run loadinitrd; run loadfdt; bootz
0x82000000 0x83000000 0x88000000'; boot

Specifying commands in full

During testing and development, it can sometimes be useful to use a different set of boot commands instead of what is listed in the jinja2 template for the device-type. This allows test writers to change boot commands beyond the scope of existing overrides. To work sensibly in the LAVA environment, these commands will still need to include the placeholders such that temporary paths etc. can be substituted in when the test job is started.

In this example (for an x86 test machine using iPXE), the commands change the root argument to the kernel to boot from a SATA drive which has been configured separately. (For example, by the admins or by test writers from a hacking session.)

- boot:
    commands:
      - dhcp net0
      - set console console=ttyS0,115200n8 lava_mac={LAVA_MAC}
      - set extraargs ip=dhcp root=/dev/sda1 rw
      - kernel tftp://{SERVER_IP}/{KERNEL} ${extraargs} ${console}
      - initrd tftp://{SERVER_IP}/{RAMDISK}
      - boot

Caution

This support is only recommended for use for corner cases and administrator-level debugging. Accordingly, LAVA will raise a warning each time this support is used. Abuse of this support can potentially stop devices from working in subsequent tests, or maybe even damage them permanently - be careful!

If the commands are to be used regularly, file a bug requesting that a label is created in the templates for this set of commands. Alternatively, the bug report can request a new override to make the existing labels more flexible.

method

The boot method determines how the device is booted and which commands and prompts are used to determine a successful boot.

fastboot

The fastboot boot method takes no arguments or parameters.

grub

The grub boot method takes no arguments or parameters.

- boot:
    method: grub
    commands: ramdisk

grub-efi

The grub-efi boot method takes no arguments or parameters. However, in most cases, starting Grub from UEFI requires using the uefi-menu as well.

- boot:
    method: grub-efi
    commands: nfs

Download or view mustang-grub-efi.yaml

Note

Admins can refer to the mustang-grub-efi.jinja2 template for an example of how to make selections from a UEFI menu to load Grub. See Device type templates.

ipxe

The ipxe boot method takes no arguments or parameters.

- boot:
   method: ipxe
   commands: ramdisk
   prompts:
   - 'root@debian:~#'
   - '/ #'

lxc

See also

LXC protocol

- boot:
   namespace: tlxc
   prompts:
   - 'root@(.*):/#'
   timeout:
     minutes: 5
   method: lxc

LXC Boot example

- boot:
   namespace: droid
   prompts:
   - 'root@(.*):/#'
   timeout:
     minutes: 5
   method: fastboot
   failure_retry: 2
   connection: lxc

 - boot:
     method: grub
     commands: ramdisk
     timeout:
         minutes: 50
     prompts:
      - 'root@genericarmv8:~#'
      - '/ #'

qemu

The qemu method is used to boot the downloaded image from the deployment action using QEMU. This runs the QEMU command line on the dispatcher. Only certain elements of the command line are available for modification using the job context. The available values can vary depending on local admin configuration. For example, many admins restrict the available memory of each QEMU device, so the memory option in the job context may be ignored.

context:
  arch: aarch64
  memory: 2048
  # comment out or change to user if the dispatcher does not support bridging.
  # netdevice: tap
  extra_options:
  - -smp
  - 1
  - -global
  - virtio-blk-device.scsi=off
  - -device virtio-scsi-device,id=scsi
  - --append "console=ttyAMA0 root=/dev/vda rw"

The version of qemu installed on the dispatcher is a choice made by the admin. Generally, this will be the same as the version of qemu available from Debian in the same suite as the rest of the packages installed on the dispatcher, e.g. jessie. Information on the available versions of qemu in Debian is available at http://tracker.debian.org/qemu

media

When booting a QEMU image file directly, the media needs to be specified as tmpfs.

- boot:
    method: qemu
    media: tmpfs

qemu-nfs

The qemu-nfs method is used to boot a downloaded kernel with a root filesystem deployed on the worker. Only certain elements of the command line are available for modification using the job context. The available values can vary depending on local admin configuration. For example, many admins restrict the available memory of each QEMU device, so the memory option in the job context may be ignored.

The version of qemu installed on the dispatcher is a choice made by the admin. Generally, this will be the same as the version of qemu available from Debian in the same suite as the rest of the packages installed on the dispatcher, e.g. jessie. Information on the available versions of qemu in Debian is available at http://tracker.debian.org/qemu

QEMU can be used with an NFS using the qemu-nfs method and the nfs media:

      minutes: 4
    method: qemu-nfs
    media: nfs
    connection: serial
    auto_login:
      login_prompt: 'login:'

See also

boot method qemu.

When using qemu-nfs, the hostname element of the prompt will vary according to the worker running QEMU:

- test:

media

When booting a QEMU image using NFS, the media needs to be specified as nfs.

      minutes: 4
    method: qemu-nfs
    media: nfs
    connection: serial
    auto_login:
      login_prompt: 'login:'

qemu-iso

The qemu-iso method is used to boot the downloaded installer from the deployment action using QEMU. This runs the QEMU command line on the dispatcher. Only certain elements of the command line are available for modification using the job context.

The version of qemu installed on the dispatcher is a choice made by the admin. Generally, this will be the same as the version of qemu available from Debian in the same suite as the rest of the packages installed on the dispatcher, e.g. jessie. Information on the available versions of qemu in Debian is available at http://tracker.debian.org/qemu

- boot:
   method: qemu-iso
   media: img
   timeout:
     minutes: 20
   connection: serial
   auto_login:
     login_prompt: 'login:'
     username: root
     password_prompt: 'Password:'
     password: root
   prompts:
   - 'root@debian:~#'

media

When booting an installer using QEMU, the media needs to be specified as img

- boot:
    method: qemu-iso
    media: img

transfer_overlay

An overlay is a tarball of scripts which run the LAVA Test Shell for the test job. The tarball also includes the git clones of the repositories specified in the test job submission and the LAVA helper scripts. Normally, this overlay is integrated into the test job automatically. In some situations, for example when using a command list to specify an alternative rootfs, it is necessary to transfer the overlay from the worker to the device using commands within the booted system prior to starting to run the test shell.

Some overlay tarballs can be quite large. The LAVA TestShell helpers are tiny shell scripts but the git repositories cloned for your test shell definitions can become large over time. Additionally, if your test shell definition clones the git repo of source code, those clones will also appear in the overlay tarball.

Note

The situations where transfer_overlay is useful tend to also require restricting the test job to specific devices of a particular device type. This needs to be arranged with the lab admins who can create suitable device tags which will need to be specified in all test job definitions.

See also

Secondary media which is more flexible but slower.

The overlay is transferred before any test shell operations can occur, so the method of transferring and then unpacking the overlay must work without any further setup of the rootfs. All dependencies must be pre-installed and all configuration must be in place (possibly using a hacking session). This includes the network configuration - the worker offers an apache host to download the overlay and LAVA can populate the URL but the device must automatically configure the networking immediately upon boot and the network must work straight away.

transfer_overlay:
  download_command: wget -S --progress=dot:giga
  unpack_command: tar -C / -xzf

Note

The -C / command to tar is essential or the test shell will not be able to start. The overlay will use gzip compresssion, so pass the z option to tar.

Deployment differences

The -S --progress=dot:giga options to wget in the example above optimise the output for serial console logging to avoid wasting line upon line of progress percentage dots. If the system uses busybox, these options may not be supported by the version of wget on the device.

Some systems do not store the current time between boots. The --warning no-timestamp option is a useful addition for tar for those systems but note that busybox tar does not support this option.

The download_command and the unpack_command can include one or more shell commands. However, as with the test shell definitions, avoid using redirects (> or >>) or other complex shell syntax. This example changes to /tmp to ensure there is enough writeable space for the download.

transfer_overlay:
   download_command: cd /tmp ; wget
   unpack_command: tar -C / -xzf

u-boot

The u-boot method boots the downloaded files using U-Boot commands.

commands

The predefined set of U-Boot commands into which the location of the downloaded files can be substituted (along with details like the SERVERIP and NFS location, where relevant). See the device configuration for the complete set of commands.

Certain elements of the command line are available for modification using the job context. The available values vary by device type.

type

Caution

This support is deprecated and has been replaced by kernel type in the deploy action.

The type of boot, dependent on the U-Boot configuration. This needs to match the supported boot types in the device configuration, e.g. it may change the load addresses passed to U-Boot.

- boot:
  method: u-boot
  commands: nfs
  type: bootz
  prompts:
    - 'root@debian:~#'

uefi-menu

The uefi-menu method selects a pre-defined menu in the UEFI configuration for the device. In most cases, this is used to execute a different bootloader. For example, a fastboot device can execute fastboot from a menu item or a device could execute an PXE menu item to download and execute Grub.

Caution

Although it is possible to create new menu entries in UEFI each time a test job starts, this has proven to be unreliable on both of the device types tested so far. If the build of UEFI is not able to download a bootloader using PXE, then experiment with creating a UEFI menu item which is able to execute a local file and have a build of Grub on local storage. Build the grub binary using grub-mkstandalone to ensure that all modules are available.

UEFI menus will renumber themselves each time a new item is added or removed, so LAVA must be able to match the description of the menu item and then identify the correct selector to be able to send the correct character to execute that menu option. This means that the admins must create the same menu structures on each device of the same device type and correlate the text content of the menu with the jinja2 templates.

To use uefi-menu, the device must offer a menu from which items can be selected using a standard regular expression: 'a-zA-Z0-9\s\:', for example:

[1] bootloader
[2] boot from eMMC
[3] Boot Manager
[4] Reboot

The device type template would need to specify the separator (whitespace in the example) as well as how to identify the item matching the requested selector:

item_markup:
  - "["
  - "]"
item_class: '0-9'
separator: ' '

This allows LAVA to match a menu item matching \[[0-9]\] ['a-zA-Z0-9\s\:'] and select the correct selector when the menu item string matches one (and only one) line output by the UEFI menu. In this example, the selector must be a digit.

The template must then also specify which menu item to select, according to the commands set in the testjob:

method: uefi-menu
commands: fastboot

The template would then need:

fastboot:
- select:
    items:
     - 'boot from eMMC'