the boot menu will allow selecting between _script1_ and _script2_
configurations.
-# OPTIONS
+# PHASES AND OPTIONS
-- \-a, --append=<parameters>
+Novaboot perform its work in several phases. Each phase can be
+influenced by several options, certain phases can be skipped. The list
+of phases with the corresponding options follows.
- Appends a string to the root task's command line.
+## Command line processing phase
-- \-b, --bender
+- \-c, --config=<filename>
- Boot bender tool before the kernel to find PCI serial ports.
+ Use a different configuration file than the default one (i.e.
+ `~/.novaboot`).
-- \--build-dir=<directory>
+- \--dump-config
- Overrides the default build directory location.
+ Dumps current configuration to stdout end exits. Useful as an initial
+ template for a configuration file.
- The default build directory location is determined as follows:
+- \-h, --help
- 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.
+ Print short (__\-h__) or long (__\--help__) help.
-- \-c, --config=<filename>
+- \-I
- Use a different configuration file than the default one (i.e.
- `~/.novaboot`).
+ 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.
-- \-d, --dhcp-tftp
+- \-J
- 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.
+ 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.
- 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.
+## Script preprocessing phase
- 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
+This phases allows to modify the parsed novaboot script before it is
+used in the later phases.
+
+- \-a, --append=<parameters>
+
+ Appends a string to the first "filename" line in the novaboot script.
+ This can be used to append parameters to the kernel's or root task's
+ command line.
+
+- \-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.
- \--dump
Prints the content of the novaboot script after removing comments and
- evaluating all _\--scriptmod_ expressions.
+ evaluating all _\--scriptmod_ expressions. Exit after reading (and
+ dumping) the script.
-- \--dump-config
+- \--scriptmod=_perl expression_
- Dumps current configuration to stdout end exits. Useful as an initial
- template for a configuration file.
+ 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.
+
+- \--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.
+
+## File generation phase
+
+In this phase, files needed for booting are generated in a so called
+_build directory_ (see TODO). 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 there is a configuration file, the value specified in the
+ _$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.
- \-g, --grub\[=_filename_\]
- Generates grub menu file. If the _filename_ is not specified,
- `menu.lst` is used. The _filename_ is relative to NUL build
- directory.
+ 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__).
- \--grub-prefix=_prefix_
- Specifies _prefix_ that is put before every file in GRUB's menu.lst.
+ 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.
- \--grub2\[=_filename_\]
Generate GRUB2 menuentry in _filename_. If _filename_ is not
- specified grub.cfg is used. The content of the menuentry can be
+ specified `grub.cfg` is used. The content of the menuentry can be
customized by _$grub2\_prolog_ and _$server\_grub\_prefix_
configuration variables.
source /path/to/nul/build/grub.cfg
fi
+- \--name=_string_
+ 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.
-- \-h, --help
+- \--no-file-gen
- Print short (__\-h__) or long (__\--help__) help.
+ Do not generate files on the fly (i.e. "<" syntax) except for the
+ files generated via "<<WORD" syntax.
-- \--iprelay\[=addr or cmd\]
+- \-p, --pulsar\[=mac\]
- 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.
+ 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.
- 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.
+## File deployment phase
- Note: This option is expected to work with HWG-ER02a IP relays.
+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 NOVA
+ can be booted via PXE BIOS on a test machine directly connected by
+ a plain Ethernet cable to your workstation.
+
+ 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.
+
+ 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
- \-i, --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 (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__).
-- \-J
+ 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.
- 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.
+- \--rsync-flags=_flags_
-- \--on, --off
+ Specifies which _flags_ are appended to `rsync` command line when
+ copying files as a result of _\--server_ option.
- Synonym for --iprelay=on/off.
+- \--scons\[=scons command\]
-- \--name=_string_
+ Runs _scons_ to build files that are not generated by novaboot
+ itself.
- 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.
+## Target power-on and reset phase
-- \--no-file-gen
+- \--iprelay\[=addr or cmd\]
- Do not generate files on the fly (i.e. "<" syntax) except for the
- files generated via "<<WORD" syntax.
+ 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.
-- \-p, --pulsar\[=mac\]
+ 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.
- 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.
+ Note: This option is expected to work with HWG-ER02a IP relays.
+
+- \--on, --off
+
+ Synonym for --iprelay=on/off.
- \-Q, --qemu=_qemu-binary_
- Use specific version of qemu binary. The default is 'qemu'.
+ The name of qemu binary to use. The default is 'qemu'.
- \--qemu-append=_flags_
Replace the default qemu flags (QEMU\_FLAGS variable or `-cpu coreduo
-smp 2`) with _flags_ specified here.
-- \--rsync-flags=_flags_
-
- Specifies which _flags_ are appended to `rsync` command line when
- copying files as a result of _\--server_ option.
-
-- \--scons\[=scons command\]
-
- Runs _scons_ to build files that are not generated by novaboot
- itself.
-
-- \--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.
+## Interaction with the bootloader on the target
-- \--server\[=\[\[user@\]server:\]path\]
+See __\--serial__. There will be new options soon.
- 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__).
-
- 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.
+## Reception of target's output (e.g. console) on the host system
- \-s, --serial\[=device\]
- Use serial line to control GRUB bootloader and to get the serial
- output of the machine. The default value is /dev/ttyUSB0.
+Use serial line to control GRUB bootloader and to see the output
+serial output of the machine. The default value is `/dev/ttyUSB0`.
-- \--strip-rom
+## Termination phase
- Strip _rom://_ prefix from command lines and generated config files.
- This is needed for NRE.
+Daemons that were spwned (`dhcpd` and `tftpd`) are killed here.
# NOVABOOT SCRIPT SYNTAX
section.
Otherwise, the first word on the line represents the filename
-(relative to the build directory (see _\--build-dir_) of the module to
+(relative to the build directory (see __\--build-dir__) of the module to
load and the remaining words are passed as the command line
parameters.
# CONFIGURATION FILE
Novaboot can read its configuration from a file. Configuration file
-was necessary in early days of novaboot. Nowadays, the attempt is made
+was necessary in early days of novaboot. Nowadays, an attempt is made
to not use the configuration file because it makes certain novaboot
scripts unusable on systems without (or with different) configuration
file. The only recommended use of the configuration file is to specify
custom\_options (see bellow).
If you decide to use the configuration file, its default location is
-~/.novaboot, other location can be specified __\-c__ parameter or with
-NOVABOOT\_CONFIG environment variable. The configuration has perl
-syntax and sets values of certain variables. The current configuration
-can be dumped with __\--dump-config__ switch. Some configuration
-variables can be overriden by environment variables (see below) or by
-command line switches.
+~/.novaboot, other 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 overriden by environment variables
+(see below) or by command line switches.
Documentation of some configuration variables follows:
projects / novaboot.git / blobdiff