DOCSEARCHbyAlgolia
Submit Docs

Net::SFTP

repository·master·Indexed 43 days ago

https://github.com/net-ssh/net-sftp

A pure-Ruby implementation of the SFTP protocol (versions 1-6) providing secure file transfers, directory manipulation, and remote file I/O over SSH. It includes a high-level API via Net::SFTP::Session and a synchronous, IO-like interface through Net::SFTP::Operations::File for reading, writing, and seeking remote files.

Tokens
7.2K
Snippets
25
Records
34
Agent score
55%

What's inside Net::SFTP

  1. Basic usage of Net::SFTP

    master

    Use Net::SFTP.start to establish a session. The block provides an sftp session object used to perform file transfers, directory operations, and file I/O.

    Common operations include:

    • upload!(local, remote): Upload a file or directory.
    • download!(remote, local): Download a file or directory.
    • download!(remote): Download remote data directly to a buffer.
    • mkdir!(path): Create a directory.
    • dir.foreach(path): Iterate through directory entries.
    require 'net/sftp'

Net::SFTP.start('host', 'username', :password => 'password') do |sftp|
    # upload a file or directory to the remote host
    sftp.upload!("/path/to/local", "/path/to/remote")

    # download a file or directory from the remote host
    sftp.download!("/path/to/remote", "/path/to/local")

    # grab data off the remote host directly to a buffer
    data = sftp.download!("/path/to/remote")

    # create a directory
    sftp.mkdir! "/path/to/directory"

    # list the entries in a directory
    sftp.dir.foreach("/path/to/directory") do |entry|
      puts entry.longname
    end
end

  2. Install Net::SFTP via gem

    master

    You can install the net-sftp gem using the standard RubyGems command. Note that you may require sudo privileges depending on your environment.

    Requirements:

    • Net::SSH 2 must be installed.
    gem install net-sftp

  3. Install Net::SFTP from source

    master

    If you prefer not to use RubyGems, you can install the package manually from a tarball:

    1. Extract the tarball.
    2. Navigate into the directory.
    3. Run the configuration script.
    4. Run the installation script (may require sudo).
    tar xzf net-ssh-*.tgz
cd net-ssh-*
ruby setup.rb config
ruby setup.rb install

  4. Verify Net::SFTP gem signature for high security

    master

    To ensure the integrity of the installed code, you can verify the gem's signature by adding the project's public key as a trusted certificate before installation.

    1. Download the public certificate.
    2. Add it to your trusted certificates using gem cert.
    3. Install the gem using the -P HighSecurity flag.

    If you skip the certificate step, you may encounter a "Couldn't verify data signature" error.

    # Add the public key as a trusted certificate (only needs to be done once)
$ curl -O https://raw.githubusercontent.com/net-ssh/net-sftp/master/net-sftp-public_cert.pem
$ gem cert --add net-sftp-public_cert.pem

# Install the gem with high security
$ gem install net-sftp -P HighSecurity

  5. Use Net::SFTP::Session instead of Net::SFTP::Protocol::V04::Base

    master

    The Net::SFTP::Protocol::V04::Base class is a low-level driver for the SFTP version 4 protocol. Its methods are non-blocking and return immediately, requiring the underlying SSH event loop to be running to process server responses.

    You should almost certainly never use this driver directly. Instead, use the high-level Net::SFTP::Session interface for all SFTP operations.

  6. Use Net::SFTP::Operations::File for synchronous remote file IO

    master

    The Net::SFTP::Operations::File class provides a synchronous (blocking), IO-like interface for interacting with remote files. It wraps an SFTP file handle and allows you to perform standard file operations such as reading, writing, and seeking, similar to Ruby's built-in File or IO classes.

    To use this, you typically do not instantiate the class directly. Instead, you use the Net::SFTP::Session#file factory to open a file, which returns a File wrapper.

    Key Capabilities:

    • Reading: Use read(n), gets(sep_or_limit, limit), or readline to consume data.
    • Writing: Use write(data), puts(*items), or print(*items) to send data to the remote host.
    • Navigation: Use pos= to seek to a specific offset or rewind to return to the start of the file.
    • Metadata: Use size to get the file size or stat to get the remote file attributes.
    # A wrapper is usually created via the Net::SFTP::Session#file factory:
file = sftp.file.open("/path/to/remote")
puts file.gets
file.close

  7. Use Net::SFTP::Session instead of Net::SFTP::Protocol::V01::Base

    master

    The Net::SFTP::Protocol::V01::Base class is a low-level driver for the SFTP version 1 protocol. Its methods are non-blocking and return immediately, requiring the SSH event loop to be running to handle server responses.

    You should almost certainly never use this driver directly. Instead, use the Net::SFTP::Session class, which provides the recommended high-level interface for interacting with SFTP servers.

  8. Read and write remote files using pseudo-IO

    master

    Net::SFTP provides a pseudo-IO interface via sftp.file.open to interact with remote files using standard Ruby IO-like methods (e.g., puts, gets).

    • Writing: Open a file with mode "w".
    • Reading: Open a file with mode "r".
    require 'net/sftp'

Net::SFTP.start('host', 'username', :password => 'password') do |sftp|
  # open and write to a pseudo-IO for a remote file
  sftp.file.open("/path/to/remote", "w") do |f|
    f.puts "Hello, world!\n"
  end

  # open and read from a pseudo-IO for a remote file
  sftp.file.open("/path/to/remote", "r") do |f|
    puts f.gets
  end
end

  9. Retrieve file status with stat, lstat, and fstat

    master

    The V04 protocol implementation provides methods to request file status. These methods are non-blocking.

    If flags is not provided, they default to a comprehensive set of attributes including size, permissions, access/create/modify times, ACL, owner/group, subsecond times, and extended attributes.

    • stat(path, flags=nil): Sends an FXP_STAT packet for the given path.
    • lstat(path, flags=nil): Sends an FXP_LSTAT packet for the given path (useful for symbolic links).
    • fstat(handle, flags=nil): Sends an FXP_FSTAT packet for the given file handle.

    Default flags are defined by Net::SFTP::Protocol::V04::Attributes::DEFAULT_FLAGS (composed of F_SIZE, F_PERMISSIONS, F_ACCESSTIME, F_CREATETIME, F_MODIFYTIME, F_ACL, F_OWNERGROUP, F_SUBSECOND_TIMES, and F_EXTENDED).

  10. Seek and manage file state in Net::SFTP::Operations::File

    master

    You can manipulate the file pointer and manage the lifecycle of the remote file handle using these methods:

    • pos=(offset): Repositions the file pointer to the given offset (relative to the start of the file). This also resets the EOF flag and clears the internal buffer.
    • rewind: Resets the file position to the beginning of the file (pos = 0).
    • close: Closes the underlying remote file handle and sets the handle to nil. Subsequent operations on the object will fail.
    • stat: Performs an fstat operation on the handle and returns the attribute object (e.g., Net::SFTP::Protocol::V01::Attributes).
    • size: Returns the size of the file via a stat operation.

  11. Low-level SFTP v1 protocol operations

    master

    The Net::SFTP::Protocol::V01::Base class implements the following low-level SFTP v1 protocol operations. Note that these are non-blocking and require an active SSH event loop.

    File and Directory Management

    • open(path, flags, options): Sends an FXP_OPEN packet. flags can be an integer (combination of IO constants) or a string (e.g., 'r', 'w', 'a'). options is a hash used to construct attributes.
    • close(handle): Sends an FXP_CLOSE packet for the given handle.
    • remove(filename): Sends an FXP_REMOVE packet to delete a file.
    • mkdir(path, attrs): Sends an FXP_MKDIR packet to create a directory with specific attrs.
    • rmdir(path): Sends an FXP_RMDIR packet to delete a directory.
    • realpath(path): Sends an FXP_REALPATH packet to canonicalize a path.

    File Attributes and Status

    • stat(path, flags=nil): Sends an FXP_STAT packet (follows symbolic links).
    • lstat(path, flags=nil): Sends an FXP_LSTAT packet (does NOT follow symbolic links).
    • fstat(handle, flags=nil): Sends an FXP_FSTAT packet for a file identified by handle.
    • setstat(path, attrs): Sends an FXP_SETSTAT packet to update attributes for a path.
    • fsetstat(handle, attrs): Sends an FXP_FSETSTAT packet to update attributes for a handle.

    Data Transfer

    • read(handle, offset, length): Sends an FXP_READ packet to read length bytes from offset.
    • write(handle, offset, data): Sends an FXP_WRITE packet to write data at offset.

    Directory Operations

    • opendir(path): Sends an FXP_OPENDIR packet to get a handle for a directory.
    • readdir(handle): Sends an FXP_READDIR packet to read directory entries using a directory handle.

  12. Handle SFTP responses with Net::SFTP::Response

    master

    When performing asynchronous operations or using Net::SFTP::Request#wait, you receive a Net::SFTP::Response object. This object encapsulates the result of a remote server request, including its success status, associated data (like file handles), and error codes.

    Key methods:

    • ok?: Returns true if the status code is FX_OK.
    • eof?: Returns true if the status code is FX_EOF.
    • [] (key): Retrieves request-specific data from the response (e.g., :handle or attribute information). The key is converted to a symbol.
    • code: Returns the numeric status code (one of the FX_* constants).
    • message: Returns the textual message provided by the server.
    • to_s: Returns a string description including the status name and code.
    sftp.open("/path/to/file") do |response|
  p response.ok?
  p response[:handle]
end