view release on metacpan or  search on metacpan

lib/App/BCVI.pm  view on Meta::CPAN

package App::BCVI;
{
  $App::BCVI::VERSION = '3.09';
}

# This file is documentation only - all code is in bin/bcvi.  Package name is
# only mentioned here to claim the namespace on CPAN/PAUSE.

1;

__END__

=head1 NAME

App::BCVI - Back-channel vi, a shell utility to proxy commands back over ssh

=head1 DESCRIPTION


The C<bcvi> utility works with SSH to allow commands issued on the SSH server
host to be sent I<back> to the SSH client host over a port-forwarded 'back
channel'.  A few examples might help clarify how C<bcvi> is used (note you can
read an illustrated version of the following examples at:
L<http://sshmenu.sourceforge.net/articles/bcvi/>):

=head2 Example 1

A user 'sally' opens a gnome-terminal window on her workstation and uses the
SSH command to log in to the host 'pluto'.  She then types a command to edit a
file:

  ~$ ssh pluto
  sally@pluto:~$ vi .bashrc

Through the magic of C<bcvi>, the result is that the file is opened for editing
in a 'gvim' editor window on Sally's workstation.  Note, this does B<not> use
X-forwarding.  The GUI editor process is running on Sally's workstation.  The
file is copied transparently to and from the server pluto using scp (via gvim's
'netrw' network transport layer).

Compared to running vim on the remote server in the terminal window, C<bcvi>
provides these advantages to Sally:

=over 4

=item *

gvim on Sally's workstation has all her preferred key mappings, custom macros,
plugins and scripts

=item *

gvim is a GUI app that responds to mouse input for scrolling, selecting text,
copying and pasting

=item *

gvim knows when Sally is pasting so it disables autoindent automatically and
avoids the dreaded stair-step effect often seen when pasting into vim in a
terminal window

=item *

because gvim is running locally (rather than via X-forwarding) the application
loads quickly and is responsive to user input

=item *

no GUI apps or libraries need to be installed on the server*

=back

*You might argue that C<bcvi> itself will need to be installed on the server,
but Sally can do that from her workstation with one simple command (and no need
for root access):

  ~$ bcvi --install pluto
  Creating ~/bin directory on pluto
  Copying bcvi to remote bin directory on pluto
  Creating plugins directory on pluto
  Copying plugin files to pluto
  Added bcvi commands to /home/sally/.bashrc

=head2 How Example 1 Worked

The C<bcvi> utility was not responsible for copying files to and from the
server 'pluto' (gvim can already do that).  Rather, C<bcvi> was used to
establish a communications channel from 'pluto' back to Sally's workstation.
This back channel was used to send a message triggering the launching of gvim
and the loading of the specified file.

The example above assumed:

=over 4

=item *

a C<bcvi> 'listener' process had been launched by Sally's X session startup