~$ bcvi --help
NAME
bcvi - Back-channel vi, a shell utility to proxy commands back over ssh
SYNOPSIS
bcvi [options] [<files>]
Options:
--add-aliases install bcvi into shell startup files
--command|-c <cmnd> command to send over back-channel
--help|-? detailed help message
--install <hosts> copy bcvi to named hosts and install aliases
--listener|-l start in listener mode
--no-path-xlate|-n skip translation of args from relative to absolute
--plugin-help <plugin> display documentation for <plugin>
--port|-p <port> port number for listener/port-forward
--reuse-auth don’t generate a new auth key on listener startup
--unpack-term unpack the overloaded TERM variable
--version|-v display bcvi version number
--wrap-ssh|-s pass all args after -- to ssh
DESCRIPTION
This utility works with SSH to allow commands issued on the SSH server
host to be ‘proxied’ back to the SSH client host. For example:
* user sally establishes an SSH connection from her workstation to a
server named pluto and runs the command “bcvi .bashrc”
* bcvi tunnels the details back to sally’s workstation which then
invokes the command “gvim scp://pluto//home/sally/.bashrc”
* the result is that sally gets a responsive GUI editor running on her
local machine, but editing a file on the remote machine
See “perldoc App::BCVI” for more examples and background information.
OPTIONS
--add-aliases
Edit the bash startup script to add (or update) the required command
aliases for bcvi.
--command (alias: -c) <cmnd>
Use “cmnd” as the command to send over the back-channel (default: vi).
Recognised commands are described in COMMANDS below.
--help (alias: -?)
Display this documentation.
--install <hosts>
Copy the “bcvi” script to the “$HOME/bin” directory on the specified
host and then remotely invoke it with the “--add-aliases” option.
--listener (alias: -l)
Start a background listener process. Also generates a new
authentication key.
--no-path-xlate (alias: -n)
Displays the version number of the bcvi client and if applicable, of
the listener process.
--plugin-help <plugin>
The --help output includes a list of installed plugins. Use this
option to read the documentation for a named plugin.
--port (alias: -p) <port>
When used with “--listener”, this is the port the server process will
listen on. When used with “--wrap-ssh” this is the port number on the
remote machine that will be forwarded back to the listener process.
The default in both cases is calculated using the user’s numeric UID
multiplied by 10 and added to 9. The intent is to reduce the chance
of collisions with other bcvi users.
--reuse-auth
A new (random) authorisation key is generated when the listener
process is started - this will invalidate the keys in use by existing
SSH sessions. This option is for use when it is necessary to restart
the listener process without invalidating client keys.
--unpack-term
This option is intended for use from a .profile script. It outputs a
snippet of shell script to be passed to “eval” in the calling shell.
--version (alias: -v)
When invoking a command use this option to indicate that the arguments
are not filenames and the translation of relative pathnames to
absolute should be skipped.
--wrap-ssh (alias: -s)
A wrapper around invoking ssh to connect to a specified host. Ensures
the environment is set up to pass the authentication key and other
data to the “bcvi” client on the remote server.
COMMANDS
The following commands can be passed back to the listener process.
notify
Send a message which will be displayed as a notification on the user’s
desktop (where the bcvi listener is running). Typically used with the
“--no-path-xlate” option so that any arguments are passed as text
strings rather than as a list of filenames.
scpd
Uses “scp” to copy the specified files to the calling user’s
~/Desktop.
vi Invokes “gvim” on the remote file - after translating the host+path to
an scp URI. This is the default command if no “--command” option is
specified. If multiple filenames are supplied, the first will be
opened in gvim and you should use “:n” to load the ‘next’ file.
viwait
This command works exactly the same as “vi” above, except it waits for
the editor process to exit before bcvi exits on the remote machine.
This is primarily for use with “sudoedit”. Note: when used with
“sudoedit”, the file will not be updated on the remote machine until
you exit the editor on your workstation.
USING BCVI
You’ll need to start a listener process on your workstation (perhaps from
your window manager session startup).
bcvi -l &
To install the bcvi client to a remote machine:
bcvi --install <hostname>
To ssh to a server with tunnelling enabled:
bcvi --wrap-ssh -- hostname
To enable bcvi on all ssh connections:
alias ssh=“bcvi --wrap-ssh --”
On a target server, you’ll need to unpack the overloaded TERM variable:
test -n “$(which bcvi)” && eval “$(bcvi --unpack-term)”
To use vi over the back-channel:
bcvi filename
The installation to a remote server should set up aliases, e.g.:
test -n “${BCVI_CONF}” && alias vi=“bcvi”
test -n “${BCVI_CONF}” && alias bcp=“bcvi -c scpd”
PLUGINS
You have the following plugin installed:
NotifyClient - Send a notification message back to the user’s desktop
Use “bcvi --plugin-help plugin-name” for detailed info.
COPYRIGHT
Copyright 2007-2010 Grant McLean <grantm@cpan.org>
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
~$