=encoding utf8
+
=head1 NAME
novaboot - Boots a locally compiled operating system on a remote
Configuration file syntax is described in section L</"CONFIGURATION
FILES">.
-Simple examples of using C<novaboot>:
+Novaboot newcomers may be confused by a large number of configuration
+options. Understanding all these options is not always needed,
+depending on the used setup. The L<figure from the doc directory
+|https://github.com/wentasah/novaboot/blob/master/doc/typical-setups.svg>
+shows different setups that vary in how much effort is needed
+configure novaboot for them. The setups are:
+
+=over 3
+
+=item A: Laptop and target device only
+
+This requires to configure everything on the laptop side, including a
+serial line connection (L</--serial>, L</--remote-cmd>, ...), power
+on/off/reset commands (L</--reset-cmd>, ...), TFTP server
+(L</--server>, L</--prefix>...), device IP addresses, etc.
+
+=item B: Laptop, target device and external TFTP server
+
+Like the previous setup, but the TFTP (and maybe DHCP) configuration
+is handled by a server. Novaboot users need to understand where to
+copy their files to the TFTP server (L</--server>) and which IP
+addresses their target will get, but do not need to configure the
+servers themselves.
+
+=item C: Novaboot server running novaboot-shell
+
+With this setup, the configuration is done on the server. Users only
+need to know the SSH account (L</--ssh>) used to communicate between
+novaboot and novaboot server. The server is implemented as a
+restricted shell (L<novaboot-shell(1)>) on the server. No need to give
+full shell access to novaboot users on the server.
+
+=back
+
+=head2 Simple examples of using C<novaboot>:
+
+To boot Linux (files F<bzImage> and F<rootfs.cpio> in current
+directory), create F<mylinux> file with this content:
+
+ #!/usr/bin/env novaboot
+ load bzImage console=ttyS0,115200
+ load rootfs.cpio
=over 3
=item 1.
-Running an OS in Qemu can be accomplished by giving the B<--qemu> option.
+Booting an OS in Qemu can be accomplished by giving the B<--qemu> option.
Thus running
- novaboot --qemu myos
+ novaboot --qemu mylinux
-(or C<./myos --qemu> as described above) will run Qemu and make it
-boot the configuration specified in the F<myos> script.
+(or C<./mylinux --qemu> as described above) will run Qemu and make it
+boot the configuration specified in the F<mylinux> script. How is qemu
+started can be configured in various ways (see below).
=item 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
+with all other files needed for booting to a remote TFTP server. Then
use a TCP/IP-controlled relay/serial-to-TCP converter to reset the
target and receive its serial output.
- ./myos --grub2 --server=192.168.1.1:/tftp --iprelay=192.168.1.2
+ ./mylinux --grub2 --server=192.168.1.1:/tftp --iprelay=192.168.1.2
Alternatively, you can put these switches to the configuration file
and run:
- ./myos --target mytarget
+ ./mylinux --target mytarget
=item 3.
+Specifying all the options needed by novaboot to successfully control
+the target, either on command line or in configuration files, can be
+difficult for users. Novaboot supports configuring the target
+centrally via L<novaboot-shell(1)> on a server. With such a
+configuration, users only need to use the B<--ssh> option to specify
+where to boot their OS:
+
+ ./mylinux --ssh myboard@example.com
+
+Typically, the server is the computer connected to and controlling the
+target board and running the TFTP server.
+
+=item 4.
+
Run DHCP and TFTP server on developer's machine to boot the target
from it.
- ./myos --dhcp-tftp
+ ./mylinux --dhcp-tftp
This usage is useful when no network infrastructure is in place, and
the target is connected directly to developer's box.
-=item 4.
+=item 5.
Create bootable ISO image.
=head1 PHASES AND OPTIONS
-Novaboot performs its work in several phases. Command like options
+Novaboot performs its work in several phases. Command line options
described bellow influence the execution of each phase or allow their
skipping. The list of phases (in the execution order) is as follows.
to use from either B<NOVABOOT_TARGET> environment variable or
B<$default_target> configuration file variable.
+=item --ssh=I<user@hostname>
+
+Configures novaboot to control the target via C<novaboot-shell>
+running remotely via SSH.
+
+Using this option is the same as specifying B<--remote-cmd>,
+B<--remote-expect>, B<--server> B<--rsync-flags>, B<--prefix> and
+B<--reset-cmd> manually in a way compatible with C<novaboot-shell>.
+The server can be configured to provide other, safe bootloader-related
+options, to the client. When this happens, novaboot prints them to
+stdout.
+
+Currently, this in an initial experimental implementation. We plan to
+change/extend this feature soon!
+
=back
=head2 Script preprocessing phase
Note: This option is supposed to work with HWG-ER02a IP relays.
+=item --iprelay-cmd=I<command>
+
+Similar to B<--iprelay> but uses I<command> to talk to the iprelay
+rather than direct network connection.
+
=item -s, --serial[=device]
Target's serial line is connected to host's serial line (device). The
=item --remote-expect=I<string>
-Wait for reception of I<string> after establishing the remote
-connection. This option is needed when novaboot should wait for
-confirmation before deploying files to the target, e.g. to not
-overwrite other user's files when they are using the target.
+Wait for reception of I<string> after establishing the remote serial
+line connection. Novaboot assumes that after establishing the serial
+line connection, the user running novaboot has exclusive access to the
+target. If establishing of the serial line connection happens
+asynchronously (e.g. running a command remotely via SSH), we need this
+option to wait until the exclusive access is confirmed by the remote
+side.
+
+Depending on target configuration, this option can solve two practical
+problems: 1) Overwriting of files deployed by another user currently
+using the target. 2) Resetting the target board before serial line
+connection is established and thus missing bootloader interaction.
+
+Example of usage with the L<sterm
+tool|https://rtime.felk.cvut.cz/gitweb/sojka/sterm.git>:
+
+ --remote-cmd='ssh -tt example.com sterm -v /dev/ttyUSB0' --remote-expect='sterm: Connected'
=item --remote-expect-silent=I<string>
matched string is printed to stdout, so you may want to include line
end characters in the I<string> as well.
+=item --remote-expect-timeout=I<seconds>
+
+Timeout in seconds for B<--remote-expect> or
+B<--remote-expect-seconds>. When negative, waits forever. The default
+is -1 seconds.
+
=back
=head2 File deployment phase
=item --on, --off
Switch on/off the target machine and exit. The script (if any) is
-completely ignored. Currently, it works only with B<--iprelay> or
-B<--amt>.
+completely ignored. Currently, it works only with the following
+options: B<--iprelay>, B<--amt>, B<--ssh>.
=item -Q, --qemu[=I<qemu-binary>]
Interact with U-Boot bootloader to boot the thing described in the
novaboot script. I<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
-that we use. It may be subject to changes in the future!
=item --no-uboot
Disable U-Boot interaction previously enabled with B<--uboot>.
+=item --uboot-stop-key=I<key>
+
+Character, which is sent as a response to U-Boot's "Hit any key to
+stop autoboot" message. The default value is newline, but some devices
+(e.g. TP-Link TD-W8970) require a specific key to be pressed.
+
=item --uboot-init
Command(s) to send the U-Boot bootloader before loading the images and
=item --exiton-timeout=I<seconds>
By default B<--exiton> waits for the string match forever. When this
-option is specified, "exiton" timeouts after the specifies the number of
+option is specified, "exiton" timeouts after the specified number of
seconds and novaboot returns non-zero exit code.
=item -i, --interactive
-Setup things for the interactive use of the 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.
+Setup things for the interactive use of the target. Your terminal will
+be switched to raw mode. In raw mode, your local terminal does not
+process input in any way (no echoing of entered characters, no
+interpretation of special characters). This, among others, means that
+Ctrl-C is passed to the target and does not interrupt novaboot. To
+exit from novaboot interactive mode type "~~.".
=item --no-interaction, --interaction
Assigning this variable has the same effect as specifying L</--exiton>
option.
+=item INTERACTION
+
+Setting this variable to zero is the same as giving
+L</--no-interaction>, specifying to one corresponds to
+L</--interaction>.
+
=item HYPERVISOR_PARAMS
Parameters passed to the hypervisor. The default value is "serial", unless
projects / novaboot.git / blobdiff