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 ¶
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 ¶
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)
}
}
Output:
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 ¶
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 ¶
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 ¶
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 ¶
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)
}
}
Output: