Add support for jump hosts

The jump-session function is used to obtain a session that can be
connected across jump hosts.

The `the-session` function is added to obtain a jsch session from a
connected jump-session, or a connected jsch Session, and can be used in
code that wants to support jump sessions.

Author: hugoduncan

README.md

@@ -115,6 +115,26 @@ SSH tunneling is also supported:
             (comment do something with port 8080 here)))))
 ```
 
+Jump hosts can be used with the `jump-session`.  Once the session is
+connected, the `the-session` function can be used to obtain a session
+that can be used with `ssh-exec`, etc.  The `the-session` function can
+be used on a session returned by `session`, so you can write code that
+works with both a `jump-session` session and a single host session.
+
+```clj
+(let [s (jump-session
+         (ssh-agent {})
+         [{:hostname "host1" :username "user"
+           :strict-host-key-checking :no}
+          {:hostname "final-host" :username "user"
+           :strict-host-key-checking :no}]
+         {})]
+  (with-connection s
+    (ssh-exec (the-session s) "ls" "" "" {}))
+```
+
+
+
 ## Documentation
 
 [Annotated source](http:/hugoduncan.github.com/clj-ssh/0.5/annotated/uberdoc.html).

src/clj_ssh/ssh.clj

@@ -26,6 +26,7 @@
    [clj-ssh.agent :as agent]
    [clj-ssh.keychain :as keychain]
    [clj-ssh.reflect :as reflect]
+   [clj-ssh.ssh.protocols :as protocols]
    [clojure.java.io :as io]
    [clojure.string :as string]
    [clojure.tools.logging :as logging])
@@ -98,6 +99,30 @@
   "Predicate to test for an ssh-agent."
   [object] (instance? JSch object))
 
+;;; Session extension
+
+;; This is only relevant if you want to support using jump hosts.  If
+;; you do, the you should always use the `the-session` to get the jsch
+;; session object once connected.
+
+;; This is here since JSch Session has a package scoped constructor,
+;; and doesn't implement an interface, so provides no means for
+;; extending it.
+
+(extend-protocol protocols/Session
+  Session
+  (connect
+    ([session] (.connect session))
+    ([session timeout] (.connect session timeout)))
+  (connected? [session] (.isConnected session))
+  (disconnect [session] (.disconnect session))
+  (session [session] session))
+
+(defn ^Session the-session
+  "Return the JSch session for the given session."
+  [session]
+  (protocols/session session))
+
 ;;; Agent
 (defn ssh-agent
   "Create a ssh-agent. By default a system ssh-agent is preferred."
@@ -257,23 +282,31 @@ keyword argument, or constructed from the other keyword arguments.
         (add-identity agent options)))))
 
 ;;; Sessions
+(defn- init-session
+  "Initialise options on a session"
+  [^Session session ^String password options]
+  (when password
+    (.setPassword session password))
+  (doseq [[k v :as option] options]
+    (.setConfig
+     session
+     (if (string? k)
+       k
+       (camelize (as-string k)))
+     (as-string v))))
+
 (defn- ^Session session-impl
   [^JSch agent hostname username port ^String password options]
-  (let [session (.getSession agent username hostname port)]
-    (when password
-      (.setPassword session password))
-    (doseq [[k v :as option] options]
-      (.setConfig
-       session
-       (if (string? k)
-         k
-         (camelize (as-string k)))
-       (as-string v)))
-    session))
+  (doto (.getSession agent username hostname port)
+    (init-session password options)))
+
+(defn- session-options
+  [options]
+  (dissoc options :username :port :password :agent))
 
 (defn ^Session session
   "Start a SSH session.
-Requires hostname.  you can also pass values for :username, :password and :port
+Requires hostname.  You can also pass values for :username, :password and :port
 keys.  All other option key pairs will be passed as SSH config options."
   [^JSch agent hostname
    {:keys [port username password] :or {port 22} :as options}]
@@ -282,7 +315,7 @@ keys.  All other option key pairs will be passed as SSH config options."
    (or username (System/getProperty "user.name"))
    port
    password
-   (dissoc options :username :port :password :agent)))
+   (session-options options)))
 
 (defn forward-remote-port
   "Start remote port forwarding"
@@ -309,7 +342,7 @@ keys.  All other option key pairs will be passed as SSH config options."
       (unforward-remote-port ~session ~remote-port))))
 
 (defn forward-local-port
-  "Start local port forwarding"
+  "Start local port forwarding. Returns the actual local port."
   ([^Session session local-port remote-port remote-host]
      (.setPortForwardingL session local-port remote-host remote-port))
   ([session local-port remote-port]
@@ -333,24 +366,25 @@ keys.  All other option key pairs will be passed as SSH config options."
 
 (defn connect
   "Connect a session."
-  ([^Session session]
-     (.connect session))
-  ([^Session session timeout]
-     (.connect session timeout)))
+  ([session]
+     (protocols/connect session))
+  ([session timeout]
+     (protocols/connect session timeout)))
 
 (defn disconnect
   "Disconnect a session."
-  [^Session session]
-  (.disconnect session)
-  (when-let [^Thread t (reflect/get-field
-                        com.jcraft.jsch.Session 'connectThread session)]
+  [session]
+  (protocols/disconnect session)
+  (when-let [^Thread t (and (instance? Session session)
+                            (reflect/get-field
+                             com.jcraft.jsch.Session 'connectThread session))]
     (when (.isAlive t)
       (.interrupt t))))
 
 (defn connected?
   "Predicate used to test for a connected session."
-  [^Session session]
-  (.isConnected session))
+  [session]
+  (protocols/connected? session))
 
 (defmacro with-connection
   "Creates a context in which the session is connected. Ensures the session is
@@ -364,6 +398,81 @@ keys.  All other option key pairs will be passed as SSH config options."
        (finally
         (disconnect session#)))))
 
+;;; Jump Hosts
+(defn- jump-connect [agent hosts sessions timeout]
+  (let [host (first hosts)
+        s (session agent (:hostname host) (dissoc host :hostname))
+        throw-e (fn [e s]
+                  (throw
+                   (ex-info
+                    (str "Failed to connect "
+                         (.getUserName s) "@"
+                         (.getHost s) ":"
+                         (.getPort s)
+                         " " (pr-str (into [] (.getIdentityNames agent)))
+                         " " (pr-str hosts))
+                    {:hosts hosts}
+                    e)))]
+    (swap! sessions (fnil conj []) s)
+    (try
+      (connect s timeout)
+      (catch Exception e (throw-e e s)))
+    (.setDaemonThread s true)
+    (loop [hosts (rest hosts)
+           prev-s s]
+      (if-let [{:keys [hostname port username password]
+                :or {port 22}
+                :as options}
+               (first hosts)]
+        (let [p (forward-local-port prev-s 0 port hostname)
+              options (-> options
+                          (dissoc :hostname)
+                          (assoc :port p))
+              s (session agent "localhost" options)]
+          (.setDaemonThread s true)
+          (.setHostKeyAlias s hostname)
+          (swap! sessions conj s)
+          (try
+            (connect s timeout)
+            (catch Exception e (throw-e e s)))
+          (recur (rest hosts) s))))))
+
+(defn- jump-connected? [sessions]
+  (seq @sessions))
+
+(defn- jump-disconnect
+  [sessions]
+  (doseq [s (reverse @sessions)]
+    (.disconnect s))
+  (reset! sessions nil))
+
+(defn- jump-the-session
+  [sessions]
+  (assert (jump-connected? sessions) "not connected")
+  (last @sessions))
+
+(deftype JumpHostSession [agent hosts sessions timeout]
+  protocols/Session
+  (connect [session] (protocols/connect session timeout))
+  (connect [session timeout] (jump-connect agent hosts sessions timeout))
+  (connected? [session] (jump-connected? sessions))
+  (disconnect [session] (jump-disconnect sessions))
+  (session [session] (jump-the-session sessions)))
+
+;; http://www.jcraft.com/jsch/examples/JumpHosts.java.html
+(defn jump-session
+  "Connect via a sequence of jump hosts.  Returns a session.  Once the
+session is connected, use `the-session` to get a jsch Session object.
+
+Each host is a map with :hostname, :username, :password and :port
+keys.  All other key pairs in each host map will be passed as SSH
+config options."
+  [^JSch agent hosts {:keys [timeout]}]
+  (when-not (seq hosts)
+    (throw (ex-info "Must provide at least one host to connect to"
+                    {:hosts hosts})))
+  (JumpHostSession. agent hosts (atom []) (or timeout 0)))
+
 ;;; Channels
 (defn connect-channel
   "Connect a channel."

src/clj_ssh/ssh/protocols.clj

@@ -0,0 +1,9 @@
+(ns clj-ssh.ssh.protocols
+  "Protocols for ssh")
+
+(defprotocol Session
+  "Provides a protocol for a session."
+  (connect [x] [x timeout] "Connect the session")
+  (connected? [x] "Predicate for a connected session")
+  (disconnect [x] "Disconnect the session")
+  (session [x] "Return a Jsch Session for the session"))

test/clj_ssh/ssh_test.clj

@@ -581,3 +581,24 @@
           (is (port-reachable? 2222)))
         (with-remote-port-forward [session 2222 22 "localhost"]
           (is (port-reachable? 2222)))))))
+
+(deftest jump-session-test
+  (is (let [s (jump-session (ssh-agent {})
+                            [{:hostname "localhost"
+                              :username (username)
+                              :strict-host-key-checking :no}]
+                            {})]
+        (with-connection s
+            (ssh-exec (the-session s) "ls" "" "" {})))
+      "one host")
+  (is (let [s (jump-session (ssh-agent {})
+                            [{:hostname "localhost"
+                              :username (username)
+                              :strict-host-key-checking :no}
+                             {:hostname "localhost"
+                              :username (username)
+                              :strict-host-key-checking :no}]
+                            {})]
+        (with-connection s
+            (ssh-exec (the-session s) "ls" "" "" {})))
+      "two hosts"))