# SYNOPSIS
-__novaboot__ --help
+**novaboot** --help
-__novaboot__ \[option\]... \[--\] script...
+**novaboot** \[option\]... \[--\] script...
-__./script__ \[option\]...
+**./script** \[option\]...
# DESCRIPTION
(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, Pulsar and U-Boot) and copy it with all
-other files needed for booting to a remote boot server.
+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=192.168.1.1:/tftp --iprelay=192.168.1.2
serial output.
3. Run DHCP and TFTP server on developer's machine to PXE-boot the target
-host from it. E.g.
+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.
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__
+["CONFIGURATION FILE"](#configuration-file). Then it is sufficient to use only the **-t**
option to specify the name of the target.
# PHASES AND OPTIONS
Novaboot performs its work in several phases. Each phase can be
-influenced by several options, certain phases can be skipped. The list
-of phases (in the execution order) and the corresponding options
-follow.
+influenced by several command line options, certain phases can be
+skipped. The list of phases (in the execution order) and the
+corresponding options follow.
## Configuration reading phase
-After starting, novaboot reads configuration files. By default, it
-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 configuration files are read in
-order from the root directory downwards with latter files overriding
-settings from the former ones.
+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
+`/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.
+
+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`.
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
-and options precede the script name, as in the example ["4."](#4) above.
-In this case the current working directory is used as a starting point
-for configuration file search.
+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.
- -c, --config=_filename_
- -h, --help
- Print short (__-h__) or long (__--help__) help.
+ Print short (**-h**) or long (**--help**) help.
- -t, --target=_target_
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. Can appear multiple times.
+ command line. This option can appear multiple times.
- -b, --bender
- --chainloader=_chainloader_
- Chainloader that is loaded before the kernel and other files specified
- in the novaboot script. E.g. 'bin/boot/bender promisc'.
+ Specifies a chainloader that is loaded before the kernel and other
+ files specified in the novaboot script. E.g. 'bin/boot/bender
+ promisc'.
- --dump
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__).
+ build directory (see **--build-dir**).
- --grub-preamble=_prefix_
GRUB or GRUB2 config files. This is useful for specifying GRUB's
timeout.
-- --grub-prefix=_prefix_
+- --prefix=_prefix_
- Specifies _prefix_ that is put in front of every file name in GRUB's
- `menu.lst`. The default value is the absolute path to the build directory.
+ 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).
If the _prefix_ contains string $NAME, it will be replaced with the
- name of the novaboot script (see also __--name__).
+ name of the novaboot script (see also **--name**).
+
+ If the _prefix_ contains string $BUILDDIR, it will be replaced with
+ the build directory (see also **--build-dir**).
+
+- --grub-prefix
+
+ Alias for **--prefix**.
- --grub2\[=_filename_\]
- Generate GRUB2 menuentry in _filename_. If _filename_ is not
- specified `grub.cfg` is used. The content of the menuentry can be
- customized with __--grub-preable__, __--grub2-prolog__ or
- __--grub\_prefix__ options.
+ 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,
i.e. run update-grub on Debian/Ubuntu.
- --grub2-prolog=_prolog_
- Specifies text _preable_ that is put at the beginning of the entry
- GRUB2 entry.
+ Specifies text that is put at the beginning of the GRUB2 menu entry.
- -m, --make\[=make command\]
- --stty=_settings_
Specifies settings passed to `stty` invoked on the serial line
- specified with __--serial__ option. If this option is not given,
+ specified with **--serial** option. If this option is not given,
`stty` is called with `raw -crtscts -onlcr 115200` settings.
- --remote-cmd=_cmd_
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 require root privileges and `novaboot`
+ 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.
+ _/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 --foreground --secure -v -v -v --pidfile tftpd.pid *, /usr/bin/touch dhcpd.leases, /usr/bin/pkill --pidfile=dhcpd.pid, /usr/bin/pkill --pidfile=tftpd.pid
+ 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 the novaboot script (see also __--name__).
+ of the novaboot script (see also **--name**).
- --server\[=\[\[user@\]server:\]path\]
- Copy all files needed for booting to another location (implies __-g__
- unless __--grub2__ is given). 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__).
+ 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**).
+
+- --rsync-flags=_flags_
+
+ Specifies which _flags_ are appended to `rsync` command line when
+ copying files as a result of _--server_ option.
- --concat
- If __--server__ is used and its value ends with $NAME, then after
+ 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__
+ 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".
-- --rsync-flags=_flags_
+- --ider
- Specifies which _flags_ are appended to `rsync` command line when
- copying files as a result of _--server_ option.
+ 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.
## Target power-on and reset phase
+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**.
+
- --on, --off
Switch on/off the target machine and exit. The script (if any) is
- completely ignored. Currently it works only with __--iprelay__ or
- __--amt__.
+ completely ignored. Currently it works only with **--iprelay** or
+ **--amt**.
- -Q, --qemu\[=_qemu-binary_\]
## Interaction with the bootloader on the target
-- --uboot
+- --uboot\[=_prompt_\]
- Interact with uBoot bootloader to boot the thing described in the
- novaboot script. Implementation of this option is currently tied to a
- particular board that we use. It may be subject to changes in the
- future!
+ 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!
- --uboot-init
Command(s) to send the U-Boot bootloader before loading the images and
- booting them.
+ booting them. This option can be given multiple times. After sending
+ commands from each option novaboot waits for U-Boot _prompt_.
+
+ If the command contains string _$NB\_MYIP_ then this string is
+ replaced by IPv4 address of eth0 interface.
+
+- --uboot-addr _name_=_address_
+
+ Load address of U-Boot's `tftpboot` command for loading _name_,
+ where name is one of _kernel_, _ramdisk_ or _fdt_ (flattened device
+ tree).
## Target interaction phase
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
+ If _string_ is `-re`, then the next **--exiton**'s _string_ is
treated as regular expression. For example:
--exiton -re --exiton 'error:.*failed'
- --expect=_string_
When _string_ is received from the target, send the string specified
- with the subsequent __--send\*__ option to the target.
+ 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.
+ string specified with the subsequent **--send\*** option to the target.
- --expect-raw=_perl-code_
- --send=_string_
Send _string_ to the target after the previously specified
- __--expect\*__ was matched in the target's output. The _string_ may
+ **--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
- --sendcont=_string_
- Similar to __--send__ but continue expecting more input.
+ Similar to **--send** but continue expecting more input.
Example: `--expect='Continue?' --sendcont='yes\n'`
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
+(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
- QEMU
- Use a specific qemu binary (can be overridden with __-Q__) and flags
+ 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__).
+ Use specific qemu flags (can be overridden with **-q**).
- WVDESC
- Description of the wvtest-compliant program.
+ Description of the WvTest-compliant program.
- WVTEST\_TIMEOUT
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, its 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.
+["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.
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 on command line with the **--target** option.
- %targets
- Hash of shortcuts to be used with the __--target__ option. If the hash
- contains, for instance, the following pair of values
+ 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:
- 'mybox' => '--server=boot:/tftproot --serial=/dev/ttyUSB0 --grub',
+ $targets{'mybox'} = '--server=boot:/tftproot --serial=/dev/ttyUSB0 --grub',
then the following two commands are equivalent:
Name of the novaboot configuration file to use instead of the default
one(s).
+- NOVABOOT\_CONFIG\_DIR
+
+ Name of the novaboot configuration directory. When not specified
+ `/etc/novaboot.d` is used.
+
- NOVABOOT\_BENDER
- Defining this variable has the same meaning as __--bender__ option.
+ Defining this variable has the same meaning as **--bender** option.
# AUTHORS
projects / novaboot.git / blobdiff