From: Michal Sojka Date: Tue, 26 Jan 2021 10:45:36 +0000 (+0100) Subject: server: Split documentation to separate files X-Git-Tag: 20210126a~10 X-Git-Url: https://rtime.felk.cvut.cz/gitweb/novaboot.git/commitdiff_plain/cae040530d9563ca769b173b4d2b1b799cb78c11 server: Split documentation to separate files It will be easier to look up the documentation on GitHub. --- diff --git a/server/Makefile b/server/Makefile index 190c5a1..e8e5955 100644 --- a/server/Makefile +++ b/server/Makefile @@ -2,10 +2,10 @@ PREFIX=/usr all: adduser-novaboot.8 novaboot-shell.1 -adduser-novaboot.8: adduser-novaboot +adduser-novaboot.8: adduser-novaboot.pod pod2man --section=8 --center="System Manager's Manual" $< $@ -novaboot-shell.1: novaboot-shell +novaboot-shell.1: novaboot-shell.pod pod2man --center="User commands" $< $@ install: all diff --git a/server/adduser-novaboot b/server/adduser-novaboot index 36afefa..7d6a483 100755 --- a/server/adduser-novaboot +++ b/server/adduser-novaboot @@ -101,80 +101,4 @@ the target. EOF fi - - echo "Done" -exit 0 - -: < --key KEY [--admin-id NAME] [adduser options] user - -=head1 DESCRIPTION - -B is a wrapper of L command that -simplifies creation of user accounts for I's --ssh option. -The created account has its shell set to L. The -command also creates a template of the configuration file, sets up -administrator's SSH key in L prepares directories -and symlinks that for integration with TFTP server. - -=head2 Automatic power-off - -When your system uses L, you can configure a systemd -service to automatically power-off the target after timeout. To enable -this run: - - systemctl --user enable novaboot-delayed-power-off - -as the created user (e.g. via shell subcommand). To enable delayed -power-off for all novaboot-shell account, run the follwing as root: - - systemctl --global enable novaboot-delayed-power-off - -Individual accounts may disable this global configuration by running: - - systemctl --user mask novaboot-delayed-power-off - -The power-off timeout is hardcoded in the B -unit. To override the timeout, run C for your B and insert the -following to the spawned editor: - - [Timer] - OnActiveSec=30min - -=head1 OPTIONS - -=over 8 - -=item --key KEY - -Mandatory argument specifying administrator's public SSH key (e.g. -F<~/.ssh/id_rsa.pub>). The key will be copied to the created account's -F<~/.ssh/authorized_keys> and marked with administrator flag. - -=item --admin-id NAME - -User name associated with the key. This user name is shown to -connecting users when the target is occupied by the administrator. -When omitted, I is used as the user name. - -=back - -=head1 AUTHORS - -Michal Sojka - -Latest version can be found at -L. - -=cut -EOF diff --git a/server/adduser-novaboot.pod b/server/adduser-novaboot.pod new file mode 100644 index 0000000..01380de --- /dev/null +++ b/server/adduser-novaboot.pod @@ -0,0 +1,70 @@ +=encoding utf8 + +=head1 NAME + +adduser-novaboot - create user account for use with novaboot's --ssh option + +=head1 SYNOPSIS + +B --key KEY [--admin-id NAME] [adduser options] user + +=head1 DESCRIPTION + +B is a wrapper of L command that +simplifies creation of user accounts for I's --ssh option. +The created account has its shell set to L. The +command also creates a template of the configuration file, sets up +administrator's SSH key in L prepares directories +and symlinks that for integration with TFTP server. + +=head2 Automatic power-off + +When your system uses L, you can configure a systemd +service to automatically power-off the target after timeout. To enable +this run: + + systemctl --user enable novaboot-delayed-power-off + +as the created user (e.g. via shell subcommand). To enable delayed +power-off for all novaboot-shell account, run the follwing as root: + + systemctl --global enable novaboot-delayed-power-off + +Individual accounts may disable this global configuration by running: + + systemctl --user mask novaboot-delayed-power-off + +The power-off timeout is hardcoded in the B +unit. To override the timeout, run C for your B and insert the +following to the spawned editor: + + [Timer] + OnActiveSec=30min + +=head1 OPTIONS + +=over 8 + +=item --key KEY + +Mandatory argument specifying administrator's public SSH key (e.g. +F<~/.ssh/id_rsa.pub>). The key will be copied to the created account's +F<~/.ssh/authorized_keys> and marked with administrator flag. + +=item --admin-id NAME + +User name associated with the key. This user name is shown to +connecting users when the target is occupied by the administrator. +When omitted, I is used as the user name. + +=back + +=head1 AUTHORS + +Michal Sojka + +Latest version can be found at +L. + +=cut diff --git a/server/novaboot-shell b/server/novaboot-shell index e8ddd1d..bd16c44 100755 --- a/server/novaboot-shell +++ b/server/novaboot-shell @@ -205,185 +205,3 @@ if [ -z "$NOVABOOT_ID" ] && [ "$PPID" -ne 1 ]; then else run_subcommand "$@" fi -exit - -: < -c "[command [arguments...]]" - -B [command [arguments...]] - -B [command [arguments...]] - -=head1 DESCRIPTION - -B provides L with a unified SSH-based -interface for controlling the target hardware. This simplifies -client-side configuration, because clients typically need only the -I<--ssh=...> option. B is typically configured as a -login shell of special user accounts associated with the target -hardware (as set by L). It ensures that users can -perform only a limited set of actions (see L below) with -the target and have no shell access on the server. - -=head1 COMMANDS - -=over 8 - -=item console - -Connect to target console (usually serial line). When somebody is -connected to the console, other users are blocked from controlling the -target. Blocked users see a message indicating who blocks them. - -The user connected to the console is able to invoke other commands -such as L, but only when the command is invoked via the same -SSH connection. This can be accomplished by using SSH connection -sharing, which is what L uses (see I<-M> and I<-S> in -L). - -This is the default command when no command is specified on the -command line and C is not set in the configuration file. - -=item reset - -Reset the target hardware. - -=item on - -Power on the target hardware. - -=item off - -Power off the target hardware. - -=item rsync [...] - -This command is not meant to be invoked directly by the user. It -allows using L to copy files to the target, perhaps for TFTP -server. The rsync command must be invoked as: C, i.e. without specifying destination path. The files -will be stored into I<$HOME/tftproot>. - -=item user [admin] - -User command is meant to be used with C option in SSH's -L file. It allows the shell to display -human-readable names when printing information about who blocks the -target. Then, the real command is taken from SSH_ORIGINAL_COMMAND -environment variable. - -When "admin" is specified after the user name, this user is considered -an administrator and is allowed to run L and L -commands. - -=item get-config - -Prints novaboot configuration options needed for the target. One -option per line. - -=back - -=head2 Administration commands - -Only administrators (see L) are allowed to execute these -commands. - -=over 8 - -=item add-key - -Reads the SSH public key from standard input and adds it into in -F<~/.ssh/authorized_keys>. - -Example: C - -=item shell - -Runs shell on the server. Useful for editing configuration file. It is -better used with allocated pseudo-terminal. - -Example: C - -=back - -=head1 CONFIGURATION FILE - -B reads configuration file from -F<$HOME/.novaboot-shell>. It can define values for the following -variables in the shell syntax. - -=over 8 - -=item console_cmd - -Command to C that connects to target's console. - -Note that if you need more complex behaviour of the console command, -e.g., different behaviour for different users (distinguished by the -value of C<$NB_USER> variable), you can set this variable to a name of -a shell function, which you define in the configuration file and -implement the complex behaviour there. - -=item reset_cmd - -Command to C that resets the Target. - -=item on_cmd - -Command to C that powers the target on. - -=item off_cmd - -Command to C that powers the target off. - -=item target_config - -Novaboot command line options that specify which boot loader is used -by the target (L rejects other, possibly dangerous, options). -Each option is on its own line and no quoting, escaping or stripping -is performed on the values. - -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 - " - -=item default_cmd - -If set, this command is executed when no command is specified on the -command line. If not set, C is executed instead. - -As F (client) always uses the C command to connect -to the console, C can be used to boot the target with -some default configuration for users who do not use F client -to boot their own configuration. For example, C can be -set to execute a novaboot script. - -In other words, C boots the board in the default -configuration, whereas C boots the -board as configured in C<...>. - -=back - -=head1 AUTHORS - -Michal Sojka - -Latest version can be found at -L. - -=cut -EOF diff --git a/server/novaboot-shell.pod b/server/novaboot-shell.pod new file mode 100644 index 0000000..9681f68 --- /dev/null +++ b/server/novaboot-shell.pod @@ -0,0 +1,178 @@ +=encoding utf8 + +=head1 NAME + +novaboot-shell - provides novaboot with unified SSH-based interface for controlling target hardware + +=head1 SYNOPSIS + +B -c "[command [arguments...]]" + +B [command [arguments...]] + +B [command [arguments...]] + +=head1 DESCRIPTION + +B provides L with a unified SSH-based +interface for controlling the target hardware. This simplifies +client-side configuration, because clients typically need only the +I<--ssh=...> option. B is typically configured as a +login shell of special user accounts associated with the target +hardware (as set by L). It ensures that users can +perform only a limited set of actions (see L below) with +the target and have no shell access on the server. + +=head1 COMMANDS + +=over 8 + +=item console + +Connect to target console (usually serial line). When somebody is +connected to the console, other users are blocked from controlling the +target. Blocked users see a message indicating who blocks them. + +The user connected to the console is able to invoke other commands +such as L, but only when the command is invoked via the same +SSH connection. This can be accomplished by using SSH connection +sharing, which is what L uses (see I<-M> and I<-S> in +L). + +This is the default command when no command is specified on the +command line and C is not set in the configuration file. + +=item reset + +Reset the target hardware. + +=item on + +Power on the target hardware. + +=item off + +Power off the target hardware. + +=item rsync [...] + +This command is not meant to be invoked directly by the user. It +allows using L to copy files to the target, perhaps for TFTP +server. The rsync command must be invoked as: C, i.e. without specifying destination path. The files +will be stored into I<$HOME/tftproot>. + +=item user [admin] + +User command is meant to be used with C option in SSH's +L file. It allows the shell to display +human-readable names when printing information about who blocks the +target. Then, the real command is taken from SSH_ORIGINAL_COMMAND +environment variable. + +When "admin" is specified after the user name, this user is considered +an administrator and is allowed to run L and L +commands. + +=item get-config + +Prints novaboot configuration options needed for the target. One +option per line. + +=back + +=head2 Administration commands + +Only administrators (see L) are allowed to execute these +commands. + +=over 8 + +=item add-key + +Reads the SSH public key from standard input and adds it into in +F<~/.ssh/authorized_keys>. + +Example: C + +=item shell + +Runs shell on the server. Useful for editing configuration file. It is +better used with allocated pseudo-terminal. + +Example: C + +=back + +=head1 CONFIGURATION FILE + +B reads configuration file from +F<$HOME/.novaboot-shell>. It can define values for the following +variables in the shell syntax. + +=over 8 + +=item console_cmd + +Command to C that connects to target's console. + +Note that if you need more complex behaviour of the console command, +e.g., different behaviour for different users (distinguished by the +value of C<$NB_USER> variable), you can set this variable to a name of +a shell function, which you define in the configuration file and +implement the complex behaviour there. + +=item reset_cmd + +Command to C that resets the Target. + +=item on_cmd + +Command to C that powers the target on. + +=item off_cmd + +Command to C that powers the target off. + +=item target_config + +Novaboot command line options that specify which boot loader is used +by the target (L rejects other, possibly dangerous, options). +Each option is on its own line and no quoting, escaping or stripping +is performed on the values. + +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 + " + +=item default_cmd + +If set, this command is executed when no command is specified on the +command line. If not set, C is executed instead. + +As F (client) always uses the C command to connect +to the console, C can be used to boot the target with +some default configuration for users who do not use F client +to boot their own configuration. For example, C can be +set to execute a novaboot script. + +In other words, C boots the board in the default +configuration, whereas C boots the +board as configured in C<...>. + +=back + +=head1 AUTHORS + +Michal Sojka + +Latest version can be found at +L. + +=cut