Merge branch 'feature/add-public-key-args' into develop

Author: hugoduncan

.gitignore

@@ -5,3 +5,5 @@ lib
 classes
 autodoc/**
 doc/**
+.lein-deps-sum
+.lein-failures

README.md

@@ -1,62 +1,69 @@
 # clj-ssh
 
-SSH in clojure.  Uses jsch.  Provides a ssh function that tries to look similar
-to clojure.contrib.shell/sh.
+SSH in clojure.  Uses jsch.
 
 ## Usage
 
-The top level namespace is `clj-ssh.ssh`
+### REPL
+
+The `clj-ssh.cli` namespace provides some functions for ease of use at the REPL.
 
     (use 'clj-ssh.ssh)
 
-There is a simple `ssh` function, which by default, will try and use a id_rsa
-key in your $HOME/.ssh directory.
+There is a simple `ssh` function, which by default, will use the system
+ssh-agent.
 
     (ssh "hostname" "ls")
 
 Strict host key checking can be turned off.
 
     (default-session-options {:strict-host-key-checking :no})
 
-By default, your current username and id_rsa key are used.  If your key has a
-passphrase, and you are on OSX, then you should be asked for access to your
-keychain.  If you are on any other OS, you will need to explicitly add your key
-to the clj-ssh's ssh-agent with the appropriate add-identity call.
+By default, your current username is used.  If your key has a passphrase, and
+you are on OSX, then you should be asked for access to your keychain.  If you
+are on any other OS without a ssh-agent, you will need to explicitly add your
+key to the clj-ssh's ssh-agent with the appropriate add-identity call.
 
-More advance usage is possible.
+SFTP is supported:
 
-    (with-ssh-agent []
-      (add-identity "/user/name/.ssh/id_dsa")
-      (let [session (session "localhost" :strict-host-key-checking :no)]
-        (with-connection session
-          (let [result (ssh session :in "echo hello" :result-map true)]
-            (println (result :out)))
-          (let [result (ssh session "/bin/bash" "-c" "ls" "/")]
-            (println (second result))))))
+```clj
+(sftp "hostname" :put "/from/this/path" "to/this/path")
+```
 
-SFTP is supported, both with a simple interface,
+Note that any sftp commands that change the state of the sftp session (such as
+cd) do not work with the simplified interface, as a new session is created each
+time.
 
-     (sftp "hostname" :put "/from/this/path" "to/this/path")
+### Non REPL
 
-as well as more advanced usage.
+The `clj-ssh.ssh` namespace should be using SSH from functional code.
 
-    (with-ssh-agent []
-      (let [session (session "localhost" :strict-host-key-checking :no)]
-        (with-connection session
-          (let [channel (ssh-sftp session)]
-            (with-connection channel
-              (sftp channel :cd "/remote/path")
-              (sftp channel :put "/some/file" "filename"))))))
+```clj
+(let [agent (ssh-agent {:use-system-ssh-agent false})]
+  (add-identity agent "/user/name/.ssh/id_rsa")
+  (let [session (session agent "localhost" {:strict-host-key-checking :no})]
+    (with-connection session
+      (let [result (ssh session {:in "echo hello"})]
+        (println (result :out)))
+      (let [result (ssh session "/bin/bash" "-c" "ls" "/")]
+        (println (second result))))))
+```
 
-Note that any sftp commands that change the state of the sftp session (such as
-cd) do not work with the simplified interface, as a new session is created each
-time.
+```clj
+(let [agent (ssh-agent {})]
+  (let [session (session agent "localhost" {:strict-host-key-checking :no})]
+    (with-connection session
+      (let [channel (ssh-sftp session)]
+        (with-channel-connection channel
+          (sftp channel :cd "/remote/path")
+          (sftp channel :put "/some/file" "filename"))))))
+```
 
 SSH tunneling is also supported:
 
 ```clj
-    (with-ssh-agent []
-      (let [session (session "localhost" :strict-host-key-checking :no)]
+    (let [agent (ssh-agent {:use-system-ssh-agent false})]
+      (let [session (session agent "localhost" :strict-host-key-checking :no)]
         (with-connection session
           (with-local-port-forward [session 8080 80]
             (comment do something with port 8080 here)))))
@@ -69,11 +76,9 @@ SSH tunneling is also supported:
 
 ## FAQ
 
-Q: Why doesn't clj-ssh integrate with the OS's ssh agent?
-
-A: Java has no access to the Unix domain socket used by the system ssh-agent.
-
-Q: What does  "4: Failure @ com.jcraft.jsch.ChannelSftp.throwStatusError(ChannelSftp.java:2289)" during an sftp transfer signify?
+Q: What does
+"4: Failure @ com.jcraft.jsch.ChannelSftp.throwStatusError(ChannelSftp.java:2289)"
+during an sftp transfer signify?
 
 A: Probably a disk full, or permission error.
 
@@ -82,7 +87,7 @@ A: Probably a disk full, or permission error.
 Via [clojars](http://clojars.org) and
 [Leiningen](http://github.com/technomancy/leiningen).
 
-    :dependencies [clj-ssh "0.3.3"]
+    :dependencies [clj-ssh "0.4.0-SNAPSHOT"]
 
 or your favourite maven repository aware tool.
 

pom.xml

@@ -1,10 +1,19 @@
-(defproject clj-ssh "0.3.2-SNAPSHOT"
+(defproject clj-ssh "0.4.0-SNAPSHOT"
   :description "Library for using SSH from clojure."
-  :dependencies [[org.clojure/clojure "1.2.0"]
+  :url "https://github.com/hugoduncan/clj-ssh"
+  :dependencies [[org.clojure/clojure "1.2.1"]
                  [org.clojure/tools.logging "0.1.2"]
-                 [slingshot "0.2.0"]
-                 [com.jcraft/jsch "0.1.44-1"]]
-  :dev-dependencies [[log4j/log4j "1.2.14"]]
+                 [jsch-agent-proxy "0.0.4"]
+                 [jsch-agent-proxy/jsch-agent-proxy-jna "0.0.4"]
+                 [slingshot "0.10.2"]
+                 [com.jcraft/jsch "0.1.48"]]
+  :dev-dependencies [[org.slf4j/slf4j-api "1.6.1"]
+                     [ch.qos.logback/logback-core "1.0.0"]
+                     [ch.qos.logback/logback-classic "1.0.0"]]
+  :profiles {:dev {:dependencies [[org.slf4j/slf4j-api "1.6.1"]
+                                  [ch.qos.logback/logback-core "1.0.0"]
+                                  [ch.qos.logback/logback-classic "1.0.0"]
+                                  [codox-md "0.1.0"]]}}
   :multi-deps {"slingshot-0.10.1" [[slingshot "0.10.1"]
                                    [org.clojure/clojure "1.2.1"]]
                "clojure-1.2.1" [[slingshot "0.10.1"]
@@ -14,5 +23,8 @@
                "clojure-1.4.0" [[slingshot "0.10.1"]
                                 [org.clojure/clojure "1.4.0-beta1"]]}
   :codox {:writer codox-md.writer/write-docs
-          :version "0.3"
-          :output-dir "doc/api/0.3"})
+          :version "0.4"
+          :output-dir "doc/api/0.4"
+          :exclude [clj-ssh.agent clj-ssh.reflect clj-ssh.keychain]}
+  :license {:name "Eclipse Public License"
+            :url "http://www.eclipse.org/legal/epl-v10.html"})