Permalink
Browse files

more docs for Connection::Term. Docs for the connection proxy impleme…

…ntations.
  • Loading branch information...
jamis committed Mar 22, 2008
1 parent 7dc5d9e commit 39d68b31a61c58a83934c6f3f19abefa1282414f
@@ -1,6 +1,9 @@
module Net; module SSH; module Connection
- # Terminal opcodes, for use when opening pty's.
+ # These constants are used when requesting a pseudo-terminal (via
+ # Net::SSH::Connection::Channel#request_pty). The descriptions for each are
+ # taken directly from RFC 4254 ("The Secure Shell (SSH) Connection Protocol"),
+ # http://tools.ietf.org/html/rfc4254.
module Term
# Interrupt character; 255 if none. Similarly for the other characters.
# Not all of these characters are supported on all systems.
@@ -8,7 +8,7 @@ class Error < Net::SSH::Exception; end
# Used for reporting proxy connection errors.
class ConnectError < Error; end
- # Used when the server doesn't recognize the users credentials
+ # Used when the server doesn't recognize the user's credentials.
class UnauthorizedError < Error; end
end; end; end
View
@@ -3,18 +3,43 @@
module Net; module SSH; module Proxy
- # An implementation of a socket factory that returns a socket which
- # will tunnel the connection through an HTTP proxy. It allows explicit
- # specification of the user and password, but if none are given it
- # will look in the HTTP_PROXY_USER/HTTP_PROXY_PASSWORD and
- # CONNECT_USER/CONNECT_PASSWORD environment variables as well.
+ # An implementation of an HTTP proxy. To use it, instantiate it, then
+ # pass the instantiated object via the :proxy key to Net::SSH.start:
+ #
+ # require 'net/ssh/proxy/http'
+ #
+ # proxy = Net::SSH::Proxy::HTTP.new('proxy.host', proxy_port)
+ # Net::SSH.start('host', 'user', :proxy => proxy) do |ssh|
+ # ...
+ # end
+ #
+ # If the proxy requires authentication, you can pass :user and :password
+ # to the proxy's constructor:
+ #
+ # proxy = Net::SSH::Proxy::HTTP.new('proxy.host', proxy_port,
+ # :user => "user", :password => "password")
+ #
+ # Note that HTTP digest authentication is not supported; Basic only at
+ # this point.
class HTTP
- attr_reader :proxy_host, :proxy_port
+ # The hostname or IP address of the HTTP proxy.
+ attr_reader :proxy_host
+
+ # The port number of the proxy.
+ attr_reader :proxy_port
+
+ # The map of additional options that were given to the object at
+ # initialization.
attr_reader :options
# Create a new socket factory that tunnels via the given host and
- # port.
+ # port. The +options+ parameter is a hash of additional settings that
+ # can be used to tweak this proxy connection. Specifically, the following
+ # options are supported:
+ #
+ # * :user => the user name to use when authenticating to the proxy
+ # * :password => the password to use when authenticating
def initialize(proxy_host, proxy_port=80, options={})
@proxy_host = proxy_host
@proxy_port = proxy_port
@@ -7,20 +7,37 @@ module Net
module SSH
module Proxy
- # An implementation of a socket factory that returns a socket which
- # will tunnel the connection through a SOCKS4 proxy. It allows explicit
- # specification of the user.
+ # An implementation of a SOCKS4 proxy. To use it, instantiate it, then
+ # pass the instantiated object via the :proxy key to Net::SSH.start:
+ #
+ # require 'net/ssh/proxy/socks4'
+ #
+ # proxy = Net::SSH::Proxy::SOCKS4.new('proxy.host', proxy_port, :user => 'user')
+ # Net::SSH.start('host', 'user', :proxy => proxy) do |ssh|
+ # ...
+ # end
class SOCKS4
+ # The SOCKS protocol version used by this class
VERSION = 4
+
+ # The packet type for connection requests
CONNECT = 1
+
+ # The status code for a successful connection
GRANTED = 90
- attr_reader :proxy_host, :proxy_port
+ # The proxy's host name or IP address, as given to the constructor.
+ attr_reader :proxy_host
+
+ # The proxy's port number.
+ attr_reader :proxy_port
+
+ # The additional options that were given to the proxy's constructor.
attr_reader :options
# Create a new proxy connection to the given proxy host and port.
- # Optionally, a @:user@ option may be given to identify the username
+ # Optionally, a :user key may be given to identify the username
# with which to authenticate.
def initialize(proxy_host, proxy_port=1080, options={})
@proxy_host = proxy_host
@@ -5,24 +5,53 @@ module Net
module SSH
module Proxy
- # An implementation of a socket factory that returns a socket which
- # will tunnel the connection through a SOCKS5 proxy. It allows explicit
- # specification of the user and password.
+ # An implementation of a SOCKS5 proxy. To use it, instantiate it, then
+ # pass the instantiated object via the :proxy key to Net::SSH.start:
+ #
+ # require 'net/ssh/proxy/socks5'
+ #
+ # proxy = Net::SSH::Proxy::SOCKS5.new('proxy.host', proxy_port,
+ # :user => 'user', :password => "password")
+ # Net::SSH.start('host', 'user', :proxy => proxy) do |ssh|
+ # ...
+ # end
class SOCKS5
- VERSION = 5
+ # The SOCKS protocol version used by this class
+ VERSION = 5
+
+ # The SOCKS authentication type for requests without authentication
METHOD_NO_AUTH = 0
- METHOD_PASSWD = 2
- METHOD_NONE = 0xFF
- CMD_CONNECT = 1
- ATYP_IPV4 = 1
- ATYP_DOMAIN = 3
- SUCCESS = 0
-
- attr_reader :proxy_host, :proxy_port
+
+ # The SOCKS authentication type for requests via username/password
+ METHOD_PASSWD = 2
+
+ # The SOCKS authentication type for when there are no supported
+ # authentication methods.
+ METHOD_NONE = 0xFF
+
+ # The SOCKS packet type for requesting a proxy connection.
+ CMD_CONNECT = 1
+
+ # The SOCKS address type for connections via IP address.
+ ATYP_IPV4 = 1
+
+ # The SOCKS address type for connections via domain name.
+ ATYP_DOMAIN = 3
+
+ # The SOCKS response code for a successful operation.
+ SUCCESS = 0
+
+ # The proxy's host name or IP address
+ attr_reader :proxy_host
+
+ # The proxy's port number
+ attr_reader :proxy_port
+
+ # The map of options given at initialization
attr_reader :options
# Create a new proxy connection to the given proxy host and port.
- # Optionally, @:user@ and @:password@ options may be given to
+ # Optionally, :user and :password options may be given to
# identify the username and password with which to authenticate.
def initialize(proxy_host, proxy_port=1080, options={})
@proxy_host = proxy_host

0 comments on commit 39d68b3

Please sign in to comment.