view release on metacpan or  search on metacpan

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

Note, for security reasons, the C<bcvi> process running on pluto is not allowed
to specify the command that gets executed on the workstation.  It simply sends
a request which includes hostname and filename details.  The listener process
determines which types of requests it will accept and which commands it will
run to handle them.

=head2 Example 3

Sally is now making progress setting up the Acme CRM package.  The next step is
to restore a database dump.  This will take some time and Sally has other
things to get on with so she kicks off this command (actually, two commands
separated by a semicolon):

  sally@pluto:~$ pg_restore -d acmecrm crm.pgdump; bnotify 'DB is restored!'

Sally then minimises her shell/ssh window and gets on with some other important
work.  Some minutes later, a desktop notification window pops up on her screen:

  +-------------------------+
  | Notification from pluto |
  | DB is restored!         |
  +-------------------------+

Sally can now return to her number one priority - completing the set up of the
Acme CRM software on pluto.

=head2 How Example 3 Worked

Once again, this example used all the same back channel infrastructure used by
the previous examples, but this one also used C<bcvi> plugins.

The C<bcvi> script itself requires no extra CPAN modules, but the interface to
the desktop notifications API requires the L<Desktop::Notify> module from CPAN.
It also requires a small 'plugin' module to provide the glue between the
listener process and the additional modules.  Plugins are described in more
detail in L<App::BCVI::Plugins>.

=head1 INSTALLATION

The C<bcvi> program is a standalone script with no companion modules and no
non-core dependencies.  To install it, simply copy the C<bin/bcvi> file from
the distribution to a directory in your search PATH.  Alternatively, you can
use the standard CPAN installation procedure to install the script to your
site bin directory:

    perl Makefile.PL
    make
    make test
    make install

The 'back channel' protocol requires a client and a server - the C<bcvi> script
performs both roles.  The server runs on your workstation and is typically
launched by adding a command to your X session startup.  For example under
Ubuntu/GNOME you might use the 'System' menu and select C<< Preferences >
Startup Applications >> and then use the 'Add' button to add this command:

    bcvi --listener

If you start a listener manually from a shell window you will want to append an
ampersand (C<< & >>) to put the command in the background.

When connecting to a server you will want to use this command to wrap the SSH
command and add the required port forwarding options:

    bcvi --wrap-ssh -- hostname

It is probably more convenient to set up an alias so that this happens on every
SSH connection.  Use this command to add the appropriate aliases to your bash
startup scripts:

    bcvi --add-aliases

Now that you have the server set up and ssh connection wrapping in place, you
need to install C<bcvi> on the machine you will ssh to:

    bcvi --install HOSTNAME

At this point it should all work.  When you log in to the machine using SSH, a
number of shell aliases will be available to you:

=over 4

=item B<vi>

Invokes gvim on your workstation, passing it an scp://... URL of the file(s)
you wish to edit

=item B<suvi>

Same as above, but uses sudoedit so system files (requiring root access) can be
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: