# NAME
-novaboot - A tool for booting various operating systems on various hardware or in qemu
+novaboot - Boots a locally compiled operating system on a remote
+target or in qemu
# SYNOPSIS
# DESCRIPTION
-This program makes booting of an operating system (e.g. NOVA or Linux)
-as simple as running a local program. It facilitates booting on local
-or remote hosts or in emulators such as qemu. Novaboot operation is
-controlled by command line options and by a so called novaboot script,
-which can be thought as a generalization of bootloader configuration
-files (see ["NOVABOOT SCRIPT SYNTAX"](#novaboot-script-syntax)). Based on this input,
-novaboot setups everything for the target host to boot the desired
-configuration, i.e. it generates the bootloader configuration file in
-the proper format, deploy the binaries and other needed files to
-required locations, perhaps on a remote boot server and reset the
-target host. Finally, target host's serial output is redirected to
-standard output if that is possible.
-
+This program makes booting of a locally compiled operating system (OS)
+(e.g. NOVA or Linux) on remote targets as simple as running a program
+locally. It automates things like copying OS images to a TFTP server,
+generation of bootloader configuration files, resetting of target
+hardware or redirection of target's serial line to stdin/out. Novaboot
+is highly configurable and it makes it easy to boot a single image on
+different targets or different images on a single target.
+
+Novaboot operation is controlled by command line options and by a so
+called novaboot script, which can be thought as a generalization of
+bootloader configuration files (see ["NOVABOOT SCRIPT SYNTAX"](#novaboot-script-syntax)).
Typical way of using novaboot is to make the novaboot script
executable and set its first line to _#!/usr/bin/env novaboot_. Then,
booting a particular OS configuration becomes the same as executing a
local program - the novaboot script.
-For example, with `novaboot` you can:
+Novaboot uses configuration files to, among other things, define
+command line options needed for different targets. Users typically use
+only the **-t**/**--target** command line option to select the target.
+Internally, this option expands to the pre-configured options.
+Configuration files are searched at multiple places, which allows to
+have per-system, per-user or per-project configurations. Configuration
+file syntax is described in section ["CONFIGURATION FILE"](#configuration-file).
+
+Simple examples of using `novaboot`:
-1. Run an OS in Qemu. This is the default action when no other action is
-specified by command line switches. Thus running `novaboot ./script`
-(or `./script` as described above) will run Qemu and make it boot the
-configuration specified in the `script`.
+1. Run an OS in Qemu. This is can be specified with the **--qemu** option.
+Thus running `novaboot --qemu myos` (or `./myos --qemu` as described
+above) will run Qemu and make it boot the configuration specified in
+the `myos` script.
2. Create a bootloader configuration file (currently supported
bootloaders are GRUB, GRUB2, ISOLINUX, Pulsar and U-Boot) and copy it
-with all other files needed for booting to a remote boot server.
+with all other files needed for booting to a remote boot server. Then
+use a TCP/IP-controlled relay/serial-to-TCP converter to reset the
+target and receive its serial output.
- ./script --server=192.168.1.1:/tftp --iprelay=192.168.1.2
+ ./myos --grub2 --server=192.168.1.1:/tftp --iprelay=192.168.1.2
- This command copies files to the TFTP server and uses
- TCP/IP-controlled relay to reset the target host and receive its
- serial output.
+3. Run DHCP and TFTP server on developer's machine to boot the target
+from it.
-3. Run DHCP and TFTP server on developer's machine to PXE-boot the target
-machine from it. E.g.
+ ./myos --dhcp-tftp
- ./script --dhcp-tftp
+ This is useful when no network infrastructure is in place and
+ the target is connected directly to developer's box.
- When a PXE-bootable machine is connected via Ethernet to developer's
- machine, it will boot the configuration described in the _script_.
-
-4. Create bootable ISO images. E.g.
+4. Create bootable ISO image.
novaboot --iso -- script1 script2
- The created ISO image will use ISOLINUX bootloader installed on it and
- the boot menu will allow selecting between _script1_ and _script2_
- configurations.
-
-Note that the options needed for a specific target can be stored in a
-["CONFIGURATION FILE"](#configuration-file). Then it is sufficient to use only the **-t**
-option to specify the name of the target.
+ The created ISO image will have ISOLINUX bootloader installed on it
+ and the boot menu will allow selecting between _script1_ and
+ _script2_ configurations.
# PHASES AND OPTIONS
Novaboot performs its work in several phases. Each phase can be
influenced by several command line options, certain phases can be
-skipped. The list of phases (in the execution order) and the
-corresponding options follow.
+skipped. The list of phases (in the execution order) is as follows.
+
+- 1. [Configuration reading](#configuration-reading-phase)
+- 2. [Command line processing](#command-line-processing-phase)
+- 3. [Script preprocessing](#script-preprocessing-phase)
+- 4. [File generation](#file-generation-phase)
+- 5. [Target connection](#target-connection-check)
+- 6. [File deployment](#file-deployment-phase)
+- 7. [Target power-on and reset](#target-power-on-and-reset-phase)
+- 8. [Interaction with the bootloader](#interaction-with-the-bootloader-on-the-target)
+- 9. [Target interaction](#target-interaction-phase)
+
+Each phase is described in the following sections together with the
+command line options that control it.
## Configuration reading phase
After starting, novaboot reads configuration files. Their content is
described in section ["CONFIGURATION FILE"](#configuration-file). By default,
-configuration is read from two locations. First from the configuration
-directory and second from `.novaboot` files along the path to the
-current directory. The later read files override settings from the
-former ones.
-
-Configuration directory is determined by the content of
-NOVABOOT\_CONFIG\_DIR environment variable defaulting to
+configuration is read from multiple locations. First from the system
+configuration directory (`/etc/novaboot.d/`), second from the user
+configuration file (`~/.config/novaboot`) and third from `.novaboot`
+files along the path to the current directory. Alternatively, a single
+configuration file specified with the **-c** switch or with the
+`NOVABOOT_CONFIG` environment variable is read. The latter read files
+override settings from the former ones.
+
+The system configuration directory is determined by the content of
+NOVABOOT\_CONFIG\_DIR environment variable and defaults to
`/etc/novaboot.d`. Files in this directory with names consisting
-solely from English letters, numbers, dashes '-' and underscores '\_'
+solely of English letters, numbers, dashes '-' and underscores '\_'
(note that dot '.' is not included) are read in alphabetical order.
-Then novaboot searches for files named `.novaboot` starting from the
+Then, the user configuration file is read from
+`$XDG_CONFIG_HOME/novaboot`. If `$XDG_CONFIG_HOME` environemnt
+variable is not set `~/.config/novaboot` is read instead.
+
+Finally, novaboot searches for files named `.novaboot` starting from the
directory of the novaboot script (or working directory, see bellow)
and continuing upwards up to the root directory. The found
configuration files are then read in the opposite order (i.e. from the
-root directory downwards). This allows to have, for example, user
-specific configuration in `~/.novaboot` and project specific one in
-`~/project/.novaboot`.
+root directory downwards). This allows to have, for example, a project
+specific configuration in `~/project/.novaboot`.
+
+Note the difference between `~/.config/novaboot` and `~/.novaboot`.
+The former one is read always, whereas the latter only when novaboot
+script or working directory is under the `$HOME` directory.
In certain cases, the location of the novaboot script cannot be
determined in this early phase. This happens either when the script is
- --dump-config
- Dump the current configuration to stdout end exits. Useful as an
+ Dump the current configuration to stdout end exit. Useful as an
initial template for a configuration file.
- -h, --help
- -t, --target=_target_
This option serves as a user configurable shortcut for other novaboot
- options. The effect of this option is the same as the options stored
- in the `%targets` configuration variable under key _target_. See
- also ["CONFIGURATION FILE"](#configuration-file).
+ options. The effect of this option is the same as specifying the
+ options stored in the `%targets` configuration variable under key
+ _target_. See also ["CONFIGURATION FILE"](#configuration-file).
+
+ When this option is not given, novaboot tries to determine the target
+ to use from either **NOVABOOT\_TARGET** environment variable or from
+ **$default\_target** configuration file variable.
## Script preprocessing phase
- --remote-expect=_string_
- Wait for reception of _string_ after establishing the the remote
- connection before continuing.
+ Wait for reception of _string_ after establishing the remote
+ connection.
+
+- --remote-expect-silent=_string_
+
+ The same as **--remote-expect** except that the remote output is not
+ echoed to stdout while waiting for the _string_. Everything after the
+ matched string is printed to stdout, so you may want to include line
+ end characters in the _string_ as well.
## File deployment phase
- --no-reset, --reset
- Disable/enable reseting of the target.
+ Disable/enable resetting of the target.
## Interaction with the bootloader on the target
Implementation of this option is currently tied to a particular board
that we use. It may be subject to changes in the future!
+- --no-uboot
+
+ Disable U-Boot interaction previously enabled with **--uboot**.
+
- --uboot-init
Command(s) to send the U-Boot bootloader before loading the images and
where name is one of _kernel_, _ramdisk_ or _fdt_ (flattened device
tree).
+ The default addresses are ${_name_\_addr\_r}, i.e. U-Boot environment
+ variables used by convention for this purpose.
+
+- --uboot-cmd=_command_
+
+ Specifies U-Boot command used to execute the OS. If the command
+ contains strings `$kernel_addr`, `$ramdisk_addr`, `$fdt_addr`,
+ these are replaced with the addresses configured with **--uboot-addr**.
+
+ The default value is
+
+ bootm $kernel_addr $ramdisk_addr $fdt_addr
+
+ or the `UBOOT_CMD` variable if defined in the novaboot script.
+
## Target interaction phase
In this phase, target's serial output is redirected to stdout and if
- --exiton=_string_
When _string_ is sent by the target, novaboot exits. This option can
- be specified multiple times.
+ be specified multiple times, in which case novaboot exits whenever
+ either of the specified strings is sent.
If _string_ is `-re`, then the next **--exiton**'s _string_ is
treated as regular expression. For example:
--exiton -re --exiton 'error:.*failed'
+- --exiton-re=_regex_
+
+ The same as --exiton -re --exiton _regex_.
+
+- --exiton-timeout=_seconds_
+
+ By default **--exiton** waits for the string match forever. When this
+ option is specified, "exiton" timeouts after the specifies number of
+ seconds and novaboot returns non-zero exit code.
+
- -i, --interactive
Setup things for interactive use of target. Your terminal will be
to the target and does no longer interrupt novaboot. Use "~~."
sequence to exit novaboot.
+- --no-interaction, --interaction
+
+ Skip resp. force target interaction phase. When skipped, novaboot exits
+ immediately when boot is initiated.
+
- --expect=_string_
When _string_ is received from the target, send the string specified
Lines starting with `uboot` represent U-Boot commands that are sent
to the target if **--uboot** option is given. Having a U-Boot line in
the novaboot script is the same as passing an equivalent
-**--uboot-init** option to novaboot.
+**--uboot-init** option to novaboot. The `uboot` keyword can be
+suffixed with timeout specification. The syntax is `uboot:Ns`, where
+`N` is the whole number of seconds. If the U-Boot command prompt does
+not appear before the timeout, novaboot fails. The default timeout is
+10 seconds.
Example (Linux):
Use specific qemu flags (can be overridden with **-q**).
+- UBOOT\_CMD
+
+ See ["--uboot-cmd"](#uboot-cmd).
+
- WVDESC
Description of the WvTest-compliant program.
# CONFIGURATION FILE
Novaboot can read its configuration from one or more files. By
-default, novaboot looks for files named `.novaboot` as described in
+default, novaboot looks for files in `/etc/novaboot.d`, file
+`~/.config/novaboot` and files named `.novaboot` as described in
["Configuration reading phase"](#configuration-reading-phase). Alternatively, configuration file
location can be specified with the **-c** switch or with the
NOVABOOT\_CONFIG environment variable. The configuration file has Perl
-syntax and should set values of certain Perl variables. The current
-configuration can be dumped with the **--dump-config** switch. Some
-configuration variables can be overridden by environment variables
-(see below) or by command line switches.
+syntax (i.e. it is better to put `1;` as the last line) and should set
+values of certain Perl variables. The current configuration can be
+dumped with the **--dump-config** switch. Some configuration variables
+can be overridden by environment variables (see below) or by command
+line switches.
Supported configuration variables include:
- $default\_target
Default target (see below) to use when no target is explicitly
- specified on command line with the **--target** option.
+ specified with the **--target** command line option or
+ **NOVABOOT\_TARGET** environment variable.
- %targets
then the following two commands are equivalent:
- ./script --server=boot:/tftproot --serial=/dev/ttyUSB0 --grub
- ./script -t mybox
+ ./myos --server=boot:/tftproot --serial=/dev/ttyUSB0 --grub
+ ./myos -t mybox
# ENVIRONMENT VARIABLES
Name of the novaboot configuration directory. When not specified
`/etc/novaboot.d` is used.
+- NOVABOOT\_TARGET
+
+ Name of the novaboot target to use. This overrides the value of
+ **$default\_target** from the configuration file and can be overriden
+ with the **--target** command line option.
+
- NOVABOOT\_BENDER
Defining this variable has the same meaning as **--bender** option.
projects / novaboot.git / blobdiff