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.
 136
 137 =item target_config
 138
 139 Novaboot command line options that specify which boot loader is used
 140 by the target (L<novaboot(1)> rejects other, possibly dangerous, options).
 141 Each option is on its own line and no quoting, escaping or stripping
 142 is performed on the values.
 143
 144 Example:
 145
 146   target_config="\
 147   --uboot=(uboot)
 148   --uboot-init=setenv serverip 192.168.1.1; setenv ipaddr 192.168.1.10
 149   --uboot-addr=kernel=0x8100000
 150   --uboot-addr=fdt=0x83000000
 151   --uboot-addr=ramdisk=0x83100000
 152   "
 153
 154 =item default_cmd
 155
 156 If set, this command is executed when no command is specified on the
 157 command line. If not set, C<console_cmd> is executed instead.
 158
 159 As F<novaboot> (client) always uses the C<console> command to connect
 160 to the console, C<default_cmd> can be used to boot the target with
 161 some default configuration for users who do not use F<novaboot> client
 162 to boot their own configuration. For example, C<default_cmd> can be
 163 set to execute a novaboot script.
 164
 165 In other words, C<ssh board@host> boots the board in the default
 166 configuration, whereas C<novaboot --ssh=board@host ...> boots the
 167 board as configured in C<...>.
 168
 169 =back
 170
 171 =head1 AUTHORS
 172
 173 Michal Sojka <sojkam1@fel.cvut.cz>
 174
 175 Latest version can be found at
 176 L<https://github.com/wentasah/novaboot>.
 177
 178 =cut