server/novaboot-shell.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 novaboot-shell - provides novaboot with unified SSH-based interface for controlling target hardware
   6
   7 =head1 SYNOPSIS
   8
   9 B<novaboot-shell> -c "[command [arguments...]]"
  10
  11 B<novaboot-shell> [command [arguments...]]
  12
  13 B<ssh target@server> [command [arguments...]]
  14
  15 =head1 DESCRIPTION
  16
  17 B<novaboot-shell> provides L<novaboot(1)> with a unified SSH-based
  18 interface for controlling the target hardware. This simplifies
  19 client-side configuration, since clients typically only need the
  20 I<--ssh=...> option. B<novaboot-shell> is usually configured as the
  21 login shell of special user accounts associated with the target
  22 hardware (as set by L<adduser-novaboot(8)>). It ensures that users can
  23 only perform a limited number of actions (see L</COMMANDS> below) with
  24 the target and have no shell access on the server.
  25
  26 =head1 COMMANDS
  27
  28 =over 8
  29
  30 =item console
  31
  32 Connect to the target console (usually a serial line). When someone is
  33 connected to the console, other users are blocked from controlling the
  34 target. Blocked users see a message indicating who is blocking them.
  35
  36 The user connected to the console can invoke other commands such as
  37 L</reset>, but only if the command is invoked via the same SSH
  38 connection. This can be accomplished by using SSH connection sharing,
  39 which is what L<novaboot(1)> uses (see I<-M> and I<-S> in L<ssh(1)>).
  40
  41 This is the default command if no command is specified on the command
  42 line and C<default_cmd> is not set in the configuration file.
  43
  44 =item reset
  45
  46 Reset the target hardware.
  47
  48 =item on
  49
  50 Power on the target hardware.
  51
  52 =item off
  53
  54 Power off the target hardware.
  55
  56 =item rsync [...]
  57
  58 This command is not intended to be invoked directly by the user. It
  59 allows using L<rsync(1)> to copy files to the target, perhaps for a
  60 TFTP server. The rsync command must be invoked as: C<rsync ...
  61 target@server:>, i.e. without specifying destination path. The files
  62 will be stored into I<$HOME/tftproot>.
  63
  64 =item user <uernamename> [admin]
  65
  66 User command is intended for use with the C<command=> option in the
  67 SSH L<authorized_keys(5)> file. It allows the shell to display
  68 human-readable names when printing information about who is blocking
  69 the target. Then, the actual command is taken from
  70 SSH_ORIGINAL_COMMAND environment variable.
  71
  72 If "admin" is specified after the user name, that user is considered
  73 an administrator and is allowed to run the L</add-key> and L</shell>
  74 commands.
  75
  76 =item get-config
  77
  78 Prints novaboot configuration options needed for the target. One
  79 option per line.
  80
  81 =back
  82
  83 =head2 Administration commands
  84
  85 Only administrators (see L</user>) are authorized to execute these
  86 commands.
  87
  88 =over 8
  89
  90 =item add-key <username>
  91
  92 Reads the SSH public key from standard input and adds it to
  93 F<~/.ssh/authorized_keys>.
  94
  95 Example: C<ssh target@server add-key johndoe < john_rsa.pub>
  96
  97 =item shell
  98
  99 Runs the shell on the server. Useful for editing the configuration
 100 file. It is better used with an allocated pseudo-terminal.
 101
 102 Example: C<ssh -t target@server shell>
 103
 104 =back
 105
 106 =head1 CONFIGURATION FILE
 107
 108 B<novaboot-shell> reads the configuration file from
 109 F<$HOME/.novaboot-shell>. It can define values for the following
 110 variables in shell syntax.
 111
 112 =over 8
 113
 114 =item console_cmd
 115
 116 Command to C<exec> that connects to the target's console.
 117
 118 Note that if you need more complex behavior of the console command,
 119 e.g., different behavior for different users (distinguished by the
 120 value of the C<$NB_USER> variable), you can set this variable to the
 121 name of a shell function, that you define in the configuration file
 122 and implement the complex behavior there.
 123
 124 =item reset_cmd
 125
 126 Command to C<exec> that resets the Target.
 127
 128 =item on_cmd
 129
 130 Command to C<exec> that powers the target on.
 131
 132 =item off_cmd
 133
 134 Command to C<exec> that powers the target off. This command is
 135 executed either explicitly, when novaboot-shell C<off> command is
 136 invoked or automatically, after the last novaboot-shell session
 137 finishes and the C<novaboot-delayed-power-off> systemd user service is
 138 enabled (see below).
 139
 140 =item target_config
 141
 142 Novaboot command line options that specify which boot loader is used
 143 by the target (L<novaboot(1)> rejects other, possibly dangerous,
 144 options). Each option is on a separate line and the values are not
 145 quoted, escaped or stripped.
 146
 147 Example:
 148
 149   target_config="\
 150   --uboot=(uboot)
 151   --uboot-init=setenv serverip 192.168.1.1; setenv ipaddr 192.168.1.10
 152   --uboot-addr=kernel=0x8100000
 153   --uboot-addr=fdt=0x83000000
 154   --uboot-addr=ramdisk=0x83100000
 155   "
 156
 157 =item default_cmd
 158
 159 If set, this command will be executed if no command is specified on
 160 the command line. If not set, C<console_cmd> will be executed instead.
 161
 162 F<novaboot> (client) always uses the C<console> command to connect to
 163 the console, therefore C<default_cmd> can be used to boot the target
 164 with a default configuration for users who do not use F<novaboot>
 165 client to boot their own configuration.
 166
 167 In other words, C<ssh board@host> will boot the board with a default
 168 configuration, whereas C<novaboot --ssh=board@host ...> will boot the
 169 board as configured in C<...>.
 170
 171 It is often desirable to run F<novaboot> on the server to boot the
 172 default configuration. To configure this more easily, the
 173 C<default_cmd> can be set to:
 174
 175   run_novaboot <nbscript> [<extra args>...]
 176
 177 This command will execute C<novaboot> with the F<\<nbscript> script as
 178 argument and passes it a few switches with values from the
 179 F<$HOME/.novaboot-shell> configuration file. In particular, it will
 180 pass all switches from the C<target_config> variable, the switches
 181 C<--reset-cmd> and C<--remote-cmd> with values of C<reset_cmd> and
 182 C<console_cmd> variables respectively (see above) and the C<--server>
 183 switch.
 184
 185 Therefore, to boot the default configuration as specified in the
 186 F<default_boot> script, it is sufficient to set C<default_cmd> to:
 187
 188   run_novaboot ./default_boot --interactive
 189
 190 To have different configurations for different users, you can use the
 191 C<$NB_USER> variable as outlined above. Perhaps the simplest example
 192 is this command:
 193
 194   run_novaboot ./default_boot-"$NB_USER" --interactive
 195
 196 =back
 197
 198 =head1 AUTOMATIC POWER OFF
 199
 200 The target can be powered off automatically when the last session is
 201 finished. This can be enabled by running:
 202
 203     systemctl --user enable novaboot-delayed-power-off
 204
 205 Perhaps via the C<shell> subcommand. To enable delayed power-off for
 206 all novaboot-shell accounts, run the follwing as root:
 207
 208     systemctl --global enable novaboot-delayed-power-off
 209
 210 Individual accounts can disable this global configuration by running:
 211
 212     systemctl --user mask novaboot-delayed-power-off
 213
 214 When C<novaboot-delayed-power-off> is enabled, the I<on> and I<off>
 215 commands are executed through systemd rather than by C<novaboot-shell>
 216 directly. The delay between the end of the session and power off is
 217 hard-coded in the B<novaboot-power-off@.timer> unit. To override the
 218 timeout for individual targets, run:
 219
 220     systemctl edit novaboot-power-off@TARGET.timer
 221
 222 for your B<TARGET> (the user running C<novaboot-shell>) and insert the
 223 following into the spawned editor:
 224
 225     [Timer]
 226     OnActiveSec=30min
 227
 228 =head2 Implementation/Debugging
 229
 230 Implementation of delayed power off is a bit tricky because it uses
 231 C<sudo> in combination with several systemd services and timers. Here
 232 is a summary of the call chains in various situations. This might be
 233 useful for debugging.
 234
 235 Powering on (via I<on> or I<console> subcommands):
 236
 237   novaboot-shell -c on
 238     systemctl --user start novaboot-delayed-power-off.service
 239       sudo novaboot-power on
 240         systemctl stop  "novaboot-power-off@${SUDO_USER}.timer"
 241         systemctl start "novaboot-power@${SUDO_USER}.service"
 242           novaboot-shell -c on (with $PPID = 1)
 243             eval "$on_cmd"
 244
 245 Powering off via explicit I<off> subcommand:
 246
 247   novaboot-shell -c off
 248     sudo novaboot-power off
 249       systemctl stop "novaboot-power@${SUDO_USER}.service"
 250         novaboot-shell -c off (with $PPID = 1)
 251           eval $off_cmd
 252
 253 Delayed off (executed automatically as a stop job of
 254 novaboot-delayed-power-off.service at session end):
 255
 256   sudo novaboot-power delayed-off
 257     systemctl start "novaboot-power-off@${SUDO_USER}.timer"
 258   ...
 259   novaboot-power-off@${SUDO_USER}.service conflicts novaboot-power@${SUDO_USER}.service
 260     novaboot-shell -c off (with $PPID = 1)
 261       eval $off_cmd
 262
 263 =head1 AUTHORS
 264
 265 Michal Sojka <sojkam1@fel.cvut.cz>
 266
 267 Latest version can be found at
 268 L<https://github.com/wentasah/novaboot>.
 269
 270 =cut