1. Introduction
1.1. What is Net::SSH?
Net::SSH is a pure-Ruby implementation of the SSH2 client protocol. It supports the following features:
- User authentication via explicit username/password, or using a public-key/private-key pair.
- Port forwarding, both from the local host to a remote computer via the remote host, and from the remote host to the local host.
- Execute processes on the remote machine, both interactively and non-interactively (“batch”).
1.2. What isn’t Net::SSH?
Net::SSH is only a client implementation, not a server. Given sufficient motivation and encouragement from the community, perhaps it will someday include an SSH server, but as of right now, it does not.
Furthermore, it is only an SSH2 client. This means that it cannot connect to SSH servers that only understand the older SSH1 protocol.
1.3. Getting Net::SSH
Prerequisites:
In order to use Net::SSH, you must be using a supported version of Ruby’s OpenSSL module. The version distributed with Ruby 1.8.1 and earlier is not sufficient, and is lacking several features that Net::SSH relies on. If you are using Ruby 1.8.1 (or earlier), you should either upgrade to 1.8.2, or download and install an updated version of the OpenSSL module. You can download a usable snapshot from the Net::SSH downloads page.
Furthermore, you must make sure that Ruby’s OpenSSL module has been compiled against at least version 0.9.7 of the OpenSSL library. Prior versions lacked functionality that Net::SSH depends on (notably, the ‘padding’ property of ciphers).
Optionally, you can install the ruby-termios. If you do, then your passwords won’t be echoed to the screen when prompting you for the passphrases needed to load your keys (if your keys have passphrases).
Using RubyGems
If you have RubyGems installed, installing Net::SSH is simple:
gem install net-ssh
You still need to make sure you have a working version of Ruby’s OpenSSL module, but other than that, you should be good to go!
Using rpa-base
If you have rpa-base installed:
rpa install net-ssh
As with the gem install, you still need to make sure you have a working version of Ruby’s OpenSSL module, but other than that, you should be good to go!
Doing it the hard way
If you don’t have RubyGems or rpa-base, or if you just prefer to install things by hand, you can always go to the Net::SSH downloads page and grab the package of your choice: tar.gz
, tar.bz2
, or zip
.
Then, unpack the archive and run the setup.rb
script:
ruby setup.rb config ruby setup.rb setup ruby setup.rb install
1.4. License Information
Net::SSH is made available under either the BSD license, or the same license Ruby (which, by extension, also allows the GPL as a permissable license as well). You can view the full text of any of these licenses in the doc
subdirectory of the Net::SSH distrubtion. The texts of the BSD and GPL licenses are also available online: BSD and GPL.
This manual (in any form, be it source or otherwise) and the scripts and templates used to generate it, are all distributed under the Creative Commons Attribution-ShareAlike license.
If you desire permission to use either Net::SSH or the manual in a manner incompatible with these licenses, please contact the copyright holder (Jamis Buck) in order to negotiate a more compatible license.
1.5. Support
Mailing lists, bug trackers, feature requests, and public forums are all available (courtesty of RubyForge) at the Net::SSH project page.
Mailing Lists
List Name | — | Description |
---|---|---|
net-ssh-users | subscribe / unsubscribe | The Net::SSH users list is devoted to the discussion of and questions about the usage of the Net::SSH module. If you can’t quite figure out how to get a feature of Net::SSH to work, this is the list you would go to in order to ask your questions. |
net-ssh-devel | subscribe / unsubscribe | The Net::SSH developers list is devoted to the discussion of Net::SSH’s implementation. If you have created a patch that you would like to discuss, or if you would like to discuss a new feature, this is the list for you. |
1.6. About the Author
Net::SSH was written by Jamis Buck. Feel free to send him compliments, candy, money, praise, or new feature patches—he likes all those things. You can send him questions and suggestions, too, if you really want to. (see below.) However, for bug reports and general feature requests, please use the issue tracker.
1.7. Maintainer
Net::SSH is maintained by Delano Mandelbaum. Please direct questions, patches, pull request, etc to him.