]> rtime.felk.cvut.cz Git - novaboot.git/blobdiff - README.md
Update changelog for 20141031 release
[novaboot.git] / README.md
index 687646fca0eaf6897db450b17653d6f2fff29a8e..08028ee6e6abf34e04a4081be673a60261c603ff 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 # NAME
 
-novaboot - A tool for booting various operating systems on various hardware or in qemu
+novaboot - Boots a locally compiled operating system on a remote
+target or in qemu
 
 # SYNOPSIS
 
@@ -12,95 +13,96 @@ novaboot - A tool for booting various operating systems on various hardware or i
 
 # DESCRIPTION
 
-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.
-
+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.
+
+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.
 
-For example, with `novaboot` you can:
+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).
+
+Simple examples of using `novaboot`:
 
 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`.
+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, Pulsar and U-Boot) and copy it with all
-other files needed for booting to a remote boot server.
-
-        ./script --server=192.168.1.1:/tftp --iprelay=192.168.1.2
+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.
 
-    This command copies files to the TFTP server and uses
-    TCP/IP-controlled relay to reset the target host and receive its
-    serial output.
+        ./myos --grub2 --server=192.168.1.1:/tftp --iprelay=192.168.1.2
 
-3. Run DHCP and TFTP server on developer's machine to PXE-boot the target
-host from it. E.g.
+3. Run DHCP and TFTP server on developer's machine to boot the target
+from it.
 
-        ./script --dhcp-tftp
+        ./myos --dhcp-tftp
 
-    When a PXE-bootable machine is connected via Ethernet to developer's
-    machine, it will boot the configuration described in _script_.
+    This is useful when no network infrastructure is in place and
+    the target is connected directly to developer's box.
 
-4. Create bootable ISO images. E.g.
+4. Create bootable ISO image.
 
         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.
+    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 options, certain phases can be skipped. The list
-of phases (in the execution order) and the corresponding options
-follow.
+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 ["CONFIGURATION FILE"](#configuration-file). By default, configuration is
-read from two locations. First from the configuration directory and
-second from `.novaboot` files along the path to the current
-directory. The later read files override settings from the former
-ones.
+described in section ["CONFIGURATION FILE"](#configuration-file). By default,
+configuration is read from two locations. First from the configuration
+directory and second from `.novaboot` files along the path to the
+current directory. The latter read files override settings from the
+former ones.
 
 Configuration directory is determined by the content of
-NOVABOOT\_CONFIG\_DIR environment variable defaulting to
+NOVABOOT\_CONFIG\_DIR environment variable and defaults to
 `/etc/novaboot.d`. Files in this directory with names consisting
-solely from English letters, numbers, dashes '-' and underscores '\_'
+solely of English letters, numbers, dashes '-' and underscores '\_'
 (note that dot '.' is not included) are read in alphabetical order.
 
-Then 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 order from the root directory
-downwards.
+Then 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, user
+specific configuration in `~/.novaboot` and project specific one in
+`~/project/.novaboot`.
 
 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 instead of the novaboot script
-directory.
+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_
 
@@ -110,7 +112,7 @@ directory.
 
 - --dump-config
 
-    Dump the current configuration to stdout end exits. Useful as an
+    Dump the current configuration to stdout end exit. Useful as an
     initial template for a configuration file.
 
 - -h, --help
@@ -133,7 +135,7 @@ used in the later phases.
 
     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.
+    command line. This option can appear multiple times.
 
 - -b, --bender
 
@@ -143,8 +145,9 @@ used in the later phases.
 
 - --chainloader=_chainloader_
 
-    Chainloader that is loaded before the kernel and other files specified
-    in the novaboot script. E.g. 'bin/boot/bender promisc'.
+    Specifies a chainloader that is loaded before the kernel and other
+    files specified in the novaboot script. E.g. 'bin/boot/bender
+    promisc'.
 
 - --dump
 
@@ -201,22 +204,30 @@ running `scons` or `make`.
     GRUB or GRUB2 config files. This is useful for specifying GRUB's
     timeout.
 
-- --grub-prefix=_prefix_
+- --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.
+    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 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
+    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 menuentry on your development
+    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.
@@ -227,8 +238,7 @@ running `scons` or `make`.
 
 - --grub2-prolog=_prolog_
 
-    Specifies text _preable_ that is put at the beginning of the entry
-    GRUB2 entry.
+    Specifies text that is put at the beginning of the GRUB2 menu entry.
 
 - -m, --make\[=make command\]
 
@@ -281,14 +291,6 @@ user/instance.
     used. The _port_ specifies a TCP port for SOL. If not specified, the
     default is 16992. Default _user_ is admin.
 
-- --ider
-
-    Use Intel AMT technology for IDE redirection. This allows the target
-    machine to boot from nonvaboot created ISO image.
-
-    The experimental _amtider_ utility needed by this option can be
-    obtained from https://github.com/wentasah/amtterm.
-
 - --iprelay=_addr\[:port\]_
 
     Use TCP/IP relay and serial port to access the target's serial port
@@ -365,11 +367,15 @@ to a particular location, e.g. to a TFTP boot server or to the
 
 - --server\[=\[\[user@\]server:\]path\]
 
-    Copy all files needed for booting to another location (implies **-g**
-    unless **--grub2** is given). The files will be copied (by **rsync**
-    tool) to the directory _path_. If the _path_ contains string $NAME,
-    it will be replaced with the name of the novaboot script (see also
-    **--name**).
+    Copy all files needed for booting to another location. The files will
+    be copied (by **rsync** tool) to the directory _path_. If the _path_
+    contains string $NAME, it will be replaced with the name of the
+    novaboot script (see also **--name**).
+
+- --rsync-flags=_flags_
+
+    Specifies which _flags_ are appended to `rsync` command line when
+    copying files as a result of _--server_ option.
 
 - --concat
 
@@ -380,13 +386,21 @@ to a particular location, e.g. to a TFTP boot server or to the
     concatenating all files of the same name from all subdirectories of
     _path-wo-name_ found on the "server".
 
-- --rsync-flags=_flags_
+- --ider
 
-    Specifies which _flags_ are appended to `rsync` command line when
-    copying files as a result of _--server_ option.
+    Use Intel AMT technology for IDE redirection. This allows the target
+    machine to boot from novaboot created ISO image. Implies **--iso**.
+
+    The experimental `amtider` utility needed by this option can be
+    obtained from https://github.com/wentasah/amtterm.
 
 ## Target power-on and reset phase
 
+At this point, the target is reset (or switched on/off). There is
+several ways how this can be accomplished. Resetting a physical target
+can currently be accomplished by the following options: **--amt**,
+**--iprelay**, **--reset-cmd**.
+
 - --on, --off
 
     Switch on/off the target machine and exit. The script (if any) is
@@ -412,11 +426,15 @@ to a particular location, e.g. to a TFTP boot server or to the
 
     Command that resets the target.
 
+- --no-reset, --reset
+
+    Disable/enable resetting of the target.
+
 ## Interaction with the bootloader on the target
 
 - --uboot\[=_prompt_\]
 
-    Interact with uBoot bootloader to boot the thing described in the
+    Interact with U-Boot bootloader to boot the thing described in the
     novaboot script. _prompt_ specifies the U-Boot's prompt (default is
     "=> ", other common prompts are "U-Boot> " or "U-Boot# ").
     Implementation of this option is currently tied to a particular board
@@ -428,6 +446,33 @@ to a particular location, e.g. to a TFTP boot server or to the
     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
@@ -437,13 +482,24 @@ interactive work with the target.
 - --exiton=_string_
 
     When _string_ is sent by the target, novaboot exits. This option can
-    be specified multiple times.
+    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
@@ -520,6 +576,15 @@ for `load` keyboard except that the command's output is not
 redirected to a file. The ordering of commands is the same as they
 appear in the novaboot script.
 
+Lines starting with `uboot` represent U-Boot commands that are sent
+to the target if **--uboot** option is given. Having a U-Boot line in
+the novaboot script is the same as passing an equivalent
+**--uboot-init** option to novaboot. The `uboot` keyword can be
+suffixed with timeout specification. The syntax is `uboot:Ns`, where
+`N` is the whole number of seconds. If the U-Boot command prompt does
+not appear before the timeout, novaboot fails. The default timeout is
+10 seconds.
+
 Example (Linux):
 
     #!/usr/bin/env novaboot
@@ -572,6 +637,13 @@ The following variables are interpreted in the novaboot script:
     parameters. If this variable is defined and non-empty, the variable
     HYPERVISOR\_PARAMS is not used.
 
+- NO\_BOOT
+
+    If this variable is 1, the system is not booted. This is currently
+    only implemented for U-Boot bootloader where it is useful for
+    interacting with the bootloader without booting the system - e.g. for
+    flashing.
+
 - QEMU
 
     Use a specific qemu binary (can be overridden with **-Q**) and flags
@@ -583,9 +655,13 @@ The following variables are interpreted in the novaboot script:
 
     Use specific qemu flags (can be overridden with **-q**).
 
+- UBOOT\_CMD
+
+    See ["--uboot-cmd"](#uboot-cmd).
+
 - WVDESC
 
-    Description of the wvtest-compliant program.
+    Description of the WvTest-compliant program.
 
 - WVTEST\_TIMEOUT
 
@@ -597,14 +673,15 @@ The following variables are interpreted in the novaboot script:
 # CONFIGURATION FILE
 
 Novaboot can read its configuration from one or more files. By
-default, novaboot looks for files named `.novaboot` as described in
-["Configuration reading phase"](#configuration-reading-phase). Alternatively, configuration file
-location can be specified with the **-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 **--dump-config** switch. Some
-configuration variables can be overridden by environment variables
-(see below) or by command line switches.
+default, novaboot looks for files in `/etc/novaboot.d` and files
+named `.novaboot` as described in ["Configuration reading phase"](#configuration-reading-phase).
+Alternatively, configuration file location can be specified with the
+**-c** switch or with the NOVABOOT\_CONFIG environment variable. The
+configuration file has Perl syntax (i.e. it is better to put `1;` as
+a last line) and should set values of certain Perl variables. The
+current configuration can be dumped with the **--dump-config** switch.
+Some configuration variables can be overridden by environment
+variables (see below) or by command line switches.
 
 Supported configuration variables include:
 
@@ -628,8 +705,8 @@ Supported configuration variables include:
 
     then the following two commands are equivalent:
 
-        ./script --server=boot:/tftproot --serial=/dev/ttyUSB0 --grub
-        ./script -t mybox
+        ./myos --server=boot:/tftproot --serial=/dev/ttyUSB0 --grub
+        ./myos -t mybox
 
 # ENVIRONMENT VARIABLES