Skip to content

Latest commit

 

History

History
270 lines (181 loc) · 8.22 KB

novaboot-shell.pod

File metadata and controls

270 lines (181 loc) · 8.22 KB
Raw

NAME

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

SYNOPSIS

novaboot-shell -c "[command [arguments...]]"

novaboot-shell [command [arguments...]]

ssh target@server [command [arguments...]]

DESCRIPTION

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

COMMANDS

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 "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 novaboot(1) uses (see -M and -S in ssh(1)).

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

reset

Reset the target hardware.

on

Power on the target hardware.

off

Power off the target hardware.

rsync [...]

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

user <uernamename> [admin]

User command is intended for use with the command= option in the SSH 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 "add-key" and "shell" commands.

get-config

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

Administration commands

Only administrators (see "user") are authorized to execute these commands.

add-key <username>

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

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

shell

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

Example: ssh -t target@server shell

CONFIGURATION FILE

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

console_cmd

Command to 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 $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.

reset_cmd

Command to exec that resets the Target.

on_cmd

Command to exec that powers the target on.

off_cmd

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

target_config

Novaboot command line options that specify which boot loader is used by the target (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
"
default_cmd

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

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

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

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

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

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

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

run_novaboot ./default_boot --interactive

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

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

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 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 novaboot-delayed-power-off is enabled, the on and off commands are executed through systemd rather than by novaboot-shell directly. The delay between the end of the session and power off is hard-coded in the [email protected] unit. To override the timeout for individual targets, run:

systemctl edit [email protected]

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

[Timer]
OnActiveSec=30min

Implementation/Debugging

Implementation of delayed power off is a bit tricky because it uses 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 on or 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 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

AUTHORS

Michal Sojka <[email protected]>

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