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

start (host, user, ssh_options={}, sftp_options={}, &block)

Source

# 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

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 (see Net::SSH for more information)
The Net::SFTP connection options (only :version is supported, to let you set the SFTP protocol version to be used)

Public Instance Methods

dir ()

Source

# File lib/net/sftp/session.rb, line 155
def dir
  @dir ||= Operations::Dir.new(self)
end

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.

download (remote, local, options={}, &block)

Source

# File lib/net/sftp/session.rb, line 116
def download(remote, local, options={}, &block)
  Operations::Download.new(self, local, remote, options, &block)
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

download! (remote, local=nil, options={}, &block)

Source

# 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

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 ()

Source

# File lib/net/sftp/session.rb, line 142
def file
  @file ||= Operations::FileFactory.new(self)
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.

upload! (local, remote = File.basename(local), options={}, &block)

Source

# File lib/net/sftp/session.rb, line 104
def upload!(local, remote = File.basename(local), options={}, &block)
  upload(local, remote, options, &block).wait
end

Identical to upload, but blocks until the upload is complete.