README.rdoc
author Mahlon E. Smith <mahlon@laika.com>
Wed, 28 May 2014 11:45:18 -0700
changeset 8 01c2ba6b0a44
parent 2 5ef02faaf5a5
child 11 ffa70066522c
permissions -rw-r--r--
Bump version.
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
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    25
	symphony_ssh:
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    26
		path: /usr/bin/ssh
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    27
		user: root
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    28
		key: /path/to/a/private_key.rsa
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    29
		opts:
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    30
		  - -e
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    31
		  - none
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    32
		  - -T
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    33
		  - -x
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    34
		  - -o
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    35
		  - CheckHostIP=no'
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    36
		  - -o
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    37
		  - BatchMode=yes'
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    38
		  - -o
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    39
		  - StrictHostKeyChecking=no
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    40
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    41
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    42
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    43
=== path
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    44
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    45
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
    46
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    47
=== user
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 default user to connect to remote hosts with.  This can be
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    50
changes per connection in the AMQP payload.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    51
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    52
=== key
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    53
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    54
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
    55
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    56
=== opts
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
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
    59
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
    60
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
    61
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    62
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    63
== Installation
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    64
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    65
    gem install symphony-ssh
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
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    68
== Contributing
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    69
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    70
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
    71
{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
    72
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    73
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
    74
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    75
    $ rake
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
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
    78
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    79
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
    80
install any required development dependencies.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    81
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
== License
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    84
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    85
Copyright (c) 2014, Mahlon E. Smith and Michael Granger
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    86
All rights reserved.
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    87
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    88
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
    89
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
    90
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    91
* 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
    92
  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
    93
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    94
* 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
    95
  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
    96
  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
    97
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    98
* 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
    99
  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
   100
  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
   101
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   102
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
   103
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
   104
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
   105
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
   106
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
   107
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
   108
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
   109
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
   110
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
   111
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
   112
aef8f9f4a788 Initial commit -- ssh base classes, converted from GroundControl and
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
   113