X-Git-Url: https://rtime.felk.cvut.cz/gitweb/novaboot.git/blobdiff_plain/9db3bed414e652b4ff924d8600cfc782c6e23440..HEAD:/README.md diff --git a/README.md b/README.md index ab5df87..0be003e 100644 --- a/README.md +++ b/README.md @@ -1,380 +1,47 @@ -# NAME +# Novaboot -novaboot - NOVA boot script interpreter +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__ \[ options \] \[--\] script... +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. -__./script__ \[ options \] +You can also install everything (including man pages) by: -__novaboot__ --help + make install -# DESCRIPTION +To install the optional server part (see below), run: -This program makes it easier to boot NOVA or other operating system -(OS) in different environments. It reads a so called novaboot script -and uses it either to boot the OS in an emulator (e.g. in qemu) or to -generate the configuration for a specific bootloader and optionally to -copy the necessary binaries and other needed files to proper -locations, perhaps on a remote server. In case the system is actually -booted, its serial output is redirected to standard output if that is -possible. - -A 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. - -With `novaboot` you can: - -1. Run NOVA 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 with configuration -specified in the _script_. -2. Create a bootloader configuration file (currently supported -bootloaders are GRUB, GRUB2 and Pulsar) and copy it with all files -needed for booting another, perhaps remote, location. - - ./script --server --iprelay - - This command copies files to a TFTP server specified in the - configuration file and uses TCP/IP-controlled relay to reset the test - box and receive its serial output. - -3. Run DHCP and TFTP server on developer's machine to PXE-boot NOVA from -it. E.g. - - ./script --dhcp-tftp - - When a PXE-bootable machine is connected via Ethernet to developer's - machine, it will boot the configuration described in _script_. - -4. Create bootable ISO images. E.g. - - 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. - -# OPTIONS - -- \-a, --append= - - Appends a string to the root task's command line. - -- \-b, --bender - - Boot bender tool before the kernel to find PCI serial ports. - -- \--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 _$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. - -- \-c, --config= - - Use a different configuration file than the default one (i.e. - `~/.novaboot`). - -- \-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 - -- \--dump - - Prints the content of the novaboot script after removing comments and - evaluating all _\--scriptmod_ expressions. - -- \--dump-config - - Dumps current configuration to stdout end exits. Useful as an initial - template for a configuration file. - -- \-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. - -- \--grub-prefix=_prefix_ - - 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 - customized by _$grub2\_prolog_ and _$server\_grub\_prefix_ - configuration variables. - - 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 - - - -- \-h, --help - - Print short (__\-h__) or long (__\--help__) help. - -- \--iprelay\[=addr or cmd\] - - 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. - - 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. - - Note: This option is expected to work with HWG-ER02a IP relays. - -- \-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__). - -- \-I - - 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. - -- \-J - - 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. - -- \--on, --off - - Synonym for --iprelay=on/off. - -- \--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. + make -C server install -- \--no-file-gen +## Documentation - Do not generate files on the fly (i.e. "<" syntax) except for the - files generated via "< ~/.novaboot - -to create a default configuration file and modify it to your needs. -Some configuration variables can be overriden by environment variables -(see below) or by command line switches. - -Documentation of some configuration variables follows: - -- @chainloaders - - Custom chainloaders to load before hypervisor and files specified in - novaboot script. E.g. ('bin/boot/bender promisc', 'bin/boot/zapp'). - -- %custom\_options - - Defines custom command line options that can serve as aliases for - other options. E.g. 'S' => '--server=boot:/tftproot - \--serial=/dev/ttyUSB0'. - -# 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 - - A name of default novaboot configuration file. +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. -- NOVABOOT\_BENDER +### Client side - Defining this variable has the same meaning as __\--bender__ option. +- novaboot [documentation](./README.pod) -- NOVABOOT\_IPRELAY +### Server-side (optional, needed only by server administrators for setup C) - The IP address (and optionally the port) of the IP relay. This - overrides $iprelay\_addr variable from the configuration file. +- [novaboot-shell](server/novaboot-shell.pod) +- [adduser-novaboot](server/adduser-novaboot.pod) -# AUTHORS +### Hardware guides -Michal Sojka +- [Raspberry Pi](./doc/README.rpi.md) (work-in-progress)