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

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: CopyFile(fileReader, remotePath, permission)

	err = client.CopyFile(f, "/home/server/test.txt", "0655")

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

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) 2020 Bram Vandenbogaerde
* 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) 2020 Bram Vandenbogaerde
* 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

• type Client
  • func NewClient(host string, config *ssh.ClientConfig) Client
  • func NewClientWithTimeout(host string, config *ssh.ClientConfig, timeout time.Duration) Client
  • func (a *Client) Close()
  • func (a *Client) Connect() error
  • func (a *Client) Copy(r io.Reader, remotePath string, permissions string, size int64) error
  • func (a *Client) CopyFile(fileReader io.Reader, remotePath string, permissions string) error
  • func (a *Client) CopyFilePassThru(fileReader io.Reader, remotePath string, permissions string, passThru PassThru) error
  • func (a *Client) CopyFromFile(file os.File, remotePath string, permissions string) error
  • func (a *Client) CopyFromFilePassThru(file os.File, remotePath string, permissions string, passThru PassThru) error
  • func (a *Client) CopyPassThru(r io.Reader, remotePath string, permissions string, size int64, ...) 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) Timeout(timeout time.Duration) *ClientConfigurer
• 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
• type ResponseType

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 clients waits for the given timeout until given up the connection
	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 NewClientWithTimeout

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

Returns a new scp.Client with provides host, ssh.ClientConfig and timeout

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

func (a *Client) CopyPassThru(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) Timeout

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

Changes the connection timeout. Defaults to one minute

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

type ResponseType

type ResponseType = uint8

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