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/pkg/sftp" "golang.org/x/crypto/ssh" ) func main() { var conn *ssh.Client // open an SFTP session over an existing ssh connection. client, err := sftp.NewClient(conn) if err != nil { log.Fatal(err) } defer client.Close() // walk a directory w := client.Walk("/home/user") for w.Step() { if w.Err() != nil { continue } log.Println(w.Path()) } // leave your mark f, err := client.Create("hello.txt") if err != nil { log.Fatal(err) } if _, err := f.Write([]byte("Hello world!")); err != nil { log.Fatal(err) } f.Close() // check it's there fi, err := client.Lstat("hello.txt") if err != nil { log.Fatal(err) } log.Println(fi) }
Output:
Index ¶
- Constants
- Variables
- func Join(elem ...string) string
- func Match(pattern, name string) (matched bool, err error)
- func SetSFTPExtensions(extensions ...string) error
- func Split(p string) (dir, file string)
- type Client
- func (c *Client) Chmod(path string, mode os.FileMode) error
- func (c *Client) Chown(path string, uid, gid int) error
- func (c *Client) Chtimes(path string, atime time.Time, mtime time.Time) error
- func (c *Client) Close() error
- func (c *Client) Create(path string) (*File, error)
- func (c *Client) Getwd() (string, error)
- func (c *Client) Glob(pattern string) (matches []string, err error)
- func (c *Client) HasExtension(name string) (string, bool)
- func (c *Client) Join(elem ...string) string
- func (c *Client) Link(oldname, newname string) error
- func (c *Client) Lstat(p string) (os.FileInfo, error)
- func (c *Client) Mkdir(path string) error
- func (c *Client) MkdirAll(path string) error
- func (c *Client) Open(path string) (*File, error)
- func (c *Client) OpenFile(path string, f int) (*File, error)
- func (c *Client) PosixRename(oldname, newname string) error
- func (c *Client) ReadDir(p string) ([]os.FileInfo, error)
- func (c *Client) ReadDirContext(ctx context.Context, p string) ([]os.FileInfo, error)
- func (c *Client) ReadLink(p string) (string, error)
- func (c *Client) RealPath(path string) (string, error)
- func (c *Client) Remove(path string) error
- func (c *Client) RemoveAll(path string) error
- func (c *Client) RemoveDirectory(path string) error
- func (c *Client) Rename(oldname, newname string) error
- func (c *Client) SetExtendedData(path string, extended []StatExtended) error
- func (c *Client) Stat(p string) (os.FileInfo, error)
- func (c *Client) StatVFS(path string) (*StatVFS, error)
- func (c *Client) Symlink(oldname, newname string) error
- func (c *Client) Truncate(path string, size int64) error
- func (c *Client) Wait() error
- func (c *Client) Walk(root string) *fs.Walker
- type ClientOption
- func MaxConcurrentRequestsPerFile(n int) ClientOption
- func MaxPacket(size int) ClientOption
- func MaxPacketChecked(size int) ClientOption
- func MaxPacketUnchecked(size int) ClientOption
- func UseConcurrentReads(value bool) ClientOption
- func UseConcurrentWrites(value bool) ClientOption
- func UseFstat(value bool) ClientOption
- type File
- func (f *File) Chmod(mode os.FileMode) error
- func (f *File) Chown(uid, gid int) error
- func (f *File) Close() error
- func (f *File) Name() string
- func (f *File) Read(b []byte) (int, error)
- func (f *File) ReadAt(b []byte, off int64) (int, error)
- func (f *File) ReadFrom(r io.Reader) (int64, error)
- func (f *File) ReadFromWithConcurrency(r io.Reader, concurrency int) (read int64, err error)
- func (f *File) Seek(offset int64, whence int) (int64, error)
- func (f *File) SetExtendedData(path string, extended []StatExtended) error
- func (f *File) Stat() (os.FileInfo, error)
- func (f *File) Sync() error
- func (f *File) Truncate(size int64) error
- func (f *File) Write(b []byte) (int, error)
- func (f *File) WriteAt(b []byte, off int64) (written int, err error)
- func (f *File) WriteTo(w io.Writer) (written int64, err error)
- type FileAttrFlags
- type FileCmder
- type FileInfoExtendedData
- type FileInfoUidGid
- type FileLister
- type FileOpenFlags
- type FileReader
- type FileStat
- type FileWriter
- type Handlers
- type ListerAt
- type LstatFileLister
- type NameLookupFileLister
- type OpenFileWriter
- type PosixRenameFileCmder
- type ReadlinkFileLister
- type RealPathFileLister
- type Request
- type RequestServer
- type RequestServerOption
- type Server
- type ServerOption
- type StatExtended
- type StatVFS
- type StatVFSFileCmder
- type StatusError
- type TransferError
- type WriterAtReaderAt
Examples ¶
Constants ¶
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.
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
const EBADF = syscall.EBADF
const S_IFMT = uint32(sshfx.ModeType)
S_IFMT is a legacy export, and was brought in to support GOOS environments whose sysconfig.S_IFMT may be different from the value used internally by SFTP standards. There should be no reason why you need to import it, or use it, but unexporting it could cause code to break in a way that cannot be readily fixed. As such, we continue to export this value as the value used in the SFTP standard.
Deprecated: Remove use of this value, and avoid any future use as well. There is no alternative provided, you should never need to access this value.
const (
// SftpServerWorkerCount defines the number of workers for the SFTP server
SftpServerWorkerCount = 8
)
Variables ¶
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 )
var ErrBadPattern = path.ErrBadPattern
ErrBadPattern indicates a globbing pattern was malformed.
var MaxFilelist int64 = 100
MaxFilelist is the max number of files to return in a readdir batch.
Functions ¶
func Join ¶
Join joins any number of path elements into a single path, separating them with slashes.
This is an alias for path.Join from the standard library, offered so that callers need not import the path package. For details, see https://golang.org/pkg/path/#Join.
func Match ¶
Match reports whether name matches the shell pattern.
This is an alias for path.Match from the standard library, offered so that callers need not import the path package. For details, see https://golang.org/pkg/path/#Match.
func SetSFTPExtensions ¶ added in v1.11.0
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 ¶
Split splits the path p immediately following the final slash, separating it into a directory and file name component.
This is an alias for path.Split from the standard library, offered so that callers need not import the path package. For details, see https://golang.org/pkg/path/#Split.
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 ¶
package main import ( "fmt" "log" "os" "os/exec" "github.com/pkg/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 ¶
Chmod changes the permissions of the named file.
Chmod does not apply a umask, because even retrieving the umask is not possible in a portable way without causing a race condition. Callers should mask off umask bits, if desired.
func (*Client) Create ¶
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 ¶
Getwd returns the current working directory of the server. Operations involving relative paths will be based at this location.
func (*Client) Glob ¶
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.
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 ¶ added in v1.13.0
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 ¶
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) Link ¶ added in v1.11.0
Link creates a hard link at 'newname', pointing at the same inode as 'oldname'
func (*Client) Lstat ¶
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 ¶
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) ¶
package main import ( "fmt" "log" "os" "path" "strings" "github.com/pkg/sftp" "golang.org/x/crypto/ssh" ) func main() { // Example of mimicing 'mkdir --parents'; I.E. recursively create // directoryies and don't error if any directories already exists. var conn *ssh.Client client, err := sftp.NewClient(conn) if err != nil { log.Fatal(err) } defer client.Close() sshFxFailure := uint32(4) mkdirParents := func(client *sftp.Client, dir string) (err error) { var parents string if path.IsAbs(dir) { // Otherwise, an absolute path given below would be turned in to a relative one // by splitting on "/" parents = "/" } for _, name := range strings.Split(dir, "/") { if name == "" { // Paths with double-/ in them should just move along // this will also catch the case of the first character being a "/", i.e. an absolute path continue } parents = path.Join(parents, name) err = client.Mkdir(parents) if status, ok := err.(*sftp.StatusError); ok { if status.Code == sshFxFailure { var fi os.FileInfo fi, err = client.Stat(parents) if err == nil { if !fi.IsDir() { return fmt.Errorf("file exists: %s", parents) } } } } if err != nil { break } } return err } err = mkdirParents(client, "/tmp/foo/bar") if err != nil { log.Fatal(err) } }
Output:
func (*Client) MkdirAll ¶
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 ¶
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 ¶
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 ¶
PosixRename renames a file using the posix-rename@openssh.com extension which will replace newname if it already exists.
func (*Client) ReadDir ¶
ReadDir reads the directory named by p and returns a list of directory entries.
func (*Client) ReadDirContext ¶ added in v1.13.7
ReadDirContext reads the directory named by p and returns a list of directory entries. The passed context can be used to cancel the operation returning all entries listed up to the cancellation.
func (*Client) RealPath ¶ added in v1.13.0
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 ¶
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) RemoveAll ¶ added in v1.13.6
RemoveAll delete files recursively in the directory and Recursively delete subdirectories. An error will be returned if no file or directory with the specified path exists
func (*Client) RemoveDirectory ¶
RemoveDirectory removes a directory path.
func (*Client) SetExtendedData ¶ added in v1.13.7
func (c *Client) SetExtendedData(path string, extended []StatExtended) error
SetExtendedData sets extended attributes of the named file. It uses the SSH_FILEXFER_ATTR_EXTENDED flag in the setstat request.
This flag provides a general extension mechanism for vendor-specific extensions. Names of the attributes should be a string of the format "name@domain", where "domain" is a valid, registered domain name and "name" identifies the method. Server implementations SHOULD ignore extended data fields that they do not understand.
func (*Client) Stat ¶
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 ¶
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 (*Client) Truncate ¶
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.
type ClientOption ¶
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 ¶ added in v1.13.0
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 ¶ added in v1.13.0
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 ¶ added in v1.11.0
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 ¶
Chmod changes the permissions of the current file.
See Client.Chmod for details.
func (*File) Close ¶
Close closes the File, rendering it unusable for I/O. It returns an error, if any.
func (*File) Read ¶
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 ¶ added in v1.12.0
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 ¶
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.
To ensure concurrent writes, the given r needs to implement one of the following receiver methods:
Len() int Size() int64 Stat() (os.FileInfo, error)
or be an instance of io.LimitedReader to determine the number of possible concurrent requests. Otherwise, reads/writes are performed sequentially. ReadFromWithConcurrency can be used explicitly to guarantee concurrent processing of the reader.
Example (Bufio) ¶
package main import ( "bufio" "io" "github.com/pkg/sftp" ) func main() { // Using Bufio to buffer writes going to an sftp.File won't buffer as it // skips buffering if the underlying writer support ReadFrom. The // workaround is to wrap your writer in a struct that only implements // io.Writer. // // For background see github.com/pkg/sftp/issues/125 var data_source io.Reader var f *sftp.File type writerOnly struct{ io.Writer } bw := bufio.NewWriter(writerOnly{f}) // no ReadFrom() bw.ReadFrom(data_source) }
Output:
func (*File) ReadFromWithConcurrency ¶ added in v1.13.1
ReadFromWithConcurrency implements ReaderFrom, but uses the given concurrency to issue multiple requests at the same time.
Giving a concurrency of less than one will default to the Client’s max concurrency.
Otherwise, the given concurrency will be capped by the Client's max concurrency.
When one needs to guarantee concurrent reads/writes, this method is preferred over ReadFrom.
func (*File) Seek ¶
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) SetExtendedData ¶ added in v1.13.7
func (f *File) SetExtendedData(path string, extended []StatExtended) error
SetExtendedData sets extended attributes of the current file. It uses the SSH_FILEXFER_ATTR_EXTENDED flag in the setstat request.
This flag provides a general extension mechanism for vendor-specific extensions. Names of the attributes should be a string of the format "name@domain", where "domain" is a valid, registered domain name and "name" identifies the method. Server implementations SHOULD ignore extended data fields that they do not understand.
func (*File) Sync ¶ added in v1.13.0
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 ¶
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 ¶
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 ¶ added in v1.13.0
WriteAt writes 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 ¶
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 ¶
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 FileInfoExtendedData ¶ added in v1.13.6
type FileInfoExtendedData interface { os.FileInfo Extended() []StatExtended }
FileInfoUidGid extends os.FileInfo and adds a callbacks for extended data retrieval.
type FileInfoUidGid ¶ added in v1.13.6
FileInfoUidGid extends os.FileInfo and adds callbacks for Uid and Gid retrieval, as an alternative to *syscall.Stat_t objects on unix systems.
type FileLister ¶
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
Since Filelist returns an os.FileInfo, this can make it non-ideal for implementing Readlink. This is because the Name receiver method defined by that interface defines that it should only return the base name. However, Readlink is required to be capable of returning essentially any arbitrary valid path relative or absolute. In order to implement this more expressive requirement, implement ReadlinkFileLister which will then be used instead.
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 ¶
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) AccessTime ¶ added in v1.13.7
AccessTime returns the Atime SFTP file attribute converted to a time.Time
type FileWriter ¶
FileWriter should return an io.WriterAt for the filepath.
The request server code will call Close() on the returned io.WriterAt object 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 ¶
ListerAt does for file lists what io.ReaderAt does for files, i.e. a []os.FileInfo buffer is passed to the ListAt function and the entries that are populated in the buffer will be passed to the client.
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.
Uid and gid information will on unix systems be retrieved from os.FileInfo.Sys if this function returns a syscall.Stat_t when called on a populated entry. Alternatively, if the entry implements FileInfoUidGid, it will be used for uid and gid information.
If a populated entry implements FileInfoExtendedData, extended attributes will also be returned to the client.
The request server code will call Close() on ListerAt if an io.Closer type assertion succeeds.
Note in cases of an error, the error text will be sent to the client.
type LstatFileLister ¶ added in v1.13.0
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 NameLookupFileLister ¶ added in v1.13.3
type NameLookupFileLister interface { FileLister LookupUserName(string) string LookupGroupName(string) string }
NameLookupFileLister is a FileLister that implmeents the LookupUsername and LookupGroupName methods. If this interface is implemented, then longname ls formatting will use these to convert usernames and groupnames.
type OpenFileWriter ¶ added in v1.13.0
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 ¶ added in v1.13.0
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 ReadlinkFileLister ¶ added in v1.13.6
type ReadlinkFileLister interface { FileLister Readlink(string) (string, error) }
ReadlinkFileLister is a FileLister that implements the Readlink method. By implementing the Readlink method, it is possible to return any arbitrary valid path relative or absolute. This allows giving a better response than via the default FileLister (which is limited to os.FileInfo, whose Name method should only return the base name of a file)
type RealPathFileLister ¶ added in v1.13.1
type RealPathFileLister interface { FileLister RealPath(string) (string, error) }
RealPathFileLister is a FileLister that implements the Realpath method. The built-in RealPath implementation does not resolve symbolic links. By implementing this interface you can customize the returned path and, for example, resolve symbolinc links if needed for your use case. You have to return an absolute POSIX path.
Up to v1.13.5 the signature for the RealPath method was:
RealPath(string) string ¶
we have added a legacyRealPathFileLister that implements the old method to ensure that your code does not break. You should use the new method signature to avoid future issues
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 ¶
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 ¶
Attributes parses file attributes byte blob and return them in a FileStat object.
func (*Request) 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.
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 ¶ added in v1.12.0
type RequestServerOption func(*RequestServer)
A RequestServerOption is a function which applies configuration to a RequestServer.
func WithRSAllocator ¶ added in v1.12.0
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
func WithRSMaxTxPacket ¶ added in v1.13.7
func WithRSMaxTxPacket(size uint32) RequestServerOption
WithRSMaxTxPacket sets the maximum size of the payload returned to the client, measured in bytes. The default value is 32768 bytes, and this option can only be used to increase it. Setting this option to a larger value should be safe, because the client decides the size of the requested payload.
The default maximum packet size is 32768 bytes.
func WithStartDirectory ¶ added in v1.13.5
func WithStartDirectory(startDirectory string) RequestServerOption
WithStartDirectory sets a start directory to use as base for relative paths. If unset the default is "/"
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 https://filezilla-project.org/specs/draft-ietf-secsh-filexfer-02.txt
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.
type ServerOption ¶
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 ¶ added in v1.12.0
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.
func WithMaxTxPacket ¶ added in v1.13.7
func WithMaxTxPacket(size uint32) ServerOption
WithMaxTxPacket sets the maximum size of the payload returned to the client, measured in bytes. The default value is 32768 bytes, and this option can only be used to increase it. Setting this option to a larger value should be safe, because the client decides the size of the requested payload.
The default maximum packet size is 32768 bytes.
func WithServerWorkingDirectory ¶ added in v1.13.6
func WithServerWorkingDirectory(workDir string) ServerOption
WithServerWorkingDirectory sets a working directory to use as base for relative paths. If unset the default is current working directory (os.Getwd).
type StatExtended ¶
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) MarshalBinary ¶
MarshalBinary encodes the StatVFS as an SSH_FXP_EXTENDED_REPLY packet.
func (*StatVFS) TotalSpace ¶
TotalSpace calculates the amount of total space in a filesystem.
type StatVFSFileCmder ¶ added in v1.13.0
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 ¶ added in v1.11.0
func (s *StatusError) FxCode() fxerr
FxCode returns the error code typed to match against the exported codes
type TransferError ¶ added in v1.11.0
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
Source Files ¶
- allocator.go
- attrs.go
- attrs_unix.go
- client.go
- conn.go
- errno_posix.go
- ls_formatting.go
- ls_unix.go
- match.go
- packet-manager.go
- packet-typing.go
- packet.go
- pool.go
- release.go
- request-attrs.go
- request-errors.go
- request-example.go
- request-interfaces.go
- request-server.go
- request-unix.go
- request.go
- server.go
- server_statvfs_impl.go
- server_statvfs_linux.go
- server_unix.go
- sftp.go
- stat.go
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. |
internal
|
|
encoding/ssh/filexfer
Package sshfx implements the wire encoding for secsh-filexfer as described in https://filezilla-project.org/specs/draft-ietf-secsh-filexfer-02.txt
|
Package sshfx implements the wire encoding for secsh-filexfer as described in https://filezilla-project.org/specs/draft-ietf-secsh-filexfer-02.txt |
encoding/ssh/filexfer/openssh
Package openssh implements the openssh secsh-filexfer extensions as described in https://github.com/openssh/openssh-portable/blob/master/PROTOCOL
|
Package openssh implements the openssh secsh-filexfer extensions as described in https://github.com/openssh/openssh-portable/blob/master/PROTOCOL |