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
# File lib/net/sftp.rb, line 30 def self.start(host, user, options={}, &block) session = Net::SSH.start(host, user, options) sftp = Net::SFTP::Session.new(session, &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 153 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 hos this method can be used.
download = sftp.download("/remote/path", "/local/path") download.wait
# File lib/net/sftp/session.rb, line 114 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 122 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 140 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 102 def upload!(local, remote = File.basename(local), options={}, &block) upload(local, remote, options, &block).wait end