net-ssh 8.0.0.rc4 → 8.0.0.rc5

data/lib/net/ssh/multiplex/client.rb

@@ -0,0 +1,162 @@
+require 'io/wait'
+require 'socket'
+
+require 'net/ssh/buffer'
+require 'net/ssh/errors'
+require 'net/ssh/loggable'
+
+module Net
+  module SSH
+    module Multiplex
+      # Raised when the ControlMaster socket can't be used, e.g. the master
+      # refused the request or spoke an unexpected protocol.
+      class Error < Net::SSH::Exception; end
+
+      # Connects to an OpenSSH ControlMaster's UNIX socket and switches it to
+      # proxy mode (MUX_C_PROXY, OpenSSH 7.4 and later), after which the socket
+      # carries plain SSH connection-protocol packets. See PROTOCOL.mux and
+      # mux.c in OpenSSH.
+      class Client
+        include Loggable
+
+        MUX_MSG_HELLO = 0x00000001
+        MUX_C_PROXY = 0x1000000f
+        MUX_S_PERMISSION_DENIED = 0x80000002
+        MUX_S_FAILURE = 0x80000003
+        MUX_S_PROXY = 0x8000000f
+
+        PROTOCOL_VERSION = 4
+
+        # Mux control messages are small; this only guards against reading a
+        # bogus length from something that isn't a ControlMaster.
+        MAX_MESSAGE_SIZE = 256 * 1024
+
+        attr_reader :path
+
+        def initialize(path, timeout:, logger: nil)
+          self.logger = logger
+          @path = path
+          @timeout = timeout
+        end
+
+        # Performs the HELLO and PROXY exchange and returns the connected
+        # socket, positioned at the first proxied packet. Raises
+        # Multiplex::Error, SystemCallError or IOError if the master can't be
+        # used; the socket is closed in that case.
+        def connect_proxy
+          @deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
+          @socket = open_socket
+          verify_peer
+          hello
+          request_proxy
+          @socket
+        rescue StandardError
+          @socket&.close
+          raise
+        end
+
+        private
+
+        def open_socket
+          socket = Socket.new(Socket::AF_UNIX, Socket::SOCK_STREAM)
+          address = Socket.sockaddr_un(path)
+          loop do
+            result = socket.connect_nonblock(address, exception: false)
+            break if result == 0
+
+            wait_for(:writable, socket)
+          rescue Errno::EISCONN
+            break
+          end
+          socket
+        rescue StandardError
+          socket&.close
+          raise
+        end
+
+        # The master itself rejects clients with a different uid (channels.c,
+        # getpeereid); checking here also keeps us off a socket someone else
+        # planted at the ControlPath.
+        def verify_peer
+          euid = begin
+            @socket.getpeereid.first
+          rescue NotImplementedError
+            File.stat(path).uid
+          end
+          raise Error, "#{path} is owned by uid #{euid}, not #{Process.euid}" unless euid == Process.euid
+        end
+
+        def hello
+          type, body = read_message
+          raise Error, "expected MUX_MSG_HELLO, got 0x#{type.to_s(16)}" unless type == MUX_MSG_HELLO
+
+          version = body.read_long
+          raise Error, "unsupported mux protocol version #{version}" unless version == PROTOCOL_VERSION
+
+          # Any extensions the master advertises (OpenSSH 10.3 sends "info")
+          # are optional, so the rest of the body is ignored.
+          write_message(MUX_MSG_HELLO, :long, PROTOCOL_VERSION)
+          debug { "mux hello exchanged with #{path}" }
+        end
+
+        def request_proxy
+          request_id = 1
+          write_message(MUX_C_PROXY, :long, request_id)
+          type, body = read_message
+          case type
+          when MUX_S_PROXY
+            reply_id = body.read_long
+            raise Error, "MUX_S_PROXY for request #{reply_id}, expected #{request_id}" unless reply_id == request_id
+          when MUX_S_PERMISSION_DENIED, MUX_S_FAILURE
+            body.read_long
+            raise Error, "master refused proxy request: #{body.read_string}"
+          else
+            raise Error, "unexpected reply 0x#{type.to_s(16)} to MUX_C_PROXY"
+          end
+        end
+
+        def write_message(type, *args)
+          body = Net::SSH::Buffer.from(:long, type, *args).to_s
+          data = [body.bytesize].pack('N') + body
+          until data.empty?
+            written = @socket.write_nonblock(data, exception: false)
+            if written == :wait_writable
+              wait_for(:writable, @socket)
+            else
+              data = data.byteslice(written..-1)
+            end
+          end
+        end
+
+        def read_message
+          length = read_exactly(4).unpack1('N')
+          raise Error, "mux message length #{length} out of range" unless length.between?(4, MAX_MESSAGE_SIZE)
+
+          body = Net::SSH::Buffer.new(read_exactly(length))
+          [body.read_long, body]
+        end
+
+        # Reads exactly +count+ bytes so nothing after the PROXY reply, which
+        # already belongs to the packet stream, is consumed here.
+        def read_exactly(count)
+          data = String.new(encoding: Encoding::BINARY)
+          while data.bytesize < count
+            chunk = @socket.read_nonblock(count - data.bytesize, exception: false)
+            case chunk
+            when :wait_readable then wait_for(:readable, @socket)
+            when nil then raise Error, "#{path} closed the connection during the mux handshake"
+            else data << chunk
+            end
+          end
+          data
+        end
+
+        def wait_for(direction, socket)
+          remaining = @deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          ready = remaining > 0 && (direction == :readable ? socket.wait_readable(remaining) : socket.wait_writable(remaining))
+          raise Error, "timed out talking to #{path}" unless ready
+        end
+      end
+    end
+  end
+end

data/lib/net/ssh/multiplex/control_path.rb

@@ -0,0 +1,120 @@
+require 'digest/sha1'
+require 'ipaddr'
+require 'etc'
+require 'socket'
+
+module Net
+  module SSH
+    module Multiplex
+      # Expands a ControlPath the way OpenSSH's ssh does: a leading ~ first,
+      # then ${ENV} and the % tokens below in a single pass (ssh.c,
+      # DEFAULT_CLIENT_PERCENT_EXPAND_ARGS in sshconnect.h, misc.c
+      # percent_dollar_expand).
+      #
+      #   %%  a literal %
+      #   %C  SHA1 hex of %l%h%p%r%j
+      #   %d  local home directory
+      #   %h  remote host name, after HostName
+      #   %i  local uid
+      #   %j  host of the last ProxyJump hop, or empty
+      #   %k  the host key alias, or the host name as given
+      #   %L  local host name up to the first dot
+      #   %l  local host name
+      #   %n  the host name as given
+      #   %p  remote port
+      #   %r  remote user
+      #   %u  local user
+      class ControlPath
+        # +host_arg+ is the host as given, +host+ the one connected to after
+        # HostName.
+        def initialize(host_arg:, host:, port:, remote_user:, jump_host: '', host_key_alias: nil) # rubocop:disable Metrics/ParameterLists
+          @host_arg = host_arg.to_s
+          # ssh lowercases host names, but not addresses, before expanding.
+          @host = address?(host.to_s) ? host.to_s : host.to_s.downcase
+          @port = port.to_s
+          @remote_user = remote_user.to_s
+          @jump_host = jump_host.to_s
+          @host_key_alias = host_key_alias
+        end
+
+        # Raises ArgumentError for an unknown % token, an unset ${ENV}
+        # variable or an unknown ~user, which make ssh refuse the ControlPath
+        # too.
+        def expand(path)
+          expand_tokens(expand_tilde(path))
+        end
+
+        def tokens
+          @tokens ||= begin
+            pw = Etc.getpwuid(Process.uid)
+            local_host = Socket.gethostname
+            {
+              'C' => Digest::SHA1.hexdigest("#{local_host}#{@host}#{@port}#{@remote_user}#{@jump_host}"),
+              'd' => pw.dir,
+              'h' => @host,
+              'i' => Process.uid.to_s,
+              'j' => @jump_host,
+              'k' => @host_key_alias || @host_arg,
+              'L' => local_host.split('.', 2).first,
+              'l' => local_host,
+              'n' => @host_arg,
+              'p' => @port,
+              'r' => @remote_user,
+              'u' => pw.name
+            }
+          end
+        end
+
+        # The host ssh uses for %j: the last hop of a ProxyJump list, without
+        # user or port (readconf.c, parse_jump).
+        def self.jump_host(proxy_jump)
+          last = proxy_jump.to_s.split(',').last.to_s.strip.delete_prefix('ssh://')
+          last = last.split('@').last.to_s
+          if last.start_with?('[')
+            last[1...last.index(']').to_i]
+          else
+            last.split(':').first.to_s
+          end
+        end
+
+        private
+
+        # ssh uses the home directory from the password database, not $HOME
+        # (misc.c, tilde_expand).
+        def expand_tilde(path)
+          return path unless path.start_with?('~')
+
+          user, rest = path[1..].split('/', 2)
+          home = user.nil? || user.empty? ? Etc.getpwuid(Process.uid).dir : Etc.getpwnam(user).dir
+
+          rest.nil? ? home : File.join(home, rest)
+        end
+
+        def expand_tokens(path)
+          path.gsub(/\$\{([^}]*)\}|%(.?)|\$\{.*/m) do
+            if Regexp.last_match(1)
+              name = Regexp.last_match(1)
+              raise ArgumentError, "empty ${} variable" if name.empty?
+
+              ENV.fetch(name) { raise ArgumentError, "variable ${#{name}} is not set" }
+            elsif Regexp.last_match(2)
+              token = Regexp.last_match(2)
+              next '%' if token == '%'
+
+              tokens.fetch(token) { raise ArgumentError, "unknown token %#{token}" }
+            else
+              raise ArgumentError, "unterminated ${"
+            end
+          end
+        end
+
+        def address?(host)
+          IPAddr.new(host)
+          true
+        rescue IPAddr::Error
+          false
+        end
+      end
+    end
+  end
+end

data/lib/net/ssh/multiplex/proxy_transport.rb

@@ -0,0 +1,218 @@
+require 'io/wait'
+
+require 'net/ssh/buffer'
+require 'net/ssh/buffered_io'
+require 'net/ssh/errors'
+require 'net/ssh/loggable'
+require 'net/ssh/packet'
+require 'net/ssh/connection/constants'
+
+module Net
+  module SSH
+    module Multiplex
+      # Packet framing on a ControlMaster socket in proxy mode: the usual
+      # uint32 packet_length and byte padding_length, but no padding, MAC,
+      # encryption or compression. The master parses everything after the
+      # padding_length byte as payload (channel_proxy_downstream in OpenSSH's
+      # channels.c), so padding must not be sent.
+      module PacketSocket
+        include BufferedIo
+
+        # OpenSSH's PACKET_MAX_SIZE.
+        MAX_PACKET_SIZE = 256 * 1024
+
+        def self.extended(object) # :nodoc:
+          object.__send__(:initialize_buffered_io)
+        end
+
+        def available_for_read?
+          !wait_readable(0).nil?
+        end
+
+        # Same contract as Net::SSH::Transport::PacketStream#next_packet.
+        def next_packet(mode = :nonblock, timeout = nil)
+          case mode
+          when :nonblock
+            packet = poll_next_packet
+            return packet if packet
+
+            if available_for_read? && fill <= 0
+              packet = poll_next_packet
+              raise Net::SSH::Disconnect, "connection closed by ControlMaster" if packet.nil?
+
+              return packet
+            end
+            poll_next_packet
+          when :block
+            loop do
+              packet = poll_next_packet
+              return packet if packet
+
+              raise Net::SSH::ConnectionTimeout, "timeout waiting for next packet" unless wait_readable(timeout)
+              raise Net::SSH::Disconnect, "connection closed by ControlMaster" if fill <= 0
+            end
+          else
+            raise ArgumentError, "expected :block or :nonblock, got #{mode.inspect}"
+          end
+        end
+
+        def enqueue_packet(payload)
+          data = payload.to_s
+          enqueue([data.bytesize + 1, 0].pack('NC') + data.b)
+        end
+
+        def send_packet(payload)
+          enqueue_packet(payload)
+          wait_for_pending_sends
+        end
+
+        private
+
+        def poll_next_packet
+          return nil if available < 4
+
+          start = input.position
+          length = input.read_long
+          raise Net::SSH::Exception, "invalid packet length #{length} from ControlMaster" unless length.between?(1, MAX_PACKET_SIZE)
+
+          if available < length
+            input.position = start
+            return nil
+          end
+
+          data = input.read(length)
+          input.consume!
+          padding = data.getbyte(0)
+          raise Net::SSH::Exception, "invalid padding length #{padding} from ControlMaster" if padding > length - 2
+
+          Net::SSH::Packet.new(data.byteslice(1, length - 1 - padding))
+        end
+      end
+
+      # Stands in for Net::SSH::Transport::Session underneath a
+      # Net::SSH::Connection::Session when connected through an OpenSSH
+      # ControlMaster in proxy mode. Key exchange, rekeying, host key
+      # verification and authentication all belong to the master, so the
+      # matching transport methods are no-ops or raise
+      # NotSupportedOverControlMaster.
+      class ProxyTransport
+        include Loggable
+        include Net::SSH::Connection::Constants
+
+        DEFAULT_PORT = 22
+
+        # Channel requests whose follow-up channel the server opens towards
+        # the master, which serves it from its own agent or X display only if
+        # it has ForwardAgent or ForwardX11 enabled itself, and rejects it
+        # otherwise (clientloop.c, client_input_channel_open).
+        UNSUPPORTED_CHANNEL_REQUESTS = %w[auth-agent-req@openssh.com auth-agent-req x11-req].freeze
+
+        attr_reader :host, :port, :socket, :options
+
+        # The ControlMaster socket path this transport is connected through.
+        attr_reader :control_path
+
+        def initialize(socket, host:, control_path:, options: {})
+          self.logger = options[:logger]
+          @host = host
+          @port = options[:port] || DEFAULT_PORT
+          @options = options
+          @control_path = control_path
+          @socket = socket
+          @socket.extend(PacketSocket)
+          @socket.logger = logger
+        end
+
+        def host_as_string
+          @host_as_string ||= port == DEFAULT_PORT ? host.to_s : "[#{host}]:#{port}"
+        end
+
+        def peer
+          @peer ||= { ip: nil, port: port.to_i, host: host, canonized: host_as_string }
+        end
+
+        def closed?
+          socket.closed?
+        end
+
+        def close
+          socket.close unless closed?
+        end
+
+        def shutdown!
+          error { "forcing connection closed" }
+          close
+        end
+
+        def next_message
+          poll_message(:block)
+        end
+
+        def poll_message(mode = :nonblock, *)
+          socket.next_packet(mode, options[:timeout])
+        end
+
+        def send_message(message)
+          socket.send_packet(check_supported(message.to_s))
+        end
+
+        def enqueue_message(message)
+          socket.enqueue_packet(check_supported(message.to_s))
+        end
+
+        # The master rekeys its own connection.
+        def rekey!; end
+
+        def rekey_as_needed; end
+
+        def hint(*); end
+
+        def server_version
+          not_supported("the server version")
+        end
+
+        def algorithms
+          not_supported("the negotiated algorithms")
+        end
+
+        def host_keys
+          not_supported("the host keys")
+        end
+
+        def host_key_verifier
+          not_supported("host key verification")
+        end
+
+        private
+
+        def not_supported(what)
+          raise NotSupportedOverControlMaster, "#{what} belong(s) to the ControlMaster at #{control_path}"
+        end
+
+        # The master kills the proxy connection on any global request other
+        # than tcpip-forward, and consumes the reply to that one itself, so
+        # its success or failure and an allocated port 0 can't be observed
+        # (channels.c channel_proxy_downstream, clientloop.c
+        # client_global_request_reply).
+        def check_supported(data)
+          case data.getbyte(0)
+          when GLOBAL_REQUEST
+            request = Net::SSH::Buffer.new(data.byteslice(1..-1)).read_string
+            if request == 'tcpip-forward'
+              raise NotSupportedOverControlMaster, "remote forwarding (tcpip-forward) is not supported over a ControlMaster: " \
+                                                   "the master consumes the reply, so success and the allocated port can't be observed"
+            end
+
+            raise NotSupportedOverControlMaster, "global request #{request} is not supported over a ControlMaster"
+          when CHANNEL_REQUEST
+            request = Net::SSH::Buffer.new(data.byteslice(5..-1)).read_string
+            if UNSUPPORTED_CHANNEL_REQUESTS.include?(request)
+              raise NotSupportedOverControlMaster, "channel request #{request} is not supported over a ControlMaster"
+            end
+          end
+          data
+        end
+      end
+    end
+  end
+end

data/lib/net/ssh/multiplex.rb

@@ -0,0 +1,130 @@
+require 'socket'
+
+require 'net/ssh/errors'
+require 'net/ssh/connection/session'
+require 'net/ssh/multiplex/client'
+require 'net/ssh/multiplex/control_path'
+require 'net/ssh/multiplex/proxy_transport'
+
+module Net
+  module SSH
+    # Reuse of an existing OpenSSH ControlMaster connection, enabled by the
+    # :control_master option of Net::SSH.start. Net::SSH only ever connects to
+    # a master someone else started (e.g. with ssh -M or ControlMaster auto);
+    # it never becomes one.
+    module Multiplex
+      # Used for the mux handshake when the :timeout option isn't set.
+      DEFAULT_TIMEOUT = 5
+
+      # Options for setting up a connection, which the master already did
+      # with its own settings.
+      MASTER_OWNED_OPTIONS = %i[
+        agent_socket_factory append_all_supported_algorithms auth_methods
+        bind_address check_host_ip compression compression_level encryption
+        fingerprint_hash global_known_hosts_file hmac host_key identity_agent
+        keepalive keepalive_interval keepalive_maxcount kex key_data keycert_data
+        keycerts keys keys_only known_hosts languages minimum_dh_bits no_delay
+        non_interactive number_of_password_prompts passphrase password
+        password_prompt proxy pubkey_algorithms rekey_blocks_limit rekey_limit
+        rekey_packet_limit use_agent user_known_hosts_file verify_host_key
+      ].freeze
+
+      VALUES = [:auto, false, nil].freeze
+
+      def self.validate_options!(options)
+        unless VALUES.include?(options[:control_master])
+          raise ArgumentError, "control_master must be :auto or false, got #{options[:control_master].inspect}"
+        end
+        return unless options[:control_master] && options[:forward_agent]
+
+        raise ArgumentError, "forward_agent can't be used with control_master: the ControlMaster serves agent requests " \
+                             "from its own agent only if it has ForwardAgent enabled itself, and rejects them otherwise"
+      end
+
+      # Returns a Connection::Session running through the ControlMaster for
+      # this connection, or nil (after logging why) when there is no usable
+      # master, in which case the caller connects as usual. +explicit+ are
+      # the option names the caller passed to Net::SSH.start. Raises
+      # ArgumentError for an invalid ControlPath, as ssh does.
+      def self.connect(host_arg, host, user, options, explicit: [])
+        logger = options[:logger]
+        path = socket_path(host_arg, host, user, options)
+        return nil unless path
+
+        socket = open_proxy(path, options)
+        return nil unless socket
+
+        logger.info { "control_master: using ControlMaster at #{path}" }
+        warn_master_owned(logger, explicit)
+        begin
+          transport = ProxyTransport.new(socket, host: host, control_path: path, options: options)
+          Connection::Session.new(transport, session_options(logger, options))
+        rescue StandardError
+          socket.close
+          raise
+        end
+      end
+
+      # ENOENT and ECONNREFUSED just mean no master is running, while the
+      # other errors mean a socket is there but can't be used.
+      def self.open_proxy(path, options)
+        Client.new(path, timeout: options[:timeout] || DEFAULT_TIMEOUT, logger: options[:logger]).connect_proxy
+      rescue Errno::ENOENT, Errno::ECONNREFUSED => e
+        options[:logger].info { "control_master: no ControlMaster at #{path}: #{e.message} (#{e.class})" }
+        nil
+      rescue Multiplex::Error, SystemCallError, IOError, SocketError => e
+        options[:logger].warn { "control_master: not using ControlMaster at #{path}: #{e.message} (#{e.class})" }
+        nil
+      end
+
+      def self.socket_path(host_arg, host, user, options)
+        if Gem.win_platform? || !defined?(UNIXSocket)
+          options[:logger].debug { "control_master: UNIX sockets are not available on this platform" }
+          return nil
+        end
+
+        control_path = options[:control_path]
+        if control_path.nil? || control_path.to_s == 'none'
+          options[:logger].debug { "control_master: no ControlPath set" }
+          return nil
+        end
+
+        expander = ControlPath.new(
+          host_arg: host_arg, host: host, port: options[:port] || ProxyTransport::DEFAULT_PORT, remote_user: user,
+          jump_host: jump_host(options[:proxy]), host_key_alias: options[:host_key_alias]
+        )
+        begin
+          path = expander.expand(control_path.to_s)
+          Socket.sockaddr_un(path)
+        rescue ArgumentError => e
+          raise ArgumentError, "invalid control_path #{control_path.to_s.inspect}: #{e.message}"
+        end
+        path
+      end
+
+      def self.jump_host(proxy)
+        return '' unless defined?(Net::SSH::Proxy::Jump) && proxy.is_a?(Net::SSH::Proxy::Jump)
+
+        ControlPath.jump_host(proxy.jump_proxies)
+      end
+
+      def self.warn_master_owned(logger, explicit)
+        bypassed = explicit & MASTER_OWNED_OPTIONS
+        return if bypassed.empty?
+
+        logger.warn { "control_master: ignoring #{bypassed.join(', ')}, the ControlMaster's own settings apply" }
+      end
+
+      # Keepalive is a global request, which the master doesn't allow; it
+      # watches its own connection anyway. ForwardAgent from ssh_config is
+      # dropped for the reason given in validate_options!.
+      def self.session_options(logger, options)
+        logger.info { "control_master: keepalive is left to the ControlMaster" } if options[:keepalive]
+        logger.info { "control_master: ignoring ForwardAgent, the ControlMaster's own ForwardAgent setting applies" } if options[:forward_agent]
+        options.merge(keepalive: false, forward_agent: false)
+      end
+
+      private_class_method :open_proxy, :socket_path, :jump_host, :warn_master_owned, :session_options
+    end
+  end
+end

data/lib/net/ssh/proxy/jump.rb

@@ -15,14 +15,33 @@ module Net
       #   Net::SSH.start('host', 'user', :proxy => proxy) do |ssh|
       #     ...
       #   end
+      #
+      # ssh_config options for the jump host can be given as a Hash via
+      # +options:+; each is passed to the ssh command as +-o Key=value+:
+      #
+      #   proxy = Net::SSH::Proxy::Jump.new('user@proxy', options: { 'StrictHostKeyChecking' => 'no' })
+      #
+      # Options that ssh_config allows more than once (+IdentityFile+,
+      # +CertificateFile+ and +SendEnv+) take an Array and are passed once per
+      # element; an empty Array passes nothing:
+      #
+      #   proxy = Net::SSH::Proxy::Jump.new('user@proxy', options: { 'IdentityFile' => ['~/.ssh/jump', '~/.ssh/jump_old'] })
+      #
+      # A +nil+ value, alone or in an Array, raises ArgumentError, as it does
+      # for the options passed to Net::SSH.start; omit the option instead.
+      #
+      # The options apply to the first jump host only; any further hosts in
+      # the chain are connected to by that host's own ssh.
       class Jump < Command
         # The jump proxies
         attr_reader :jump_proxies
 
         # Create a new socket factory that tunnels via multiple jump proxes as
         # [user@]host[:port].
-        def initialize(jump_proxies)
+        def initialize(jump_proxies, options: {})
           @jump_proxies = jump_proxies
+          @options = options
+          validate_options!
         end
 
         # Return a new socket connected to the given host and port via the jump
@@ -43,7 +62,10 @@ module Net
           template << " -l #{uri.user}"    if uri.user
           template << " -p #{uri.port}"    if uri.port
           template << " -J #{extra_jumps}" if extra_jumps
-          template << " -F #{Shellwords.escape(config)}" if config != true && config
+          template << " -F #{escape(config)}" if config != true && config
+          @options.each do |key, values|
+            Array(values).each { |value| template << " -o #{escape(key)}=#{escape(value)}" }
+          end
           template << " -W %h:%p "
           template << uri.host
 
@@ -52,6 +74,22 @@ module Net
 
         private
 
+        # Like Net::SSH.start, reject nil option values (alone or in an Array)
+        # rather than silently passing nothing or an empty value to ssh.
+        def validate_options!
+          nil_keys = @options.select { |_key, value| value.nil? || (value.is_a?(Array) && value.include?(nil)) }.keys
+          return if nil_keys.empty?
+
+          raise ArgumentError, "nil is not allowed for #{nil_keys.map(&:inspect).join(', ')} in Net::SSH::Proxy::Jump options; " \
+                               "omit the option to use the default or ssh_config value"
+        end
+
+        # Escape for the shell, and double any % so it survives the %h/%p
+        # substitution done on the template in Command#open.
+        def escape(value)
+          Shellwords.escape(value).gsub("%", "%%")
+        end
+
         def validate_jump!(jump)
           uri = URI.parse("ssh://#{jump}")
           validate_user_name!(uri.user) if uri.user