tbm 0.1.2 → 0.2.0.rc1

data/README.md

@@ -1,5 +1,48 @@
-# Tunnels
+# Tunnel Boring Machine
 
-A simple Ruby script to manage named SSH tunnels because I need these regularly and it's a bit of a pain to manage this in some other way.
+Tunnel Boring Machine is a ruby application to manage SSH tunnels, which you can use to achieve something a little like a VPN, wherein SSH access to a server can give you access to the network beyond that server.
 
-At the moment, this will be a command that you invoke, and leave running. At some point, it might make sense to make this two processes -- one that stays alive while there are active tunnels, and a command-line that interacts with that process. For now, that's more work than I intend to bite off -- more of a v2 feature.
+I use SSH tunnels on a regular basis to access resources at client sites that are not exposed directly to the internet as a whole. Managing those tunnels as a series of bash scripts or aliases became cumbersome. I wanted / needed something better, and the tunnel boring machine has evolved from that need.
+
+## Current Status ##
+It's pretty early days. I'm using this myself, but I haven't gone out of my way to share it with anyone because so much is still in flux. I imagine it will be starting to stabilize soon into something I might call a 'beta' product. At the moment, it's probably more of an 'alpha'.
+
+## Installing ##
+It is bundled as a ruby gem, so if you have Ruby and RubyGems installed, simply run:
+
+    gem install tbm
+
+If you prefer, you can certainly download it and build it yourself, or simply invoke the ruby code from the command-line.
+
+## Invocation ##
+For the time being, TBM is a simple command you invoke to open the tunnels you need, then you cancel with `^C` to close the tunnels that you had opened. Something like this:
+
+    $ tbm dev-ngnix
+
+Eventually, I expect that TBM will become a little more interactive, allowing you to open additional tunnels without closing the ones you already opened, close a tunnel without closing all of them, and so forth. Whether it does this as an interactive program, a shell command that interacts with a running process is all TBD.
+
+## Configuration ##
+You configure the tunnel boring machine by creating a configuration file in YAML form at `~/.tunnels`. At the moment, you can't have multiple configuration files, change the location of the configuration file or anything of that nature.
+
+An example configuration file follows:
+
+    jira:
+        host: ssh.example.com
+        forward: 8080
+    teamcity:
+        host: ssh.example.com
+        forward: 8111
+        alias: tc
+    jdbc-as400:
+        host: ssh.example.com
+        forward:
+          greenmachine: [ 449, 8470, 8471, 8476 ]
+        alias: [ ja, j400 ] 
+
+This configuration file is still evolving -- I expect the format to continue to change, the above simply represents the current state.
+
+## License ##
+I've put it under the UNLICENSE. Basically, I don't care if you use it, bundle it inside commercial software, or otherwise make use of it, and I don't offer any kind of warranty or support guarantees, nor do I guarantee that any of the projects dependencies are suited for whatever purpose you have in mind. That's all up to you. That said, if you want to talk about it, see the next section.
+
+## Contact ##
+If you're using TBM and you want to talk about it or make suggestions, get in touch with me on [Twitter](http://twitter.com/geoffreywiseman) or send me an [email](mailto:geoffrey.wiseman@codiform.com). If there's enough interest, I'd be happy to set up a group, but for the time being that seems like overkill.

data/Rakefile

@@ -22,17 +22,17 @@ end
 
 spec = Gem::Specification.new do |spec|
   spec.name = 'tbm'
-  spec.version = Tunnel::VERSION
-  spec.date = Tunnel::DATE
-  spec.summary = 'Named SSH tunnels, like bookmarks.'
+  spec.version = TBM::VERSION
+  spec.date = TBM::RELEASE_DATE
+  spec.summary = 'Manages SSH Tunnels by creating an SSH connection and forwarding ports based on named targets defined in configuration.'
   spec.description = 'The "Tunnel Boring Machine" is meant to bore ssh tunnels through the internet to your desired destination simply and repeatedly, as often as you need them. This is a tool for someone who needs SSH tunnels frequently.'
   spec.author = 'Geoffrey Wiseman'
   spec.email = 'geoffrey.wiseman@codiform.com'
   spec.homepage = 'http://github.com/geoffreywiseman/tunnel-boring-machine'
   spec.executables << 'tbm'
-  
+
   spec.files = Dir['{lib,spec}/**/*.rb', 'bin/*', 'Rakefile', 'README.md', 'UNLICENSE']
-  
+
   spec.add_dependency( 'net-ssh', '>= 2.6.2' )
 end
 

data/bin/tbm

@@ -2,4 +2,4 @@
 
 require 'tbm'
 
-Tunnel::CommandLineInterface.parse_and_run
+TBM::CommandLineInterface.parse_and_run

data/lib/TBM/cli.rb

@@ -0,0 +1,83 @@
+module TBM
+
+	# The command-line interface for TBM, this parses the supplied arguments and orchestrates the 
+	# rest of the classes based on those supplied arguments.
+	class CommandLineInterface
+		attr_reader :targets
+
+		# Initialize the CLI with a parsed config.
+		#
+		# @param [Config] config the parsed configuration
+		def initialize( config )
+			@config = config
+			@targets = nil
+			@cancelled = false
+		end
+
+		# Parses the command-line arguments by seeking targets, and print errors/usage if necessary.
+		def parse
+			if ARGV.empty? then 
+				print_targets "SYNTAX: tbm <targets>\n\nWhere <targets> is a comma-separated list of:" 
+			else
+				parse_targets( ARGV )
+			end
+		end
+
+		# The CLI is valid if no errors were found during parsing, and that are known target tunnels to bore.
+		#
+		# @return true if there are targets defined, which will only happen if there were no parsing errors
+		def valid?
+			!@targets.nil?
+		end
+
+		# Parse the configuration and command-line arguments and run the tunnel boring machine if both are valid.
+		def self.parse_and_run
+			config = ConfigParser.parse
+			if config.valid?
+				cli = CommandLineInterface.new( config )
+				cli.parse
+				if cli.valid?
+					machine = Machine.new( cli.targets )
+					machine.bore
+				end
+			else
+				puts "Cannot parse configuration:\n\t#{config.errors.join('\n\t')}"
+			end
+		end
+
+		private
+
+		def parse_targets( targets )
+			found_targets = []
+			missing_targets = []
+			targets.each do |target_name|
+				target = @config.get_target( target_name )
+				if target.nil? then
+					missing_targets << target_name
+				else
+					found_targets << target
+				end
+			end
+
+			if missing_targets.any?
+				print_targets( "Cannot find target(s): #{missing_targets.join(', ')}\n\nThese are the targets currently defined:")
+			elsif invalid_combination?( found_targets )
+				puts "Can't combine targets: #{targets.join(', ')}."
+			else
+				@targets = found_targets
+			end
+		end
+
+		def invalid_combination?( targets )
+			num_hosts = targets.map { |t| t.host }.uniq.size
+			num_usernames = targets.map { |t| t.username }.uniq.size
+			num_hosts != 1 || num_usernames != 1
+		end
+
+		def print_targets( message )
+			puts message
+			@config.each_target { |target| puts "\t#{target.to_s}" }
+		end
+
+	end
+end

data/lib/TBM/config.rb

@@ -0,0 +1,41 @@
+module TBM
+
+	# Configuration for the Tunnel Boring Machine. This class is both the parser of the configuration
+	# data in YAML form, and the artifact that results from the parsing.
+	class Config
+
+		# Any errors discovered while parsing the configuration.
+		attr_reader :errors
+
+		# The targets defined in the configuration.
+		attr_reader :targets
+
+		def initialize
+			@errors = []
+			@targets = []
+		end
+
+		# The configuration is valid if there are no errors.
+		#
+		# @return true if the error collection is empty
+		def valid?
+			@errors.empty?
+		end
+
+		# Request a target having the specified name.
+		#
+		# @param [String] name the name of the target
+		def get_target( name )
+			@targets.find { |target| target.has_name?(name) }
+		end
+
+		# Iterate over each target and yield to the specified block.
+		#
+		# @yield [target] a block to which each target will be passed
+		def each_target( &block )
+			@targets.each { |target| yield target }
+		end
+
+	end
+
+end

data/lib/TBM/config_parser.rb

@@ -0,0 +1,221 @@
+require 'etc'
+require 'yaml'
+require 'tbm'
+
+module TBM
+	class ConfigParser
+
+		# The configuration file used for parsing config.
+		CONFIG_FILE = File.expand_path( '~/.tbm' )
+		GATEWAY_PATTERN = /^([^@]+)(@([^@]+))?$/
+
+		# Parses the tunnel boring machine configuration to get a list of targets which can 
+		# be invoked to bore tunnels.
+		#
+		# @return [Config] the parsed configuration for TBM
+		def self.parse
+			config = Config.new
+			if File.file? CONFIG_FILE
+				config_data = YAML.load_file( CONFIG_FILE )
+				case config_data
+				when Hash
+					parse_gateways( config_data, config ) if config_data.is_a? Hash
+				else
+					config.errors << "Cannot parse TBM configuration of type: #{config_data.class}"
+				end
+			else
+				config.errors << "No configuration file found. Specify your tunnels in YAML form in: ~/.tunnels"
+			end
+			return config
+		rescue Psych::SyntaxError => pse
+			config.errors << "TBM config is invalid YAML: #{pse}"
+			return config
+		end
+
+		private
+
+		def self.parse_gateways( gateways, config )
+			if gateways.empty?
+				config.errors << "No gateways specified."
+			else
+				gateways.each_key { |key| parse_gateway key, gateways[key], config }
+			end
+			return config
+		end
+
+		private
+
+		def self.parse_gateway( gateway_name, targets, config )
+			if String === gateway_name
+				(gateway_host, gateway_username) = parse_gateway_name( gateway_name )
+				parse_targets( gateway_host, gateway_username, targets, config ) unless gateway_host.nil?
+			else
+				config.errors << "Cannot parse gateway name: #{gateway_name} (#{gateway_name.class})"
+			end
+		end
+
+		def self.parse_gateway_name( gateway_name )
+			if GATEWAY_PATTERN =~ gateway_name
+				if $3.nil?
+					[$1,Etc.getlogin]
+				else
+					[$3,$1]
+				end
+			else
+				config.errors << "Cannot parse gateway name: #{gateway_name}"
+				nil
+			end
+		end
+
+		def self.parse_targets( gateway_host, gateway_username, targets, config )
+			if Hash === targets
+				targets.each_key do |target_name|
+					target = Target.new( target_name.to_s, gateway_host, gateway_username )
+					config.targets << target
+					configure_target( target, targets[target_name], config )
+				end
+			else
+				config.errors << "Cannot parse targets, expected Hash, received: #{targets.class}"
+			end
+		end
+
+		def self.configure_target( target, target_config, config )
+			case target_config
+			when Fixnum, String
+				tunnel( target, target_config, config )
+			when Array
+				target_config.each { |tunnel_config| tunnel(target, tunnel_config, config) }
+				config.errors << "Target #{target} contains no tunnels." if target_config.empty?
+			when Hash
+				target_config.each { |key,value| configure_target_attribute( target, key, value, config ) }
+				config.errors << "Target #{target} contains no tunnels." if target_config.empty?
+			when nil
+				config.errors << "No target config for #{target}."
+			else
+				config.errors << "Cannot parse target config: #{target_config} (#{target_config.class})"
+			end
+		end
+
+		def self.tunnel( target, tunnel_config, config )
+			case tunnel_config
+			when Fixnum
+				if valid_port?( tunnel_config )
+					target.add_tunnel( Tunnel.new( tunnel_config ) )
+				else
+					config.errors << "Invalid port number: #{tunnel_config}"
+				end
+			when String
+				case tunnel_config 
+				when /^\d{1,5}$/
+					port = tunnel_config.to_i
+					if valid_port?( port )
+						target.add_tunnel( Tunnel.new( port ) )
+					else
+						config.errors << "Invalid port number: #{tunnel_config}"
+					end
+				when /^(\d{1,5}):(\d{1,5})$/
+					port = $1.to_i
+					remote_port = $2.to_i
+					if !valid_port?( port )
+						config.errors << "Invalid local port number #{port} from #{tunnel_config}"
+					elsif !valid_port?( remote_port )
+						config.errors << "Invalid remote port number #{remote_port} from #{tunnel_config}"
+					else
+						target.add_tunnel( Tunnel.new( port, :remote_port => remote_port ) )
+					end
+				when /^(\d{1,5}):([a-zA-Z0-9\.\-]+):(\d{1,5})$/
+					port = $1.to_i
+					remote_host = $2
+					remote_port = $3.to_i
+					if !valid_port?( port )
+						config.errors << "Invalid local port number #{port} from #{tunnel_config}"
+					elsif !valid_port?( remote_port )
+						config.errors << "Invalid remote port number #{remote_port} from #{tunnel_config}"
+					else
+						target.add_tunnel( Tunnel.new( port, :remote_host => remote_host, :remote_port => remote_port ) )
+					end
+				when /^([a-zA-Z0-9\.\-]+):(\d{1,5})$/
+					port = $2.to_i
+					remote_host = $1
+					if !valid_port?( port )
+						config.errors << "Invalid port number #{port} from #{tunnel_config}"
+					else
+						target.add_tunnel( Tunnel.new( port, :remote_host => remote_host ) )
+					end
+				else
+					config.errors << "Cannot parse tunnel: #{tunnel_config} (#{tunnel_config.class})"
+				end
+			else
+				config.errors << "Cannot parse tunnel: #{tunnel_config} (#{tunnel_config.class})"
+			end
+		end
+
+		def self.valid_port?( port )
+			port.between?( 1, 65535 )
+		end
+
+		def self.configure_target_attribute( target, attribute_name, attribute_value, config )
+			case attribute_name
+			when "tunnel"
+				tunnel( target, attribute_value, config )
+			when "alias"
+				case attribute_value
+				when Array
+					attribute_value.each { |name| target.add_alias( name.to_s ) }
+				else
+					target.add_alias( attribute_value.to_s )
+				end
+			else 
+				remote_host = attribute_name.to_s
+				case attribute_value
+				when Fixnum, String
+					remote_tunnel( target, remote_host, attribute_value, config )
+				when Array
+					attribute_value.each { |tunnel_config| remote_tunnel(target, remote_host, tunnel_config, config) }
+					config.errors << "Host #{remote_host} on target #{target} contains no tunnels." if attribute_value.empty?
+				when nil
+					config.errors << "No target config for host #{remote_host} on target #{target}."
+				else
+					config.errors << "Cannot parse target config: #{attribute_name} = #{attribute_value} (#{attribute_value.class})"
+				end
+			end
+		end
+
+		def self.remote_tunnel( target, remote_host, tunnel_config, config )
+			case tunnel_config
+			when Fixnum
+				if valid_port?( tunnel_config )
+					target.add_tunnel( Tunnel.new( tunnel_config, :remote_host => remote_host ) )
+				else
+					config.errors << "Invalid port number: #{tunnel_config}"
+				end
+			when String
+				case tunnel_config 
+				when /^\d{1,5}$/
+					port = tunnel_config.to_i
+					if valid_port?( port )
+						target.add_tunnel( Tunnel.new( port, :remote_host => remote_host ) )
+					else
+						config.errors << "Invalid port number: #{tunnel_config}"
+					end
+				when /^(\d{1,5}):(\d{1,5})$/
+					port = $1.to_i
+					remote_port = $2.to_i
+					if !valid_port?( port )
+						config.errors << "Invalid local port number #{port} from #{tunnel_config}"
+					elsif !valid_port?( remote_port )
+						config.errors << "Invalid remote port number #{remote_port} from #{tunnel_config}"
+					else
+						target.add_tunnel( Tunnel.new( port, :remote_port => remote_port, :remote_host => remote_host ) )
+					end
+				else
+					config.errors << "Cannot parse tunnel: #{tunnel_config} (#{tunnel_config.class})"
+				end
+			else
+				config.errors << "Cannot parse tunnel: #{tunnel_config} (#{tunnel_config.class})"
+			end
+		end
+
+
+	end
+end

data/lib/TBM/machine.rb

@@ -0,0 +1,59 @@
+require 'net/ssh'
+
+module TBM
+
+  # The "Machine" class does all the actual interaction with SSH to perform the tunneling.
+  class Machine
+
+    # Initialize the Machine with a set of tunnels to bore
+    #
+    # @param [Array<Target>] tunnels the tunnels to be bored
+    def initialize( targets )
+      @targets = targets
+    end
+
+    # Open a connection to the gateway server, and then set up (bore) any
+    # tunnels specified in the initialize method.
+    def bore
+      puts "Starting #{APP_NAME} v#{VERSION}"
+      puts
+
+      trap("INT") { @cancelled = true }
+      host = @targets.first.host
+      username = @targets.first.username
+      Net::SSH.start( host, username ) do |session|
+        puts "Opened connection to #{username}@#{host}:"
+        forward_ports( session )
+      end
+
+      puts "Shutting down the machine."
+    rescue Errno::ECONNRESET
+      puts "\nConnection lost (reset). Shutting down the machine."
+    rescue Errno::ETIMEDOUT
+      puts "\nConnection lost (timed out). Shutting down the machine."
+    rescue Errno::EADDRINUSE
+      puts "\tPorts already in use, cannot forward.\n\nShutting down the machine."
+    rescue Errno::EACCES
+      puts "\tCould not open all ports; you may need to sudo if port < 1000."
+    end
+
+    private
+
+    def forward_ports( session )
+      @targets.each do |target|
+        target.each_tunnel do |tunnel|
+          port = tunnel.port
+          remote_host = tunnel.remote_host || 'localhost'
+          remote_host_name = tunnel.remote_host || target.host
+          remote_port = tunnel.remote_port
+          session.forward.local( port, remote_host, remote_port )
+          puts "\ttunneled port #{port} to #{remote_host_name}:#{remote_port}"
+        end
+      end
+      puts "\twaiting for Ctrl-C..."
+      session.loop(0.1) { not @cancelled }
+      puts "\n\tCtrl-C pressed. Exiting."
+    end
+
+  end
+end