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.

CI Status Go Reference

usage and examples

See https://pkg.go.dev/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 try to 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.

Thanks.

Expand ▾ Collapse ▴

Documentation

Overview

    Package sftp implements the SSH File Transfer Protocol as described in https://tools.ietf.org/html/draft-ietf-secsh-filexfer-02

    Example
    Output:
    
    

    Index

    Examples

    Constants

    View Source
    const (
    	ErrSSHFxOk               = fxerr(sshFxOk)
    	ErrSSHFxEOF              = fxerr(sshFxEOF)
    	ErrSSHFxNoSuchFile       = fxerr(sshFxNoSuchFile)
    	ErrSSHFxPermissionDenied = fxerr(sshFxPermissionDenied)
    	ErrSSHFxFailure          = fxerr(sshFxFailure)
    	ErrSSHFxBadMessage       = fxerr(sshFxBadMessage)
    	ErrSSHFxNoConnection     = fxerr(sshFxNoConnection)
    	ErrSSHFxConnectionLost   = fxerr(sshFxConnectionLost)
    	ErrSSHFxOpUnsupported    = fxerr(sshFxOPUnsupported)
    )

      Error types that match the SFTP's SSH_FXP_STATUS codes. Gives you more direct control of the errors being sent vs. letting the library work them out from the standard os/io errors.

      View Source
      const (
      	ErrSshFxOk               = ErrSSHFxOk
      	ErrSshFxEof              = ErrSSHFxEOF
      	ErrSshFxNoSuchFile       = ErrSSHFxNoSuchFile
      	ErrSshFxPermissionDenied = ErrSSHFxPermissionDenied
      	ErrSshFxFailure          = ErrSSHFxFailure
      	ErrSshFxBadMessage       = ErrSSHFxBadMessage
      	ErrSshFxNoConnection     = ErrSSHFxNoConnection
      	ErrSshFxConnectionLost   = ErrSSHFxConnectionLost
      	ErrSshFxOpUnsupported    = ErrSSHFxOpUnsupported
      )

        Deprecated error types, these are aliases for the new ones, please use the new ones directly

        View Source
        const EBADF = syscall.EBADF
        View Source
        const S_IFMT = syscall.S_IFMT
        View Source
        const (
        	// SftpServerWorkerCount defines the number of workers for the SFTP server
        	SftpServerWorkerCount = 8
        )

        Variables

        View Source
        var (
        	// ErrInternalInconsistency indicates the packets sent and the data queued to be
        	// written to the file don't match up. It is an unusual error and usually is
        	// caused by bad behavior server side or connection issues. The error is
        	// limited in scope to the call where it happened, the client object is still
        	// OK to use as long as the connection is still open.
        	ErrInternalInconsistency = errors.New("internal inconsistency")
        	// InternalInconsistency alias for ErrInternalInconsistency.
        	//
        	// Deprecated: please use ErrInternalInconsistency
        	InternalInconsistency = ErrInternalInconsistency
        )
        View Source
        var ErrBadPattern = path.ErrBadPattern

          ErrBadPattern indicates a globbing pattern was malformed.

          View Source
          var MaxFilelist int64 = 100

            MaxFilelist is the max number of files to return in a readdir batch.

            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 SetSFTPExtensions

                func SetSFTPExtensions(extensions ...string) error

                  SetSFTPExtensions allows to customize the supported server extensions. See the variable supportedSFTPExtensions for supported extensions. This method accepts a slice of sshExtensionPair names for example 'hardlink@openssh.com'. If an invalid extension is given an error will be returned and nothing will be changed

                  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 ...ClientOption) (*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 ...ClientOption) (*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
                          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. If you need more control over the flags/mode used to open the file see client.OpenFile.

                                    Note that some SFTP servers (eg. AWS Transfer) do not support opening files read/write at the same time. For those services you will need to use `client.OpenFile(os.O_WRONLY|os.O_CREATE|os.O_TRUNC)`.

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

                                        func (c *Client) HasExtension(name string) (string, bool)

                                          HasExtension checks whether the server supports a named extension.

                                          The first return value is the extension data reported by the server (typically a version number).

                                          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 (c *Client) Link(oldname, newname string) error

                                              Link creates a hard link at 'newname', pointing at the same inode as 'oldname'

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

                                                  Example (Parents)
                                                  Output:
                                                  
                                                  

                                                  func (*Client) MkdirAll

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

                                                    MkdirAll creates a directory named path, along with any necessary parents, and returns nil, or else returns an error. If path is already a directory, MkdirAll does nothing and returns nil. If path contains a regular file, an error is returned

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

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

                                                          PosixRename renames a file using the posix-rename@openssh.com extension which will replace newname if it already exists.

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

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

                                                                RealPath can be used to have the server canonicalize any given path name to an absolute path.

                                                                This is useful for converting path names containing ".." components, or relative pathnames without a leading slash into absolute paths.

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

                                                                              func (c *Client) Wait() error

                                                                                Wait blocks until the conn has shut down, and return the error causing the shutdown. It can be called concurrently from multiple goroutines.

                                                                                func (*Client) Walk

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

                                                                                  Walk returns a new Walker rooted at root.

                                                                                  type ClientOption

                                                                                  type ClientOption func(*Client) error

                                                                                    A ClientOption is a function which applies configuration to a Client.

                                                                                    func MaxConcurrentRequestsPerFile

                                                                                    func MaxConcurrentRequestsPerFile(n int) ClientOption

                                                                                      MaxConcurrentRequestsPerFile sets the maximum concurrent requests allowed for a single file.

                                                                                      The default maximum concurrent requests is 64.

                                                                                      func MaxPacket

                                                                                      func MaxPacket(size int) ClientOption

                                                                                        MaxPacket sets the maximum size of the payload, measured in bytes. This option only accepts sizes servers should support, ie. <= 32768 bytes. This is a synonym for MaxPacketChecked that provides backward compatibility.

                                                                                        If you get the error "failed to send packet header: EOF" when copying a large file, try lowering this number.

                                                                                        The default packet size is 32768 bytes.

                                                                                        func MaxPacketChecked

                                                                                        func MaxPacketChecked(size int) ClientOption

                                                                                          MaxPacketChecked sets the maximum size of the payload, measured in bytes. This option only accepts sizes servers should support, ie. <= 32768 bytes.

                                                                                          If you get the error "failed to send packet header: EOF" when copying a large file, try lowering this number.

                                                                                          The default packet size is 32768 bytes.

                                                                                          func MaxPacketUnchecked

                                                                                          func MaxPacketUnchecked(size int) ClientOption

                                                                                            MaxPacketUnchecked sets the maximum size of the payload, measured in bytes. It accepts sizes larger than the 32768 bytes all servers should support. Only use a setting higher than 32768 if your application always connects to the same server or after sufficiently broad testing.

                                                                                            If you get the error "failed to send packet header: EOF" when copying a large file, try lowering this number.

                                                                                            The default packet size is 32768 bytes.

                                                                                            func UseConcurrentReads

                                                                                            func UseConcurrentReads(value bool) ClientOption

                                                                                              UseConcurrentReads allows the Client to perform concurrent Reads.

                                                                                              Concurrent reads are generally safe to use and not using them will degrade performance, so this option is enabled by default.

                                                                                              When enabled, WriteTo will use Stat/Fstat to get the file size and determines how many concurrent workers to use. Some "read once" servers will delete the file if they receive a stat call on an open file and then the download will fail. Disabling concurrent reads you will be able to download files from these servers. If concurrent reads are disabled, the UseFstat option is ignored.

                                                                                              func UseConcurrentWrites

                                                                                              func UseConcurrentWrites(value bool) ClientOption

                                                                                                UseConcurrentWrites allows the Client to perform concurrent Writes.

                                                                                                Using concurrency while doing writes, requires special consideration. A write to a later offset in a file after an error, could end up with a file length longer than what was successfully written.

                                                                                                When using this option, if you receive an error during `io.Copy` or `io.WriteTo`, you may need to `Truncate` the target Writer to avoid “holes” in the data written.

                                                                                                func UseFstat

                                                                                                func UseFstat(value bool) ClientOption

                                                                                                  UseFstat sets whether to use Fstat or Stat when File.WriteTo is called (usually when copying files). Some servers limit the amount of open files and calling Stat after opening the file will throw an error From the server. Setting this flag will call Fstat instead of Stat which is suppose to be called on an open file handle.

                                                                                                  It has been found that that with IBM Sterling SFTP servers which have "extractability" level set to 1 which means only 1 file can be opened at any given time.

                                                                                                  If the server you are working with still has an issue with both Stat and Fstat calls you can always open a file and read it until the end.

                                                                                                  Another reason to read the file until its end and Fstat doesn't work is that in some servers, reading a full file will automatically delete the file as some of these mainframes map the file to a message in a queue. Once the file has been read it will get deleted.

                                                                                                  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.

                                                                                                              To maximise throughput for transferring the entire file (especially over high latency links) it is recommended to use WriteTo rather than calling Read multiple times. io.Copy will do this automatically.

                                                                                                              func (*File) ReadAt

                                                                                                              func (f *File) ReadAt(b []byte, off int64) (int, error)

                                                                                                                ReadAt reads up to len(b) byte from the File at a given offset `off`. It returns the number of bytes read and an error, if any. ReadAt follows io.ReaderAt semantics, so the file offset is not altered during the 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.

                                                                                                                  This method is preferred over calling Write multiple times to maximise throughput for transferring the entire file, especially over high-latency links.

                                                                                                                  Example (Bufio)
                                                                                                                  Output:
                                                                                                                  
                                                                                                                  

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

                                                                                                                      func (f *File) Sync() error

                                                                                                                        Sync requests a flush of the contents of a File to stable storage.

                                                                                                                        Sync requires the server to support the fsync@openssh.com extension.

                                                                                                                        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. We send a SSH_FXP_FSETSTAT here since we have a file handle

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

                                                                                                                            To maximise throughput for transferring the entire file (especially over high latency links) it is recommended to use ReadFrom rather than calling Write multiple times. io.Copy will do this automatically.

                                                                                                                            func (*File) WriteAt

                                                                                                                            func (f *File) WriteAt(b []byte, off int64) (written int, err error)

                                                                                                                              WriteAt writess up to len(b) byte to the File at a given offset `off`. It returns the number of bytes written and an error, if any. WriteAt follows io.WriterAt semantics, so the file offset is not altered during the write.

                                                                                                                              func (*File) WriteTo

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

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

                                                                                                                                This method is preferred over calling Read multiple times to maximise throughput for transferring the entire file, especially over high latency links.

                                                                                                                                type FileAttrFlags

                                                                                                                                type FileAttrFlags struct {
                                                                                                                                	Size, UidGid, Permissions, Acmodtime bool
                                                                                                                                }

                                                                                                                                  FileAttrFlags that indicate whether SFTP file attributes were passed. When a flag is true the corresponding attribute should be available from the FileStat object returned by Attributes method. Used with SetStat.

                                                                                                                                  type FileCmder

                                                                                                                                  type FileCmder interface {
                                                                                                                                  	Filecmd(*Request) error
                                                                                                                                  }

                                                                                                                                    FileCmder should return an error Note in cases of an error, the error text will be sent to the client. Called for Methods: Setstat, Rename, Rmdir, Mkdir, Link, Symlink, Remove

                                                                                                                                    type FileLister

                                                                                                                                    type FileLister interface {
                                                                                                                                    	Filelist(*Request) (ListerAt, error)
                                                                                                                                    }

                                                                                                                                      FileLister should return an object that fulfils the ListerAt interface Note in cases of an error, the error text will be sent to the client. Called for Methods: List, Stat, Readlink

                                                                                                                                      type FileOpenFlags

                                                                                                                                      type FileOpenFlags struct {
                                                                                                                                      	Read, Write, Append, Creat, Trunc, Excl bool
                                                                                                                                      }

                                                                                                                                        FileOpenFlags defines Open and Write Flags. Correlate directly with with os.OpenFile flags (https://golang.org/pkg/os/#pkg-constants).

                                                                                                                                        type FileReader

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

                                                                                                                                          FileReader should return an io.ReaderAt for the filepath Note in cases of an error, the error text will be sent to the client. Called for Methods: Get

                                                                                                                                          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(). It is also used server side to store the unmarshalled values for SetStat.

                                                                                                                                            func (FileStat) FileMode

                                                                                                                                            func (a FileStat) FileMode() os.FileMode

                                                                                                                                              FileMode returns the Mode SFTP file attributes wrapped as os.FileMode

                                                                                                                                              type FileWriter

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

                                                                                                                                                FileWriter should return an io.WriterAt for the filepath.

                                                                                                                                                The request server code will call Close() on the returned io.WriterAt ojbect if an io.Closer type assertion succeeds. Note in cases of an error, the error text will be sent to the client. Note when receiving an Append flag it is important to not open files using O_APPEND if you plan to use WriteAt, as they conflict. Called for Methods: Put, Open

                                                                                                                                                type Handlers

                                                                                                                                                type Handlers struct {
                                                                                                                                                	FileGet  FileReader
                                                                                                                                                	FilePut  FileWriter
                                                                                                                                                	FileCmd  FileCmder
                                                                                                                                                	FileList FileLister
                                                                                                                                                }

                                                                                                                                                  Handlers contains the 4 SFTP server request handlers.

                                                                                                                                                  func InMemHandler

                                                                                                                                                  func InMemHandler() Handlers

                                                                                                                                                    InMemHandler returns a Hanlders object with the test handlers.

                                                                                                                                                    type ListerAt

                                                                                                                                                    type ListerAt interface {
                                                                                                                                                    	ListAt([]os.FileInfo, int64) (int, error)
                                                                                                                                                    }

                                                                                                                                                      ListerAt does for file lists what io.ReaderAt does for files. ListAt should return the number of entries copied and an io.EOF error if at end of list. This is testable by comparing how many you copied to how many could be copied (eg. n < len(ls) below). The copy() builtin is best for the copying. Note in cases of an error, the error text will be sent to the client.

                                                                                                                                                      type LstatFileLister

                                                                                                                                                      type LstatFileLister interface {
                                                                                                                                                      	FileLister
                                                                                                                                                      	Lstat(*Request) (ListerAt, error)
                                                                                                                                                      }

                                                                                                                                                        LstatFileLister is a FileLister that implements the Lstat method. If this interface is implemented Lstat requests will call it otherwise they will be handled in the same way as Stat

                                                                                                                                                        type OpenFileWriter

                                                                                                                                                        type OpenFileWriter interface {
                                                                                                                                                        	FileWriter
                                                                                                                                                        	OpenFile(*Request) (WriterAtReaderAt, error)
                                                                                                                                                        }

                                                                                                                                                          OpenFileWriter is a FileWriter that implements the generic OpenFile method. You need to implement this optional interface if you want to be able to read and write from/to the same handle. Called for Methods: Open

                                                                                                                                                          type PosixRenameFileCmder

                                                                                                                                                          type PosixRenameFileCmder interface {
                                                                                                                                                          	FileCmder
                                                                                                                                                          	PosixRename(*Request) error
                                                                                                                                                          }

                                                                                                                                                            PosixRenameFileCmder is a FileCmder that implements the PosixRename method. If this interface is implemented PosixRename requests will call it otherwise they will be handled in the same way as Rename

                                                                                                                                                            type Request

                                                                                                                                                            type Request struct {
                                                                                                                                                            	// Get, Put, Setstat, Stat, Rename, Remove
                                                                                                                                                            	// Rmdir, Mkdir, List, Readlink, Link, Symlink
                                                                                                                                                            	Method   string
                                                                                                                                                            	Filepath string
                                                                                                                                                            	Flags    uint32
                                                                                                                                                            	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.

                                                                                                                                                                func (*Request) AttrFlags

                                                                                                                                                                func (r *Request) AttrFlags() FileAttrFlags

                                                                                                                                                                  AttrFlags returns a FileAttrFlags boolean struct based on the bitmap/uint32 file attribute flags from the SFTP packaet.

                                                                                                                                                                  func (*Request) Attributes

                                                                                                                                                                  func (r *Request) Attributes() *FileStat

                                                                                                                                                                    Attributes parses file attributes byte blob and return them in a FileStat object.

                                                                                                                                                                    func (*Request) Context

                                                                                                                                                                    func (r *Request) Context() context.Context

                                                                                                                                                                      Context returns the request's context. To change the context, use WithContext.

                                                                                                                                                                      The returned context is always non-nil; it defaults to the background context.

                                                                                                                                                                      For incoming server requests, the context is canceled when the request is complete or the client's connection closes.

                                                                                                                                                                      func (*Request) Pflags

                                                                                                                                                                      func (r *Request) Pflags() FileOpenFlags

                                                                                                                                                                        Pflags converts the bitmap/uint32 from SFTP Open packet pflag values, into a FileOpenFlags struct with booleans set for flags set in bitmap.

                                                                                                                                                                        func (*Request) WithContext

                                                                                                                                                                        func (r *Request) WithContext(ctx context.Context) *Request

                                                                                                                                                                          WithContext returns a copy of r with its context changed to ctx. The provided ctx must be non-nil.

                                                                                                                                                                          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, options ...RequestServerOption) *RequestServer

                                                                                                                                                                              NewRequestServer creates/allocates/returns new RequestServer. Normally 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 RequestServerOption

                                                                                                                                                                                  type RequestServerOption func(*RequestServer)

                                                                                                                                                                                    A RequestServerOption is a function which applies configuration to a RequestServer.

                                                                                                                                                                                    func WithRSAllocator

                                                                                                                                                                                    func WithRSAllocator() RequestServerOption

                                                                                                                                                                                      WithRSAllocator enable the allocator. After processing a packet we keep in memory the allocated slices and we reuse them for new packets. The allocator is experimental

                                                                                                                                                                                      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.

                                                                                                                                                                                            type ServerOption

                                                                                                                                                                                            type ServerOption func(*Server) error

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

                                                                                                                                                                                              func ReadOnly

                                                                                                                                                                                              func ReadOnly() ServerOption

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

                                                                                                                                                                                                func WithAllocator

                                                                                                                                                                                                func WithAllocator() ServerOption

                                                                                                                                                                                                  WithAllocator enable the allocator. After processing a packet we keep in memory the allocated slices and we reuse them for new packets. The allocator is experimental

                                                                                                                                                                                                  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)

                                                                                                                                                                                                          func (*StatVFS) TotalSpace

                                                                                                                                                                                                          func (p *StatVFS) TotalSpace() uint64

                                                                                                                                                                                                            TotalSpace calculates the amount of total space in a filesystem.

                                                                                                                                                                                                            type StatVFSFileCmder

                                                                                                                                                                                                            type StatVFSFileCmder interface {
                                                                                                                                                                                                            	FileCmder
                                                                                                                                                                                                            	StatVFS(*Request) (*StatVFS, error)
                                                                                                                                                                                                            }

                                                                                                                                                                                                              StatVFSFileCmder is a FileCmder that implements the StatVFS method. You need to implement this interface if you want to handle statvfs requests. Please also be sure that the statvfs@openssh.com extension is enabled

                                                                                                                                                                                                              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

                                                                                                                                                                                                                func (*StatusError) FxCode

                                                                                                                                                                                                                func (s *StatusError) FxCode() fxerr

                                                                                                                                                                                                                  FxCode returns the error code typed to match against the exported codes

                                                                                                                                                                                                                  type TransferError

                                                                                                                                                                                                                  type TransferError interface {
                                                                                                                                                                                                                  	TransferError(err error)
                                                                                                                                                                                                                  }

                                                                                                                                                                                                                    TransferError is an optional interface that readerAt and writerAt can implement to be notified about the error causing Serve() to exit with the request still open

                                                                                                                                                                                                                    type WriterAtReaderAt

                                                                                                                                                                                                                    type WriterAtReaderAt interface {
                                                                                                                                                                                                                    	io.WriterAt
                                                                                                                                                                                                                    	io.ReaderAt
                                                                                                                                                                                                                    }

                                                                                                                                                                                                                      WriterAtReaderAt defines the interface to return when a file is to be opened for reading and writing

                                                                                                                                                                                                                      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.
                                                                                                                                                                                                                      go-sftp-server
                                                                                                                                                                                                                      An example SFTP server implementation using the golang SSH package.
                                                                                                                                                                                                                      An example SFTP server implementation using the golang SSH package.
                                                                                                                                                                                                                      request-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.