em-wssh 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 60abc80ee170a46ba2b1b2e70166eeb4a5f5718e
-  data.tar.gz: be2a072ef48e86d235c1a88781f9855f482ee416
+  metadata.gz: 1db6dba2f0f3dff81eed7b595806938e0bd8f064
+  data.tar.gz: 473cd9aaa813c0f21a5f178e03a90cf52acde42c
 SHA512:
-  metadata.gz: eb11f5728fc982b93a87fb395e98eed141e45cac2993e37e0d080c250fbed1c84f211b47fe7bdcd2f267a0397c22c5d5ffc29cf0c4f12591882ab265a26d5888
-  data.tar.gz: d69126590e4af9e4337769032a31e8dc461ad019b9c84ef04ed3fcb3e8b1bdd514edb9f2aebc839fb8a837c3d5f796459254624a6dfb0474644df81eb09df40f
+  metadata.gz: c01b25a7cf340ddb7f9ad0aadc5feaee60afc1f6acbb1660122eb3724011d8e2062abf02db60144052b23be6113584cd848cd02338806108894058820d78542b
+  data.tar.gz: 52d414591dfaf37c7c65c3a4610974f0ad491bb8c9d7b1d0bdfbfec3da832328b2189230638f0f72676476f5e4b2262c03908a2e4456806c19cfb359494fd20f

data/README.md

@@ -11,24 +11,128 @@ Ruby version of ssh thru websocket proxying.
 Add this line to your application's Gemfile:
 
 ```ruby
-  gem 'em-wssh' if Gem.win_platform?
+gem 'em-wssh' if Gem.win_platform?
 ```
 
 And then execute:
 
 ```sh
-  $ bundle
+$ bundle
 ```
 
 Or install it yourself as:
 
 ```sh
-  $ gem install em-wssh
+$ gem install em-wssh
 ```
 
 ## Usage
 
-...
+Single command `wssh` is exported. Sometimes it should be `bundle exec wssh`.
+
+### WSSH Server
+
+To run WSSH server say `wssh server`.
+
+### nginx
+
+Directly exposing WSSH server to Internet is not a good idea.
+One should better install nginx (with TLS) and [force it to redirect](nginx/ssh)
+WSSH connections to WSSH server.
+
+### WSSH Client
+
+Client is started with `wssh client URI`, eg `wssh client ws://localhost:4567`.
+
+Running client from terminal is not very useful. It should be called by ssh client:
+
+```sh
+ssh -o ProxyCommand='wssh client wss://server.host.com/ssh/%h' sshd.local
+```
+
+By default WSSH server has 60 seconds timeout. To prevent idle connection to drop,
+one can use `ServerAliveInterval` parameter:
+
+```sh
+ssh -o ProxyCommand='wssh client wss://server.host.com/ssh/%h' -o ServerAliveInterval=50 sshd.local
+```
+
+### WSSH Proxy
+
+WSSH client is in fact unusable on Windows.
+It can be impractical when we create a lot of SSH connections (eg with Capistrano mass deploy).
+
+In these cases run `wssh connect URI`, it will listen to TCP port (3122 by default) and will work
+as normal HTTP proxy, so proxy-capable clients (PuTTY/Plink and Net::SSH) can use it to connect to SSH servers.
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'net/ssh'
+require 'net/ssh/proxy/http'
+
+x=Net::SSH.start 'sshd.local', 'root',
+  proxy: Net::SSH::Proxy::HTTP.new('localhost', 3122)
+
+puts x.exec! 'hostname'
+```
+
+## API
+
+WSSH server, client or proxy can be start programmaticaly:
+
+```ruby
+require 'em/wssh/server'
+
+s=EventMachine::Wssh::Server
+s.options.merge! base: '.'
+s.loop!
+```
+
+```ruby
+require 'em/wssh/client'
+
+s=EventMachine::Wssh::Client
+s.options[:uri]='wss://server.host.com/ssh/sshd.local'
+s.loop!
+```
+
+```ruby
+require 'em/wssh/connect'
+
+s=EventMachine::Wssh::Connect
+s.options.merge! base: '.', all: true, uri: 'wss://server.host.com/ssh/sshd.local'
+s.loop!
+```
+
+Some options are not accesible to `wssh` command and can be used only programmaticaly.
+
+Eg, EventMachine::Wssh::Connect has option `onlisten` that allows listening to random port:
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'net/ssh'
+require 'net/ssh/proxy/http'
+require 'em/wssh/connect'
+
+q=Queue.new
+c=EventMachine::Wssh::Connect
+c.options.merge!(
+  port: 0,
+  uri: 'wss://server.host.com/ssh',
+  onlisten: Proc.new{|port| q.push port},
+)
+
+Thread.new{c.loop!}
+
+puts "Port=#{port=q.pop}"
+
+x=Net::SSH.start 'sshd.local', 'root',
+  proxy: Net::SSH::Proxy::HTTP.new('localhost', port)
+
+puts x.exec! 'hostname'
+```
 
 ## Data flow
 
@@ -40,8 +144,8 @@ Normal SSH session is very simple:
 
 WSSH session is:
 
-  * SSH Client with -o ProxyCommand='ruby client.rb WSSH-URI'
-  * client.rb listening to its stdin
+  * SSH Client with -o ProxyCommand='wssh client WSSH-URI'
+  * WSSH client listening to its stdin
   * Websocket (HTTP/HTTPS) connection to nginx
   * nginx [configured](nginx/ssh) to redirect connection to WSSH server
   * Another Websocket connection from nginx to WSSH server
@@ -53,9 +157,9 @@ And nginx stage can be omited in development/testing scenarios.
 
 In some scenarios this path can be even longer:
 
-  * SSH Client, capable to connect via HTTP proxy (eg PuTTY/PLink)
+  * SSH Client, capable to connect via HTTP proxy (eg PuTTY/PLink or Net::SSH)
   * TCP connection to local proxy
-  * connect.rb listening to dedicated port (3122 by default)
+  * `wssh connect` listening to dedicated port (3122 by default)
   * Websocket (HTTP/HTTPS) connection to nginx
   * nginx [configured](nginx/ssh) to redirect connection to WSSH server
   * Another Websocket connection from nginx to WSSH server
@@ -74,7 +178,7 @@ Windows installation of EventMachine has a few bugs:
 So, this package is in fact almost unusable on MS Windows.
 
 The only exception: if you connect to Non-TLS WSSH server
-(ws: or http:, not wss: or https:), you **can** start connect.rb
+(ws: or http:, not wss: or https:), you **can** start `wssh connect`
 and then use SSH client, capable to connect via HTTP proxy.
 
 To connect to TLS WSSH server, you should use Node.js version.

data/lib/em/wssh.rb

@@ -1,5 +1,5 @@
 module EventMachine
   module Wssh
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/em/wssh/connect.rb

@@ -161,7 +161,7 @@ Usage: #{Exe.biname} [options...] ws[s]://host[:port]/uri
 
   def self.listen!
     conn=EM.start_server options[:host], options[:port], Http
-    options[:onport].call Socket.unpack_sockaddr_in(EM.get_sockname conn)[0] if options[:onport]
+    options[:onlisten].call Socket.unpack_sockaddr_in(EM.get_sockname conn)[0] if options[:onlisten]
   end
 end
 end

data/lib/em/wssh/service.rb

@@ -6,7 +6,7 @@ module Service
 
   def log *msg
     msg.unshift "[#{Time.now}]"
-    (options[:logger]||=STDOUT).puts msg*' '
+    puts msg*' '
   end
 
   def helptions
@@ -78,7 +78,6 @@ EOF
     log "Going on in background..."
 
     f = File.open mkdir(:log), 'a'
-    f.sync=true
 
     STDIN.reopen '/dev/null'
     STDOUT.reopen f
@@ -101,6 +100,7 @@ EOF
 
   def loop!
     self::Need.each{|f| require f}
+    STDOUT.sync=true
     EM.run{ listen! }
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: em-wssh
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Stas Ukolov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-04 00:00:00.000000000 Z
+date: 2015-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: em-websocket