module Net::SFTP
Net::SFTP
is a pure-Ruby module for programmatically interacting with a remote host via the SFTP
protocol (that’s SFTP
as in “Secure File Transfer Protocol” produced by the Secure Shell Working Group, not “Secure FTP” and certainly not “Simple FTP”).
See Net::SFTP#start for an introduction to the library. Also, see Net::SFTP::Session
for further documentation.
Public Class Methods
A convenience method for starting a standalone SFTP
session. It will start up an SSH
session using the given arguments (see the documentation for Net::SSH::Session for details), and will then start a new SFTP
session with the SSH
session. This will block until the new SFTP
is fully open and initialized before returning it.
sftp = Net::SFTP.start("localhost", "user") sftp.upload! "/local/file.tgz", "/remote/file.tgz"
If a block is given, it will be passed to the SFTP
session and will be called once the SFTP
session is fully open and initialized. When the block terminates, the new SSH
session will automatically be closed.
Net::SFTP.start("localhost", "user") do |sftp| sftp.upload! "/local/file.tgz", "/remote/file.tgz" end
Extra parameters can be passed:
-
The
Net::SSH
connection options (seeNet::SSH
for more information) -
The
Net::SFTP
connection options (only :version is supported, to let you set theSFTP
protocol version to be used)
# File lib/net/sftp.rb, line 35 def self.start(host, user, ssh_options={}, sftp_options={}, &block) session = Net::SSH.start(host, user, ssh_options) # We only use a single option here, but this leaves room for more later # without breaking the external API. version = sftp_options.fetch(:version, nil) sftp = Net::SFTP::Session.new(session, version, &block).connect! if block_given? sftp.loop session.close return nil end sftp rescue Object => anything begin session.shutdown! rescue ::Exception # swallow exceptions that occur while trying to shutdown end raise anything end
Public Instance Methods
Returns a Net::SFTP::Operations::Dir
instance, which can be used to conveniently iterate over and search directories on the remote server.
sftp.dir.glob("/base/path", "*/**/*.rb") do |entry| p entry.name end
See Net::SFTP::Operations::Dir
for a more detailed discussion of how to use this.
# File lib/net/sftp/session.rb, line 155 def dir @dir ||= Operations::Dir.new(self) end
Initiates a download from remote
to local
, asynchronously. This method will return a new Net::SFTP::Operations::Download
instance, and requires that the event loop be run in order for the download to progress. See Net::SFTP::Operations::Download
for a full discussion of how this method can be used.
download = sftp.download("/remote/path", "/local/path") download.wait
# File lib/net/sftp/session.rb, line 116 def download(remote, local, options={}, &block) Operations::Download.new(self, local, remote, options, &block) end
Identical to download
, but blocks until the download is complete. If local
is omitted, downloads the file to an in-memory buffer and returns the result as a string; otherwise, returns the Net::SFTP::Operations::Download
instance.
# File lib/net/sftp/session.rb, line 124 def download!(remote, local=nil, options={}, &block) require 'stringio' unless defined?(StringIO) destination = local || StringIO.new result = download(remote, destination, options, &block).wait local ? result : destination.string end
Returns an Net::SFTP::Operations::FileFactory
instance, which can be used to mimic synchronous, IO-like file operations on a remote file via SFTP
.
sftp.file.open("/path/to/file") do |file| while line = file.gets puts line end end
See Net::SFTP::Operations::FileFactory
and Net::SFTP::Operations::File
for more details.
# File lib/net/sftp/session.rb, line 142 def file @file ||= Operations::FileFactory.new(self) end
Identical to upload, but blocks until the upload is complete.
# File lib/net/sftp/session.rb, line 104 def upload!(local, remote = File.basename(local), options={}, &block) upload(local, remote, options, &block).wait end