1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
|
<html>
<head>
<title>Net::SFTP FAQ</title>
<style type="text/css">
a, a:visited, a:active {
color: #00F;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
.faq-list {
color: #000;
font-family: vera-sans, verdana, arial, sans-serif;
}
.faq-title {
background: #007;
color: #FFF;
font-family: vera-sans, verdana, arial, sans-serif;
padding-left: 1em;
padding-top: 0.5em;
padding-bottom: 0.5em;
font-weight: bold;
font-size: large;
border: 1px solid #000;
}
.faq-answer {
margin-left: 1em;
color: #000;
font-family: vera-sans, verdana, arial, sans-serif;
}
.faq-answer pre {
margin-left: 1em;
color: #000;
background: #FFE;
font-size: normal;
border: 1px dotted #CCC;
padding: 1em;
}
h1 {
background: #005;
color: #FFF;
font-family: vera-sans, verdana, arial, sans-serif;
padding-left: 1em;
padding-top: 1em;
padding-bottom: 1em;
font-weight: bold;
font-size: x-large;
border: 1px solid #00F;
}
</style>
</head>
<body>
<h1>Net::SFTP FAQ</h1>
<div class="faq-list">
<ul>
<li><a href='#2254408'>What is Net::SFTP?</a></li>
<li>How do I…
<ul>
<li>...connect to an <span class="caps">SFTP</span> server?
<ul>
<li><a href='#2254328'>I’d like to connect without first getting a Net::SSH connection…</a></li>
<li><a href='#2254288'>I already have an open Net::SSH connection…</a></li>
</ul>
</li>
<li>...upload data?
<ul>
<li><a href='#2254198'>I want to upload an entire file on disk…</a></li>
<li><a href='#2254138'>I want to upload bytes from a string or other object…</a></li>
</ul>
</li>
<li>...download data?
<ul>
<li><a href='#2254048'>I want to download directly to a local file…</a></li>
<li><a href='#2253998'>I want to download to a string in memory…</a></li>
<li><a href='#2253958'>I want to be notified of the progress of the download…</a></li>
</ul>
</li>
<li>...manage file permissions?
<ul>
<li><a href='#2253878'>I want to query a file’s permissions…</a></li>
<li><a href='#2253828'>I want to change a file’s permissions…</a></li>
<li><a href='#2253788'>I already have an open handle for the remote file…</a></li>
</ul>
</li>
<li>...manage directories?
<ul>
<li><a href='#2253688'>I want to query the contents of a directory…</a></li>
<li><a href='#2253648'>I want to create a directory…</a></li>
<li><a href='#2253608'>I want to remove a directory…</a></li>
</ul>
</li>
<li><a href='#2253538'>...delete a file?</a></li>
<li><a href='#2253498'>...rename a file?</a></li>
</ul>
</li>
</ul>
</div>
<a name='2254408'></a>
<div class='faq-title'>What is Net::SFTP?</div>
<div class='faq-answer'><p>Net::SFTP is a pure-Ruby implementation of the <span class="caps">SFTP</span> protocol. That’s
“SFTP” as in “Secure File Transfer Protocol”, as defined as an adjuct to the
<span class="caps">SSH</span> specification. <em>Not</em> “SFTP” as in “Secure <span class="caps">FTP</span>” (a <em>completely</em> different
beast). Nor is it an implementation of the “Simple File Transfer Protocol”
(which is in no way secure).</p></div>
<a name='2254328'></a>
<div class='faq-title'>How do I… ...connect to an <span class="caps">SFTP</span> server? I’d like to connect without first getting a Net::SSH connection…</div>
<div class='faq-answer'><p>Something like this:</p>
<code><pre>
require 'net/sftp'
Net::SFTP.start(host, user, password) do |sftp|
...
end
</pre></code>
<p><code>Net::SFTP.start</code> accepts the same parameters as <code>Net::SSH.start</code>,
so I’ll direct you to that documentation for all the particulars.</p></div>
<a name='2254288'></a>
<div class='faq-title'>How do I… ...connect to an <span class="caps">SFTP</span> server? I already have an open Net::SSH connection…</div>
<div class='faq-answer'><p>You can piggy-back an <span class="caps">SFTP</span> connection on an existing Net::SSH
connection, which can be useful if you’ve already got an <span class="caps">SSH</span>
connection that you’re using for port forwarding or whatever.</p>
<code><pre>
require 'net/ssh'
require 'net/sftp'
Net::SSH.start(host, user, password) do |ssh|
...
ssh.sftp.connect do |sftp|
...
end
...
end
</pre></code></div>
<a name='2254198'></a>
<div class='faq-title'>How do I… ...upload data? I want to upload an entire file on disk…</div>
<div class='faq-answer'><p>Assuming you already have an <span class="caps">SFTP</span> connection:</p>
<code><pre>
sftp.put_file "/path/to/local.file", "/path/to/remote.file"
</pre></code></div>
<a name='2254138'></a>
<div class='faq-title'>How do I… ...upload data? I want to upload bytes from a string or other object…</div>
<div class='faq-answer'><p>Assuming you already have an <span class="caps">SFTP</span> connection, and your data is stored
in a string named <code>data</code>:</p>
<code><pre>
sftp.open_handle("/path/to/remote.file", "w") do |handle|
result = sftp.write(handle, data)
puts result.code # the result of the operation
end
</pre></code>
<p>If (for whatever reason) you’d rather not use blocks, you can do
without, but be sure to call <code>close_handle</code> when you’re done:</p>
<code><pre>
handle = sftp.open_handle("/path/to/remote.file", "w")
result = sftp.write(handle, data)
puts result.code # the result of the operation
sftp.close_handle(handle)
</pre></code></div>
<a name='2254048'></a>
<div class='faq-title'>How do I… ...download data? I want to download directly to a local file…</div>
<div class='faq-answer'><p>Assuming you already have an <span class="caps">SFTP</span> connection:</p>
<code><pre>
sftp.get_file "/path/to/remote.file", "/path/to/local.file"
</pre></code></div>
<a name='2253998'></a>
<div class='faq-title'>How do I… ...download data? I want to download to a string in memory…</div>
<div class='faq-answer'><p>Assuming you already have an <span class="caps">SFTP</span> connection:</p>
<code><pre>
data = nil
sftp.open_handle("/path/to/remote.file") do |handle|
data = sftp.read(handle)
end
</pre></code></div>
<a name='2253958'></a>
<div class='faq-title'>How do I… ...download data? I want to be notified of the progress of the download…</div>
<div class='faq-answer'><p>You can specify both a “chunk size” and a “progress callback”. The
callback will be invoked for every “chunk size” bytes that are
received:</p>
<code><pre>
sftp.open_handle("/path/to/remote.file") do |handle|
begin
STDOUT.sync = true
data = sftp.read(handle, :chunk_size => 4096,
:progress_callback => lambda { |data| print "." })
puts
ensure
STDOUT.sync = false
end
end
</pre></code></div>
<a name='2253878'></a>
<div class='faq-title'>How do I… ...manage file permissions? I want to query a file’s permissions…</div>
<div class='faq-answer'><p>File permissions are one of the <code>stat</code> attributes of files and
directories:</p>
<code><pre>
p sftp.stat("/path/to/remote.file").permissions
</pre></code></div>
<a name='2253828'></a>
<div class='faq-title'>How do I… ...manage file permissions? I want to change a file’s permissions…</div>
<div class='faq-answer'><p>Just use <code>setstat</code> to change the permissions of an existing file:</p>
<code><pre>
sftp.setstat("/path/to/remote.file", :permissions => 0644)
</pre></code></div>
<a name='2253788'></a>
<div class='faq-title'>How do I… ...manage file permissions? I already have an open handle for the remote file…</div>
<div class='faq-answer'><p>If you have a handle for the remote file, you can use <code>fstat</code> and
<code>fsetstat</code> to query and set the permissions:</p>
<code><pre>
sftp.open_handle("/path/to/remote.file") do |handle|
permissions = sftp.fstat(handle)
sftp.fsetstat(handle, :permissions => permissions | 0444)
end
</pre></code></div>
<a name='2253688'></a>
<div class='faq-title'>How do I… ...manage directories? I want to query the contents of a directory…</div>
<div class='faq-answer'><p>You query the contents of a directory by calling <code>opendir</code> to obtain
a handle to the directory, and then using <code>readdir</code> on the handle to
obtain a list of directory entries. Be sure to close the handle when
you’re done:</p>
<code><pre>
handle = sftp.opendir("/usr/lib")
items = sftp.readdir(handle)
items.each do |item|
puts item.filename
puts item.longname
p item.attributes # permissions, atime, etc.
end
sftp.close_handle(handle)
</pre></code></div>
<a name='2253648'></a>
<div class='faq-title'>How do I… ...manage directories? I want to create a directory…</div>
<div class='faq-answer'><p>Use <code>mkdir</code>:</p>
<code><pre>
sftp.mkdir("/path/to/remote/dir", :permissions => 0500)
</pre></code></div>
<a name='2253608'></a>
<div class='faq-title'>How do I… ...manage directories? I want to remove a directory…</div>
<div class='faq-answer'><p>Use <code>rmdir</code>:</p>
<code><pre>
sftp.rmdir("/path/to/remote/dir")
</pre></code></div>
<a name='2253538'></a>
<div class='faq-title'>How do I… ...delete a file?</div>
<div class='faq-answer'><p>Use <code>remove</code>:</p>
<code><pre>
sftp.remove("/path/to/remote.file")
</pre></code></div>
<a name='2253498'></a>
<div class='faq-title'>How do I… ...rename a file?</div>
<div class='faq-answer'><p>Use <code>rename</code>:</p>
<code><pre>
sftp.rename("/path/to/remote.file", "/path/to/new.file")
</pre></code>
<p>It should be noted that <code>rename</code> is only supported by version 2 or
later of the <span class="caps">SFTP</span> protocol, so if you’re using an older <span class="caps">SFTP</span> server you
might not be able to use this operation.</p></div>
</body></html>
|
