sftp

package module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package sftp copies files to and from a remote host over SFTP, as OpenSSH's "scp -s" does, in the same shape as package scp's Client: CopyTo and CopyFrom, with Recursive, Preserve and Glob.

SFTP reaches hosts that the classic scp protocol cannot: a host that offers only the SFTP subsystem, with no shell and no scp program. Auto picks whichever of the two protocols a host offers.

This package lives in a module of its own, so a program that uses only package scp does not depend on github.com/pkg/sftp, which this package is built on.

Index

Examples

Constants

This section is empty.

Variables

View Source
var ErrUnavailable = errors.New("sftp: no SFTP session")

ErrUnavailable is returned, wrapped, when an SFTP session cannot be started: the host offers no SFTP subsystem, or the program given to NewProgramClient did not start or did not speak SFTP. Auto falls back to the classic protocol on it.

Functions

func CopyBetween added in v0.2.0

func CopyBetween(ctx context.Context, src *Client, sources []string, dst *Client, target string) error

CopyBetween copies sources on the host src reaches into target on the host dst reaches, through this program, as "scp -3" does over SFTP. Each file is read from one session and written to the other as it arrives; nothing is written to this machine.

src's settings decide the copy: Recursive copies directories, Preserve keeps times and modes, Glob matches wildcards in the sources, MaxSize refuses a larger file, Limit paces the copy, and Atomic has each file replace its target whole, as CopyTo does. With more than one source, or with Glob, target must be an existing directory on the second host; otherwise target is written into when it is a directory and as the copy itself when it is not, as CopyFrom does locally.

A file either side cannot handle is reported and skipped, and the copy carries on; the error lists every such failure, each an scp.FileError that scp.Failures finds.

Types

type Auto

type Auto struct {
	scp.Options

	SFTP *Client
	SCP  *scp.Client
}

Auto copies over SFTP when the host offers it, and over scp's classic protocol when it does not: a host with no SFTP subsystem still has its scp program, and one that offers only SFTP has no scp program to run.

Set the shared Options on Auto itself: every copy uses them, over whichever protocol it takes, in place of the clients' own. Settings that only one protocol has, such as SFTP's Resume or SCP's Program, stay on that client.

Example

Copy over whichever protocol the host offers: SFTP when it has the subsystem, and the classic scp protocol when it does not. The options are set once, on Auto, and apply over either.

package main

import (
	"context"
	"log"

	"github.com/antimatter-studios/go-scp/pkg/sftp"
	"golang.org/x/crypto/ssh"
)

func main() {
	var conn *ssh.Client // dialled as in the Client.CopyTo example

	a := sftp.NewAuto(conn)
	a.Recursive = true
	a.Preserve = true
	a.Limit = 1 << 20 // bytes per second
	if err := a.CopyFrom(context.Background(), "./backup", "/etc/app"); err != nil {
		log.Fatal(err)
	}
}

func NewAuto

func NewAuto(conn *ssh.Client) *Auto

NewAuto returns an Auto that copies over conn.

func (*Auto) CopyFrom

func (a *Auto) CopyFrom(ctx context.Context, target string, sources ...string) error

CopyFrom copies files from the remote host into target on this host; see Client.CopyFrom and scp.Client.CopyFrom.

func (*Auto) CopyTo

func (a *Auto) CopyTo(ctx context.Context, target string, sources ...string) error

CopyTo copies local files to target on the remote host; see Client.CopyTo and scp.Client.CopyTo.

type Client

type Client struct {
	scp.Options

	// Requests caps how many requests may be in flight for one file, as
	// "-X nrequests=n" does; 0 leaves github.com/pkg/sftp's default.
	Requests int

	// BufferSize is the most one request carries, as "-X buffer=n" does; 0 leaves
	// the default of 32768 bytes, the size every server must accept. A larger size
	// works only with a server that allows it.
	BufferSize int

	// Resume continues a file that a copy left part-way, as sftp's reget and
	// reput do: where the destination already holds the start of a file, CopyTo
	// and CopyFrom copy only the rest. A destination longer than its source is
	// that file's failure. Nothing checks that the part already there matches.
	Resume bool

	// Parallel is how many files a copy moves at once over its one session; 0 or
	// 1 copies them one at a time. Each file costs round trips before its data
	// moves, so a tree of many small files copies faster with several in flight.
	// The files of a directory go together, which is entered before them and
	// given its mode and times only once they are all in. Failures are still
	// reported in the order of the listing, and Progress is never called from
	// two files at once.
	Parallel int
	// contains filtered or unexported fields
}

Client copies files over SFTP. Each transfer opens its own SFTP session, so one Client serves any number of them.

Of the shared Options, Preserve keeps modification and access times and modes, and Limit paces each copy as a whole.

func NewClient

func NewClient(conn *ssh.Client) *Client

NewClient returns a Client that copies over conn, through the host's SFTP subsystem. Verifying the host's key is conn's business, settled when it was dialled.

func NewProgramClient

func NewProgramClient(program string, args ...string) *Client

NewProgramClient returns a Client that, for each transfer, runs an SFTP server program on this host and speaks SFTP over its standard input and output, as "scp -D program" does. There is no SSH connection, so the "remote" files are local ones, seen through the program.

func (*Client) CopyFrom

func (c *Client) CopyFrom(ctx context.Context, target string, sources ...string) error

CopyFrom copies files from the remote host into target on this host, as "scp -s [-r] [-p] host:source... target" does. With Recursive a source may be a remote directory, copied with its contents. With more than one source, or with Glob, target must be an existing local directory. Files are written the way scp.DirSink writes them, and never outside target.

A source that cannot be copied is skipped; the rest are copied and the error lists every failure, each an scp.FileError that scp.Failures finds. A directory that cannot be created here ends the copy.

func (*Client) CopyTo

func (c *Client) CopyTo(ctx context.Context, target string, sources ...string) error

CopyTo copies local files to target on the remote host, as "scp -s [-r] [-p] source... host:target" does. With Recursive a source may be a directory, copied with its contents. With more than one source, target must be an existing remote directory.

A new file takes the source's mode, less 022 as a server would take its umask off, before any of it is written; an existing file keeps its own. With Preserve both take the source's mode and modification time exactly. With Atomic every file is written as a new one beside its target and renamed over it once whole, which needs the server's posix-rename@openssh.com extension.

A source that cannot be copied is skipped; the rest are copied and the error lists every failure, each an scp.FileError that scp.Failures finds.

Example

Upload a directory over SFTP, eight files at a time, as "scp -s -r ./photos deploy@example.com:/srv/photos" does, and list any file it skipped.

package main

import (
	"context"
	"log"
	"os"
	"path/filepath"

	"github.com/antimatter-studios/go-scp/pkg/scp"
	"github.com/antimatter-studios/go-scp/pkg/sftp"
	"golang.org/x/crypto/ssh"
	"golang.org/x/crypto/ssh/knownhosts"
)

func main() {
	home, _ := os.UserHomeDir()
	hostKeys, err := knownhosts.New(filepath.Join(home, ".ssh", "known_hosts"))
	if err != nil {
		log.Fatal(err)
	}
	pem, err := os.ReadFile(filepath.Join(home, ".ssh", "id_ed25519"))
	if err != nil {
		log.Fatal(err)
	}
	key, err := ssh.ParsePrivateKey(pem)
	if err != nil {
		log.Fatal(err)
	}
	conn, err := ssh.Dial("tcp", "example.com:22", &ssh.ClientConfig{
		User:            "deploy",
		Auth:            []ssh.AuthMethod{ssh.PublicKeys(key)},
		HostKeyCallback: hostKeys,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()

	c := sftp.NewClient(conn)
	c.Recursive = true
	c.Parallel = 8
	err = c.CopyTo(context.Background(), "/srv/photos", "./photos")
	skipped, rest := scp.Failures(err)
	for _, f := range skipped {
		log.Printf("skipped %s: %v", f.Path, f.Err)
	}
	if rest != nil {
		log.Fatal(rest)
	}
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址