=encoding utf8

=head1 NAME

novaboot-shell - provides novaboot with unified SSH-based interface for controlling target hardware

=head1 SYNOPSIS

B<novaboot-shell> -c "[command [arguments...]]"

B<novaboot-shell> [command [arguments...]]

B<ssh target@server> [command [arguments...]]

=head1 DESCRIPTION

B<novaboot-shell> provides L<novaboot(1)> with a unified SSH-based
interface for controlling the target hardware. This simplifies
client-side configuration, since clients typically only need the
I<--ssh=...> option. B<novaboot-shell> is usually configured as the
login shell of special user accounts associated with the target
hardware (as set by L<adduser-novaboot(8)>). It ensures that users can
only perform a limited number of actions (see L</COMMANDS> below) with
the target and have no shell access on the server.

=head1 COMMANDS

=over 8

=item console

Connect to the target console (usually a serial line). When someone is
connected to the console, other users are blocked from controlling the
target. Blocked users see a message indicating who is blocking them.

The user connected to the console can invoke other commands such as
L</reset>, but only if the command is invoked via the same SSH
connection. This can be accomplished by using SSH connection sharing,
which is what L<novaboot(1)> uses (see I<-M> and I<-S> in L<ssh(1)>).

This is the default command if no command is specified on the command
line and C<default_cmd> is not set in the configuration file.

=item reset

Reset the target hardware.

=item on

Power on the target hardware.

=item off

Power off the target hardware.

=item rsync [...]

This command is not intended to be invoked directly by the user. It
allows using L<rsync(1)> to copy files to the target, perhaps for a
TFTP server. The rsync command must be invoked as: C<rsync ...
target@server:>, i.e. without specifying destination path. The files
will be stored into I<$HOME/tftproot>.

=item user <uernamename> [admin]

User command is intended for use with the C<command=> option in the
SSH L<authorized_keys(5)> file. It allows the shell to display
human-readable names when printing information about who is blocking
the target. Then, the actual command is taken from
SSH_ORIGINAL_COMMAND environment variable.

If "admin" is specified after the user name, that user is considered
an administrator and is allowed to run the L</add-key> and L</shell>
commands.

=item get-config

Prints novaboot configuration options needed for the target. One
option per line.

=back

=head2 Administration commands

Only administrators (see L</user>) are authorized to execute these
commands.

=over 8

=item add-key <username>

Reads the SSH public key from standard input and adds it to
F<~/.ssh/authorized_keys>.

Example: C<ssh target@server add-key johndoe < john_rsa.pub>

=item shell

Runs the shell on the server. Useful for editing the configuration
file. It is better used with an allocated pseudo-terminal.

Example: C<ssh -t target@server shell>

=back

=head1 CONFIGURATION FILE

B<novaboot-shell> reads the configuration file from
F<$HOME/.novaboot-shell>. It can define values for the following
variables in shell syntax.

=over 8

=item console_cmd

Command to C<exec> that connects to the target's console.

Note that if you need more complex behavior of the console command,
e.g., different behavior for different users (distinguished by the
value of the C<$NB_USER> variable), you can set this variable to the
name of a shell function, that you define in the configuration file
and implement the complex behavior there.

=item reset_cmd

Command to C<exec> that resets the Target.

=item on_cmd

Command to C<exec> that powers the target on.

=item off_cmd

Command to C<exec> that powers the target off. This command is
executed either explicitly, when novaboot-shell C<off> command is
invoked or automatically, after the last novaboot-shell session
finishes and the C<novaboot-delayed-power-off> systemd user service is
enabled (see below).

=item target_config

Novaboot command line options that specify which boot loader is used
by the target (L<novaboot(1)> rejects other, possibly dangerous,
options). Each option is on a separate line and the values are not
quoted, escaped or stripped.

Example:

  target_config="\
  --uboot=(uboot)
  --uboot-init=setenv serverip 192.168.1.1; setenv ipaddr 192.168.1.10
  --uboot-addr=kernel=0x8100000
  --uboot-addr=fdt=0x83000000
  --uboot-addr=ramdisk=0x83100000
  "

=item default_cmd

If set, this command will be executed if no command is specified on
the command line. If not set, C<console_cmd> will be executed instead.

F<novaboot> (client) always uses the C<console> command to connect to
the console, therefore C<default_cmd> can be used to boot the target
with a default configuration for users who do not use F<novaboot>
client to boot their own configuration.

In other words, C<ssh board@host> will boot the board with a default
configuration, whereas C<novaboot --ssh=board@host ...> will boot the
board as configured in C<...>.

It is often desirable to run F<novaboot> on the server to boot the
default configuration. To configure this more easily, the
C<default_cmd> can be set to:

  run_novaboot <nbscript> [<extra args>...]

This command will execute C<novaboot> with the F<\<nbscript> script as
argument and passes it a few switches with values from the
F<$HOME/.novaboot-shell> configuration file. In particular, it will
pass all switches from the C<target_config> variable, the switches
C<--reset-cmd> and C<--remote-cmd> with values of C<reset_cmd> and
C<console_cmd> variables respectively (see above) and the C<--server>
switch.

Therefore, to boot the default configuration as specified in the
F<default_boot> script, it is sufficient to set C<default_cmd> to:

  run_novaboot ./default_boot --interactive

To have different configurations for different users, you can use the
C<$NB_USER> variable as outlined above. Perhaps the simplest example
is this command:

  run_novaboot ./default_boot-"$NB_USER" --interactive

=back

=head1 AUTOMATIC POWER OFF

The target can be powered off automatically when the last session is
finished. This can be enabled by running:

    systemctl --user enable novaboot-delayed-power-off

Perhaps via the C<shell> subcommand. To enable delayed power-off for
all novaboot-shell accounts, run the follwing as root:

    systemctl --global enable novaboot-delayed-power-off

Individual accounts can disable this global configuration by running:

    systemctl --user mask novaboot-delayed-power-off

When C<novaboot-delayed-power-off> is enabled, the I<on> and I<off>
commands are executed through systemd rather than by C<novaboot-shell>
directly. The delay between the end of the session and power off is
hard-coded in the B<novaboot-power-off@.timer> unit. To override the
timeout for individual targets, run:

    systemctl edit novaboot-power-off@TARGET.timer

for your B<TARGET> (the user running C<novaboot-shell>) and insert the
following into the spawned editor:

    [Timer]
    OnActiveSec=30min

=head2 Implementation/Debugging

Implementation of delayed power off is a bit tricky because it uses
C<sudo> in combination with several systemd services and timers. Here
is a summary of the call chains in various situations. This might be
useful for debugging.

Powering on (via I<on> or I<console> subcommands):

  novaboot-shell -c on
    systemctl --user start novaboot-delayed-power-off.service
      sudo novaboot-power on
        systemctl stop  "novaboot-power-off@${SUDO_USER}.timer"
        systemctl start "novaboot-power@${SUDO_USER}.service"
          novaboot-shell -c on (with $PPID = 1)
            eval "$on_cmd"

Powering off via explicit I<off> subcommand:

  novaboot-shell -c off
    sudo novaboot-power off
      systemctl stop "novaboot-power@${SUDO_USER}.service"
        novaboot-shell -c off (with $PPID = 1)
          eval $off_cmd

Delayed off (executed automatically as a stop job of
novaboot-delayed-power-off.service at session end):

  sudo novaboot-power delayed-off
    systemctl start "novaboot-power-off@${SUDO_USER}.timer"
  ...
  novaboot-power-off@${SUDO_USER}.service conflicts novaboot-power@${SUDO_USER}.service
    novaboot-shell -c off (with $PPID = 1)
      eval $off_cmd

=head1 AUTHORS

Michal Sojka <sojkam1@fel.cvut.cz>

Latest version can be found at
L<https://github.com/wentasah/novaboot>.

=cut