Skip to content
This repository
Browse code

add CPAN distribution files

  • Loading branch information...
commit a090303af6ee249fc037544825efcb7937f6d03a 1 parent bf12b30
Grant McLean authored
11 .gitignore
... ... @@ -0,0 +1,11 @@
  1 +blib*
  2 +Makefile
  3 +Makefile.old
  4 +Build
  5 +_build*
  6 +pm_to_blib*
  7 +*.bak
  8 +*.tar.gz
  9 +.lwpcookies
  10 +App-BCVI-*
  11 +cover_db
16 Changes
... ... @@ -0,0 +1,16 @@
  1 +Revision history for App-BCVI
  2 +
  3 +3.00 2010-??-??
  4 + First version, uploaded to CPAN
  5 + Complete rewrite to support plugin API
  6 +
  7 +2.xx ????-??-??
  8 + Numerous unreleased versions added support for:
  9 + * authentication via shared secrets
  10 + * additional backchannel commands
  11 + * automated installation
  12 + * improved reliability
  13 +
  14 +1.00 2007-04-23
  15 + First version published on PerlMonks
  16 +
9 MANIFEST
... ... @@ -0,0 +1,9 @@
  1 +bin/bcvi
  2 +Changes
  3 +lib/App/BCVI.pod
  4 +Makefile
  5 +Makefile.PL
  6 +MANIFEST
  7 +README
  8 +t/00_syntax.t
  9 +t/pod.t
6 MANIFEST.SKIP
... ... @@ -0,0 +1,6 @@
  1 +^README.markdown
  2 +^\.git
  3 +\.(SKIP|bak|old|swp|gz)$
  4 +^blib
  5 +^pm_to_blib
  6 +^cover_db
17 Makefile.PL
... ... @@ -0,0 +1,17 @@
  1 +use strict;
  2 +use warnings;
  3 +use ExtUtils::MakeMaker;
  4 +
  5 +WriteMakefile(
  6 + NAME => 'App::BCVI',
  7 + AUTHOR => 'Grant McLean <grantm@cpan.org>',
  8 + VERSION_FROM => 'bin/bcvi',
  9 + ABSTRACT_FROM => 'lib/App/BCVI.pod',
  10 + PL_FILES => {},
  11 + PREREQ_PM => {
  12 + 'Test::More' => 0,
  13 + },
  14 + EXE_FILES => [ qw(bin/bcvi) ],
  15 + dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', },
  16 + clean => { FILES => 'App-BCVI-*' },
  17 +);
91 README
... ... @@ -0,0 +1,91 @@
  1 +App-BCVI
  2 +
  3 +This distribution provides the 'bcvi' utility which works with SSH to
  4 +provide a 'back channel' from the SSH server back to your workstation.
  5 +Messages sent over the back channel can initiate a number of tasks
  6 +including invoking a GUI editor on your workstation and instructing it
  7 +to open a file on the server. A number of back channel commands are
  8 +available 'out of the box' and you can write plugins to add more.
  9 +
  10 +
  11 +INSTALLATION
  12 +
  13 +The 'bcvi' program is a standalone script with no companion modules and
  14 +no non-core dependencies. To install it, simply copy the bin/bcvi file
  15 +from the distribution to a directory in your search PATH. Alternatively,
  16 +you can use the standard CPAN installation procedure to install the
  17 +script to /usr/local/bin:
  18 +
  19 + perl Makefile.PL
  20 + make
  21 + make test
  22 + make install
  23 +
  24 +The backchannel protocol requires a client and a server - the 'bcvi' script
  25 +performs both roles. The server runs on your workstation and is typically
  26 +launched by adding this command to your X session startup:
  27 +
  28 + bcvi --listener
  29 +
  30 +When connecting to a server you will want to use this command to wrap the
  31 +SSH command and add the required port forwarding options:
  32 +
  33 + bcvi --wrap-ssh -- hostname
  34 +
  35 +It is probably more convenient to set up an alias so that this happens on
  36 +every SSH connection. Use this command to add the appropriate aliases to
  37 +your bash startup scripts:
  38 +
  39 + bcvi --add-aliases
  40 +
  41 +Now that you have the server set up and ssh connection wrapping in place,
  42 +you need to install 'bcvi' on the machine you will ssh to:
  43 +
  44 + bcvi --install HOSTNAME
  45 +
  46 +Now that the installation is complete, when you log in to the machine
  47 +using SSH, a number of shell aliases will be available to you:
  48 +
  49 + vi
  50 + Invokes gvim on your workstation, passing it an scp://... URL
  51 + of the file(s) you wish to edit
  52 +
  53 + suvi
  54 + Same as above, but uses sudoedit so system files (requiring
  55 + root access) can be edited too
  56 +
  57 + bcp
  58 + Copies the named file back to your workstation desktop
  59 +
  60 +SUPPORT AND DOCUMENTATION
  61 +
  62 +The 'bcvi' command has built-in documentation which you can read with:
  63 +
  64 + bcvi --help
  65 +
  66 +To find out more about writing and installing plugins, use perldoc:
  67 +
  68 + perldoc App::BCVI
  69 +
  70 +You can also look for information at:
  71 +
  72 + RT, CPAN's request tracker
  73 + http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-BCVI
  74 +
  75 + AnnoCPAN, Annotated CPAN documentation
  76 + http://annocpan.org/dist/App-BCVI
  77 +
  78 + CPAN Ratings
  79 + http://cpanratings.perl.org/d/App-BCVI
  80 +
  81 + Search CPAN
  82 + http://search.cpan.org/dist/App-BCVI
  83 +
  84 +
  85 +COPYRIGHT AND LICENCE
  86 +
  87 +Copyright (C) 2007-2010 Grant McLean
  88 +
  89 +This program is free software; you can redistribute it and/or modify it
  90 +under the same terms as Perl itself.
  91 +
371 lib/App/BCVI.pod
Source Rendered
... ... @@ -0,0 +1,371 @@
  1 +package App::BCVI;
  2 +
  3 +use warnings;
  4 +use strict;
  5 +
  6 +=head1 NAME
  7 +
  8 +App::BCVI - Back-channel vi, proxy commands back over ssh
  9 +
  10 +=head1 DESCRIPTION
  11 +
  12 +The C<bcvi> utility works with SSH to allow commands issued on the SSH server
  13 +host to be sent I<back> to the SSH client host over a port-forwarded 'back
  14 +channel'. A few examples might help clarify how bcvi is used:
  15 +
  16 +=head2 Example 1
  17 +
  18 +A user 'sally' opens a gnome-terminal window on her workstation and uses the
  19 +SSH command to log in to the host 'pluto'. She then types a command to edit a
  20 +file:
  21 +
  22 + ~$ ssh pluto
  23 + sally@pluto:~$ vi .bashrc
  24 +
  25 +The result is that the file is opened for editing in a 'gvim' editor window on
  26 +sally's workstation. Note, this does B<not> use X-forwarding. The GUI editor
  27 +process is running on sally's workstation. The file is copied transparently to
  28 +and from the server pluto using scp (via gvim's 'netrw' network transport
  29 +layer).
  30 +
  31 +The advantages to sally include:
  32 +
  33 +=over 4
  34 +
  35 +=item *
  36 +
  37 +no GUI apps or libraries need to be installed on the server
  38 +
  39 +=item *
  40 +
  41 +gvim on sally's workstation has all her preferred key mappings, custom macros,
  42 +plugins and scripts
  43 +
  44 +=item *
  45 +
  46 +gvim is a GUI app that responds to mouse input for scrolling, selecting text,
  47 +copying and pasting
  48 +
  49 +=item *
  50 +
  51 +gvim knows when sally is pasting so it disables autoindent automatically and
  52 +avoids the dreaded stair-step effect often seen when pasting into vim in a
  53 +terminal window
  54 +
  55 +=item *
  56 +
  57 +because gvim is running locally (rather than via X-forwarding) the application
  58 +loads quickly and is responsive to user input
  59 +
  60 +=back
  61 +
  62 +=head2 How it Works
  63 +
  64 +The C<bcvi> utility was not responsible for copying files to and from the server
  65 +'pluto'. Rather, bcvi was used to establish a communications channel from
  66 +'pluto' back to sally's workstation. This back channel was used to send a
  67 +message triggering the launching of gvim and the loading of the specified file.
  68 +
  69 +The example above assumed:
  70 +
  71 +=over 4
  72 +
  73 +=item *
  74 +
  75 +a bcvi 'listener' process had been started by sally's X session startup scripts
  76 +
  77 +=item *
  78 +
  79 +the 'ssh' command used to connect to 'pluto' was actually a shell alias that
  80 +set up the environment and invoked the real ssh command with additional
  81 +parameters for port forwarding the 'back channel'
  82 +
  83 +=item *
  84 +
  85 +sally's login script on 'pluto' invoked bcvi to unpack the environment and set
  86 +up the required authentication key
  87 +
  88 +=item *
  89 +
  90 +the 'vi' command used to edit the file on pluto was actually a shell alias
  91 +that invoked bcvi to pass a message over the backchannel to the listener
  92 +process on sally's workstation
  93 +
  94 +=item *
  95 +
  96 +the listener process unpacked the message to extract the hostname and filename
  97 +information needed to launch this command:
  98 +
  99 + gvim scp://pluto//home/sally/.bashrc
  100 +
  101 +=back
  102 +
  103 +For more information on setting up the listener and aliases, see
  104 +L<"INSTALLATION"> below.
  105 +
  106 +=head2 Example 2
  107 +
  108 +Our friend 'sally' is logged on to the server 'pluto' and is trying to configure
  109 +the 'Acme CRM' package. She explores the filesystem and locates a useful file
  110 +in the documentation directory:
  111 +
  112 + sally@pluto:~$ cd /usr/share/doc/acmecrm/
  113 + sally@pluto:acmecrm$ ls
  114 + changelog.Debian.gz copyright README
  115 + changelog.gz manual.pdf README.Debian
  116 + sally@pluto:acmecrm$ bcp manual.pdf
  117 +
  118 +In the final command above, sally used the C<bcp> command to copy the PDF file
  119 +back to the desktop on her workstation. Then she simply double-clicked the
  120 +file to open it in her PDF viewer.
  121 +
  122 +=head2 How It Worked
  123 +
  124 +This second example used all the same infrastructure as the first (listener
  125 +process, shell aliases and port forward) but added the command C<bcp> Once
  126 +again, this is a shell alias that invokes C<bcvi> to send a message back to the
  127 +listener process. The only difference is that this time the message instructs
  128 +the listener process to run this command:
  129 +
  130 + scp -q pluto:/usr/share/doc/acmecrm/manual.pdf /home/sally/Desktop
  131 +
  132 +Note, for security reasons, the bcvi process running on pluto is not allowed to
  133 +specify the command that gets executed on the workstation. It simply sends a
  134 +request which includes hostname and filename details. The listener process
  135 +determines which requests it will accept and which commands it will run to
  136 +handle them.
  137 +
  138 +=head2 Example 3
  139 +
  140 +Sally is now making progress setting up the Acme CRM package. The next step is
  141 +to restore a database dump. This will take some time and Sally has other
  142 +things to get on with so she kicks off this command (actually, two commands
  143 +separated by a semicolon):
  144 +
  145 + sally@pluto:~$ pg_restore -d acmecrm crm.pgdump; bnotify "DB is restored!"
  146 +
  147 +Sally then minimises her shell/ssh window and gets on with some other important
  148 +work. Some minutes later, a desktop notification window pops up on her screen:
  149 +
  150 + +-------------------------+
  151 + | Notification from pluto |
  152 + | DB is restored! |
  153 + +-------------------------+
  154 +
  155 +Sally can now return to her number one priority - completing the set up of the
  156 +Acme CRM software on pluto.
  157 +
  158 +=head2 How It Worked
  159 +
  160 +Once again, this example used all the same back channel infrastructure used by
  161 +the previous examples, but this one also used bcvi plugins.
  162 +
  163 +The C<bcvi> script itself requires no extra CPAN modules, but the interface to
  164 +the desktop notifications API requires the L<Desktop::Notify> module from CPAN.
  165 +It also requires a small 'plugin' module to provide the glue between the
  166 +listener process and the additional modules. Plugins are described in more
  167 +detail in L<App::BCVI::Plugins>.
  168 +
  169 +=head1 INSTALLATION
  170 +
  171 +The C<bcvi> program is a standalone script with no companion modules and no
  172 +non-core dependencies. To install it, simply copy the C<bin/bcvi> file from
  173 +the distribution to a directory in your search PATH. Alternatively, you can
  174 +use the standard CPAN installation procedure to install the script to
  175 +/usr/local/bin:
  176 +
  177 + perl Makefile.PL
  178 + make
  179 + make test
  180 + make install
  181 +
  182 +The 'back channel' protocol requires a client and a server - the C<bcvi> script
  183 +performs both roles. The server runs on your workstation and is typically
  184 +launched by adding a command to your X session startup. For example under
  185 +Ubuntu/GNOME you might use the 'System' menu and select C<< Preferences >
  186 +Startup Applications >> and then use the 'Add' button to add this command:
  187 +
  188 + bcvi --listener
  189 +
  190 +If you start a listener manually from a shell window you will want to append an
  191 +ampersand (C<< & >>) to put the command in the background.
  192 +
  193 +When connecting to a server you will want to use this command to wrap the SSH
  194 +command and add the required port forwarding options:
  195 +
  196 + bcvi --wrap-ssh -- hostname
  197 +
  198 +It is probably more convenient to set up an alias so that this happens on every
  199 +SSH connection. Use this command to add the appropriate aliases to your bash
  200 +startup scripts:
  201 +
  202 + bcvi --add-aliases
  203 +
  204 +Now that you have the server set up and ssh connection wrapping in place, you
  205 +need to install C<bcvi> on the machine you will ssh to:
  206 +
  207 + bcvi --install HOSTNAME
  208 +
  209 +At this point it should all work. When you log in to the machine using SSH, a
  210 +number of shell aliases will be available to you:
  211 +
  212 +=over 4
  213 +
  214 +=item B<vi>
  215 +
  216 +Invokes gvim on your workstation, passing it an scp://... URL of the file(s)
  217 +you wish to edit
  218 +
  219 +=item B<suvi>
  220 +
  221 +Same as above, but uses sudoedit so system files (requiring root access) can be
  222 +edited too
  223 +
  224 +=item B<bcp>
  225 +
  226 +Copies the named file back to your workstation desktop
  227 +
  228 +=back
  229 +
  230 +Note: you may like to try SSHMenu (L<http://sshmenu.sourceforge.net/>) which
  231 +can invoke the ssh wrapper automatically when connecting to servers.
  232 +
  233 +=head1 TECHNICAL DETAILS
  234 +
  235 +If you successfully followed the installation instructions above, you can
  236 +probably skip this section.
  237 +
  238 +When the listener process starts, it generates a random authentication key
  239 +which is saved in the file: F<$HOME/.config/bcvi/listener_key>
  240 +
  241 +The process id of the listener is saved in F<$HOME/.config/bcvi/listener_pid>.
  242 +If you start a new listener, it will automatically kill off the old one.
  243 +
  244 +The listener process then opens a local TCP port (by default, your user ID,
  245 +with a 9 appended, but you can use C<--port> to override it), saves the port
  246 +number in F<$HOME/.config/bcvi/listener_port> and waits for incoming
  247 +connections.
  248 +
  249 +When you initiate an SSH connection using the shell alias, a command like
  250 +this is generated:
  251 +
  252 + ssh -R 10569:localhost:10569 HOSTNAME
  253 +
  254 +The first port number is the local port that the listener is waiting on. The
  255 +second port number is the port on the remote machine that the C<bcvi> client
  256 +will connect to and which SSH will forward back to the listener. You can
  257 +override the second port number when you connect. The first port number will
  258 +be read from the F<listener_port> file.
  259 +
  260 +The remote host needs to know three things in order to use the back channel:
  261 +
  262 +=over 4
  263 +
  264 +=item *
  265 +
  266 +The hostname/FQDN that the server is known by from the originating workstation's
  267 +perspective
  268 +
  269 +=item *
  270 +
  271 +The port number on the server that SSH will forward back to the listener
  272 +
  273 +=item *
  274 +
  275 +The random authentication key from the F<listener_key_file>
  276 +
  277 +=back
  278 +
  279 +The ssh wrapper command arranges for these pieces of information to be
  280 +forwarded to the remote host. If you don't want to know how it does that then
  281 +please skip the rest of this paragraph. WARNING: It's not pretty. OK, so you
  282 +really want to know? Don't say I didn't warn you. SSH does not pass
  283 +environment variables from client to server without additional parameters in
  284 +server and client config files. However, SSH B<does> pass the TERM variable.
  285 +So, BCVI appends all the extra info to the end of the TERM variable before
  286 +invoking SSH. This 'overstuffed' TERM variable then needs to be unpacked by
  287 +the user's shell startup script on the server. If this is not done, then your
  288 +term variable will be wrong and you'll need to set it manually before editing
  289 +your .profile to fix it.
  290 +
  291 +Unpacking the environment is achieved by running bcvi with the C<<
  292 +--unpack-term >> option to generate a few lines of Bash script. Those lines
  293 +then need to be eval'd in the shell. The standard installation procedure
  294 +achieves this by adding this line to your shell startup script:
  295 +
  296 + test -n "$(which bcvi)" && eval "$(bcvi --unpack-term)"
  297 +
  298 +This line assumes that C<bcvi> is in your path. Normally C<bcvi> will be in
  299 +your C<$HOME/bin> directory and normally this will be in your $PATH, but it's
  300 +something to check if things go wrong.
  301 +
  302 +The standard installation will also set up the shell aliases listed above,
  303 +notably C<vi>, C<suvi> and C<bcp>, however plugin modules can install
  304 +additional aliases.
  305 +
  306 +When one of these aliases is invoked, C<bcvi> connects to the listener via the
  307 +port-forward and sends a request similar to this:
  308 +
  309 + Auth-Key: 90a5aa7b5d55159b92828d4ba955fe75
  310 + Host-Alias: pluto
  311 + Command: vi
  312 + Content-Length: 20
  313 +
  314 + /home/sally/.bashrc
  315 +
  316 +The line protocol is intended to be UTF8 encoded with Content-Length specified
  317 +in bytes rather than characters.
  318 +
  319 +=head1 SUPPORT
  320 +
  321 +The bcvi script includes bult-in documentation which you can access with this
  322 +command:
  323 +
  324 + bcvi --help
  325 +
  326 +The documentation displayed will be customised to describe all options and
  327 +commands available - including those provided by plugin modules.
  328 +
  329 +This documentation and more details on plugins are available via:
  330 +
  331 + perldoc App::BCVI
  332 + perldoc App::BCVI::Plugins
  333 +
  334 +You can also refer to:
  335 +
  336 +=over 4
  337 +
  338 +=item * RT: CPAN's request tracker (for bug reports)
  339 +
  340 +L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-BCVI>
  341 +
  342 +=item * AnnoCPAN: Annotated CPAN documentation
  343 +
  344 +L<http://annocpan.org/dist/App-BCVI>
  345 +
  346 +=item * CPAN Ratings
  347 +
  348 +L<http://cpanratings.perl.org/d/App-BCVI>
  349 +
  350 +=item * Search CPAN
  351 +
  352 +L<http://search.cpan.org/dist/App-BCVI>
  353 +
  354 +=item * Source Repository
  355 +
  356 +L<http://github.com/grantm/bcvi>
  357 +
  358 +=back
  359 +
  360 +
  361 +=head1 COPYRIGHT & LICENSE
  362 +
  363 +Copyright 2007-2010 Grant McLean C<< <grantm at cpan.org> >>
  364 +
  365 +This program is free software; you can redistribute it and/or modify it under
  366 +the same terms as Perl itself.
  367 +
  368 +
  369 +=cut
  370 +
  371 +1;
23 t/00_syntax.t
... ... @@ -0,0 +1,23 @@
  1 +#!perl
  2 +
  3 +use strict;
  4 +use warnings;
  5 +
  6 +use Test::More tests => 1;
  7 +
  8 +use FindBin;
  9 +
  10 +my @part = File::Spec->splitdir($FindBin::Bin);
  11 +splice(@part, -1, 1, 'bin', 'bcvi');
  12 +my $path = File::Spec->catfile(@part);
  13 +
  14 +my $output = `perl -c $path 2>&1`;
  15 +
  16 +if($? == 0) {
  17 + ok(1, 'syntax chack of bin/bcvi');
  18 +}
  19 +else {
  20 + ok(0, 'syntax chack of bin/bcvi');
  21 + diag($output);
  22 +}
  23 +
12 t/pod.t
... ... @@ -0,0 +1,12 @@
  1 +#!perl -T
  2 +
  3 +use strict;
  4 +use warnings;
  5 +use Test::More;
  6 +
  7 +# Ensure a recent version of Test::Pod
  8 +my $min_tp = 1.22;
  9 +eval "use Test::Pod $min_tp";
  10 +plan skip_all => "Test::Pod $min_tp required for testing POD" if $@;
  11 +
  12 +all_pod_files_ok();

0 comments on commit a090303

Please sign in to comment.
Something went wrong with that request. Please try again.