Class: Net::SCP

Class | Net::SCP
In: | lib/net/scp/download.rb lib/net/scp/errors.rb lib/net/scp/upload.rb lib/net/scp/version.rb lib/net/scp.rb lib/net/scp/download.rb lib/net/scp/errors.rb lib/net/scp/upload.rb lib/net/scp/version.rb lib/net/scp.rb
Parent: | Object

Net::SCP implements the SCP (Secure CoPy) client protocol, allowing Ruby programs to securely and programmatically transfer individual files or entire directory trees to and from remote servers. It provides support for multiple simultaneous SCP copies working in parallel over the same connection, as well as for synchronous, serial copies.

Basic usage:

      require 'net/scp'

      Net::SCP.start("remote.host", "username", :password => "passwd") do |scp|
        # synchronous (blocking) upload; call blocks until upload completes
        scp.upload! "/local/path", "/remote/path"

        # asynchronous upload; call returns immediately and requires SSH
        # event loop to run
        channel = scp.upload("/local/path", "/remote/path")
        channel.wait
      end

Net::SCP also provides an open-uri tie-in, so you can use the Kernel#open method to open and read a remote file:

      # if you just want to parse SCP URL's:
      require 'uri/scp'
      url = URI.parse("scp://user@remote.host/path/to/file")

      # if you want to read from a URL voa SCP:
      require 'uri/open-scp'
      puts open("scp://user@remote.host/path/to/file").read

Lastly, Net::SCP adds a method to the Net::SSH::Connection::Session class, allowing you to easily grab a Net::SCP reference from an existing Net::SSH session:

      require 'net/ssh'
      require 'net/scp'

      Net::SSH.start("remote.host", "username", :password => "passwd") do |ssh|
        ssh.scp.download! "/remote/path", "/local/path"
      end

## Progress Reporting

By default, uploading and downloading proceed silently, without any outword indication of their progress. For long running uploads or downloads (and especially in interactive environments) it is desirable to report to the user the progress of the current operation.

To receive progress reports for the current operation, just pass a block to upload or download (or one of their variants):

      scp.upload!("/path/to/local", "/path/to/remote") do |ch, name, sent, total|
        puts "#{name}: #{sent}/#{total}"
      end

Whenever a new chunk of data is recieved for or sent to a file, the callback will be invoked, indicating the name of the file (local for downloads, remote for uploads), the number of bytes that have been sent or received so far for the file, and the size of the file.

### Methods

download download download! download! download! download! new new start start upload upload upload! upload! upload! upload!

### Included Modules

Net::SSH::Loggable Upload Download Net::SSH::Loggable Upload Download

### Classes and Modules

Module Net::SCP::Download
Module Net::SCP::Upload
Class Net::SCP::Error
Class Net::SCP::Version

### Attributes

session | [R] | The underlying Net::SSH session that acts as transport for the SCP packets.
session | [R] | The underlying Net::SSH session that acts as transport for the SCP packets.

### Public Class methods

download!(host, username, remote, local=nil, options={}, &progress)

Starts up a new SSH connection using the `host` and `username` parameters, instantiates a new SCP session on top of it, and then begins a download from `remote` to `local`. If the `options` hash includes an :ssh key, the value for that will be passed to the SSH connection as options (e.g., to set the password, etc.). All other options are passed to the download! method. If a block is given, it will be used to report progress (see "Progress Reporting", under Net::SCP).

[Source]

         # File lib/net/scp.rb, line 232
    232:     def self.download!(host, username, remote, local=nil, options={}, &progress)
    233:       options = options.dup
    234:       start(host, username, options.delete(:ssh) || {}) do |scp|
    235:         return scp.download!(remote, local, options, &progress)
    236:       end
    237:     end

download!(host, username, remote, local=nil, options={}, &progress)

Starts up a new SSH connection using the `host` and `username` parameters, instantiates a new SCP session on top of it, and then begins a download from `remote` to `local`. If the `options` hash includes an :ssh key, the value for that will be passed to the SSH connection as options (e.g., to set the password, etc.). All other options are passed to the download! method. If a block is given, it will be used to report progress (see "Progress Reporting", under Net::SCP).

[Source]

         # File lib/net/scp.rb, line 232
    232:     def self.download!(host, username, remote, local=nil, options={}, &progress)
    233:       options = options.dup
    234:       start(host, username, options.delete(:ssh) || {}) do |scp|
    235:         return scp.download!(remote, local, options, &progress)
    236:       end
    237:     end

new(session)

Creates a new Net::SCP session on top of the given Net::SSH `session` object.

[Source]

         # File lib/net/scp.rb, line 245
    245:     def initialize(session)
    246:       @session = session
    247:       self.logger = session.logger
    248:     end

new(session)

Creates a new Net::SCP session on top of the given Net::SSH `session` object.

[Source]

         # File lib/net/scp.rb, line 245
    245:     def initialize(session)
    246:       @session = session
    247:       self.logger = session.logger
    248:     end

start(host, username, options={}) {|scp| ...}

Starts up a new SSH connection and instantiates a new SCP session on top of it. If a block is given, the SCP session is yielded, and the SSH session is closed automatically when the block terminates. If no block is given, the SCP session is returned.

[Source]

         # File lib/net/scp.rb, line 195
    195:     def self.start(host, username, options={})
    196:       session = Net::SSH.start(host, username, options)
    197:       scp = new(session)
    198:
    199:       if block_given?
    200:         begin
    201:           yield scp
    202:           session.loop
    203:         ensure
    204:           session.close
    205:         end
    206:       else
    207:         return scp
    208:       end
    209:     end

start(host, username, options={}) {|scp| ...}

Starts up a new SSH connection and instantiates a new SCP session on top of it. If a block is given, the SCP session is yielded, and the SSH session is closed automatically when the block terminates. If no block is given, the SCP session is returned.

[Source]

         # File lib/net/scp.rb, line 195
    195:     def self.start(host, username, options={})
    196:       session = Net::SSH.start(host, username, options)
    197:       scp = new(session)
    198:
    199:       if block_given?
    200:         begin
    201:           yield scp
    202:           session.loop
    203:         ensure
    204:           session.close
    205:         end
    206:       else
    207:         return scp
    208:       end
    209:     end

upload!(host, username, local, remote, options={}, &progress)

Starts up a new SSH connection using the `host` and `username` parameters, instantiates a new SCP session on top of it, and then begins an upload from `local` to `remote`. If the `options` hash includes an :ssh key, the value for that will be passed to the SSH connection as options (e.g., to set the password, etc.). All other options are passed to the upload! method. If a block is given, it will be used to report progress (see "Progress Reporting", under Net::SCP).

[Source]

         # File lib/net/scp.rb, line 218
    218:     def self.upload!(host, username, local, remote, options={}, &progress)
    219:       options = options.dup
    220:       start(host, username, options.delete(:ssh) || {}) do |scp|
    221:         scp.upload!(local, remote, options, &progress)
    222:       end
    223:     end

upload!(host, username, local, remote, options={}, &progress)

Starts up a new SSH connection using the `host` and `username` parameters, instantiates a new SCP session on top of it, and then begins an upload from `local` to `remote`. If the `options` hash includes an :ssh key, the value for that will be passed to the SSH connection as options (e.g., to set the password, etc.). All other options are passed to the upload! method. If a block is given, it will be used to report progress (see "Progress Reporting", under Net::SCP).

[Source]

         # File lib/net/scp.rb, line 218
    218:     def self.upload!(host, username, local, remote, options={}, &progress)
    219:       options = options.dup
    220:       start(host, username, options.delete(:ssh) || {}) do |scp|
    221:         scp.upload!(local, remote, options, &progress)
    222:       end
    223:     end

### Public Instance methods

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

Inititiate a synchronous (non-blocking) download from `remote` to `local`. The following options are recognized:

- :recursive - the `remote` parameter refers to a remote directory, which should be downloaded to a new directory named `local` on the local machine.
- :preserve - the atime and mtime of the file should be preserved.
- :verbose - the process should result in verbose output on the server end (useful for debugging).

This method will return immediately, returning the Net::SSH::Connection::Channel object that will support the download. To wait for the download to finish, you can either call the wait method on the channel, or otherwise run the Net::SSH event loop until the channel‘s active? method returns false.

      channel = scp.download("/remote/path", "/local/path")
      channel.wait

[Source]

         # File lib/net/scp.rb, line 298
    298:     def download(remote, local, options={}, &progress)
    299:       start_command(:download, local, remote, options, &progress)
    300:     end

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

Inititiate a synchronous (non-blocking) download from `remote` to `local`. The following options are recognized:

- :recursive - the `remote` parameter refers to a remote directory, which should be downloaded to a new directory named `local` on the local machine.
- :preserve - the atime and mtime of the file should be preserved.
- :verbose - the process should result in verbose output on the server end (useful for debugging).

This method will return immediately, returning the Net::SSH::Connection::Channel object that will support the download. To wait for the download to finish, you can either call the wait method on the channel, or otherwise run the Net::SSH event loop until the channel‘s active? method returns false.

      channel = scp.download("/remote/path", "/local/path")
      channel.wait

[Source]

         # File lib/net/scp.rb, line 298
    298:     def download(remote, local, options={}, &progress)
    299:       start_command(:download, local, remote, options, &progress)
    300:     end

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

Same as download, but blocks until the download finishes. Identical to calling download and then calling the wait method on the channel object that is returned.

      scp.download!("/remote/path", "/local/path")

If `local` is nil, and the download is not recursive (e.g., it is downloading only a single file), the file will be downloaded to an in-memory buffer and the resulting string returned.

      data = download!("/remote/path")

[Source]

         # File lib/net/scp.rb, line 313
    313:     def download!(remote, local=nil, options={}, &progress)
    314:       destination = local ? local : StringIO.new
    315:       download(remote, destination, options, &progress).wait
    316:       local ? true : destination.string
    317:     end

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

Same as download, but blocks until the download finishes. Identical to calling download and then calling the wait method on the channel object that is returned.

      scp.download!("/remote/path", "/local/path")

If `local` is nil, and the download is not recursive (e.g., it is downloading only a single file), the file will be downloaded to an in-memory buffer and the resulting string returned.

      data = download!("/remote/path")

[Source]

         # File lib/net/scp.rb, line 313
    313:     def download!(remote, local=nil, options={}, &progress)
    314:       destination = local ? local : StringIO.new
    315:       download(remote, destination, options, &progress).wait
    316:       local ? true : destination.string
    317:     end

upload(local, remote, options={}, &progress)

Inititiate a synchronous (non-blocking) upload from `local` to `remote`. The following options are recognized:

- :recursive - the `local` parameter refers to a local directory, which should be uploaded to a new directory named `remote` on the remote server.
- :preserve - the atime and mtime of the file should be preserved.
- :verbose - the process should result in verbose output on the server end (useful for debugging).
- :chunk_size - the size of each "chunk" that should be sent. Defaults to 2048. Changing this value may improve throughput at the expense of decreasing interactivity.

This method will return immediately, returning the Net::SSH::Connection::Channel object that will support the upload. To wait for the upload to finish, you can either call the wait method on the channel, or otherwise run the Net::SSH event loop until the channel‘s active? method returns false.

      channel = scp.upload("/local/path", "/remote/path")
      channel.wait

[Source]

         # File lib/net/scp.rb, line 270
    270:     def upload(local, remote, options={}, &progress)
    271:       start_command(:upload, local, remote, options, &progress)
    272:     end

upload(local, remote, options={}, &progress)

Inititiate a synchronous (non-blocking) upload from `local` to `remote`. The following options are recognized:

- :recursive - the `local` parameter refers to a local directory, which should be uploaded to a new directory named `remote` on the remote server.
- :preserve - the atime and mtime of the file should be preserved.
- :verbose - the process should result in verbose output on the server end (useful for debugging).
- :chunk_size - the size of each "chunk" that should be sent. Defaults to 2048. Changing this value may improve throughput at the expense of decreasing interactivity.

This method will return immediately, returning the Net::SSH::Connection::Channel object that will support the upload. To wait for the upload to finish, you can either call the wait method on the channel, or otherwise run the Net::SSH event loop until the channel‘s active? method returns false.

      channel = scp.upload("/local/path", "/remote/path")
      channel.wait

[Source]

         # File lib/net/scp.rb, line 270
    270:     def upload(local, remote, options={}, &progress)
    271:       start_command(:upload, local, remote, options, &progress)
    272:     end

upload!(local, remote, options={}, &progress)

Same as upload, but blocks until the upload finishes. Identical to calling upload and then calling the wait method on the channel object that is returned. The return value is not defined.

[Source]

         # File lib/net/scp.rb, line 277
    277:     def upload!(local, remote, options={}, &progress)
    278:       upload(local, remote, options, &progress).wait
    279:     end

upload!(local, remote, options={}, &progress)

Same as upload, but blocks until the upload finishes. Identical to calling upload and then calling the wait method on the channel object that is returned. The return value is not defined.

[Source]

         # File lib/net/scp.rb, line 277
    277:     def upload!(local, remote, options={}, &progress)
    278:       upload(local, remote, options, &progress).wait
    279:     end

[Validate]