Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 145 lines (104 sloc) 4.138 kb
e49b2ad @hugoduncan Initial commit
authored
1 # clj-ssh
2
128ef3a @hugoduncan Split out clj-ssh.cli
authored
3 SSH in clojure. Uses jsch.
e49b2ad @hugoduncan Initial commit
authored
4
5 ## Usage
6
128ef3a @hugoduncan Split out clj-ssh.cli
authored
7 ### REPL
8
9 The `clj-ssh.cli` namespace provides some functions for ease of use at the REPL.
e49b2ad @hugoduncan Initial commit
authored
10
d912506 @hugoduncan Fix ns and escaping in readme
authored
11 ```clj
12 (use 'clj-ssh.cli)
13 ```
e49b2ad @hugoduncan Initial commit
authored
14
d912506 @hugoduncan Fix ns and escaping in readme
authored
15 Use `ssh` to execute a command, say `ls`, on a remote host "my-host",
e49b2ad @hugoduncan Initial commit
authored
16
d912506 @hugoduncan Fix ns and escaping in readme
authored
17 ```clj
18 (ssh "my-host" "ls")
19 => {:exit 0 :out "file1\nfile2\n" :err "")
20 ```
e49b2ad @hugoduncan Initial commit
authored
21
adbca58 @hugoduncan Improve cli doc
authored
22 By default this will use the system ssh-agent to obtain your ssh keys, and it
23 uses your current username, but this can be specified:
11972f6 @hugoduncan Added documentation and test for default-session-options
authored
24
d912506 @hugoduncan Fix ns and escaping in readme
authored
25 ```clj
26 (ssh "my-host" "ls" :username "remote-user")
27 => {:exit 0 :out "file1\nfile2\n" :err "")
28 ```
11972f6 @hugoduncan Added documentation and test for default-session-options
authored
29
adbca58 @hugoduncan Improve cli doc
authored
30 Strict host key checking can be turned off:
e1bcf0b @hugoduncan Update readme with note on passphrases, and on system ssh-agent integ…
authored
31
d912506 @hugoduncan Fix ns and escaping in readme
authored
32 ```clj
33 (default-session-options {:strict-host-key-checking :no})
34 ```
e49b2ad @hugoduncan Initial commit
authored
35
adbca58 @hugoduncan Improve cli doc
authored
36 SFTP is also supported. For example, to copy a local file to a remote host
d912506 @hugoduncan Fix ns and escaping in readme
authored
37 "my-host":
adbca58 @hugoduncan Improve cli doc
authored
38
d912506 @hugoduncan Fix ns and escaping in readme
authored
39 ```clj
40 (sftp "my-host" :put "/from/this/path" "to/this/path")
41 ```
e49b2ad @hugoduncan Initial commit
authored
42
128ef3a @hugoduncan Split out clj-ssh.cli
authored
43 Note that any sftp commands that change the state of the sftp session (such as
44 cd) do not work with the simplified interface, as a new session is created each
45 time.
8afc309 @hugoduncan Added sftp support
authored
46
adbca58 @hugoduncan Improve cli doc
authored
47 If your key has a passphrase, you will need to explicitly add your key either to
48 the system's ssh-agent, or to clj-ssh's ssh-agent with the appropriate
49 `add-identity` call.
50
128ef3a @hugoduncan Split out clj-ssh.cli
authored
51 ### Non REPL
8afc309 @hugoduncan Added sftp support
authored
52
f64186f @hugoduncan Add some description of using the system ssh-agent
authored
53 The `clj-ssh.ssh` namespace should be used for SSH from functional code.
8afc309 @hugoduncan Added sftp support
authored
54
128ef3a @hugoduncan Split out clj-ssh.cli
authored
55 ```clj
f64186f @hugoduncan Add some description of using the system ssh-agent
authored
56 (let [agent (ssh-agent {})]
128ef3a @hugoduncan Split out clj-ssh.cli
authored
57 (let [session (session agent "localhost" {:strict-host-key-checking :no})]
58 (with-connection session
59 (let [result (ssh session {:in "echo hello"})]
60 (println (result :out)))
5654e50 @hugoduncan Add text explaining that :cmd exec's a process without a shell
authored
61 (let [result (ssh session {:cmd "ls"}]
f64186f @hugoduncan Add some description of using the system ssh-agent
authored
62 (println (second result)))))))
128ef3a @hugoduncan Split out clj-ssh.cli
authored
63 ```
8afc309 @hugoduncan Added sftp support
authored
64
5654e50 @hugoduncan Add text explaining that :cmd exec's a process without a shell
authored
65 The above example shows using `:in` to pass commands to a shell, and using
66 `:cmd` to exec a command without a shell. When using `:cmd` you can still pass
67 a stream or a string to `:in` to be used as the process' standard input.
68
f64186f @hugoduncan Add some description of using the system ssh-agent
authored
69 By default, the system ssh-agent is used, which means the ssh keys you use at
70 the command line level should automatically be picked up (this should also work
71 with `pageant` on windows).
72
73 You can forward the ssh-agent, which allows you to run ssh based commands on the
74 remote host using the credentials in your local ssh-agent:
75
76 ```clj
77 (let [agent (ssh-agent {})]
78 (let [session (session agent "localhost" {:strict-host-key-checking :no})]
79 (with-connection session
80 (let [result (ssh session {:in "ssh somehost ls" :agent-forwarding true})]
81 (println (result :out))))))
82 ```
83
84 If you prefer not to use the system ssh-agent, or one is not running on your
85 system, then a local, isolated ssh-agent can be used.
86
87 ```clj
88 (let [agent (ssh-agent {:use-system-ssh-agent false})]
89 (add-identity agent "/user/name/.ssh/id_rsa")
90 (let [session (session agent "localhost" {:strict-host-key-checking :no})]
91 (with-connection session
92 (let [result (ssh session {:in "echo hello"})]
93 (println (result :out)))))
94 ```
95
96 SFTP is supported:
97
128ef3a @hugoduncan Split out clj-ssh.cli
authored
98 ```clj
99 (let [agent (ssh-agent {})]
100 (let [session (session agent "localhost" {:strict-host-key-checking :no})]
101 (with-connection session
102 (let [channel (ssh-sftp session)]
103 (with-channel-connection channel
77f6eb1 @hugoduncan Fix README and docstring for options map in ssh/sftp
authored
104 (sftp channel {} :cd "/remote/path")
105 (sftp channel {} :put "/some/file" "filename"))))))
128ef3a @hugoduncan Split out clj-ssh.cli
authored
106 ```
8afc309 @hugoduncan Added sftp support
authored
107
1d99321 @kzar Added SSH tunneling.
kzar authored
108 SSH tunneling is also supported:
109
7ccb4bb @hugoduncan Fix documentation for with-local-port-forward
authored
110 ```clj
f64186f @hugoduncan Add some description of using the system ssh-agent
authored
111 (let [agent (ssh-agent {})]
63bcd52 @hugoduncan Fix map argument in README
authored
112 (let [session (session agent "localhost" {:strict-host-key-checking :no})]
7ccb4bb @hugoduncan Fix documentation for with-local-port-forward
authored
113 (with-connection session
114 (with-local-port-forward [session 8080 80]
115 (comment do something with port 8080 here)))))
116 ```
1d99321 @kzar Added SSH tunneling.
kzar authored
117
67179d0 @hugoduncan Add link to marginalia output
authored
118 ## Documentation
119
0795a31 @hugoduncan Update API doc links in README
authored
120 [Annotated source](http:/hugoduncan.github.com/clj-ssh/api/0.4/uberdoc.html).
121 [API](http:/hugoduncan.github.com/clj-ssh/api/0.4/index.html).
67179d0 @hugoduncan Add link to marginalia output
authored
122
dca0877 @hugoduncan Updated 1.2 compatability. Added FAQ
authored
123 ## FAQ
124
128ef3a @hugoduncan Split out clj-ssh.cli
authored
125 Q: What does
126 "4: Failure @ com.jcraft.jsch.ChannelSftp.throwStatusError(ChannelSftp.java:2289)"
127 during an sftp transfer signify?
dca0877 @hugoduncan Updated 1.2 compatability. Added FAQ
authored
128
129 A: Probably a disk full, or permission error.
8afc309 @hugoduncan Added sftp support
authored
130
e49b2ad @hugoduncan Initial commit
authored
131 ## Installation
132
8f9a3eb @hugoduncan Update pom, readme and release notes for release
authored
133 Via [clojars](http://clojars.org) and
e49b2ad @hugoduncan Initial commit
authored
134 [Leiningen](http://github.com/technomancy/leiningen).
135
18a9e37 @hugoduncan Updated version, release notes and readme for 0.4.1
authored
136 :dependencies [clj-ssh "0.4.1"]
8f9a3eb @hugoduncan Update pom, readme and release notes for release
authored
137
138 or your favourite maven repository aware tool.
139
e49b2ad @hugoduncan Initial commit
authored
140 ## License
141
2c844e2 @hugoduncan Updated release notes and readme for 0.3.2
authored
142 Copyright © 2012 Hugo Duncan
e49b2ad @hugoduncan Initial commit
authored
143
2c844e2 @hugoduncan Updated release notes and readme for 0.3.2
authored
144 Licensed under [EPL](http://www.eclipse.org/legal/epl-v10.html)
Something went wrong with that request. Please try again.