remotus 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34953ce4b1c254e31a40b7b3ff3795124fe98b712722862a35813cceba686759
-  data.tar.gz: 3d342087b707b3078cedf38038b3ba21c1a1db6ed7c7d189f5912d9cd5adf4e7
+  metadata.gz: b375e9a93879a30b113991e9b653e602f30d970743925527af92a964298d7a27
+  data.tar.gz: 97bab3f384551a63e665d173e9b90330f03d3e8b56e6e89a9c216b18e37c2a66
 SHA512:
-  metadata.gz: c884fbb30a585899e840ab9e3dddd3b3d6ac052d4b10745bc9c582f9e67ca445aa9ef98af7ac8cbba551cc6594f23a9583d3f54cfba6202f3b8595804bd60641
-  data.tar.gz: 166f8cb4e3e633a79f1f28ddba9a3ff8793cc2927873bdd349e035870273c81ad6a9688f37d2f871413f43451604f64a06631e0813f8e111f7d36c701a168b05
+  metadata.gz: 6b3ded8d0ceb3c4b36736e875ca9ed80a85d77d388d1fb26f5a9659350622230c4f17efaee017e7765ddc081cd0ba52e767af960514a54c4061f667b38f1933c
+  data.tar.gz: 53aaf5d724c91a5639ce5f7928c6049b5912c21a523f2d1e5697191fb2511611e384fa5ce14fe92a53affaa8e707e42f5a5539ce83c93a16549bc1ac0fb3e5e5

data/.github/workflows/main.yml

@@ -6,21 +6,22 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 2.7.2
+        ruby-version: 3.0.4
     - name: Run unit tests and code linting
       run: |
-        gem install bundler -v 2.2.9
+        gem install bundler -v 2.2.33
         bundle install
         bundle exec rake
+        bundle exec rspec docker
         bundle exec yard
 
     - name: Deploy documentation
       if: github.ref == 'refs/heads/main'
-      uses: crazy-max/ghaction-github-pages@v2.2.0
+      uses: crazy-max/ghaction-github-pages@v3.0.0
       with:
         target_branch: gh-pages
         build_dir: doc

data/.rubocop.yml

@@ -19,6 +19,7 @@ Metrics/ClassLength:
 Metrics/BlockLength:
   Exclude:
     - spec/**/*.rb
+    - docker/**/*.rb
     - remotus.gemspec
     - lib/remotus/ssh_connection.rb
 

data/.ruby-version

@@ -0,0 +1 @@
+3.0.4

data/CHANGELOG.md

@@ -1,4 +1,6 @@
-## [Unreleased]
+## [0.5.0] - 2022-09-21
+* Ensure port argument is respected in `Remotus::SshConnection`
+* Add SSH gateway support
 
 ## [0.4.0] - 2022-06-02
 * Added winrm-elevated gem to solve wirnrm AuthenticationError

data/Gemfile.lock

@@ -1,10 +1,11 @@
 PATH
   remote: .
   specs:
-    remotus (0.4.0)
+    remotus (0.5.0)
       connection_pool (~> 2.2)
       net-scp (~> 3.0)
       net-ssh (~> 6.1)
+      net-ssh-gateway (~> 2.0)
       winrm (~> 2.3)
       winrm-elevated (~> 1.2)
       winrm-fs (~> 1.3)
@@ -14,9 +15,9 @@ GEM
   specs:
     ast (2.4.2)
     builder (3.2.4)
-    connection_pool (2.2.5)
+    connection_pool (2.3.0)
     diff-lcs (1.5.0)
-    erubi (1.10.0)
+    erubi (1.11.0)
     ffi (1.15.5)
     gssapi (1.3.1)
       ffi (>= 1.0.1)
@@ -24,6 +25,7 @@ GEM
       builder (>= 2.1.2)
       rexml (~> 3.0)
     httpclient (2.8.3)
+    json (2.6.2)
     little-plugger (1.1.4)
     logging (2.3.1)
       little-plugger (~> 1.1)
@@ -32,13 +34,15 @@ GEM
     net-scp (3.0.0)
       net-ssh (>= 2.6.5, < 7.0.0)
     net-ssh (6.1.0)
+    net-ssh-gateway (2.0.0)
+      net-ssh (>= 4.0.0)
     nori (2.6.0)
-    parallel (1.21.0)
-    parser (3.1.0.0)
+    parallel (1.22.1)
+    parser (3.1.2.1)
       ast (~> 2.4.1)
     rainbow (3.1.1)
     rake (13.0.6)
-    regexp_parser (2.2.1)
+    regexp_parser (2.5.0)
     rexml (3.2.5)
     rspec (3.11.0)
       rspec-core (~> 3.11.0)
@@ -46,32 +50,33 @@ GEM
       rspec-mocks (~> 3.11.0)
     rspec-core (3.11.0)
       rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.0)
+    rspec-expectations (3.11.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.11.0)
-    rspec-mocks (3.11.0)
+    rspec-mocks (3.11.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.11.0)
-    rspec-support (3.11.0)
-    rubocop (1.25.1)
+    rspec-support (3.11.1)
+    rubocop (1.36.0)
+      json (~> 2.3)
       parallel (~> 1.10)
-      parser (>= 3.1.0.0)
+      parser (>= 3.1.2.1)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
-      rexml
-      rubocop-ast (>= 1.15.1, < 2.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.20.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.15.2)
-      parser (>= 3.0.1.1)
+    rubocop-ast (1.21.0)
+      parser (>= 3.1.1.0)
     rubocop-rake (0.6.0)
       rubocop (~> 1.0)
-    rubocop-rspec (2.8.0)
-      rubocop (~> 1.19)
+    rubocop-rspec (2.13.1)
+      rubocop (~> 1.33)
     ruby-progressbar (1.11.0)
     rubyntlm (0.6.3)
     rubyzip (2.3.2)
-    unicode-display_width (2.1.0)
+    unicode-display_width (2.3.0)
     webrick (1.7.0)
     winrm (2.3.6)
       builder (>= 2.1.2)
@@ -91,7 +96,7 @@ GEM
       logging (>= 1.6.1, < 3.0)
       rubyzip (~> 2.0)
       winrm (~> 2.0)
-    yard (0.9.27)
+    yard (0.9.28)
       webrick (~> 1.7.0)
 
 PLATFORMS
@@ -108,4 +113,4 @@ DEPENDENCIES
   yard (~> 0.9)
 
 BUNDLED WITH
-   2.2.22
+   2.2.33

data/README.md

@@ -30,6 +30,15 @@ connection = Remotus.connect("remotehost.local", proto: :ssh, port: 2222)
 # Initialize a new connection pool to remotehost.local with a defined protocol and port and arbitrary metadata
 connection = Remotus.connect("remotehost.local", proto: :ssh, port: 2222, company: "Test Corp", location: "Oslo")
 
+# Initialize a new connection pool to remotehost.local via a gateway host named gateway.local
+connection = Remotus.connect("remotehost.local", gateway_host: "gateway.local")
+
+# Initialize a new connection pool to remotehost.local via a gateway host named gateway.local with a defined protocol and port
+connection = Remotus.connect("remotehost.local", proto: :ssh, port: 2222, gateway_host: "gateway.local", gateway_port: 2222)
+
+# Initialize a new connection pool to remotehost.local via a gateway host named gateway.local with arbitrary metadata
+connection = Remotus.connect("remotehost.local", company: "Test Corp", gateway_host: "gateway.local", gateway_metadata: { company: "Other Corp" })
+
 # Create a credential for the new connection pool
 connection.credential = Remotus::Auth::Credential.new("username", "password")
 

data/docker/Dockerfile

@@ -0,0 +1,16 @@
+FROM alpine:latest
+
+COPY entrypoint.sh /
+
+RUN apk add --update --no-cache openssh && \
+    sed -i '/GatewayPorts.*/d' /etc/ssh/sshd_config && \
+    echo 'GatewayPorts yes' >> /etc/ssh/sshd_config && \
+    sed -i '/AllowTcpForwarding.*/d' /etc/ssh/sshd_config && \
+    echo 'AllowTcpForwarding yes' >> /etc/ssh/sshd_config && \
+    echo 'PasswordAuthentication yes' >> /etc/ssh/sshd_config && \
+    adduser -h /home/testuser -s /bin/sh -D testuser && \
+    echo 'testuser:testuser' | chpasswd
+
+ENTRYPOINT ["/entrypoint.sh"]
+
+EXPOSE 22

data/docker/entrypoint.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+ssh-keygen -A
+exec /usr/sbin/sshd -D -e "$@"

data/docker/ssh_integration_script.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+
+# Script for use with the ssh_integration_spec.rb to validate
+# SSH script functionality.
+
+echo -n 'test complete' > /home/testuser/script_file
+
+echo -n 'success'

data/docker/ssh_integration_spec.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Assumes docker-compose is available
+
+RSpec.describe "Remotus::SshConnection Integration Tests" do
+  before(:all) do
+    # docker-compose startup
+    `docker-compose -f "docker-compose.yml" up -d --build`
+
+    # Set up Remotus credentials based on Dockerfile
+    Remotus::Auth.cache["localhost"] = Remotus::Auth::Credential.new("testuser", "testuser")
+    Remotus::Auth.cache["target"] = Remotus::Auth::Credential.new("testuser", "testuser")
+
+    # Allow time for sshd to start up
+    sleep 1
+  end
+
+  after(:all) do
+    # docker-compose cleanup
+    `docker-compose -f "docker-compose.yml" down -v`
+  end
+
+  let(:test_script) { ::File.join(__dir__, "ssh_integration_script.sh") }
+  let(:test_script_dest) { ::File.join("/home/testuser", ::File.basename(test_script)) }
+
+  context "when a gateway and inaccessible target host exist" do
+    let(:gateway_hostname) { `docker ps | grep remotus_gateway`.split.first }
+    let(:target_hostname) { `docker ps | grep remotus_target`.split.first }
+    let(:gateway_connection) { Remotus.connect("localhost", proto: :ssh, port: 2222) }
+    let(:target_connection) { Remotus.connect("target", proto: :ssh, port: 22, gateway_host: "localhost", gateway_port: 2222) }
+
+    it "Connects to the gateway host successfully" do
+      expect(gateway_connection.run("hostname").stdout.chomp).to eq(gateway_hostname)
+    end
+
+    it "Can run a script against the gateway host successfully" do
+      result = gateway_connection.run_script(test_script, test_script_dest)
+      expect(result.stdout).to eq("success")
+      expect(result.success?).to eq(true)
+    end
+
+    it "Can upload a file to the gateway host" do
+      result = gateway_connection.upload(test_script, "/home/testuser/upload_test")
+      expect(result).to eq("/home/testuser/upload_test")
+      expect(gateway_connection.file_exist?("/home/testuser/upload_test")).to eq(true)
+    end
+
+    it "Can download a file from the gateway host" do
+      gateway_connection.run('echo -n "test" > /home/testuser/download_test')
+      result = gateway_connection.download("/home/testuser/download_test")
+      expect(result).to eq("test")
+    end
+
+    it "Can check if a file exists on the gateway host" do
+      expect(gateway_connection.file_exist?("/home/testuser")).to eq(true)
+    end
+
+    it "Connects to the target host successfully" do
+      expect(target_connection.run("hostname").stdout.chomp).to eq(target_hostname)
+    end
+
+    it "Can run a script against the target host successfully" do
+      result = target_connection.run_script(test_script, test_script_dest)
+      expect(result.stdout).to eq("success")
+      expect(result.success?).to eq(true)
+    end
+
+    it "Can upload a file to the target host" do
+      result = target_connection.upload(test_script, "/home/testuser/upload_test")
+      expect(result).to eq("/home/testuser/upload_test")
+      expect(target_connection.file_exist?("/home/testuser/upload_test")).to eq(true)
+    end
+
+    it "Can download a file from the target host" do
+      target_connection.run('echo -n "test" > /home/testuser/download_test')
+      result = target_connection.download("/home/testuser/download_test")
+      expect(result).to eq("test")
+    end
+
+    it "Can check if a file exists on the target host" do
+      expect(target_connection.file_exist?("/home/testuser")).to eq(true)
+    end
+  end
+end

data/docker-compose.yml

@@ -0,0 +1,10 @@
+version: "3.9"
+services:
+  # Accessible gateway host
+  gateway:
+    build: docker
+    ports:
+      - "2222:22"
+  # Inaccessible gateway target host
+  target:
+    build: docker

data/lib/remotus/host_pool.rb

@@ -42,6 +42,13 @@ module Remotus
     # @param [Hash] metadata metadata for this connection. Useful for providing additional information to various authentication stores
     #                        should be specified using snake_case symbol keys. If keys are not snake_case, they will be converted.
     #
+    #                        To configure a connection gateway, the following metadata entries can be provided to the host pool:
+    #                          :gateway_host
+    #                          :gateway_port
+    #                          :gateway_metadata
+    #
+    #                        These function similarly to the host, port, and host_pool metadata fields.
+    #
     def initialize(host, size: DEFAULT_POOL_SIZE, timeout: DEFAULT_EXPIRATION_SECONDS, port: nil, proto: nil, **metadata)
       Remotus.logger.debug { "Creating host pool for #{host}" }
 

data/lib/remotus/result.rb

@@ -65,7 +65,7 @@ module Remotus
     def error!(accepted_exit_codes = [0])
       return unless error?(accepted_exit_codes)
 
-      raise Remotus::ResultError, "Error encountered executing #{@command}! Exit code #{@exit_code} was returned "\
+      raise Remotus::ResultError, "Error encountered executing #{@command}! Exit code #{@exit_code} was returned " \
                                   "while a value in #{accepted_exit_codes} was expected.\n#{output}"
     end
 

data/lib/remotus/ssh_connection.rb

@@ -6,6 +6,7 @@ require "remotus/result"
 require "remotus/auth"
 require "net/scp"
 require "net/ssh"
+require "net/ssh/gateway"
 
 module Remotus
   # Class representing an SSH connection to a host
@@ -21,6 +22,9 @@ module Remotus
     # Number of default retries
     DEFAULT_RETRIES = 2
 
+    # Base options for new SSH connections
+    BASE_CONNECT_OPTIONS = { non_interactive: true, keepalive: true, keepalive_interval: KEEPALIVE_INTERVAL }.freeze
+
     # @return [Integer] Remote port
     attr_reader :port
 
@@ -33,12 +37,50 @@ module Remotus
     # Delegate metadata methods to associated host pool
     def_delegators :@host_pool, :[], :[]=
 
+    # Internal gateway connection class to allow for the host and metadata to be pulled for the gateway
+    # by authentication credentials
+    class GatewayConnection
+      extend Forwardable
+
+      # @return [String] host gateway hostname
+      attr_reader :host
+
+      # @return [Integer] Remote port
+      attr_reader :port
+
+      # @return [Net::SSH::Gateway] connection gateway connection
+      attr_accessor :connection
+
+      # Delegate metadata methods to associated hash
+      def_delegators :@metadata, :[], :[]=
+
+      #
+      # Creates a GatewayConnection
+      #
+      # @param [String] host hostname
+      # @param [Integer] port remote port
+      # @param [Hash] metadata associated metadata for this gateway
+      #
+      def initialize(host, port = REMOTE_PORT, metadata = {})
+        @host = host
+        @port = port
+        @metadata = metadata
+      end
+    end
+
     #
     # Creates an SshConnection
     #
     # @param [String] host hostname
     # @param [Integer] port remote port
     # @param [Remotus::HostPool] host_pool associated host pool
+    #                                      To configure the gateway, the following metadata
+    #                                      entries can be provided to the host pool:
+    #                                        :gateway_host
+    #                                        :gateway_port
+    #                                        :gateway_metadata
+    #
+    #                                      These function similarly to the host, port, and host_pool metadata fields.
     #
     def initialize(host, port = REMOTE_PORT, host_pool: nil)
       Remotus.logger.debug { "Creating SshConnection #{object_id} for #{host}" }
@@ -77,23 +119,32 @@ module Remotus
     def connection
       return @connection unless restart_connection?
 
-      Remotus.logger.debug { "Initializing SSH connection to #{Remotus::Auth.credential(self).user}@#{@host}:#{@port}" }
+      target_cred = Remotus::Auth.credential(self)
+
+      Remotus.logger.debug { "Initializing SSH connection to #{target_cred.user}@#{@host}:#{@port}" }
 
-      options = { non_interactive: true, keepalive: true, keepalive_interval: KEEPALIVE_INTERVAL }
+      target_options = BASE_CONNECT_OPTIONS.dup
+      target_options[:password] = target_cred.password if target_cred.password
+      target_options[:keys] = [target_cred.private_key] if target_cred.private_key
+      target_options[:key_data] = [target_cred.private_key_data] if target_cred.private_key_data
+      target_options[:port] = @port || REMOTE_PORT
 
-      password = Remotus::Auth.credential(self).password
-      private_key_path = Remotus::Auth.credential(self).private_key
-      private_key_data = Remotus::Auth.credential(self).private_key_data
+      if via_gateway?
+        @gateway = GatewayConnection.new(@host_pool[:gateway_host], @host_pool[:gateway_port], @host_pool[:gateway_metadata])
+        gateway_cred = Remotus::Auth.credential(@gateway)
+        gateway_options = BASE_CONNECT_OPTIONS.dup
+        gateway_options[:port] = @gateway.port || REMOTE_PORT
+        gateway_options[:password] = gateway_cred.password if gateway_cred.password
+        gateway_options[:keys] = [gateway_cred.private_key] if gateway_cred.private_key
+        gateway_options[:key_data] = [gateway_cred.private_key_data] if gateway_cred.private_key_data
 
-      options[:password] = password if password
-      options[:keys] = [private_key_path] if private_key_path
-      options[:key_data] = [private_key_data] if private_key_data
+        Remotus.logger.debug { "Initializing SSH gateway connection to #{gateway_cred.user}@#{@gateway.host}:#{gateway_options[:port]}" }
 
-      @connection = Net::SSH.start(
-        @host,
-        Remotus::Auth.credential(self).user,
-        **options
-      )
+        @gateway.connection = Net::SSH::Gateway.new(@gateway.host, gateway_cred.user, **gateway_options)
+        @gateway.connection.ssh(@host, target_cred.user, **target_options)
+      else
+        @connection = Net::SSH.start(@host, target_cred.user, **target_options)
+      end
     end
 
     #
@@ -392,10 +443,30 @@ module Remotus
       return true unless @connection
       return true if @connection.closed?
       return true if @host != @connection.host
-      return true if Remotus::Auth.credential(self).user != @connection.options[:user]
-      return true if Remotus::Auth.credential(self).password != @connection.options[:password]
-      return true if Array(Remotus::Auth.credential(self).private_key) != Array(@connection.options[:keys])
-      return true if Array(Remotus::Auth.credential(self).private_key_data) != Array(@connection.options[:key_data])
+
+      target_cred = Remotus::Auth.credential(self)
+
+      return true if target_cred.user != @connection.options[:user]
+      return true if target_cred.password != @connection.options[:password]
+      return true if Array(target_cred.private_key) != Array(@connection.options[:keys])
+      return true if Array(target_cred.private_key_data) != Array(@connection.options[:key_data])
+
+      # Perform gateway checks
+      if via_gateway?
+        return true unless @gateway&.connection&.active?
+
+        gateway_session = @gateway.connection.instance_variable_get(:@session)
+
+        return true if gateway_session.closed?
+        return true if @host_pool[:gateway_host] != gateway_session.host
+
+        gateway_cred = Remotus::Auth.credential(@gateway)
+
+        return true if gateway_cred.user != @connection.options[:user]
+        return true if gateway_cred.password != @connection.options[:password]
+        return true if Array(gateway_cred.private_key) != Array(@connection.options[:keys])
+        return true if Array(gateway_cred.private_key_data) != Array(@connection.options[:key_data])
+      end
 
       false
     end
@@ -469,5 +540,14 @@ module Remotus
       Remotus.logger.debug { "Generated permission commands #{cmds}" }
       cmds
     end
+
+    #
+    # Whether connecting via an SSH gateway
+    #
+    # @return [Boolean] true if using a gateway, false otherwise
+    #
+    def via_gateway?
+      host_pool && host_pool[:gateway_host]
+    end
   end
 end

data/lib/remotus/version.rb

@@ -2,5 +2,5 @@
 
 module Remotus
   # Remotus gem version
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/remotus.gemspec

@@ -32,6 +32,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "connection_pool", "~> 2.2"
   spec.add_dependency "net-scp", "~> 3.0"
   spec.add_dependency "net-ssh", "~> 6.1"
+  spec.add_dependency "net-ssh-gateway", "~> 2.0"
   spec.add_dependency "winrm", "~> 2.3"
   spec.add_dependency "winrm-elevated", "~> 1.2"
   spec.add_dependency "winrm-fs", "~> 1.3"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: remotus
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Matthew Newell
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-06-09 00:00:00.000000000 Z
+date: 2022-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: connection_pool
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: net-ssh-gateway
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: winrm
   requirement: !ruby/object:Gem::Requirement
@@ -189,6 +203,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
+- ".ruby-version"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -197,6 +212,11 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docker-compose.yml
+- docker/Dockerfile
+- docker/entrypoint.sh
+- docker/ssh_integration_script.sh
+- docker/ssh_integration_spec.rb
 - lib/remotus.rb
 - lib/remotus/auth.rb
 - lib/remotus/auth/credential.rb
@@ -235,7 +255,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.33
 signing_key: 
 specification_version: 4
 summary: Ruby gem for connecting to remote systems seamlessly via WinRM or SSH.