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, because clients typically need only the
  20 I<--ssh=...> option. B<novaboot-shell> is typically configured as a
  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 perform only a limited set 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 target console (usually serial line). When somebody is
  33 connected to the console, other users are blocked from controlling the
  34 target. Blocked users see a message indicating who blocks them.
  35
  36 The user connected to the console is able to invoke other commands
  37 such as L</reset>, but only when the command is invoked via the same
  38 SSH connection. This can be accomplished by using SSH connection
  39 sharing, which is what L<novaboot(1)> uses (see I<-M> and I<-S> in
  40 L<ssh(1)>).
  41
  42 This is the default command when no command is specified on the
  43 command line and C<default_cmd> is not set in the configuration file.
  44
  45 =item reset
  46
  47 Reset the target hardware.
  48
  49 =item on
  50
  51 Power on the target hardware.
  52
  53 =item off
  54
  55 Power off the target hardware.
  56
  57 =item rsync [...]
  58
  59 This command is not meant to be invoked directly by the user. It
  60 allows using L<rsync(1)> to copy files to the target, perhaps for TFTP
  61 server. The rsync command must be invoked as: C<rsync ...
  62 target@server:>, i.e. without specifying destination path. The files
  63 will be stored into I<$HOME/tftproot>.
  64
  65 =item user <uernamename> [admin]
  66
  67 User command is meant to be used with C<command=> option in SSH's
  68 L<authorized_keys(5)> file. It allows the shell to display
  69 human-readable names when printing information about who blocks the
  70 target. Then, the real command is taken from SSH_ORIGINAL_COMMAND
  71 environment variable.
  72
  73 When "admin" is specified after the user name, this user is considered
  74 an administrator and is allowed to run L</add-key> and L</shell>
  75 commands.
  76
  77 =item get-config
  78
  79 Prints novaboot configuration options needed for the target. One
  80 option per line.
  81
  82 =back
  83
  84 =head2 Administration commands
  85
  86 Only administrators (see L</user>) are allowed to execute these
  87 commands.
  88
  89 =over 8
  90
  91 =item add-key <username>
  92
  93 Reads the SSH public key from standard input and adds it into in
  94 F<~/.ssh/authorized_keys>.
  95
  96 Example: C<ssh target@server add-key johndoe < john_rsa.pub>
  97
  98 =item shell
  99
 100 Runs shell on the server. Useful for editing configuration file. It is
 101 better used with allocated pseudo-terminal.
 102
 103 Example: C<ssh -t target@server shell>
 104
 105 =back
 106
 107 =head1 CONFIGURATION FILE
 108
 109 B<novaboot-shell> reads configuration file from
 110 F<$HOME/.novaboot-shell>. It can define values for the following
 111 variables in the shell syntax.
 112
 113 =over 8
 114
 115 =item console_cmd
 116
 117 Command to C<exec> that connects to target's console.
 118
 119 Note that if you need more complex behaviour of the console command,
 120 e.g., different behaviour for different users (distinguished by the
 121 value of C<$NB_USER> variable), you can set this variable to a name of
 122 a shell function, which you define in the configuration file and
 123 implement the complex behaviour there.
 124
 125 =item reset_cmd
 126
 127 Command to C<exec> that resets the Target.
 128
 129 =item on_cmd
 130
 131 Command to C<exec> that powers the target on.
 132
 133 =item off_cmd
 134
 135 Command to C<exec> that powers the target off. This command is
 136 executed either explicitly, when novaboot-shell C<off> command is
 137 invoked or automatically, after the last novaboot-shell session
 138 finishes and the C<novaboot-delayed-power-off> systemd user service is
 139 enabled (see below).
 140
 141 =item target_config
 142
 143 Novaboot command line options that specify which boot loader is used
 144 by the target (L<novaboot(1)> rejects other, possibly dangerous, options).
 145 Each option is on its own line and no quoting, escaping or stripping
 146 is performed on the values.
 147
 148 Example:
 149
 150   target_config="\
 151   --uboot=(uboot)
 152   --uboot-init=setenv serverip 192.168.1.1; setenv ipaddr 192.168.1.10
 153   --uboot-addr=kernel=0x8100000
 154   --uboot-addr=fdt=0x83000000
 155   --uboot-addr=ramdisk=0x83100000
 156   "
 157
 158 =item default_cmd
 159
 160 If set, this command is executed when no command is specified on the
 161 command line. If not set, C<console_cmd> is executed instead.
 162
 163 As F<novaboot> (client) always uses the C<console> command to connect
 164 to the console, C<default_cmd> can be used to boot the target with
 165 some default configuration for users who do not use F<novaboot> client
 166 to boot their own configuration.
 167
 168 In other words, C<ssh board@host> will boot the board in some default
 169 configuration, whereas C<novaboot --ssh=board@host ...> will boot the
 170 board as configured in C<...>.
 171
 172 Often, it is desired to run F<novaboot> on the server to boot the
 173 default configuration. To make this easier to configure, the
 174 C<default_cmd> can be set to:
 175
 176   run_novaboot <nbscript> [<extra args>...]
 177
 178 This command will execute C<novaboot> with the F<\<nbscript>> script
 179 as an argument and passes it a few switches with values from the
 180 F<$HOME/.novaboot-shell> configuration file. Specifically, it will
 181 pass all switches from the C<target_config> variable, C<--reset-cmd>
 182 and C<--remote-cmd> switches with the values of C<reset_cmd> and
 183 C<console_cmd> variables respectively (see above) and C<--server>
 184 switch.
 185
 186 Therefore, to boot the default configuration as specified in the
 187 F<default_boot> script, it is sufficient to set C<default_cmd> to:
 188
 189   run_novaboot ./default_boot --interactive
 190
 191 To have different default configuration for different users, one can
 192 use the C<$NB_USER> variable as outlined above. The simplest example
 193 is perhaps this command:
 194
 195   run_novaboot ./default_boot-"$NB_USER" --interactive
 196
 197 =back
 198
 199 =head1 AUTOMATIC POWER OFF
 200
 201 The target can be automatically powered off when the last session
 202 finishes. This can be enabled by running:
 203
 204     systemctl --user enable novaboot-delayed-power-off
 205
 206 perhaps via the C<shell> subcommand. To enable delayed power-off for
 207 all novaboot-shell accounts, run the follwing as root:
 208
 209     systemctl --global enable novaboot-delayed-power-off
 210
 211 Individual accounts may disable this global configuration by running:
 212
 213     systemctl --user mask novaboot-delayed-power-off
 214
 215 When C<novaboot-delayed-power-off> is enabled, the I<on> and I<off>
 216 commands are executed via systemd rather than by C<novaboot-shell>
 217 directly. The delay between the end of the session and power off is
 218 hardcoded in the B<novaboot-power-off@.timer> unit. To override the
 219 timeout for individual targets, run:
 220
 221     systemctl edit novaboot-power-off@TARGET.timer
 222
 223 for your B<TARGET> (the user running C<novaboot-shell>) and insert the
 224 following to the spawned editor:
 225
 226     [Timer]
 227     OnActiveSec=30min
 228
 229 =head1 AUTHORS
 230
 231 Michal Sojka <sojkam1@fel.cvut.cz>
 232
 233 Latest version can be found at
 234 L<https://github.com/wentasah/novaboot>.
 235
 236 =cut