sftp

package module
v0.0.0-...-0878e1f Latest Latest
Warning

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

 Go to latest Published: Dec 11, 2020 License: BSD-2-Clause Imports: 21 Imported by: 0

README

sftp

The sftp package provides support for file system operations on remote ssh servers using the SFTP subsystem. It also implements an SFTP server for serving files from the filesystem.

UNIX Build Status GoDoc

usage and examples

See godoc.org/github.com/pkg/sftp for examples and usage.

The basic operation of the package mirrors the facilities of the os package.

The Walker interface for directory traversal is heavily inspired by Keith Rarick's fs package.

roadmap

  • There is way too much duplication in the Client methods. If there was an unmarshal(interface{}) method this would reduce a heap of the duplication.

contributing

We welcome pull requests, bug fixes and issue reports.

Before proposing a large change, first please discuss your change by raising an issue.

For API/code bugs, please include a small, self contained code example to reproduce the issue. For pull requests, remember test coverage.

We handle issues and pull requests with a 0 open philosophy. That means we will try to address the submission as soon as possible and will work toward a resolution. If progress can no longer be made (eg. unreproducible bug) or stops (eg. unresponsive submitter), we will close the bug.

Please remember that we don't have infinite time and so it is a good guideline that the less time it takes us to work with you on your idea/issue the greater the chance we will have the time to do it.

Thanks.

Documentation

Overview

Package sftp implements the SSH File Transfer Protocol as described in https://filezilla-project.org/specs/draft-ietf-secsh-filexfer-02.txt

Example 
package main

import (
	"log"

	"github.com/AntiPaste/sftp"
	"golang.org/x/crypto/ssh"
)

func main() {
	var conn *ssh.Client

	// open an SFTP session over an existing ssh connection.
	sftp, err := sftp.NewClient(conn)
	if err != nil {
		log.Fatal(err)
	}
	defer sftp.Close()

	// walk a directory
	w := sftp.Walk("/home/user")
	for w.Step() {
		if w.Err() != nil {
			continue
		}
		log.Println(w.Path())
	}

	// leave your mark
	f, err := sftp.Create("hello.txt")
	if err != nil {
		log.Fatal(err)
	}
	if _, err := f.Write([]byte("Hello world!")); err != nil {
		log.Fatal(err)
	}

	// check it's there
	fi, err := sftp.Lstat("hello.txt")
	if err != nil {
		log.Fatal(err)
	}
	log.Println(fi)
}

Output:

Index

Examples

Constants

This section is empty.

Variables

View Source 
var ErrBadPattern = errors.New("syntax error in pattern")

ErrBadPattern indicates a globbing pattern was malformed.

Functions

func Join 

func Join(elem ...string) string

Join joins any number of path elements into a single path, adding a Separator if necessary. all empty strings are ignored.

func Match 

func Match(pattern, name string) (matched bool, err error)

Match reports whether name matches the shell file name pattern. The pattern syntax is: 

pattern:
	{ term }
term:
	'*'         matches any sequence of non-Separator characters
	'?'         matches any single non-Separator character
	'[' [ '^' ] { character-range } ']'
	            character class (must be non-empty)
	c           matches character c (c != '*', '?', '\\', '[')
	'\\' c      matches character c

character-range:
	c           matches character c (c != '\\', '-', ']')
	'\\' c      matches character c
	lo '-' hi   matches character c for lo <= c <= hi

Match requires pattern to match all of name, not just a substring. The only possible returned error is ErrBadPattern, when pattern is malformed.

func MaxPacket 

func MaxPacket(size int) func(*Client) error

MaxPacket sets the maximum size of the payload.

func Split 

func Split(path string) (dir, file string)

Split splits path immediately following the final Separator, separating it into a directory and file name component. If there is no Separator in path, Split returns an empty dir and file set to path. The returned values have the property that path = dir+file.

Types

type Client 

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

Client represents an SFTP session on a *ssh.ClientConn SSH connection. Multiple Clients can be active on a single SSH connection, and a Client may be called concurrently from multiple Goroutines.

Client implements the github.com/kr/fs.FileSystem interface.

func NewClient 

func NewClient(conn *ssh.Client, opts ...func(*Client) error) (*Client, error)

NewClient creates a new SFTP client on conn, using zero or more option functions.

func NewClientPipe 

func NewClientPipe(rd io.Reader, wr io.WriteCloser, opts ...func(*Client) error) (*Client, error)

NewClientPipe creates a new SFTP client given a Reader and a WriteCloser. This can be used for connecting to an SFTP server over TCP/TLS or by using the system's ssh client program (e.g. via exec.Command).

Example 
package main

import (
	"fmt"
	"log"
	"os"
	"os/exec"

	"github.com/AntiPaste/sftp"
)

func main() {
	// Connect to a remote host and request the sftp subsystem via the 'ssh'
	// command.  This assumes that passwordless login is correctly configured.
	cmd := exec.Command("ssh", "example.com", "-s", "sftp")

	// send errors from ssh to stderr
	cmd.Stderr = os.Stderr

	// get stdin and stdout
	wr, err := cmd.StdinPipe()
	if err != nil {
		log.Fatal(err)
	}
	rd, err := cmd.StdoutPipe()
	if err != nil {
		log.Fatal(err)
	}

	// start the process
	if err := cmd.Start(); err != nil {
		log.Fatal(err)
	}
	defer cmd.Wait()

	// open the SFTP session
	client, err := sftp.NewClientPipe(rd, wr)
	if err != nil {
		log.Fatal(err)
	}

	// read a directory
	list, err := client.ReadDir("/")
	if err != nil {
		log.Fatal(err)
	}

	// print contents
	for _, item := range list {
		fmt.Println(item.Name())
	}

	// close the connection
	client.Close()
}

Output:

func (*Client) Chmod 

func (c *Client) Chmod(path string, mode os.FileMode) error

Chmod changes the permissions of the named file.

func (*Client) Chown 

func (c *Client) Chown(path string, uid, gid int) error

Chown changes the user and group owners of the named file.

func (*Client) Chtimes 

func (c *Client) Chtimes(path string, atime time.Time, mtime time.Time) error

Chtimes changes the access and modification times of the named file.

func (*Client) Close 

func (c *Client) Close() error

Close closes the SFTP session.

func (*Client) Create 

func (c *Client) Create(path string) (*File, error)

Create creates the named file mode 0666 (before umask), truncating it if it already exists. If successful, methods on the returned File can be used for I/O; the associated file descriptor has mode O_RDWR.

func (*Client) Getwd 

func (c *Client) Getwd() (string, error)

Getwd returns the current working directory of the server. Operations involving relative paths will be based at this location.

func (*Client) Glob 

func (c *Client) Glob(pattern string) (matches []string, err error)

Glob returns the names of all files matching pattern or nil if there is no matching file. The syntax of patterns is the same as in Match. The pattern may describe hierarchical names such as /usr/*/bin/ed (assuming the Separator is '/').

Glob ignores file system errors such as I/O errors reading directories. The only possible returned error is ErrBadPattern, when pattern is malformed.

func (*Client) Join 

func (c *Client) Join(elem ...string) string

Join joins any number of path elements into a single path, adding a separating slash if necessary. The result is Cleaned; in particular, all empty strings are ignored.

func (*Client) Lstat 

func (c *Client) Lstat(p string) (os.FileInfo, error)

Lstat returns a FileInfo structure describing the file specified by path 'p'. If 'p' is a symbolic link, the returned FileInfo structure describes the symbolic link.

func (*Client) Mkdir 

func (c *Client) Mkdir(path string) error

Mkdir creates the specified directory. An error will be returned if a file or directory with the specified path already exists, or if the directory's parent folder does not exist (the method cannot create complete paths).

func (*Client) Open 

func (c *Client) Open(path string) (*File, error)

Open opens the named file for reading. If successful, methods on the returned file can be used for reading; the associated file descriptor has mode O_RDONLY.

func (*Client) OpenFile 

func (c *Client) OpenFile(path string, f int) (*File, error)

OpenFile is the generalized open call; most users will use Open or Create instead. It opens the named file with specified flag (O_RDONLY etc.). If successful, methods on the returned File can be used for I/O.

func (*Client) ReadDir 

func (c *Client) ReadDir(p string) ([]os.FileInfo, error)

ReadDir reads the directory named by dirname and returns a list of directory entries. 

func (c *Client) ReadLink(p string) (string, error)

ReadLink reads the target of a symbolic link.

func (*Client) Remove 

func (c *Client) Remove(path string) error

Remove removes the specified file or directory. An error will be returned if no file or directory with the specified path exists, or if the specified directory is not empty.

func (*Client) RemoveDirectory 

func (c *Client) RemoveDirectory(path string) error

RemoveDirectory removes a directory path.

func (*Client) Rename 

func (c *Client) Rename(oldname, newname string) error

Rename renames a file.

func (*Client) Stat 

func (c *Client) Stat(p string) (os.FileInfo, error)

Stat returns a FileInfo structure describing the file specified by path 'p'. If 'p' is a symbolic link, the returned FileInfo structure describes the referent file.

func (*Client) StatVFS 

func (c *Client) StatVFS(path string) (*StatVFS, error)

StatVFS retrieves VFS statistics from a remote host.

It implements the statvfs@openssh.com SSH_FXP_EXTENDED feature from http://www.opensource.apple.com/source/OpenSSH/OpenSSH-175/openssh/PROTOCOL?txt. 

func (c *Client) Symlink(oldname, newname string) error

Symlink creates a symbolic link at 'newname', pointing at target 'oldname'

func (*Client) Truncate 

func (c *Client) Truncate(path string, size int64) error

Truncate sets the size of the named file. Although it may be safely assumed that if the size is less than its current size it will be truncated to fit, the SFTP protocol does not specify what behavior the server should do when setting size greater than the current size.

func (*Client) Walk 

func (c *Client) Walk(root string) *fs.Walker

Walk returns a new Walker rooted at root.

type File 

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

File represents a remote file.

func (*File) Chmod 

func (f *File) Chmod(mode os.FileMode) error

Chmod changes the permissions of the current file.

func (*File) Chown 

func (f *File) Chown(uid, gid int) error

Chown changes the uid/gid of the current file.

func (*File) Close 

func (f *File) Close() error

Close closes the File, rendering it unusable for I/O. It returns an error, if any.

func (*File) Name 

func (f *File) Name() string

Name returns the name of the file as presented to Open or Create.

func (*File) Read 

func (f *File) Read(b []byte) (int, error)

Read reads up to len(b) bytes from the File. It returns the number of bytes read and an error, if any. Read follows io.Reader semantics, so when Read encounters an error or EOF condition after successfully reading n > 0 bytes, it returns the number of bytes read.

func (*File) ReadFrom 

func (f *File) ReadFrom(r io.Reader) (int64, error)

ReadFrom reads data from r until EOF and writes it to the file. The return value is the number of bytes read. Any error except io.EOF encountered during the read is also returned.

func (*File) Seek 

func (f *File) Seek(offset int64, whence int) (int64, error)

Seek implements io.Seeker by setting the client offset for the next Read or Write. It returns the next offset read. Seeking before or after the end of the file is undefined. Seeking relative to the end calls Stat.

func (*File) Stat 

func (f *File) Stat() (os.FileInfo, error)

Stat returns the FileInfo structure describing file. If there is an error.

func (*File) Truncate 

func (f *File) Truncate(size int64) error

Truncate sets the size of the current file. Although it may be safely assumed that if the size is less than its current size it will be truncated to fit, the SFTP protocol does not specify what behavior the server should do when setting size greater than the current size.

func (*File) Write 

func (f *File) Write(b []byte) (int, error)

Write writes len(b) bytes to the File. It returns the number of bytes written and an error, if any. Write returns a non-nil error when n != len(b).

func (*File) WriteTo 

func (f *File) WriteTo(w io.Writer) (int64, error)

WriteTo writes the file to w. The return value is the number of bytes written. Any error encountered during the write is also returned.

type FileCmder 

type FileCmder interface {
	Filecmd(Request) error
}

FileCmder should return an error (rename, remove, setstate, etc.)

type FileInfoer 

type FileInfoer interface {
	Fileinfo(Request) ([]os.FileInfo, error)
}

FileInfoer should return file listing info and errors (readdir, stat) note stat requests would return a list of 1

type FileReader 

type FileReader interface {
	Fileread(Request) (io.ReaderAt, error)
}

FileReader should return an io.Reader for the filepath

type FileStat 

type FileStat struct {
	Size     uint64
	Mode     uint32
	Mtime    uint32
	Atime    uint32
	UID      uint32
	GID      uint32
	Extended []StatExtended
}

FileStat holds the original unmarshalled values from a call to READDIR or *STAT. It is exported for the purposes of accessing the raw values via os.FileInfo.Sys()

type FileWriter 

type FileWriter interface {
	Filewrite(Request) (io.WriterAt, error)
}

FileWriter should return an io.Writer for the filepath

type Handlers 

type Handlers struct {
	FileGet  FileReader
	FilePut  FileWriter
	FileCmd  FileCmder
	FileInfo FileInfoer
}

Handlers contains the 4 SFTP server request handlers.

func InMemHandler 

func InMemHandler() Handlers

InMemHandler returns a Hanlders object with the test handlers

type Request 

type Request struct {
	// Get, Put, SetStat, Stat, Rename, Remove
	// Rmdir, Mkdir, List, Readlink, Symlink
	Method   string
	Filepath string
	Attrs    []byte // convert to sub-struct
	Target   string // for renames and sym-links
	// contains filtered or unexported fields
}

Request contains the data and state for the incoming service request.

func NewRequest 

func NewRequest(method, path string) Request

NewRequest creates a new Request object.

type RequestServer 

type RequestServer struct {
	Handlers Handlers
	// contains filtered or unexported fields
}

RequestServer abstracts the sftp protocol with an http request-like protocol

func NewRequestServer 

func NewRequestServer(rwc io.ReadWriteCloser, h Handlers) *RequestServer

NewRequestServer creates/allocates/returns new RequestServer. Normally there there will be one server per user-session.

func (*RequestServer) Close 

func (rs *RequestServer) Close() error

Close the read/write/closer to trigger exiting the main server loop

func (*RequestServer) Serve 

func (rs *RequestServer) Serve() error

Serve requests for user session

type Server 

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

Server is an SSH File Transfer Protocol (sftp) server. This is intended to provide the sftp subsystem to an ssh server daemon. This implementation currently supports most of sftp server protocol version 3, as specified at http://tools.ietf.org/html/draft-ietf-secsh-filexfer-02

func NewServer 

func NewServer(rwc io.ReadWriteCloser, options ...ServerOption) (*Server, error)

NewServer creates a new Server instance around the provided streams, serving content from the root of the filesystem. Optionally, ServerOption functions may be specified to further configure the Server.

A subsequent call to Serve() is required to begin serving files over SFTP.

func (*Server) Serve 

func (svr *Server) Serve() error

Serve serves SFTP connections until the streams stop or the SFTP subsystem is stopped.

func (*Server) Stop 

func (svr *Server) Stop() error

Stop waits for all the open files to close before shutting down the server.

type ServerOption 

type ServerOption func(*Server) error

A ServerOption is a function which applies configuration to a Server.

func AsUser 

func AsUser(u string) ServerOption

AsUser sets the current connection user. Useful when combined with Chroot.

func Chroot 

func Chroot(p string) ServerOption

Chroot configures a Server to jail the user within a directory.

func DisableRemove 

func DisableRemove() ServerOption

ReadOnly configures a Server to serve files in read-only mode.

func NotifyWrite 

func NotifyWrite(c chan WrittenFile) ServerOption

NotifyWrite sets the channel that notifications about written files are sent to.

func ReadOnly 

func ReadOnly() ServerOption

ReadOnly configures a Server to serve files in read-only mode.

func WithDebug 

func WithDebug(w io.Writer) ServerOption

WithDebug enables Server debugging output to the supplied io.Writer.

type StatExtended 

type StatExtended struct {
	ExtType string
	ExtData string
}

StatExtended contains additional, extended information for a FileStat.

type StatVFS 

type StatVFS struct {
	ID      uint32
	Bsize   uint64 /* file system block size */
	Frsize  uint64 /* fundamental fs block size */
	Blocks  uint64 /* number of blocks (unit f_frsize) */
	Bfree   uint64 /* free blocks in file system */
	Bavail  uint64 /* free blocks for non-root */
	Files   uint64 /* total file inodes */
	Ffree   uint64 /* free file inodes */
	Favail  uint64 /* free file inodes for to non-root */
	Fsid    uint64 /* file system id */
	Flag    uint64 /* bit mask of f_flag values */
	Namemax uint64 /* maximum filename length */
}

A StatVFS contains statistics about a filesystem.

func (*StatVFS) FreeSpace 

func (p *StatVFS) FreeSpace() uint64

FreeSpace calculates the amount of free space in a filesystem.

func (*StatVFS) MarshalBinary 

func (p *StatVFS) MarshalBinary() ([]byte, error)

Convert to ssh_FXP_EXTENDED_REPLY packet binary format

func (*StatVFS) TotalSpace 

func (p *StatVFS) TotalSpace() uint64

TotalSpace calculates the amount of total space in a filesystem.

type StatusError 

type StatusError struct {
	Code uint32
	// contains filtered or unexported fields
}

A StatusError is returned when an SFTP operation fails, and provides additional information about the failure.

func (*StatusError) Error 

func (s *StatusError) Error() string

type WrittenFile 

type WrittenFile struct {
	User string
	Path string
}

Source Files

View all Source files

Directories

Path Synopsis
examples
buffered-read-benchmark
buffered-read-benchmark benchmarks the peformance of reading from /dev/zero on the server to a []byte on the client via io.Copy.
 buffered-read-benchmark benchmarks the peformance of reading from /dev/zero on the server to a []byte on the client via io.Copy.
buffered-write-benchmark
buffered-write-benchmark benchmarks the peformance of writing a single large []byte on the client to /dev/null on the server via io.Copy.
 buffered-write-benchmark benchmarks the peformance of writing a single large []byte on the client to /dev/null on the server via io.Copy.
request-server
An example SFTP server implementation using the golang SSH package.
 An example SFTP server implementation using the golang SSH package.
sftp-server
An example SFTP server implementation using the golang SSH package.
 An example SFTP server implementation using the golang SSH package.
streaming-read-benchmark
streaming-read-benchmark benchmarks the peformance of reading from /dev/zero on the server to /dev/null on the client via io.Copy.
 streaming-read-benchmark benchmarks the peformance of reading from /dev/zero on the server to /dev/null on the client via io.Copy.
streaming-write-benchmark
streaming-write-benchmark benchmarks the peformance of writing from /dev/zero on the client to /dev/null on the server via io.Copy.
 streaming-write-benchmark benchmarks the peformance of writing from /dev/zero on the client to /dev/null on the server via io.Copy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.