SSH client for mruby

Inspired by Net::SSH, empowers mruby.

The snippet demontrates how to execute a command on the remote host:

SSH.start('test.rebex.net','demo',password: 'password')do |ssh|
hostname=ssh.exec('hostname')end

Installation

Add the line below to your build_config.rb:

MRuby::Build.newdo |conf|
# ... (snip) ...conf.gem'mruby-ssh'end

Or add this line to your aplication's mrbgem.rake:

MRuby::Gem::Specification.new('your-mrbgem')do |spec|
# ... (snip) ...spec.add_dependency'mruby-ssh'end

The resulting binary will be statically linked agains libssh2 and mbedtls. There are no external runtime dependencies and the code should run fine for Linux, Unix and Windows platform.

Usage

To initiate a SSH session it is recommended to use SSH.start. Next to the optional host and user, the following keys are supported: user, password, key, passphrase, properties, non_interactive, timeout, compress and sigpipe.

Password:

SSH.start('test.rebex.net','demo',password: 'password')do |ssh|
ssh# => SSH::Sessionend

Keyboard-Interactive:

SSH.start('test.rebex.net','demo')do |ssh|
ssh# => SSH::Sessionend

Publickey:

SSH.start('test.rebex.net','demo',key: '~/.ssh/id_rsa',passphrase: 'optional')do |ssh|
ssh# => SSH::Sessionend

Agent:

SSH.start('test.rebex.net','demo',use_agent: true)do |ssh|
ssh# => SSH::Sessionend

SSH::Session

A session class representing the connection service running on top of the SSH transport layer. It provides both low-level (connect, login, close, etc.) and high-level (open_channel, exec) SSH operations.

SSH.start('test.rebex.net','demo',password: 'password')do |ssh|
ssh.fingerprint# => '60 C6 65 66 13 89 7B 5A 86 C5 2F 8F 7E CC 92 36 10 3B 3E 42'end

See session.rb and session.c for a complete list of available methods.

SSH::Channel

Multiple "channels" can be multiplexed onto a single SSH channel, each operating independently and seemingly in parallel. This class represents a single such channel. Most operations performed with the mruby-ssh library will involve using one or more channels.

SSH.start('test.rebex.net','demo',password: 'password')do |ssh|
ssh.open_channeldo |channel|
channel.env('MRB_VERSION','1.4.1')channel.exec('printf $MRB_VERSION')# => '1.4.1'endend

To capture both stdout and stderr streams:

SSH.start('test.rebex.net','demo',password: 'password')do |ssh|
ssh.open_channeldo |channel|
out,err,suc=channel.capture3("ruby -e '$stdout.print(1);$stderr.print(2)'")endend

To interact with the remote process:

SSH.start('test.rebex.net','demo',password: 'password')do |ssh|
ssh.open_channeldo |channel|
io,suc=channel.popen2e('irb')io.puts('1+1')io.gets(chomp: true)# => '2'endend

To interact with a screen based process (like vim or emacs):

SSH.start('test.rebex.net','demo',password: 'password')do |ssh|
ssh.open_channeldo |channel|
channel.request_ptyterm: 'xterm',chars_wide: 120endend

See channel.rb and channel.c for a complete list of available methods.

Compression

Add the line below to your build_config.rb:

MRuby::Build.newdo |build|
# ... (snip) ...build.cc.defines += %w[LIBSSH2_HAVE_ZLIBHAVE_UNISTD_H]end

Now initiate a new SSH session with compress:true:

SSH.start('test.rebex.net','demo',password: 'password',compress: true)

Threading

To initiate SSH sessions within threads add the line below to your build_config.rb:

MRuby::Build.newdo |build|
# ... (snip) ...build.cc.defines += %w[MBEDTLS_THREADING_PTHREADMBEDTLS_THREADING_C]end

Debugging

To trace additional debug informations at runtime add the line below to your build_config.rb:

MRuby::Build.newdo |build|
# ... (snip) ...build.cc.defines << 'MRB_SSH_DEBUG'end

Dynamic linking

For dynamic linking with libssh2.so add the line below to your build_config.rb:

MRuby::Build.newdo |build|
# ... (snip) ...build.cc.defines << 'MRB_SSH_LINK_LIB'end

To only link the crypto backend at runtime (e.g. OpenSSL) add the line below to your build_config.rb:

MRuby::Build.newdo |build|
# ... (snip) ...build.cc.defines += %w[MRB_SSH_LINK_CRYPTOLIBSSH2_OPENSSL]build.linker.libraries += %w[sslcrypto]end

Development

Clone the repo:

$ git clone https://github.com/katzer/mruby-ssh.git && cd mruby-ssh/

Compile the source:

$ rake compile

Run the tests:

$ rake test

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/katzer/mruby-ssh.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Authors

• Sebastián Katzer, Fa. appPlant GmbH

License

The mgem is available as open source under the terms of the MIT License.

Made with 😋 in Leipzig

© 2017 appPlant GmbH