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


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:

Using Rubygems to install Net::SSH [shell]
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:

Using RPA to install Net::SSH [shell]
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:

Using setup.rb to install Net::SSH [shell]
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.