hrr_rb_ssh 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5069234076e5c4f106d9ef733fd232fd0df99497fc64b948e9014d74a688f608
-  data.tar.gz: 0f88f74186bf0c86aa0dd6e76770d0e028231105bb06bc4ea5870f97841194d3
+  metadata.gz: 045cac2e290061c0575c6a2f4d09e6c9ae4d45cadb5a82ed7f73ac440b97e9e9
+  data.tar.gz: 7ed94a74123486946cf35c6308af08e64fb8bda1108256a8390aecc46f4c67b1
 SHA512:
-  metadata.gz: 5937b53c91ce899fbc3b0d0b97de9c336ad14fecda882ca24f6e9fc3184ec6b07123ae78bc7fdf3a11560ad3b268cb23277453d3f1ced91a5b1fb5054e3106f3
-  data.tar.gz: c757a877562b34ca17a8015fc9829ad6babfa89dbb197b451a0a23a1c372bc2ba1ba0ce77e2756da6b63157384be7774d15dd569b8b349ed898186e8f8f1818d
+  metadata.gz: ed149cc2cba4cc2884c571ee11eb453b23ec593498a0f5ff0a3cb95c3d4cb36286c9559466210a7b9c336e2167b97bea87504e00d029d996a92d655de6f9beff
+  data.tar.gz: 76b80ab7c6635df3e9286d1a1203674d03e83209f577dce22c00d30d21042a727af22e1ed457943e7b54bf0843ebd0e184bb3ac240929ef0447a7356888d8516

data/README.md

@@ -13,10 +13,10 @@ With hrr_rb_ssh, it is possible to write an SSH server easily, and also possible
 
 - [Installation](#installation)
 - [Usage](#usage)
+    - [Requiring hrr\_rb\_ssh library](#requiring-hrr_rb_ssh-library)
+    - [Logging](#logging)
     - [Writing standard SSH server](#writing-standard-ssh-server)
-        - [Requiring hrr\_rb\_ssh library](#requiring-hrr_rb_ssh-library)
         - [Starting server application](#starting-server-application)
-        - [Logging](#logging)
         - [Registering pre\-generated secret keys for server host key](#registering-pre-generated-secret-keys-for-server-host-key)
         - [Defining authentications](#defining-authentications)
             - [Single authentication](#single-authentication)
@@ -32,6 +32,11 @@ With hrr_rb_ssh, it is possible to write an SSH server easily, and also possible
         - [Defining preferred algorithms (optional)](#defining-preferred-algorithms-optional)
         - [Hiding and/or simulating local SSH version](#hiding-and-or-simulating-local-ssh-version)
     - [Writing SSH client (Experimental)](#writing-ssh-client-experimental)
+        - [Starting SSH connection](#starting-ssh-connection)
+        - [Executing remote commands](#executing-remote-commands)
+            - [exec method](#exec-method)
+            - [shell method](#shell-method)
+            - [subsystem method](#subsystem-method)
     - [Demo](#demo)
 - [Supported Features](#supported-features)
     - [Connection layer](#connection-layer)
@@ -63,9 +68,7 @@ $ gem install hrr_rb_ssh
 
 ## Usage
 
-### Writing standard SSH server
-
-#### Requiring `hrr_rb_ssh` library
+### Requiring `hrr_rb_ssh` library
 
 First of all, `hrr_rb_ssh` library needs to be loaded.
 
@@ -73,6 +76,33 @@ First of all, `hrr_rb_ssh` library needs to be loaded.
 require 'hrr_rb_ssh'
 ```
 
+### Logging
+
+__IMPORTANT__: DEBUG log level outputs all communications between local and remote in human-readable plain-text including password and any secret. Be careful to use logging.
+
+The library provides logging functionality. To enable logging of the library, you are to initialize `HrrRbSsh::Logger` class.
+
+```ruby
+HrrRbSsh::Logger.initialize logger
+```
+
+Where, the `logger` variable can be an instance of standard Logger class or user-defined logger class. What `HrrRbSsh::Logger` class requires for `logger` variable is that the `logger` instance responds to `#fatal`, `#error`, `#warn`, `#info` and `#debug`.
+
+For instance, `logger` variable can be prepared like below.
+
+```ruby
+logger = Logger.new STDOUT
+logger.level = Logger::INFO
+```
+
+To disable logging, you can un-initialize `HrrRbSsh::Logger`.
+
+```ruby
+HrrRbSsh::Logger.uninitialize
+```
+
+### Writing standard SSH server
+
 #### Starting server application
 
 The library is to run on a socket IO. To start SSH server, running a server IO and accepting a connection are required. The 10022 port number is just an example.
@@ -98,31 +128,6 @@ end
 
 Where, an `options` variable is an instance of `Hash`, which has optional (or sometimes almost necessary) values.
 
-#### Logging
-
-__IMPORTANT__: DEBUG log level outputs all communications between local and remote in human-readable plain-text including password and any secret. Be careful to use logging.
-
-The library provides logging functionality. To enable logging of the library, you are to initialize `HrrRbSsh::Logger` class.
-
-```ruby
-HrrRbSsh::Logger.initialize logger
-```
-
-Where, the `logger` variable can be an instance of standard Logger class or user-defined logger class. What `HrrRbSsh::Logger` class requires for `logger` variable is that the `logger` instance responds to `#fatal`, `#error`, `#warn`, `#info` and `#debug`.
-
-For instance, `logger` variable can be prepared like below.
-
-```ruby
-logger = Logger.new STDOUT
-logger.level = Logger::INFO
-```
-
-To disable logging, you can un-initialize `HrrRbSsh::Logger`.
-
-```ruby
-HrrRbSsh::Logger.uninitialize
-```
-
 #### Registering pre-generated secret keys for server host key
 
 By default, server host keys are generated everytime the gem is loaded. To use pre-generated keys, it is possible to register the keys in HrrRbSsh::Transport through `options` variable. The secret key value must be PEM or DER format string. The below is an example of registering ecdsa-sha2-nistp256 secret key. The supported server host key algorithms are listed later in this document.
@@ -423,28 +428,25 @@ Please note that the beginning of the string must be `SSH-2.0-`. Otherwise SSH 2
 
 ### Writing SSH client (Experimental)
 
-#### Requiring `hrr_rb_ssh` library
+#### Starting SSH connection
 
-First of all, `hrr_rb_ssh` library needs to be loaded.
+The client mode can be started with `HrrRbSsh::Client.start`. The method takes `target` and `options` arguments. The `target` that the SSH client connects to can be one of:
 
-```ruby
-require 'hrr_rb_ssh'
-```
+- (IO) An io that is open for input and output
+- (Array) An array of the target host address or host name and its service port number
+- (String) The target host address or host name; in this case the target service port number will be 22
 
-#### Starting SSH connection
-
-The client mode can be started with `HrrRbSsh::Client.start`. The method takes `address` and `options` arguments. The `address` is the target host address that the SSH client connects to. And the `options` contains various parameters for the SSH connection. At least `username` key must be set in the `options`. Also at least one of `password`, `publickey`, or `keyboard-interactive` needs to be set for authentication instead of authenticators that are used in server mode. Also as similar to server mode, it is possible to specify preferred transport algorithms and preferred authentication methods with the same keywords.
+And the `options` contains various parameters for the SSH connection. At least `username` key must be set in the `options`. Also at least one of `password`, `publickey`, or `keyboard-interactive` needs to be set for authentication instead of authenticators that are used in server mode. Also as similar to server mode, it is possible to specify preferred transport algorithms and preferred authentication methods with the same keywords.
 
 ```ruby
-address = 'remotehost'
+target = ['remotehost', 22]
 options = {
-  port: 22,
   username: 'user1',
   password: 'password1',
   publickey: ['ssh-rsa', "/home/user1/.ssh/id_rsa")],
   authentication_preferred_authentication_methods = ['publickey', 'password'],
 }
-HrrRbSsh::Client.start(address, options) do |conn|
+HrrRbSsh::Client.start(target, options) do |conn|
   # Do something here
   # For instance: conn.exec "command"
 end
@@ -460,6 +462,10 @@ The `exec` and `exec!` methods execute command on a remote host. Both takes a co
 
 The `exec!` method returns `[stdout, stderr]` outputs. Once the command is executed and the outputs are completed, then the method returns the value.
 
+```ruby
+conn.exec! "command" # => [stdout, stderr]
+```
+
 On the other hand, `exec` method takes block like the below example and returns exit status of the command. When the command is executed and the outputs and reading them are finished, then `io_out` and `io_err` return EOF.
 
 ```ruby
@@ -478,6 +484,16 @@ conn.shell do |io_in, io_out, io_err|
 end
 ```
 
+##### subsystem method
+
+The `subsystem` method is to start a subsystem on a remote host. The method takes a subsystem name argument and a block. Its block variable is also `io_in, io_out, io_err`. `subsystem` doesn't take `pty` nor `env` optional argument.
+
+```ruby
+conn.subsystem("echo") do |io_in, io_out, io_err|
+  # Do something here
+end
+```
+
 ### Demo
 
 The `demo/server.rb` shows a good example on how to use the hrr_rb_ssh library in SSH server mode. And the `demo/client.rb` shows an example on how to use the hrr_rb_ssh library in SSH client mode.

data/demo/client.rb

@@ -15,18 +15,17 @@ logger.level = Logger::INFO
 logger.level = Logger::DEBUG
 HrrRbSsh::Logger.initialize logger
 
-address = 'localhost'
+target = ['localhost', 10022]
 options = {
-  port: 10022,
   username: 'user1',
   password: 'password1',
-  publickey: ['ssh-rsa', "/home/user1/.ssh/id_rsa")],
+  publickey: ['ssh-rsa', "/home/user1/.ssh/id_rsa"],
   keyboard_interactive: [
     'password1',
     #'password2' # when keyboard-interactive authentication requires 2nd response
   ],
 }
-HrrRbSsh::Client.start(address, options){ |conn|
+HrrRbSsh::Client.start(target, options){ |conn|
   puts conn.exec!('ls -l') # => [out, err]
 
   puts conn.exec!('ls -l', pty: true) # => [out, err] # "ls -l" command will be run on PTY
@@ -55,4 +54,13 @@ HrrRbSsh::Client.start(address, options){ |conn|
     io_in.puts "exit"
     t.join
   }
+
+  conn.subsystem("echo"){ |io_in, io_out, io_err| # => exit status
+    t = Thread.new {
+      print io_out.readpartial(10240) rescue nil
+    }
+    io_in.puts "string"
+    t.join
+    io_in.close
+  }
 }

data/lib/hrr_rb_ssh/client.rb

@@ -11,8 +11,8 @@ require 'hrr_rb_ssh/connection'
 
 module HrrRbSsh
   class Client
-    def self.start address, options={}
-      client = self.new address, options
+    def self.start target, options={}
+      client = self.new target, options
       client.start
       if block_given?
         begin
@@ -25,11 +25,19 @@ module HrrRbSsh
       end
     end
 
-    def initialize address, tmp_options={}
+    def initialize target, tmp_options={}
       @logger = Logger.new self.class.name
       @closed = true
       options = initialize_options tmp_options
-      io = TCPSocket.new address, options['port']
+      io = case target
+           when IO
+             target
+           when Array
+             io = TCPSocket.new *target
+           when String
+             port = 22
+             io = TCPSocket.new target, port
+           end
       transport      = HrrRbSsh::Transport.new      io, HrrRbSsh::Mode::CLIENT, options
       authentication = HrrRbSsh::Authentication.new transport, HrrRbSsh::Mode::CLIENT, options
       @connection    = HrrRbSsh::Connection.new     authentication, HrrRbSsh::Mode::CLIENT, options
@@ -38,7 +46,6 @@ module HrrRbSsh
     def initialize_options tmp_options
       tmp_options = Hash[tmp_options.map{|k, v| [k.to_s, v]}]
       options = {}
-      options['port'] = tmp_options['port'] || 22
       options['username'] = tmp_options['username']
       options['authentication_preferred_authentication_methods'] = tmp_options['authentication_preferred_authentication_methods']
       options['client_authentication_password']             = tmp_options['password']
@@ -194,5 +201,32 @@ module HrrRbSsh
       end
       channel_exit_status = channel.exit_status rescue nil
     end
+
+    def subsystem name
+      @logger.debug { "start subsystem" }
+      begin
+        @logger.info { "Opning channel" }
+        channel = @connection.request_channel_open "session"
+        @logger.info { "Channel opened" }
+        channel.send_channel_request_subsystem name
+        yield channel.io
+      rescue => e
+        @logger.error { "Failed opening channel" }
+        @logger.error { [e.backtrace[0], ": ", e.message, " (", e.class.to_s, ")\n\t", e.backtrace[1..-1].join("\n\t")].join }
+        raise "Error in subsystem"
+      ensure
+        if channel
+          @logger.info { "closing channel IOs" }
+          channel.io.each{ |io| io.close rescue nil }
+          @logger.info { "channel IOs closed" }
+          @logger.info { "closing channel" }
+          @logger.info { "wait until threads closed in channel" }
+          channel.wait_until_closed
+          channel.close
+          @logger.info { "channel closed" }
+        end
+      end
+      channel_exit_status = channel.exit_status rescue nil
+    end
   end
 end

data/lib/hrr_rb_ssh/connection/channel.rb

@@ -125,6 +125,8 @@ module HrrRbSsh
             else
               @logger.warn { "skip sending exit-status because exitstatus is not an instance of Integer" }
             end
+          elsif from == :sender_thread
+            send_channel_eof
           end
           send_channel_close
         rescue Error::ClosedConnection => e
@@ -389,9 +391,9 @@ module HrrRbSsh
             rescue => e
               @logger.error { [e.backtrace[0], ": ", e.message, " (", e.class.to_s, ")\n\t", e.backtrace[1..-1].join("\n\t")].join }
               @r_io_in.close rescue nil
-              close
             end
           end
+          close from=:sender_thread
           @logger.info { "sender thread closed" }
         }
       end

data/lib/hrr_rb_ssh/version.rb

@@ -2,5 +2,5 @@
 # vim: et ts=2 sw=2
 
 module HrrRbSsh
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hrr_rb_ssh
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - hirura
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-14 00:00:00.000000000 Z
+date: 2019-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ed25519