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/bramvdbogaerde/go-scp"
	"github.com/bramvdbogaerde/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()

	// Finaly, 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

Copyright (c) 2021 Bram Vandenbogaerde And Contributors
* You may use, distribute or modify this code under the
* terms of the Mozilla Public License 2.0, which is distributed
* along with the source code.

Copyright (c) 2021 Bram Vandenbogaerde And Contributors
* You may use, distribute or modify this code under the
* terms of the Mozilla Public License 2.0, which is distributed
* along with the source code.

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) Session(session *ssh.Session) *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

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)

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

Types

type Client

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

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

	// stores the SSH session while the connection is running
	Session *ssh.Session

	// stores the SSH connection itself in order to close it after transfer
	Conn ssh.Conn

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

	// the absolute path to the remote SCP binary
	RemoteBinary string
}

func NewClient

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

Returns a new scp.Client with provided host and ssh.clientConfig It has a default timeout of one minute.

func NewClientBySSH

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

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

func NewClientBySSHWithTimeout

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

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

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

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

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

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

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

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

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

Copy 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

Copy 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

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
}

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

func NewConfigurer

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

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

Alters the ssh.ClientConfig

func (*ClientConfigurer) Create

func (c *ClientConfigurer) Create() Client

Builds a client with the configuration stored within the ClientConfigurer

func (*ClientConfigurer) Host

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

Alters the host of the client connects to

func (*ClientConfigurer) RemoteBinary

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

Sets the path of the location of the remote scp binary Defaults to: /usr/bin/scp

func (*ClientConfigurer) Session

func (c *ClientConfigurer) Session(session *ssh.Session) *ClientConfigurer

Alters the ssh.Session

func (*ClientConfigurer) Timeout

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

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
}

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)

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

Returns the message the remote sent back

func (*Response) IsError

func (r *Response) IsError() bool

Returns true when the remote responded with an error

func (*Response) IsFailure

func (r *Response) IsFailure() bool

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
)