README.rdoc
author Mahlon E. Smith <mahlon@martini.nu>
Thu, 12 Jul 2018 15:25:35 -0700
changeset 11 ffa70066522c
parent 2 5ef02faaf5a5
permissions -rw-r--r--
Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     1
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     2
= symphony-ssh
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     3
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     4
== Description
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     5
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     6
This is a small collection of base classes used for interacting with
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     7
remote machines over ssh.  With them, you can use AMQP (via Symphony) to
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     8
run batch commands, execute templates as scripts, and perform any
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     9
batch/remoting stuff you can think of without the need of a separate
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    10
client agent.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    11
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    12
These classes assume you have a user that can connect and login to
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    13
remote machines using a password-less ssh keypair.  They are not meant
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    14
to be used directly.  Subclass them!
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    15
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    16
See the rdoc for additional information and examples.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    17
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    18
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    19
== Options
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    20
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    21
Symphony-ssh uses
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    22
Configurability[https://rubygems.org/gems/configurability] to determine
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    23
behavior.  The configuration is a YAML[http://www.yaml.org/] file. 
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    24
11
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    25
    symphony:
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    26
        ssh:
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    27
            path: /usr/bin/ssh
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    28
            user: root
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    29
            key: /path/to/a/private_key.rsa
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    30
            opts:
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    31
              - -e
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    32
              - none
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    33
              - -T
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    34
              - -x
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    35
              - -o
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    36
              - CheckHostIP=no'
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    37
              - -o
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    38
              - BatchMode=yes'
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    39
              - -o
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    40
              - StrictHostKeyChecking=no
0
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    41
11
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    42
**NOTE**: If you've upgrade from a version pre 0.2.0, the
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    43
Configurability path has changed from `symphony_ssh`, to an `ssh` key
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    44
under the `symphony` top level.
0
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    45
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    46
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    47
=== path
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    48
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    49
The absolute path to the ssh binary.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    50
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    51
=== user
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    52
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    53
The default user to connect to remote hosts with.  This can be
11
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    54
changed per connection in the AMQP payload.
0
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    55
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    56
=== key
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    57
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    58
An absolute path to a password-less ssh private key.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    59
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    60
=== opts
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    61
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    62
SSH client options, passed to the ssh binary on the command line.  Note
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    63
that the defaults have been tested fairly extensively, these are just
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    64
exposed if you have very specific needs and you know what you're doing.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    65
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    66
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    67
== Installation
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    68
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    69
    gem install symphony-ssh
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    70
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    71
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    72
== Contributing
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    73
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    74
You can check out the current development source with Mercurial via its
2
5ef02faaf5a5 Aaaaand fix the link to the project page.
Mahlon E. Smith <mahlon@martini.nu>
parents: 0
diff changeset
    75
{project page}[http://bitbucket.org/mahlon/symphony-ssh]. 
0
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    76
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    77
After checking out the source, run:
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    78
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    79
    $ rake
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    80
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    81
This task will run the tests/specs and generate the API documentation.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    82
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    83
If you use {rvm}[http://rvm.io/], entering the project directory will
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    84
install any required development dependencies.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    85
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    86
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    87
== License
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    88
11
ffa70066522c Update for Ruby 2.5. Moderize configurability usage, update dependencies.
Mahlon E. Smith <mahlon@martini.nu>
parents: 2
diff changeset
    89
Copyright (c) 2014-2018, Mahlon E. Smith and Michael Granger
0
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    90
All rights reserved.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    91
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    92
Redistribution and use in source and binary forms, with or without
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    93
modification, are permitted provided that the following conditions are met:
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    94
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    95
* Redistributions of source code must retain the above copyright notice,
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    96
  this list of conditions and the following disclaimer.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    97
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    98
* Redistributions in binary form must reproduce the above copyright notice,
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    99
  this list of conditions and the following disclaimer in the documentation
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   100
  and/or other materials provided with the distribution.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   101
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   102
* Neither the name of the author/s, nor the names of the project's
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   103
  contributors may be used to endorse or promote products derived from this
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   104
  software without specific prior written permission.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   105
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   106
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   107
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   108
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   109
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   110
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   111
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   112
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   113
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   114
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   115
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   116
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   117