From 4b25ddda639a09d0b5d4d378b0595dcfcf7f7bf4 Mon Sep 17 00:00:00 2001 From: Michal Sojka Date: Sat, 19 Oct 2013 16:41:28 +0200 Subject: [PATCH] Give more structure to the documentation --- README.md | 270 +++++++++++++++++++++++++++++--------------------- novaboot | 291 ++++++++++++++++++++++++++++++++---------------------- 2 files changed, 331 insertions(+), 230 deletions(-) diff --git a/README.md b/README.md index 5d7b89a..f19e724 100644 --- a/README.md +++ b/README.md @@ -58,74 +58,118 @@ it. E.g. the boot menu will allow selecting between _script1_ and _script2_ configurations. -# OPTIONS +# PHASES AND OPTIONS -- \-a, --append= +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= - 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= +- \--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= +- \-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= + + 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= + + 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. @@ -138,67 +182,94 @@ it. E.g. 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 "< +=item -c, --config= -Appends a string to the root task's command line. +Use a different configuration file than the default one (i.e. +F<~/.novaboot>). -=item -b, --bender +=item --dump-config -Boot bender tool before the kernel to find PCI serial ports. +Dumps current configuration to stdout end exits. Useful as an initial +template for a configuration file. -=item --build-dir= +=item -h, --help -Overrides the default build directory location. +Print short (B<-h>) or long (B<--help>) help. -The default build directory location is determined as follows: +=item -I -If there is a configuration file, the value specified in I<$builddir> -variable is used. Otherwise, if the current working directory is -inside git work tree and there is F directory at the top of -that tree, it is used. Otherwise, if directory F<~/nul/build> exists, -it is used. Otherwise, it is the directory that contains the first -processed novaboot script. +This is an alias (see C<%custom_options> below) defined in the default +configuration. When used, it causes novaboot to use Michal's remotely +controllable test bed. -=item -c, --config= +=item -J -Use a different configuration file than the default one (i.e. -F<~/.novaboot>). +This is an alias (see C<%custom_options> below) defined in the default +configuration. When used, it causes novaboot to use another remotely +controllable test bed. -=item -d, --dhcp-tftp +=back -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. +=head2 Script preprocessing phase -The DHCP and TFTP servers require root privileges and C -uses C command to obtain those. You can put the following to -I to allow running the necessary commands without -asking for password. +This phases allows to modify the parsed novaboot script before it is +used in the later phases. - 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 +=over 8 + +=item -a, --append= + +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. + +=item -b, --bender + +Use F 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. =item --dump Prints the content of the novaboot script after removing comments and -evaluating all I<--scriptmod> expressions. +evaluating all I<--scriptmod> expressions. Exit after reading (and +dumping) the script. -=item --dump-config +=item --scriptmod=I -Dumps current configuration to stdout end exits. Useful as an initial -template for a configuration file. +When novaboot script is read, I is executed for every +line (in $_ variable). For example, C replaces every occurrence of I +in the script with I. + +When this option is present, it overrides I<$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. + +=item --strip-rom + +Strip I prefix from command lines and generated config files. +The I prefix is used by NUL. For NRE, it has to be stripped. + +=back + +=head2 File generation phase + +In this phase, files needed for booting are generated in a so called +I (see TODO). In most cases configuration for a +bootloader is generated automatically by novaboot. It is also possible +to generate other files using I or I<"<"> syntax in novaboot +scripts. Finally, binaries can be generated in this phases by running +C or C. + +=over 8 + +=item --build-dir= + +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 +I<$builddir> variable is used. Otherwise, if the current working +directory is inside git work tree and there is F directory at +the top of that tree, it is used. Otherwise, if directory +F<~/nul/build> exists, it is used. Otherwise, it is the directory that +contains the first processed novaboot script. =item -g, --grub[=I] -Generates grub menu file. If the I is not specified, -F is used. The I is relative to NUL build -directory. +Generates grub bootloader menu file. If the I is not +specified, F is used. The I is relative to the +build directory (see B<--build-dir>). =item --grub-prefix=I -Specifies I that is put before every file in GRUB's menu.lst. +Specifies I that is put before every file in GRUB's F. This overrides the value of I<$server_grub_prefix> from the configuration file. =item --grub2[=I] Generate GRUB2 menuentry in I. If I is not -specified grub.cfg is used. The content of the menuentry can be +specified F is used. The content of the menuentry can be customized by I<$grub2_prolog> and I<$server_grub_prefix> configuration variables. @@ -883,66 +935,102 @@ i.e. run update-grub on Debian/Ubuntu. source /path/to/nul/build/grub.cfg fi +=item --name=I -=item -h, --help +Use the name I 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. -Print short (B<-h>) or long (B<--help>) help. +=item --no-file-gen -=item --iprelay[=addr or cmd] +Do not generate files on the fly (i.e. "<" syntax) except for the +files generated via "< is given, use IP relay to reset the machine and to get -the serial output. The IP address of the relay is given by I -parameter if specified or by $iprelay_addr variable in the -configuration file. +=item -p, --pulsar[=mac] -If I 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 +I<.novaboot> configuration file. -Note: This option is expected to work with HWG-ER02a IP relays. +=back + +=head2 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 +F partition. + +=over 8 + +=item -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 C +uses C command to obtain those. You can put the following to +I 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 =item -i, --iso[=filename] Generates the ISO image that boots NOVA system via GRUB. If no filename is given, the image is stored under I.iso, where I is the name -of novaboot script (see also B<--name>). +of the novaboot script (see also B<--name>). -=item -I +=item --server[=[[user@]server:]path] -This is an alias (see C<%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 B<-g> +unless B<--grub2> is given). The files will be copied (by B +tool) to the directory I. If the I contains string $NAME, +it will be replaced with the name of the novaboot script (see also +B<--name>). -=item -J +Additionally, if $NAME is the last component of the I, a file +named I/menu.lst (with $NAME removed from the I) will be +created on the server by concatenating all I/*/menu.lst (with +$NAME removed from the I) files found on the server. -This is an alias (see C<%custom_options> below) defined in the default -configuration. When used, it causes novaboot to use another remotely -controllable test bed. +=item --rsync-flags=I -=item --on, --off +Specifies which I are appended to F command line when +copying files as a result of I<--server> option. -Synonym for --iprelay=on/off. +=item --scons[=scons command] -=item --name=I +Runs I to build files that are not generated by novaboot +itself. -Use the name I 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. +=back -=item --no-file-gen +=head2 Target power-on and reset phase -Do not generate files on the fly (i.e. "<" syntax) except for the -files generated via "< configuration file. +If no I is given, use IP relay to reset the machine and to get +the serial output. The IP address of the relay is given by I +parameter if specified or by $iprelay_addr variable in the +configuration file. + +If I 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. + +Note: This option is expected to work with HWG-ER02a IP relays. + +=item --on, --off + +Synonym for --iprelay=on/off. =item -Q, --qemu=I -Use specific version of qemu binary. The default is 'qemu'. +The name of qemu binary to use. The default is 'qemu'. =item --qemu-append=I @@ -954,51 +1042,22 @@ C<-cpu coreduo -smp 2>). Replace the default qemu flags (QEMU_FLAGS variable or C<-cpu coreduo -smp 2>) with I specified here. -=item --rsync-flags=I - -Specifies which I are appended to F command line when -copying files as a result of I<--server> option. - -=item --scons[=scons command] - -Runs I to build files that are not generated by novaboot -itself. - -=item --scriptmod=I - -When novaboot script is read, I is executed for every -line (in $_ variable). For example, C replaces every occurrence of I -in the script with I. - -When this option is present, it overrides I<$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. +=back -=item --server[=[[user@]server:]path] +=head2 Interaction with the bootloader on the target -Copy all files needed for booting to a server (implies B<-g> unless -B<--grub2> is given). The files will be copied to the directory -I. If the I contains string $NAME, it will be replaced -with the name of the novaboot script (see also B<--name>). +See B<--serial>. There will be new options soon. -Additionally, if $NAME is the last component of the I, a file -named I/menu.lst (with $NAME removed from the I) will be -created on the server by concatenating all I/*/menu.lst (with -$NAME removed from the I) files found on the server. +=head2 Reception of target's output (e.g. console) on the host system =item -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. - -=item --strip-rom +Use serial line to control GRUB bootloader and to see the output +serial output of the machine. The default value is F. -Strip I prefix from command lines and generated config files. -This is needed for NRE. +=head2 Termination phase -=back +Daemons that were spwned (F and F) are killed here. =head1 NOVABOOT SCRIPT SYNTAX @@ -1014,7 +1073,7 @@ expression) assign values to internal variables. See VARIABLES section. Otherwise, the first word on the line represents the filename -(relative to the build directory (see I<--build-dir>) of the module to +(relative to the build directory (see B<--build-dir>) of the module to load and the remaining words are passed as the command line parameters. @@ -1088,19 +1147,19 @@ defined and non-empty, the variable HYPERVISOR_PARAMS is not used. =head1 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 B<-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 B<--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 B<-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 B<--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: -- 2.39.2