X-Git-Url: http://rtime.felk.cvut.cz/gitweb/novaboot.git/blobdiff_plain/05829f7a16a534bf4061203179433303db5eeeb6..HEAD:/README.md diff --git a/README.md b/README.md index cc1f0e2..0be003e 100644 --- a/README.md +++ b/README.md @@ -1,744 +1,47 @@ -# NAME +# Novaboot -novaboot - Boots a locally compiled operating system on a remote -target 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 a locally compiled operating system (OS) -(e.g. NOVA or Linux) on remote targets as simple as running a program -locally. It automates things like copying OS images to a TFTP server, -generation of bootloader configuration files, resetting of target -hardware or redirection of target's serial line to stdin/out. Novaboot -is highly configurable and it makes it easy to boot a single image on -different targets or different images on a single target. + make -C server install -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)). -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 -Novaboot uses configuration files to, among other things, define -command line options needed for different targets. Users typically use -only the **-t**/**--target** command line option to select the target. -Internally, this option expands to the pre-configured options. -Configuration files are searched at multiple places, which allows to -have per-system, per-user or per-project configurations. Configuration -file syntax is described in section ["CONFIGURATION FILE"](#configuration-file). +Novaboot can be used in variety of setups. Most typical ones are +depicted in the figure below. -Simple examples of using `novaboot`: +![Possible novaboot setups](doc/typical-setups.svg?raw=true "Title") -1. Run an OS in Qemu. This is the default action when no other action is -specified by command line switches. Thus running `novaboot myos` (or -`./myos` as described above) will run Qemu and make it boot the -configuration specified in the `myos` script. -2. Create a bootloader configuration file (currently supported -bootloaders are GRUB, GRUB2, ISOLINUX, Pulsar and U-Boot) and copy it -with all other files needed for booting to a remote boot server. Then -use a TCP/IP-controlled relay/serial-to-TCP converter to reset the -target and receive its serial output. +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. - ./myos --grub2 --server=192.168.1.1:/tftp --iprelay=192.168.1.2 +### Client side -3. Run DHCP and TFTP server on developer's machine to boot the target -from it. +- novaboot [documentation](./README.pod) - ./myos --dhcp-tftp +### Server-side (optional, needed only by server administrators for setup C) - This is useful when no network infrastructure is in place and - the target is connected directly to developer's box. +- [novaboot-shell](server/novaboot-shell.pod) +- [adduser-novaboot](server/adduser-novaboot.pod) -4. Create bootable ISO image. +### Hardware guides - novaboot --iso -- script1 script2 - - The created ISO image will have ISOLINUX bootloader installed on it - and the boot menu will allow selecting between _script1_ and - _script2_ configurations. - -# PHASES AND OPTIONS - -Novaboot performs its work in several phases. Each phase can be -influenced by several command line options, certain phases can be -skipped. The list of phases (in the execution order) and the -corresponding options follows. - -## Configuration reading phase - -After starting, novaboot reads configuration files. Their content is -described in section ["CONFIGURATION FILE"](#configuration-file). By default, -configuration is read from multiple locations. First from the system -configuration directory, second from the user configuration file and -third from `.novaboot` files along the path to the current directory. -Alternatively, a single configuration file specified with the **-c** -switch or with the `NOVABOOT_CONFIG` environment variable. The latter -read files override settings from the former ones. - -The system configuration directory is determined by the content of -NOVABOOT\_CONFIG\_DIR environment variable and defaults to -`/etc/novaboot.d`. Files in this directory with names consisting -solely of English letters, numbers, dashes '-' and underscores '\_' -(note that dot '.' is not included) are read in alphabetical order. - -Then, the user configuration file is read from -`$XDG_CONFIG_HOME/novaboot`. If `$XDG_CONFIG_HOME` environemnt -variable is not set `~/.config/novaboot` is read instead. - -Finally, 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, a project -specific configuration in `~/project/.novaboot`. - -Note the difference between `~/.config/novaboot` and `~/.novaboot`. -The former one is read always, whereas the latter only when novaboot -script or working directory is under the `$HOME` directory. - -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 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_ - - Use the specified configuration file instead of the default one(s). - -## Command line processing phase - -- --dump-config - - Dump the current configuration to stdout end exit. 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. This option 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_ - - Specifies a 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. - -- --prefix=_prefix_ - - 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**). - - 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 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 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. - - if [ -f /path/to/nul/build/grub.cfg ]; then - source /path/to/nul/build/grub.cfg - fi - -- --grub2-prolog=_prolog_ - - Specifies text that is put at the beginning of the GRUB2 menu 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 run external commands to generate files (i.e. "<" syntax and - `run` keyword). This switch does not influence generation of files - specified with "< ", 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. 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. Similarly _$NB\_PREFIX_ is - replaced with prefix given by **--prefix**. - - See also `uboot` keyword in ["NOVABOOT SCRIPT SYNTAX"](#novaboot-script-syntax)). - -- --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). - - The default addresses are ${_name_\_addr\_r}, i.e. U-Boot environment - variables used by convention for this purpose. - -- --uboot-cmd=_command_ - - Specifies U-Boot command used to execute the OS. If the command - contains strings `$kernel_addr`, `$ramdisk_addr`, `$fdt_addr`, - these are replaced with the addresses configured with **--uboot-addr**. - - The default value is - - bootm $kernel_addr $ramdisk_addr $fdt_addr - - or the `UBOOT_CMD` variable if defined in the novaboot script. - -## Target interaction phase - -In this phase, target's serial output is redirected to stdout and if -stdin is a TTY, it is redirected to the target's serial input allowing -interactive work with the target. - -- --exiton=_string_ - - When _string_ is sent by the target, novaboot exits. This option can - be specified multiple times, in which case novaboot exits whenever - either of the specified strings is sent. - - If _string_ is `-re`, then the next **--exiton**'s _string_ is - treated as regular expression. For example: - - --exiton -re --exiton 'error:.*failed' - -- --exiton-re=_regex_ - - The same as --exiton -re --exiton _regex_. - -- --exiton-timeout=_seconds_ - - By default **--exiton** waits for the string match forever. When this - option is specified, "exiton" timeouts after the specifies number of - seconds and novaboot returns non-zero exit code. - -- -i, --interactive - - Setup things for interactive use of target. Your terminal will be - switched to raw mode. In raw mode, your system does not process input - in any way (no echoing of entered characters, no interpretation - special characters). This, among others, means that Ctrl-C is passed - to the target and does no longer interrupt novaboot. Use "~~." - sequence to exit novaboot. - -- --expect=_string_ - - When _string_ is received from the target, send the string specified - 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. - -- --expect-raw=_perl-code_ - - Provides direct control over Perl's Expect module. - -- --send=_string_ - - Send _string_ to the target after the previously specified - **--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 - much more that escape sequences. This behavior may change in the - future. - - Example: `--expect='login: ' --send='root\n'` - -- --sendcont=_string_ - - Similar to **--send** but continue expecting more input. - - Example: `--expect='Continue?' --sendcont='yes\n'` - -# NOVABOOT SCRIPT SYNTAX - -The syntax tries to mimic POSIX shell syntax. The syntax is defined -with the following rules. - -Lines starting with "#" and empty lines are ignored. - -Lines that end with "\\" are concatenated with the following line after -removal of the final "\\" and leading whitespace of the following line. - -Lines of the form _VARIABLE=..._ (i.e. matching '^\[A-Z\_\]+=' regular -expression) assign values to internal variables. See ["VARIABLES"](#variables) -section. - -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 -passed to it as the command line parameters. - -When the `load` line ends with "</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 < +- [Raspberry Pi](./doc/README.rpi.md) (work-in-progress)