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