3 novaboot - A tool for booting various operating systems on various hardware or in qemu
7 __novaboot__ \[ options \] \[--\] script...
9 __./script__ \[ options \]
15 This program makes it easier to boot NOVA or other operating system
16 (OS) in different environments. It reads a so called novaboot script
17 and uses it either to boot the OS in an emulator (e.g. in qemu) or to
18 generate the configuration for a specific bootloader and optionally to
19 copy the necessary binaries and other needed files to proper
20 locations, perhaps on a remote server. In case the system is actually
21 booted, its serial output is redirected to standard output if that is
24 A typical way of using novaboot is to make the novaboot script
25 executable and set its first line to _\#!/usr/bin/env novaboot_. Then,
26 booting a particular OS configuration becomes the same as executing a
27 local program - the novaboot script.
29 With `novaboot` you can:
31 1. Run an OS in Qemu. This is the default action when no other action is
32 specified by command line switches. Thus running `novaboot ./script`
33 (or `./script` as described above) will run Qemu and make it boot the
34 configuration specified in the _script_.
35 2. Create a bootloader configuration file (currently supported
36 bootloaders are GRUB, GRUB2 and Pulsar) and copy it with all other
37 files needed for booting to another, perhaps remote, location.
39 ./script --server --iprelay
41 This command copies files to a TFTP server specified in the
42 configuration file and uses TCP/IP-controlled relay to reset the test
43 box and receive its serial output.
45 3. Run DHCP and TFTP server on developer's machine to PXE-boot NOVA from
50 When a PXE-bootable machine is connected via Ethernet to developer's
51 machine, it will boot the configuration described in _script_.
53 4. Create bootable ISO images. E.g.
55 novaboot --iso -- script1 script2
57 The created ISO image will have GRUB bootloader installed on it and
58 the boot menu will allow selecting between _script1_ and _script2_
63 Novaboot perform its work in several phases. Each phase can be
64 influenced by several options, certain phases can be skipped. The list
65 of phases with the corresponding options follows.
67 ## Command line processing phase
69 - \-c, --config=<filename>
71 Use a different configuration file than the default one (i.e.
76 Dumps current configuration to stdout end exits. Useful as an initial
77 template for a configuration file.
81 Print short (__\-h__) or long (__\--help__) help.
83 - \-t, --target=<target>
85 This option serves as a user configurable shortcut for other novaboot
86 options. The effect of this option is the same as the options stored
87 in the `%targets` configuration variable under key _target_. See
88 also ["CONFIGURATION FILE"](#CONFIGURATION FILE).
90 ## Script preprocessing phase
92 This phases allows to modify the parsed novaboot script before it is
93 used in the later phases.
95 - \-a, --append=<parameters>
97 Appends a string to the first "filename" line in the novaboot script.
98 This can be used to append parameters to the kernel's or root task's
103 Use `bender` chainloader. Bender scans the PCI bus for PCI serial
104 ports and stores the information about them in the BIOS data area for
109 Prints the content of the novaboot script after removing comments and
110 evaluating all _\--scriptmod_ expressions. Exit after reading (and
113 - \--scriptmod=_perl expression_
115 When novaboot script is read, _perl expression_ is executed for every
116 line (in $\_ variable). For example, `novaboot
117 --scriptmod=s/sigma0/omega6/g` replaces every occurrence of _sigma0_
118 in the script with _omega6_.
120 When this option is present, it overrides _$script\_modifier_ variable
121 from the configuration file, which has the same effect. If this option
122 is given multiple times all expressions are evaluated in the command
127 Strip _rom://_ prefix from command lines and generated config files.
128 The _rom://_ prefix is used by NUL. For NRE, it has to be stripped.
130 ## File generation phase
132 In this phase, files needed for booting are generated in a so called
133 _build directory_ (see TODO). In most cases configuration for a
134 bootloader is generated automatically by novaboot. It is also possible
135 to generate other files using _heredoc_ or _"<"_ syntax in novaboot
136 scripts. Finally, binaries can be generated in this phases by running
139 - \--build-dir=<directory>
141 Overrides the default build directory location.
143 The default build directory location is determined as follows:
145 If there is a configuration file, the value specified in the
146 _$builddir_ variable is used. Otherwise, if the current working
147 directory is inside git work tree and there is `build` directory at
148 the top of that tree, it is used. Otherwise, if directory
149 `~/nul/build` exists, it is used. Otherwise, it is the directory that
150 contains the first processed novaboot script.
152 - \-g, --grub\[=_filename_\]
154 Generates grub bootloader menu file. If the _filename_ is not
155 specified, `menu.lst` is used. The _filename_ is relative to the
156 build directory (see __\--build-dir__).
158 - \--grub-prefix=_prefix_
160 Specifies _prefix_ that is put before every file in GRUB's `menu.lst`.
161 This overrides the value of _$server\_grub\_prefix_ from the
164 - \--grub2\[=_filename_\]
166 Generate GRUB2 menuentry in _filename_. If _filename_ is not
167 specified `grub.cfg` is used. The content of the menuentry can be
168 customized by _$grub2\_prolog_ and _$server\_grub\_prefix_
169 configuration variables.
171 In order to use the the generated menuentry on your development
172 machine that uses GRUB2, append the following snippet to
173 `/etc/grub.d/40\_custom` file and regenerate your grub configuration,
174 i.e. run update-grub on Debian/Ubuntu.
176 if [ -f /path/to/nul/build/grub.cfg ]; then
177 source /path/to/nul/build/grub.cfg
182 Use the name _string_ instead of the name of the novaboot script.
183 This name is used for things like a title of grub menu or for the
184 server directory where the boot files are copied to.
188 Do not generate files on the fly (i.e. "<" syntax) except for the
189 files generated via "<<WORD" syntax.
191 - \-p, --pulsar\[=mac\]
193 Generates pulsar bootloader configuration file whose name is based on
194 the MAC address specified either on the command line or taken from
195 _.novaboot_ configuration file.
197 ## File deployment phase
199 In some setups, it is necessary to copy the files needed for booting
200 to a particular location, e.g. to a TFTP boot server or to the
205 Turns your workstation into a DHCP and TFTP server so that NOVA
206 can be booted via PXE BIOS on a test machine directly connected by
207 a plain Ethernet cable to your workstation.
209 The DHCP and TFTP servers require root privileges and `novaboot`
210 uses `sudo` command to obtain those. You can put the following to
211 _/etc/sudoers_ to allow running the necessary commands without
214 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
215 your_login ALL=NOPASSWD: NOVABOOT
217 - \-i, --iso\[=filename\]
219 Generates the ISO image that boots NOVA system via GRUB. If no filename
220 is given, the image is stored under _NAME_.iso, where _NAME_ is the name
221 of the novaboot script (see also __\--name__).
223 - \--server\[=\[\[user@\]server:\]path\]
225 Copy all files needed for booting to another location (implies __\-g__
226 unless __\--grub2__ is given). The files will be copied (by __rsync__
227 tool) to the directory _path_. If the _path_ contains string $NAME,
228 it will be replaced with the name of the novaboot script (see also
231 Additionally, if $NAME is the last component of the _path_, a file
232 named _path_/menu.lst (with $NAME removed from the _path_) will be
233 created on the server by concatenating all _path_/\*/menu.lst (with
234 $NAME removed from the _path_) files found on the server.
236 - \--rsync-flags=_flags_
238 Specifies which _flags_ are appended to `rsync` command line when
239 copying files as a result of _\--server_ option.
241 - \--scons\[=scons command\]
243 Runs _scons_ to build files that are not generated by novaboot
246 ## Target power-on and reset phase
248 - \--iprelay\[=addr or cmd\]
250 If no _cmd_ is given, use IP relay to reset the machine and to get
251 the serial output. The IP address of the relay is given by _addr_
252 parameter if specified or by $iprelay\_addr variable in the
255 If _cmd_ is one of "on" or "off", the IP relay is used to press power
256 button for a short (in case of "on") or long (in case of "off") time.
257 Then, novaboot exits.
259 Note: This option is expected to work with HWG-ER02a IP relays.
263 Synonym for --iprelay=on/off.
265 - \-Q, --qemu=_qemu-binary_
267 The name of qemu binary to use. The default is 'qemu'.
269 - \--qemu-append=_flags_
271 Append _flags_ to the default qemu flags (QEMU\_FLAGS variable or
272 `-cpu coreduo -smp 2`).
274 - \-q, --qemu-flags=_flags_
276 Replace the default qemu flags (QEMU\_FLAGS variable or `-cpu coreduo
277 -smp 2`) with _flags_ specified here.
279 ## Interaction with the bootloader on the target
281 See __\--serial__. There will be new options soon.
283 ## Target's output reception phase
285 - \-s, --serial\[=device\]
287 Use serial line to control GRUB bootloader and to see the output
288 serial output of the machine. The default value is `/dev/ttyUSB0`.
290 See also __\--iprelay__.
294 Daemons that were spwned (`dhcpd` and `tftpd`) are killed here.
296 # NOVABOOT SCRIPT SYNTAX
298 The syntax tries to mimic POSIX shell syntax. The syntax is defined with the following rules.
300 Lines starting with "\#" are ignored.
302 Lines that end with "\\" are concatenated with the following line after
303 removal of the final "\\" and leading whitespace of the following line.
305 Lines in the form _VARIABLE=..._ (i.e. matching '^\[A-Z\_\]+=' regular
306 expression) assign values to internal variables. See VARIABLES
309 Otherwise, the first word on the line represents the filename
310 (relative to the build directory (see __\--build-dir__) of the module to
311 load and the remaining words are passed as the command line
314 When the line ends with "<<WORD" then the subsequent lines until the
315 line containing only WORD are copied literally to the file named on
318 When the line ends with "< CMD" the command CMD is executed with
319 `/bin/sh` and its standard output is stored in the file named on that
320 line. The SRCDIR variable in CMD's environment is set to the absolute
321 path of the directory containing the interpreted novaboot script.
324 \#!/usr/bin/env novaboot
325 WVDESC=Example program
326 bin/apps/sigma0.nul S0\_DEFAULT script\_start:1,1 \\
327 verbose hostkeyb:0,0x60,1,12,2
329 hello.nulconfig <<EOF
330 sigma0::mem:16 name::/s0/log name::/s0/timer name::/s0/fs/rom ||
331 rom://bin/apps/hello.nul
334 This example will load three modules: sigma0.nul, hello.nul and
335 hello.nulconfig. sigma0 gets some command line parameters and
336 hello.nulconfig file is generated on the fly from the lines between
341 The following variables are interpreted in the novaboot script:
345 Description of the wvtest-compliant program.
349 The timeout in seconds for WvTest harness. If no complete line appears
350 in the test output within the time specified here, the test fails. It
351 is necessary to specify this for long running tests that produce no
356 Use a specific qemu binary (can be overriden with __\-Q__) and flags
357 when booting this script under qemu. If QEMU\_FLAGS variable is also
358 specified flags specified in QEMU variable are replaced by those in
363 Use specific qemu flags (can be overriden with __\-q__).
367 Parameters passed to hypervisor. The default value is "serial", unless
368 overriden in configuration file.
372 The kernel to use instead of NOVA hypervisor specified in the
373 configuration file. The value should contain the name of the kernel
374 image as well as its command line parameters. If this variable is
375 defined and non-empty, the variable HYPERVISOR\_PARAMS is not used.
379 Novaboot can read its configuration from a file. Configuration file
380 was necessary in early days of novaboot. Nowadays, an attempt is made
381 to not use the configuration file because it makes certain novaboot
382 scripts unusable on systems without (or with different) configuration
383 file. The only recommended use of the configuration file is to specify
384 custom\_options (see bellow).
386 If you decide to use the configuration file, its default location is
387 ~/.novaboot, other location can be specified with the __\-c__ switch or
388 with the NOVABOOT\_CONFIG environment variable. The configuration file
389 has perl syntax and should set values of certain Perl variables. The
390 current configuration can be dumped with the __\--dump-config__ switch.
391 Some configuration variables can be overriden by environment variables
392 (see below) or by command line switches.
394 Documentation of some configuration variables follows:
398 Custom chainloaders to load before hypervisor and files specified in
399 novaboot script. E.g. ('bin/boot/bender promisc', 'bin/boot/zapp').
403 Hash of shortcuts to be used with the __\--target__ option. If the hash
404 contains, for instance, the following pair of values
406 'mybox' => '--server=boot:/tftproot --serial=/dev/ttyUSB0 --grub',
408 then the following two commands are equivalent:
410 ./script --server=boot:/tftproot --serial=/dev/ttyUSB0 --grub
413 # ENVIRONMENT VARIABLES
415 Some options can be specified not only via config file or command line
416 but also through environment variables. Environment variables override
417 the values from configuration file and command line parameters
418 override the environment variables.
422 A name of default novaboot configuration file.
426 Defining this variable has the same meaning as __\--bender__ option.
430 The IP address (and optionally the port) of the IP relay. This
431 overrides $iprelay\_addr variable from the configuration file.
435 Michal Sojka <sojka@os.inf.tu-dresden.de>