5 novaboot-shell - provides novaboot with unified SSH-based interface for controlling target hardware
9 B<novaboot-shell> -c "[command [arguments...]]"
11 B<novaboot-shell> [command [arguments...]]
13 B<ssh target@server> [command [arguments...]]
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.
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.
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)>).
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.
46 Reset the target hardware.
50 Power on the target hardware.
54 Power off the target hardware.
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>.
64 =item user <uernamename> [admin]
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.
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>
78 Prints novaboot configuration options needed for the target. One
83 =head2 Administration commands
85 Only administrators (see L</user>) are authorized to execute these
90 =item add-key <username>
92 Reads the SSH public key from standard input and adds it to
93 F<~/.ssh/authorized_keys>.
95 Example: C<ssh target@server add-key johndoe < john_rsa.pub>
99 Runs the shell on the server. Useful for editing the configuration
100 file. It is better used with an allocated pseudo-terminal.
102 Example: C<ssh -t target@server shell>
106 =head1 CONFIGURATION FILE
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.
116 Command to C<exec> that connects to the target's console.
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.
126 Command to C<exec> that resets the Target.
130 Command to C<exec> that powers the target on.
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
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.
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
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.
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.
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<...>.
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:
175 run_novaboot <nbscript> [<extra args>...]
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>
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:
188 run_novaboot ./default_boot --interactive
190 To have different configurations for different users, you can use the
191 C<$NB_USER> variable as outlined above. Perhaps the simplest example
194 run_novaboot ./default_boot-"$NB_USER" --interactive
198 =head1 AUTOMATIC POWER OFF
200 The target can be powered off automatically when the last session is
201 finished. This can be enabled by running:
203 systemctl --user enable novaboot-delayed-power-off
205 Perhaps via the C<shell> subcommand. To enable delayed power-off for
206 all novaboot-shell accounts, run the follwing as root:
208 systemctl --global enable novaboot-delayed-power-off
210 Individual accounts can disable this global configuration by running:
212 systemctl --user mask novaboot-delayed-power-off
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:
220 systemctl edit novaboot-power-off@TARGET.timer
222 for your B<TARGET> (the user running C<novaboot-shell>) and insert the
223 following into the spawned editor:
230 Michal Sojka <sojkam1@fel.cvut.cz>
232 Latest version can be found at
233 L<https://github.com/wentasah/novaboot>.