# NAME
-novaboot - NOVA boot script interpreter
+novaboot - A tool for booting various operating systems on various hardware or in qemu
# SYNOPSIS
-__novaboot__ \[ options \] \[--\] script...
+**novaboot** --help
-__./script__ \[ options \]
+**novaboot** \[option\]... \[--\] script...
-__novaboot__ --help
+**./script** \[option\]...
# DESCRIPTION
-This program makes it easier to boot NOVA or other operating system
-(OS) in different environments. It reads a so called novaboot script
-and uses it either to boot the OS in an emulator (e.g. in qemu) or to
-generate the configuration for a specific bootloader and optionally to
-copy the necessary binaries and other needed files to proper
-locations, perhaps on a remote server. In case the system is actually
-booted, its serial output is redirected to standard output if that is
-possible.
-
-A typical way of using novaboot is to make the novaboot script
-executable and set its first line to _\#!/usr/bin/env novaboot_. Then,
+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.
+
+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.
-With `novaboot` you can:
+For example, with `novaboot` you can:
-1. Run NOVA in Qemu. This is the default action when no other action is
+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 with configuration
-specified in the _script_.
+(or `./script` as described above) will run Qemu and make it boot the
+configuration specified in the `script`.
2. Create a bootloader configuration file (currently supported
-bootloaders are GRUB, GRUB2 and Pulsar) and copy it with all files
-needed for booting another, perhaps remote, location.
+bootloaders are GRUB, GRUB2, ISOLINUX, Pulsar and U-Boot) and copy it
+with all other files needed for booting to a remote boot server.
- ./script --server --iprelay
+ ./script --server=192.168.1.1:/tftp --iprelay=192.168.1.2
- This command copies files to a TFTP server specified in the
- configuration file and uses TCP/IP-controlled relay to reset the test
- box and receive its serial output.
+ 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 PXE-boot NOVA from
-it. E.g.
+3. Run DHCP and TFTP server on developer's machine to PXE-boot the target
+machine from it. E.g.
./script --dhcp-tftp
When a PXE-bootable machine is connected via Ethernet to developer's
- machine, it will boot the configuration described in _script_.
+ machine, it will boot the configuration described in the _script_.
4. Create bootable ISO images. E.g.
novaboot --iso -- script1 script2
- The created ISO image will have GRUB bootloader installed on it and
+ The created ISO image will use ISOLINUX bootloader installed on it and
the boot menu will allow selecting between _script1_ and _script2_
configurations.
-# OPTIONS
+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.
-- \-a, --append=<parameters>
+# PHASES AND OPTIONS
- Appends a string to the root task's command line.
+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.
-- \-b, --bender
+## Configuration reading phase
- Boot bender tool before the kernel to find PCI serial ports.
+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.
-- \--build-dir=<directory>
+Configuration directory is determined by the content of
+NOVABOOT\_CONFIG\_DIR environment variable defaulting to
+`/etc/novaboot.d`. Files in this directory with names consisting
+solely from English letters, numbers, dashes '-' and underscores '\_'
+(note that dot '.' is not included) are read in alphabetical order.
- Overrides the default build directory location.
+Then 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`.
- The default build directory location is determined as follows:
+In certain cases, the location of the novaboot script cannot be
+determined in this early phase. This happens either when the script is
+read from the standard input or when novaboot is invoked explicitly as
+in the example ["4."](#4) above. In this case the current working
+directory is used as a starting point for configuration file search
+instead of the novaboot script directory.
- If there is a configuration file, the value specified in _$builddir_
- variable is used. Otherwise, if the current working directory is
- inside git work tree and there is `build` directory at the top of
- that tree, it is used. Otherwise, if directory `~/nul/build` exists,
- it is used. Otherwise, it is the directory that contains the first
- processed novaboot script.
+- -c, --config=_filename_
-- \-c, --config=<filename>
+ Use the specified configuration file instead of the default one(s).
- Use a different configuration file than the default one (i.e.
- `~/.novaboot`).
+## Command line processing phase
-- \-d, --dhcp-tftp
+- --dump-config
- Turns your workstation into a DHCP and TFTP server so that NOVA
- can be booted via PXE BIOS on a test machine directly connected by
- a plain Ethernet cable to your workstation.
+ Dump the current configuration to stdout end exits. Useful as an
+ initial template for a configuration file.
- The DHCP and TFTP servers require root privileges and `novaboot`
- uses `sudo` command to obtain those. You can put the following to
- _/etc/sudoers_ to allow running the necessary commands without
- asking for password.
+- -h, --help
- Cmnd_Alias NOVABOOT = /bin/ip a add 10.23.23.1/24 dev eth0, /bin/ip l set dev eth0 up, /usr/sbin/dhcpd -d -cf dhcpd.conf -lf dhcpd.leases -pf dhcpd.pid, /usr/sbin/in.tftpd --foreground --secure -v -v -v *, /usr/bin/touch dhcpd.leases
- your_login ALL=NOPASSWD: NOVABOOT
+ Print short (**-h**) or long (**--help**) 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).
+
+## Script preprocessing phase
+
+This phases allows to modify the parsed novaboot script before it is
+used in the later phases.
+
+- -a, --append=_parameters_
+
+ Append a string to the first `load` line in the novaboot script. This
+ can be used to append parameters to the kernel's or root task's
+ command line. This option can appear multiple times.
+
+- -b, --bender
+
+ Use `bender` chainloader. Bender scans the PCI bus for PCI serial
+ ports and stores the information about them in the BIOS data area for
+ use by the kernel.
+
+- --chainloader=_chainloader_
+
+ Specifies a chainloader that is loaded before the kernel and other
+ files specified in the novaboot script. E.g. 'bin/boot/bender
+ promisc'.
+
+- --dump
+
+ Print the modules to boot and their parameters after this phase
+ finishes. Then exit. This is useful for seeing the effect of other
+ options in this section.
+
+- -k, --kernel=`file`
+
+ Replace the first word on the first `load` line in the novaboot
+ script with `file`.
+
+- --scriptmod=_perl expression_
+
+ When novaboot script is read, _perl expression_ is executed for every
+ line (in $\_ variable). For example, `novaboot
+ \--scriptmod=s/sigma0/omega6/g` replaces every occurrence of _sigma0_
+ in the script with _omega6_.
+
+ When this option is present, it overrides _$script\_modifier_ variable
+ from the configuration file, which has the same effect. If this option
+ is given multiple times all expressions are evaluated in the command
+ line order.
+
+## File generation phase
+
+In this phase, files needed for booting are generated in a so called
+_build directory_ (see ["--build-dir"](#build-dir)). In most cases configuration
+for a bootloader is generated automatically by novaboot. It is also
+possible to generate other files using _heredoc_ or _"<"_ syntax in
+novaboot scripts. Finally, binaries can be generated in this phases by
+running `scons` or `make`.
+
+- --build-dir=_directory_
+
+ Overrides the default build directory location.
+
+ The default build directory location is determined as follows: If the
+ configuration file defines the `$builddir` variable, its value is
+ used. Otherwise, it is the directory that contains the first processed
+ novaboot script.
+
+ See also ["BUILDDIR"](#builddir) variable.
+
+- -g, --grub\[=_filename_\]
+
+ Generates grub bootloader menu file. If the _filename_ is not
+ specified, `menu.lst` is used. The _filename_ is relative to the
+ build directory (see **--build-dir**).
-- \--dump
+- --grub-preamble=_prefix_
- Prints the content of the novaboot script after removing comments and
- evaluating all _\--scriptmod_ expressions.
+ Specifies the _preable_ that is at the beginning of the generated
+ GRUB or GRUB2 config files. This is useful for specifying GRUB's
+ timeout.
-- \--dump-config
+- --prefix=_prefix_
- Dumps current configuration to stdout end exits. Useful as an initial
- template for a configuration file.
+ Specifies _prefix_ (e.g. `/srv/tftp`) that is put in front of every
+ file name in generated bootloader configuration files (or in U-Boot
+ commands).
-- \-g, --grub\[=_filename_\]
+ If the _prefix_ contains string $NAME, it will be replaced with the
+ name of the novaboot script (see also **--name**).
- Generates grub menu file. If the _filename_ is not specified,
- `menu.lst` is used. The _filename_ is relative to NUL build
- directory.
+ If the _prefix_ contains string $BUILDDIR, it will be replaced with
+ the build directory (see also **--build-dir**).
-- \--grub-prefix=_prefix_
+- --grub-prefix
- Specifies _prefix_ that is put before every file in GRUB's menu.lst.
- This overrides the value of _$server\_grub\_prefix_ from the
- configuration file.
+ Alias for **--prefix**.
-- \--grub2\[=_filename_\]
+- --grub2\[=_filename_\]
- Generate GRUB2 menuentry in _filename_. If _filename_ is not
- specified grub.cfg is used. The content of the menuentry can be
- customized by _$grub2\_prolog_ and _$server\_grub\_prefix_
- configuration variables.
+ Generate GRUB2 menu entry in _filename_. If _filename_ is not
+ specified `grub.cfg` is used. The content of the menu entry can be
+ customized with **--grub-preamble**, **--grub2-prolog** or
+ **--grub\_prefix** options.
- In order to use the the generated menuentry on your development
+ In order to use the the generated menu entry on your development
machine that uses GRUB2, append the following snippet to
- `/etc/grub.d/40\_custom` file and regenerate your grub configuration,
+ `/etc/grub.d/40_custom` file and regenerate your grub configuration,
i.e. run update-grub on Debian/Ubuntu.
if [ -f /path/to/nul/build/grub.cfg ]; then
source /path/to/nul/build/grub.cfg
fi
+- --grub2-prolog=_prolog_
+ Specifies text that is put at the beginning of the GRUB2 menu entry.
-- \-h, --help
+- -m, --make\[=make command\]
- Print short (__\-h__) or long (__\--help__) help.
+ Runs `make` to build files that are not generated by novaboot itself.
-- \--iprelay\[=addr or cmd\]
+- --name=_string_
- If no _cmd_ is given, use IP relay to reset the machine and to get
- the serial output. The IP address of the relay is given by _addr_
- parameter if specified or by $iprelay\_addr variable in the
- configuration file.
+ Use the name _string_ instead of the name of the novaboot script.
+ This name is used for things like a title of grub menu or for the
+ server directory where the boot files are copied to.
+
+- --no-file-gen
+
+ Do not run external commands to generate files (i.e. "<" syntax and
+ `run` keyword). This switch does not influence generation of files
+ specified with "<<WORD" syntax.
+
+- -p, --pulsar\[=mac\]
+
+ Generates pulsar bootloader configuration file named `config-_mac_`
+ The _mac_ string is typically a MAC address and defaults to
+ _novaboot_.
+
+- --scons\[=scons command\]
+
+ Runs `scons` to build files that are not generated by novaboot
+ itself.
+
+- --strip-rom
+
+ Strip _rom://_ prefix from command lines and generated config files.
+ The _rom://_ prefix is used by NUL. For NRE, it has to be stripped.
+
+- --gen-only
+
+ Exit novaboot after file generation phase.
+
+## Target connection check
+
+If supported by the target, the connection to it is made and it is
+checked whether the target is not occupied by another novaboot
+user/instance.
+
+- --amt=_"\[user\[:password\]@\]host\[:port\]_
- If _cmd_ is one of "on" or "off", the IP relay is used to press power
- button for a short (in case of "on") or long (in case of "off") time.
- Then, novaboot exits.
+ Use Intel AMT technology to control the target machine. WS management
+ is used to powercycle it and Serial-Over-Lan (SOL) for input/output.
+ The hostname or (IP address) is given by the _host_ parameter. If
+ _password_ is not specified, environment variable AMT\_PASSWORD is
+ used. The _port_ specifies a TCP port for SOL. If not specified, the
+ default is 16992. Default _user_ is admin.
- Note: This option is expected to work with HWG-ER02a IP relays.
+- --iprelay=_addr\[:port\]_
-- \-i, --iso\[=filename\]
+ Use TCP/IP relay and serial port to access the target's serial port
+ and powercycle it. The IP address of the relay is given by _addr_
+ parameter. If _port_ is not specified, it default to 23.
+
+ Note: This option is supposed to work with HWG-ER02a IP relays.
+
+- -s, --serial\[=device\]
+
+ Target's serial line is connected to host's serial line (device). The
+ default value for device is `/dev/ttyUSB0`.
+
+ The value of this option is exported in NB\_NOVABOOT environment
+ variable to all subprocesses run by `novaboot`.
+
+- --stty=_settings_
+
+ Specifies settings passed to `stty` invoked on the serial line
+ specified with **--serial** option. If this option is not given,
+ `stty` is called with `raw -crtscts -onlcr 115200` settings.
+
+- --remote-cmd=_cmd_
+
+ Command that mediates connection to the target's serial line. For
+ example `ssh server 'cu -l /dev/ttyS0'`.
+
+- --remote-expect=_string_
+
+ Wait for reception of _string_ after establishing the the remote
+ connection before continuing.
+
+## File deployment phase
+
+In some setups, it is necessary to copy the files needed for booting
+to a particular location, e.g. to a TFTP boot server or to the
+`/boot` partition.
+
+- -d, --dhcp-tftp
+
+ Turns your workstation into a DHCP and TFTP server so that the OS can
+ be booted via PXE BIOS (or similar mechanism) on the test machine
+ directly connected by a plain Ethernet cable to your workstation.
+
+ The DHCP and TFTP servers requires root privileges and `novaboot`
+ uses `sudo` command to obtain those. You can put the following to
+ _/etc/sudoers_ to allow running the necessary commands without asking
+ for password.
+
+ Cmnd_Alias NOVABOOT = /bin/ip a add 10.23.23.1/24 dev eth0, /bin/ip l set dev eth0 up, /usr/sbin/dhcpd -d -cf dhcpd.conf -lf dhcpd.leases -pf dhcpd.pid, /usr/sbin/in.tftpd --listen --secure -v -v -v --pidfile tftpd.pid *, /usr/bin/touch dhcpd.leases, /usr/bin/pkill --pidfile=dhcpd.pid, /usr/bin/pkill --pidfile=tftpd.pid
+ your_login ALL=NOPASSWD: NOVABOOT
+
+- --tftp
+
+ Starts a TFTP server on your workstation. This is similar to
+ **--dhcp-tftp** except that DHCP server is not started.
+
+ The TFTP server require root privileges and `novaboot` uses `sudo`
+ command to obtain those. You can put the following to _/etc/sudoers_
+ to allow running the necessary commands without asking for password.
+
+ Cmnd_Alias NOVABOOT = /usr/sbin/in.tftpd --listen --secure -v -v -v --pidfile tftpd.pid *, /usr/bin/pkill --pidfile=tftpd.pid
+ your_login ALL=NOPASSWD: NOVABOOT
+
+- --tftp-port=_port_
+
+ Port to run the TFTP server on. Implies **--tftp**.
+
+- --iso\[=filename\]
Generates the ISO image that boots NOVA system via GRUB. If no filename
is given, the image is stored under _NAME_.iso, where _NAME_ is the name
- of novaboot script (see also __\--name__).
+ of the novaboot script (see also **--name**).
-- \-I
+- --server\[=\[\[user@\]server:\]path\]
- This is an alias (see `%custom_options` below) defined in the default
- configuration. When used, it causes novaboot to use Michal's remotely
- controllable test bed.
+ Copy all files needed for booting to another location. The files will
+ be copied (by **rsync** tool) to the directory _path_. If the _path_
+ contains string $NAME, it will be replaced with the name of the
+ novaboot script (see also **--name**).
-- \-J
+- --rsync-flags=_flags_
- This is an alias (see `%custom_options` below) defined in the default
- configuration. When used, it causes novaboot to use another remotely
- controllable test bed.
+ Specifies which _flags_ are appended to `rsync` command line when
+ copying files as a result of _--server_ option.
-- \--on, --off
+- --concat
- Synonym for --iprelay=on/off.
+ If **--server** is used and its value ends with $NAME, then after
+ copying the files, a new bootloader configuration file (e.g. menu.lst)
+ is created at _path-wo-name_, i.e. the path specified by **--server**
+ with $NAME part removed. The content of the file is created by
+ concatenating all files of the same name from all subdirectories of
+ _path-wo-name_ found on the "server".
-- \--name=_string_
+- --ider
- Use the name _string_ instead of the name of the novaboot script.
- This name is used for things like a title of grub menu or for the
- server directory where the boot files are copied to.
+ Use Intel AMT technology for IDE redirection. This allows the target
+ machine to boot from novaboot created ISO image. Implies **--iso**.
+
+ The experimental `amtider` utility needed by this option can be
+ obtained from https://github.com/wentasah/amtterm.
-- \--no-file-gen
+## Target power-on and reset phase
- Do not generate files on the fly (i.e. "<" syntax) except for the
- files generated via "<<WORD" syntax.
+At this point, the target is reset (or switched on/off). There is
+several ways how this can be accomplished. Resetting a physical target
+can currently be accomplished by the following options: **--amt**,
+**--iprelay**, **--reset-cmd**.
-- \-p, --pulsar\[=mac\]
+- --on, --off
- Generates pulsar bootloader configuration file whose name is based on
- the MAC address specified either on the command line or taken from
- _.novaboot_ configuration file.
+ Switch on/off the target machine and exit. The script (if any) is
+ completely ignored. Currently it works only with **--iprelay** or
+ **--amt**.
-- \-Q, --qemu=_qemu-binary_
+- -Q, --qemu\[=_qemu-binary_\]
- Use specific version of qemu binary. The default is 'qemu'.
+ Boot the configuration in qemu. Optionally, the name of qemu binary
+ can be specified as a parameter.
-- \--qemu-append=_flags_
+- --qemu-append=_flags_
Append _flags_ to the default qemu flags (QEMU\_FLAGS variable or
`-cpu coreduo -smp 2`).
-- \-q, --qemu-flags=_flags_
+- -q, --qemu-flags=_flags_
Replace the default qemu flags (QEMU\_FLAGS variable or `-cpu coreduo
- -smp 2`) with _flags_ specified here.
+ \-smp 2`) with _flags_ specified here.
-- \--rsync-flags=_flags_
+- --reset-cmd=_cmd_
- Specifies which _flags_ are appended to `rsync` command line when
- copying files as a result of _\--server_ option.
+ Command that resets the target.
-- \--scons\[=scons command\]
+## Interaction with the bootloader on the target
- Runs _scons_ to build files that are not generated by novaboot
- itself.
+- --uboot\[=_prompt_\]
-- \--scriptmod=_perl expression_
+ Interact with U-Boot bootloader to boot the thing described in the
+ novaboot script. _prompt_ specifies the U-Boot's prompt (default is
+ "=> ", other common prompts are "U-Boot> " or "U-Boot# ").
+ Implementation of this option is currently tied to a particular board
+ that we use. It may be subject to changes in the future!
- When novaboot script is read, _perl expression_ is executed for every
- line (in $\_ variable). For example, `novaboot
- --scriptmod=s/sigma0/omega6/g` replaces every occurrence of _sigma0_
- in the script with _omega6_.
+- --uboot-init
- When this option is present, it overrides _$script\_modifier_ variable
- from the configuration file, which has the same effect. If this option
- is given multiple times all expressions are evaluated in the command
- line order.
+ Command(s) to send the U-Boot bootloader before loading the images and
+ booting them. This option can be given multiple times. After sending
+ commands from each option novaboot waits for U-Boot _prompt_.
-- \--server\[=\[\[user@\]server:\]path\]
+ If the command contains string _$NB\_MYIP_ then this string is
+ replaced by IPv4 address of eth0 interface.
- Copy all files needed for booting to a server (implies __\-g__ unless
- __\--grub2__ is given). The files will be copied to the directory
- _path_. If the _path_ contains string $NAME, it will be replaced
- with the name of the novaboot script (see also __\--name__).
+- --uboot-addr _name_=_address_
- Additionally, if $NAME is the last component of the _path_, a file
- named _path_/menu.lst (with $NAME removed from the _path_) will be
- created on the server by concatenating all _path_/\*/menu.lst (with
- $NAME removed from the _path_) files found on the server.
+ Load address of U-Boot's `tftpboot` command for loading _name_,
+ where name is one of _kernel_, _ramdisk_ or _fdt_ (flattened device
+ tree).
-- \-s, --serial\[=device\]
+## Target interaction phase
- Use serial line to control GRUB bootloader and to get the serial
- output of the machine. The default value is /dev/ttyUSB0.
+In this phase, target's serial output is redirected to stdout and if
+stdin is a TTY, it is redirected to the target's serial input allowing
+interactive work with the target.
-- \--strip-rom
+- --exiton=_string_
- Strip _rom://_ prefix from command lines and generated config files.
- This is needed for NRE.
+ When _string_ is sent by the target, novaboot exits. This option can
+ be specified multiple times.
+
+ If _string_ is `-re`, then the next **--exiton**'s _string_ is
+ treated as regular expression. For example:
+
+ --exiton -re --exiton 'error:.*failed'
+
+- -i, --interactive
+
+ Setup things for interactive use of target. Your terminal will be
+ switched to raw mode. In raw mode, your system does not process input
+ in any way (no echoing of entered characters, no interpretation
+ special characters). This, among others, means that Ctrl-C is passed
+ to the target and does no longer interrupt novaboot. Use "~~."
+ sequence to exit novaboot.
+
+- --expect=_string_
+
+ When _string_ is received from the target, send the string specified
+ with the subsequent **--send\*** option to the target.
+
+- --expect-re=_regex_
+
+ When target's output matches regular expression _regex_, send the
+ string specified with the subsequent **--send\*** option to the target.
+
+- --expect-raw=_perl-code_
+
+ Provides direct control over Perl's Expect module.
+
+- --send=_string_
+
+ Send _string_ to the target after the previously specified
+ **--expect\*** was matched in the target's output. The _string_ may
+ contain escape sequences such as "\\n".
+
+ Note that _string_ is actually interpreted by Perl, so it can contain
+ much more that escape sequences. This behavior may change in the
+ future.
+
+ Example: `--expect='login: ' --send='root\n'`
+
+- --sendcont=_string_
+
+ Similar to **--send** but continue expecting more input.
+
+ Example: `--expect='Continue?' --sendcont='yes\n'`
# NOVABOOT SCRIPT SYNTAX
-The syntax tries to mimic POSIX shell syntax. The syntax is defined with the following rules.
+The syntax tries to mimic POSIX shell syntax. The syntax is defined
+with the following rules.
-Lines starting with "\#" are ignored.
+Lines starting with "#" and empty lines are ignored.
Lines that end with "\\" are concatenated with the following line after
removal of the final "\\" and leading whitespace of the following line.
-Lines in the form _VARIABLE=..._ (i.e. matching '^\[A-Z\_\]+=' regular
-expression) assign values to internal variables. See VARIABLES
+Lines of the form _VARIABLE=..._ (i.e. matching '^\[A-Z\_\]+=' regular
+expression) assign values to internal variables. See ["VARIABLES"](#variables)
section.
-Otherwise, the first word on the line represents the filename
-(relative to the build directory (see _\--build-dir_) of the module to
-load and the remaining words are passed as the command line
-parameters.
-
-When the line ends with "<<WORD" then the subsequent lines until the
-line containing only WORD are copied literally to the file named on
-that line.
-
-When the line ends with "< CMD" the command CMD is executed with
-`/bin/sh` and its standard output is stored in the file named on that
-line. The SRCDIR variable in CMD's environment is set to the absolute
-path of the directory containing the interpreted novaboot script.
-
-Example:
- \#!/usr/bin/env novaboot
- WVDESC=Example program
- bin/apps/sigma0.nul S0\_DEFAULT script\_start:1,1 \\
- verbose hostkeyb:0,0x60,1,12,2
- bin/apps/hello.nul
- hello.nulconfig <<EOF
- sigma0::mem:16 name::/s0/log name::/s0/timer name::/s0/fs/rom ||
- rom://bin/apps/hello.nul
- EOF
-
-This example will load three modules: sigma0.nul, hello.nul and
-hello.nulconfig. sigma0 gets some command line parameters and
-hello.nulconfig file is generated on the fly from the lines between
-<<EOF and EOF.
+Lines starting with `load` keyword represent modules to boot. The
+word after `load` is a file name (relative to the build directory
+(see **--build-dir**) of the module to load and the remaining words are
+passed to it as the command line parameters.
+
+When the `load` line ends with "<<WORD" then the subsequent lines
+until the line containing solely WORD are copied literally to the file
+named on that line. This is similar to shell's heredoc feature.
+
+When the `load` line ends with "< CMD" then command CMD is executed
+with `/bin/sh` and its standard output is stored in the file named on
+that line. The SRCDIR variable in CMD's environment is set to the
+absolute path of the directory containing the interpreted novaboot
+script.
+
+Lines starting with `run` keyword contain shell commands that are run
+during file generation phase. This is the same as the "< CMD" syntax
+for `load` keyboard except that the command's output is not
+redirected to a file. The ordering of commands is the same as they
+appear in the novaboot script.
+
+Example (Linux):
+
+ #!/usr/bin/env novaboot
+ load bzImage console=ttyS0,115200
+ run make -C buildroot
+ load rootfs.cpio < gen_cpio buildroot/images/rootfs.cpio "myapp->/etc/init.d/S99myapp"
+
+Example (NOVA User Land - NUL):
+
+ #!/usr/bin/env novaboot
+ WVDESC=Example program
+ load bin/apps/sigma0.nul S0_DEFAULT script_start:1,1 \
+ verbose hostkeyb:0,0x60,1,12,2
+ load bin/apps/hello.nul
+ load hello.nulconfig <<EOF
+ sigma0::mem:16 name::/s0/log name::/s0/timer name::/s0/fs/rom ||
+ rom://bin/apps/hello.nul
+ EOF
+
+This example will load three modules: `sigma0.nul`, `hello.nul` and
+`hello.nulconfig`. sigma0 receives some command line parameters and
+`hello.nulconfig` file is generated on the fly from the lines between
+`<<EOF` and `EOF`.
## VARIABLES
The following variables are interpreted in the novaboot script:
+- BUILDDIR
+
+ Novaboot chdir()s to this directory before file generation phase. The
+ directory name specified here is relative to the build directory
+ specified by other means (see ["--build-dir"](#build-dir)).
+
+- EXITON
+
+ Assigning this variable has the same effect as specifying ["--exiton"](#exiton)
+ option.
+
+- HYPERVISOR\_PARAMS
+
+ Parameters passed to hypervisor. The default value is "serial", unless
+ overridden in configuration file.
+
+- KERNEL
+
+ The kernel to use instead of the hypervisor specified in the
+ configuration file with the `$hypervisor` variable. The value should
+ contain the name of the kernel image as well as its command line
+ parameters. If this variable is defined and non-empty, the variable
+ HYPERVISOR\_PARAMS is not used.
+
+- QEMU
+
+ Use a specific qemu binary (can be overridden with **-Q**) and flags
+ when booting this script under qemu. If QEMU\_FLAGS variable is also
+ specified flags specified in QEMU variable are replaced by those in
+ QEMU\_FLAGS.
+
+- QEMU\_FLAGS
+
+ Use specific qemu flags (can be overridden with **-q**).
+
- WVDESC
- Description of the wvtest-compliant program.
+ Description of the WvTest-compliant program.
- WVTEST\_TIMEOUT
is necessary to specify this for long running tests that produce no
intermediate output.
-- QEMU\_FLAGS
-
- Use specific qemu flags (can be overriden by __\-q__).
-
-- HYPERVISOR\_PARAMS
-
- Parameters passed to hypervisor. The default value is "serial", unless
- overriden in configuration file.
+# CONFIGURATION FILE
-- KERNEL
+Novaboot can read its configuration from one or more files. By
+default, novaboot looks for 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.
- The kernel to use instead of NOVA hypervisor specified in the
- configuration file. The value should contain the name of the kernel
- image as well as its command line parameters. If this variable is
- defined and non-empty, the variable HYPERVISOR\_PARAMS is not used.
+Supported configuration variables include:
-# CONFIGURATION FILE
+- $builddir
-novaboot can read its configuration from ~/.novaboot file (or another
-file specified with __\-c__ parameter or NOVABOOT\_CONFIG environment
-variable). It is a file with perl syntax, which sets values of certain
-variables. The current configuration can be dumped with
-__\--dump-config__ switch. Use
+ Build directory location relative to the location of the configuration
+ file.
- novaboot --dump-config > ~/.novaboot
+- $default\_target
-to create a default configuration file and modify it to your needs.
-Some configuration variables can be overriden by environment variables
-(see below) or by command line switches.
+ Default target (see below) to use when no target is explicitly
+ specified on command line with the **--target** option.
-Documentation of some configuration variables follows:
+- %targets
-- @chainloaders
+ Hash of target definitions to be used with the **--target** option. The
+ key is the identifier of the target, the value is the string with
+ command line options. For instance, if the configuration file contains:
- Custom chainloaders to load before hypervisor and files specified in
- novaboot script. E.g. ('bin/boot/bender promisc', 'bin/boot/zapp').
+ $targets{'mybox'} = '--server=boot:/tftproot --serial=/dev/ttyUSB0 --grub',
-- %custom\_options
+ then the following two commands are equivalent:
- Defines custom command line options that can serve as aliases for
- other options. E.g. 'S' => '--server=boot:/tftproot
- \--serial=/dev/ttyUSB0'.
+ ./script --server=boot:/tftproot --serial=/dev/ttyUSB0 --grub
+ ./script -t mybox
# ENVIRONMENT VARIABLES
- NOVABOOT\_CONFIG
- A name of default novaboot configuration file.
+ Name of the novaboot configuration file to use instead of the default
+ one(s).
-- NOVABOOT\_BENDER
+- NOVABOOT\_CONFIG\_DIR
- Defining this variable has the same meaning as __\--bender__ option.
+ Name of the novaboot configuration directory. When not specified
+ `/etc/novaboot.d` is used.
-- NOVABOOT\_IPRELAY
+- NOVABOOT\_BENDER
- The IP address (and optionally the port) of the IP relay. This
- overrides $iprelay\_addr variable from the configuration file.
+ Defining this variable has the same meaning as **--bender** option.
# AUTHORS