view release on metacpan or  search on metacpan

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

edited too

=item B<bcp>

Copies the named file back to your workstation desktop

=back

Note: you may like to try SSHMenu (L<http://sshmenu.sourceforge.net/>) which
can invoke the ssh wrapper automatically when connecting to servers.

=head1 TECHNICAL DETAILS

If you successfully followed the installation instructions above, you can
probably skip this section.

When the listener process starts, it generates a random authentication key
which is saved in the file: F<$HOME/.config/bcvi/listener_key>

The process id of the listener is saved in F<$HOME/.config/bcvi/listener_pid>.
If you start a new listener, it will automatically kill off the old one.

The listener process then opens a local TCP port (by default, your user ID,
with a 9 appended, but you can use C<--port> to override it), saves the port
number in F<$HOME/.config/bcvi/listener_port> and waits for incoming
connections.

When you initiate an SSH connection using the shell alias, a command like
this is generated:

  ssh -R 10569:localhost:10569 HOSTNAME

The first port number is the local port that the listener will accept
connections on.  The second port number is the port on the remote machine that
the C<bcvi> client will connect to and which SSH will forward back to the
listener.  You can override the second port number when you connect.  The first
port number will be read from the F<listener_port> file.

The remote host needs to know three things in order to use the back channel:

=over 4

=item *

The hostname/FQDN that the server is known by from the originating workstation's
perspective

=item *

The port number on the server that SSH will forward back to the listener

=item *

The random authentication key from the F<listener_key_file>

=back

The ssh wrapper command arranges for these pieces of information to be
forwarded to the remote host.  If you don't want to know how it does that then
please skip the rest of this paragraph.  WARNING: It's not pretty.  OK, so you
really want to know?  Don't say I didn't warn you.  SSH does not normally pass
environment variables from client to server unless you customise the ssh config
files on the client and the server.  However, SSH B<does> pass the TERM
variable.  So, C<bcvi> appends all the extra info to the end of the TERM
variable before invoking SSH.  This 'overstuffed' TERM variable then needs to
be unpacked by the user's shell startup script on the server.  If this is not
done, then your term variable will be wrong and you'll need to set it manually
before editing your .profile to fix it.

Unpacking the environment is achieved by running C<bcvi> with the C<<
--unpack-term >> option to generate a few lines of Bash script.  Those lines
then need to be eval'd in the shell.  The standard installation procedure
achieves this by adding this line to your shell startup script:

  test -n "$(which bcvi)" && eval "$(bcvi --unpack-term)"

This line assumes that C<bcvi> is in your path.  Normally C<bcvi> will be in
your C<$HOME/bin> directory and normally this will be in your $PATH, but it's
something to check if things go wrong.

The standard installation will also set up the shell aliases listed above,
notably C<vi>, C<suvi> and C<bcp>, however plugin modules can install
additional aliases.

When one of these aliases is invoked, C<bcvi> connects to the listener via the
port-forward and sends a request similar to this:

  Auth-Key: 90a5aa7b5d55159b92828d4ba955fe75
  Host-Alias: pluto
  Command: vi
  Content-Length: 20
  
  /home/sally/.bashrc

The wire protocol is intended to be UTF8 encoded with Content-Length specified
in bytes rather than characters.

=head1 SUPPORT

The C<bcvi> script includes built-in documentation which you can access with
this command:

  bcvi --help

The documentation displayed will be customised to describe all options and
commands available - including those provided by plugin modules.

This documentation and more details on plugins are available via:

    perldoc App::BCVI
    perldoc App::BCVI::Plugins

You can also refer to:

=over 4

=item * Source Repository

L<http://github.com/grantm/bcvi>

=item * RT: CPAN's request tracker (for bug reports)