X-Git-Url: http://rtime.felk.cvut.cz/gitweb/novaboot.git/blobdiff_plain/0c39753f65e8b93f675f4cef2a9d343b210cf5e9..HEAD:/README.md diff --git a/README.md b/README.md index 5385e91..0be003e 100644 --- a/README.md +++ b/README.md @@ -1,605 +1,47 @@ -# NAME +# Novaboot -novaboot - A tool for booting various operating systems on various hardware or in qemu +Novaboot is a tool that automates booting of operating systems on +target hardware (typically embedded boards) or in Qemu. Initially, it +was developed to boot [NOVA Microhypervisor](http://hypervisor.org/) +(hence the name), but nowadays is well suited for booting +[Linux](https://www.kernel.org/) (and perhaps other OSes) too. -# SYNOPSIS +## Instalation -__novaboot__ --help +The simplest way to install novaboot is to install `perl` and its +packages `IO-Stty` and `Expect` and copy the +[novaboot](novaboot) script somewhere to your $PATH. -__novaboot__ \[option\]... \[--\] script... +You can also install everything (including man pages) by: -__./script__ \[option\]... + make install -# DESCRIPTION +To install the optional server part (see below), run: -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. + make -C server install -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. +## Documentation -For example, with `novaboot` you can: +Novaboot can be used in variety of setups. Most typical ones are +depicted in the figure below. -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 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. +![Possible novaboot setups](doc/typical-setups.svg?raw=true "Title") - ./script --server=192.168.1.1:/tftp --iprelay=192.168.1.2 +The setups are fully described in the [documentation](./README.pod), +but in short: Setup A is for power users, who can configure everything +themselves, whereas setup C is useful for students, who just want to +access the target device with as little configuration on their side as +possible. - This command copies files to the TFTP server and uses - TCP/IP-controlled relay to reset the target host and receive its - serial output. +### Client side -3. Run DHCP and TFTP server on developer's machine to PXE-boot the target -host from it. E.g. +- novaboot [documentation](./README.pod) - ./script --dhcp-tftp +### Server-side (optional, needed only by server administrators for setup C) - When a PXE-bootable machine is connected via Ethernet to developer's - machine, it will boot the configuration described in _script_. +- [novaboot-shell](server/novaboot-shell.pod) +- [adduser-novaboot](server/adduser-novaboot.pod) -4. Create bootable ISO images. E.g. +### Hardware guides - novaboot --iso -- script1 script2 - - The created ISO image will have GRUB 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__ -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. - -## 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. - -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. - -- \-c, --config=_filename_ - - Use the specified configuration file instead of the default one(s). - -## Command line processing phase - -- \--dump-config - - Dump the current configuration to stdout end exits. Useful as an - initial template for a configuration file. - -- \-h, --help - - 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. 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_ - - 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__). - -- \--grub-preamble=_prefix_ - - Specifies the _preable_ that is at the beginning of the generated - GRUB or GRUB2 config files. This is useful for specifying GRUB's - timeout. - -- \--grub-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. - - If the _prefix_ contains string $NAME, it will be replaced with the - name of the novaboot script (see also __\--name__). - -- \--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. - - In order to use the the generated menuentry 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. - - if [ -f /path/to/nul/build/grub.cfg ]; then - source /path/to/nul/build/grub.cfg - fi - -- \--grub2-prolog=_prolog_ - - Specifies text _preable_ that is put at the beginning of the entry - GRUB2 entry. - -- \-m, --make\[=make command\] - - Runs `make` to build files that are not generated by novaboot itself. - -- \--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. - -- \--no-file-gen - - Do not generate files on the fly (i.e. "<" syntax) except for the - files generated via "</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 < '--server=boot:/tftproot --serial=/dev/ttyUSB0 --grub', - - then the following two commands are equivalent: - - ./script --server=boot:/tftproot --serial=/dev/ttyUSB0 --grub - ./script -t mybox - -# ENVIRONMENT VARIABLES - -Some options can be specified not only via config file or command line -but also through environment variables. Environment variables override -the values from configuration file and command line parameters -override the environment variables. - -- NOVABOOT\_CONFIG - - Name of the novaboot configuration file to use instead of the default - one(s). - -- NOVABOOT\_BENDER - - Defining this variable has the same meaning as __\--bender__ option. - -# AUTHORS - -Michal Sojka +- [Raspberry Pi](./doc/README.rpi.md) (work-in-progress)