scp

README

Copy files over SCP with Go

This package makes it very easy to copy files over scp in Go. It uses the golang.org/x/crypto/ssh package to establish a secure connection to a remote server in order to copy the files via the SCP protocol.

Example usage

package main

import (
	"fmt"
	scp "github.com/johnmarkli/go-scp"
	"github.com/johnmarkli/go-scp/auth"
	"golang.org/x/crypto/ssh"
	"os"
        "context"
)

func main() {
	// Use SSH key authentication from the auth package
	// we ignore the host key in this example, please change this if you use this library
	clientConfig, _ := auth.PrivateKey("username", "/path/to/rsa/key", ssh.InsecureIgnoreHostKey())

	// For other authentication methods see ssh.ClientConfig and ssh.AuthMethod

	// Create a new SCP client
	client := scp.NewClient("example.com:22", &clientConfig)

	// Connect to the remote server
	err := client.Connect()
	if err != nil {
		fmt.Println("Couldn't establish a connection to the remote server ", err)
		return
	}

	// Open a file
	f, _ := os.Open("/path/to/local/file")

	// Close client connection after the file has been copied
	defer client.Close()

	// Close the file after it has been copied
	defer f.Close()

	// Finally, copy the file over
	// Usage: CopyFromFile(context, file, remotePath, permission)

        // the context can be adjusted to provide time-outs or inherit from other contexts if this is embedded in a larger application.
	err = client.CopyFromFile(context.Background(), *f, "/home/server/test.txt", "0655")

	if err != nil {
		fmt.Println("Error while copying file ", err)
	}
}

Using an existing SSH connection

If you have an existing established SSH connection, you can use that instead.

func connectSSH() *ssh.Client {
   // setup SSH connection
}

func main() {
   sshClient := connectSSH()

   // Create a new SCP client, note that this function might
   // return an error, as a new SSH session is established using the existing connecton

   client, err := scp.NewClientBySSH(sshClient)
   if err != nil {
      fmt.Println("Error creating new SSH session from existing connection", err)
   }

   /* .. same as above .. */
}

Copying Files from Remote Server

It is also possible to copy remote files using this library. The usage is similar to the example at the top of this section, except that CopyFromRemote needsto be used instead.

For a more comprehensive example, please consult the TestDownloadFile function in t he tests/basic_test.go file.

License

This library is licensed under the Mozilla Public License 2.0.
A copy of the license is provided in the LICENSE.txt file.

Copyright (c) 2020 Bram Vandenbogaerde

Documentation

Overview

Package scp. Simple scp package to copy files over SSH.

Index

• func Ack(writer io.Writer) error
• func CopyN(writer io.Writer, src io.Reader, size int64) (int64, error)
• type Client
  • func NewClient(host string, config *ssh.ClientConfig) Client
  • func NewClientBySSH(ssh *ssh.Client) (Client, error)
  • func NewClientBySSHWithTimeout(ssh *ssh.Client, timeout time.Duration) (Client, error)
  • func NewClientWithTimeout(host string, config *ssh.ClientConfig, timeout time.Duration) Client
  • func (a *Client) Close()
  • func (a *Client) Connect() error
  • func (a *Client) Copy(ctx context.Context, r io.Reader, remotePath string, permissions string, ...) error
  • func (a *Client) CopyFile(ctx context.Context, fileReader io.Reader, remotePath string, ...) error
  • func (a *Client) CopyFilePassThru(ctx context.Context, fileReader io.Reader, remotePath string, ...) error
  • func (a *Client) CopyFromFile(ctx context.Context, file os.File, remotePath string, permissions string) error
  • func (a *Client) CopyFromFilePassThru(ctx context.Context, file os.File, remotePath string, permissions string, ...) error
  • func (a *Client) CopyFromRemote(ctx context.Context, file *os.File, remotePath string) error
  • func (a *Client) CopyFromRemotePassThru(ctx context.Context, w io.Writer, remotePath string, passThru PassThru) error
  • func (a *Client) CopyPassThru(ctx context.Context, r io.Reader, remotePath string, permissions string, ...) error
• type ClientConfigurer
  • func NewConfigurer(host string, config *ssh.ClientConfig) *ClientConfigurer
  • func (c *ClientConfigurer) ClientConfig(config *ssh.ClientConfig) *ClientConfigurer
  • func (c *ClientConfigurer) Create() Client
  • func (c *ClientConfigurer) Host(host string) *ClientConfigurer
  • func (c *ClientConfigurer) RemoteBinary(path string) *ClientConfigurer
  • func (c *ClientConfigurer) SSHClient(sshClient *ssh.Client) *ClientConfigurer
  • func (c *ClientConfigurer) Timeout(timeout time.Duration) *ClientConfigurer
• type FileInfos
• type PassThru
• type Response
  • func ParseResponse(reader io.Reader) (Response, error)
  • func (r *Response) GetMessage() string
  • func (r *Response) IsError() bool
  • func (r *Response) IsFailure() bool
  • func (r *Response) IsOk() bool
  • func (r *Response) IsWarning() bool
  • func (r *Response) ParseFileInfos() (*FileInfos, error)
• type ResponseType

Functions

func Ack

func Ack(writer io.Writer) error

Ack writes an `Ack` message to the remote, does not await its response, a seperate call to ParseResponse is therefore required to check if the acknowledgement succeeded.

func CopyN

func CopyN(writer io.Writer, src io.Reader, size int64) (int64, error)

CopyN an adaptation of io.CopyN that keeps reading if it did not return a sufficient amount of bytes.

Types

type Client

type Client struct {
	// Host the host to connect to.
	Host string

	// ClientConfig the client config to use.
	ClientConfig *ssh.ClientConfig

	// Timeout the maximal amount of time to wait for a file transfer to complete.
	// Deprecated: use context.Context for each function instead.
	Timeout time.Duration

	// RemoteBinary the absolute path to the remote SCP binary.
	RemoteBinary string
	// contains filtered or unexported fields
}

func NewClient

func NewClient(host string, config *ssh.ClientConfig) Client

NewClient returns a new scp.Client with provided host and ssh.clientConfig.

func NewClientBySSH

func NewClientBySSH(ssh *ssh.Client) (Client, error)

NewClientBySSH returns a new scp.Client using an already existing established SSH connection.

func NewClientBySSHWithTimeout

func NewClientBySSHWithTimeout(ssh *ssh.Client, timeout time.Duration) (Client, error)

NewClientBySSHWithTimeout same as NewClientWithTimeout but uses an existing SSH client. Deprecated: provide meaningful context to each "Copy*" function instead.

func NewClientWithTimeout

func NewClientWithTimeout(host string, config *ssh.ClientConfig, timeout time.Duration) Client

NewClientWithTimeout returns a new scp.Client with provides host, ssh.ClientConfig and timeout. Deprecated: provide meaningful context to each "Copy*" function instead.

func (*Client) Close

func (a *Client) Close()

func (*Client) Connect

func (a *Client) Connect() error

Connect connects to the remote SSH server, returns error if it couldn't establish a session to the SSH server.

func (*Client) Copy

func (a *Client) Copy(ctx context.Context, r io.Reader, remotePath string, permissions string, size int64) error

Copy copies the contents of an io.Reader to a remote location.

func (*Client) CopyFile

func (a *Client) CopyFile(ctx context.Context, fileReader io.Reader, remotePath string, permissions string) error

CopyFile copies the contents of an io.Reader to a remote location, the length is determined by reading the io.Reader until EOF if the file length in know in advance please use "Copy" instead.

func (*Client) CopyFilePassThru

func (a *Client) CopyFilePassThru(ctx context.Context, fileReader io.Reader, remotePath string, permissions string, passThru PassThru) error

CopyFilePassThru copies the contents of an io.Reader to a remote location, the length is determined by reading the io.Reader until EOF if the file length in know in advance please use "Copy" instead. Access copied bytes by providing a PassThru reader factory.

func (*Client) CopyFromFile

func (a *Client) CopyFromFile(ctx context.Context, file os.File, remotePath string, permissions string) error

CopyFromFile copies the contents of an os.File to a remote location, it will get the length of the file by looking it up from the filesystem.

func (*Client) CopyFromFilePassThru

func (a *Client) CopyFromFilePassThru(ctx context.Context, file os.File, remotePath string, permissions string, passThru PassThru) error

CopyFromFilePassThru copies the contents of an os.File to a remote location, it will get the length of the file by looking it up from the filesystem. Access copied bytes by providing a PassThru reader factory.

func (*Client) CopyFromRemote

func (a *Client) CopyFromRemote(ctx context.Context, file *os.File, remotePath string) error

CopyFromRemote copies a file from the remote to the local file given by the `file` parameter. Use `CopyFromRemotePassThru` if a more generic writer is desired instead of writing directly to a file on the file system.?

func (*Client) CopyFromRemotePassThru

func (a *Client) CopyFromRemotePassThru(ctx context.Context, w io.Writer, remotePath string, passThru PassThru) error

CopyFromRemotePassThru copies a file from the remote to the given writer. The passThru parameter can be used to keep track of progress and how many bytes that were download from the remote. `passThru` can be set to nil to disable this behaviour.

func (*Client) CopyPassThru

func (a *Client) CopyPassThru(ctx context.Context, r io.Reader, remotePath string, permissions string, size int64, passThru PassThru) error

CopyPassThru copies the contents of an io.Reader to a remote location. Access copied bytes by providing a PassThru reader factory

type ClientConfigurer

type ClientConfigurer struct {
	// contains filtered or unexported fields
}

ClientConfigurer a struct containing all the configuration options used by an scp client.

func NewConfigurer

func NewConfigurer(host string, config *ssh.ClientConfig) *ClientConfigurer

NewConfigurer creates a new client configurer. It takes the required parameters: the host and the ssh.ClientConfig and returns a configurer populated with the default values for the optional parameters.

These optional parameters can be set by using the methods provided on the ClientConfigurer struct.

func (*ClientConfigurer) ClientConfig

func (c *ClientConfigurer) ClientConfig(config *ssh.ClientConfig) *ClientConfigurer

ClientConfig alters the ssh.ClientConfig.

func (*ClientConfigurer) Create

func (c *ClientConfigurer) Create() Client

Create builds a client with the configuration stored within the ClientConfigurer.

func (*ClientConfigurer) Host

func (c *ClientConfigurer) Host(host string) *ClientConfigurer

Host alters the host of the client connects to.

func (*ClientConfigurer) RemoteBinary

func (c *ClientConfigurer) RemoteBinary(path string) *ClientConfigurer

RemoteBinary sets the path of the location of the remote scp binary Defaults to: /usr/bin/scp.

func (*ClientConfigurer) SSHClient

func (c *ClientConfigurer) SSHClient(sshClient *ssh.Client) *ClientConfigurer

func (*ClientConfigurer) Timeout

func (c *ClientConfigurer) Timeout(timeout time.Duration) *ClientConfigurer

Timeout Changes the connection timeout. Defaults to one minute.

type FileInfos

type FileInfos struct {
	Message     string
	Filename    string
	Permissions string
	Size        int64
}

type PassThru

type PassThru func(r io.Reader, total int64) io.Reader

type Response

type Response struct {
	Type    ResponseType
	Message string
}

Response represent a response from the SCP command. There are tree types of responses that the remote can send back: ok, warning and error

The difference between warning and error is that the connection is not closed by the remote, however, a warning can indicate a file transfer failure (such as invalid destination directory) and such be handled as such.

All responses except for the `Ok` type always have a message (although these can be empty)

The remote sends a confirmation after every SCP command, because a failure can occur after every command, the response should be read and checked after sending them.

func ParseResponse

func ParseResponse(reader io.Reader) (Response, error)

ParseResponse reads from the given reader (assuming it is the output of the remote) and parses it into a Response structure.

func (*Response) GetMessage

func (r *Response) GetMessage() string

GetMessage returns the message the remote sent back.

func (*Response) IsError

func (r *Response) IsError() bool

IsError returns true when the remote responded with an error.

func (*Response) IsFailure

func (r *Response) IsFailure() bool

IsFailure returns true when the remote answered with a warning or an error.

func (*Response) IsOk

func (r *Response) IsOk() bool

func (*Response) IsWarning

func (r *Response) IsWarning() bool

func (*Response) ParseFileInfos

func (r *Response) ParseFileInfos() (*FileInfos, error)

type ResponseType

type ResponseType = uint8

const (
	Ok      ResponseType = 0
	Warning ResponseType = 1
	Error   ResponseType = 2
)