package sftp

import "git.sr.ht/~shulhan/pakakeh.go/lib/ssh/sftp"

Package sftp implement SSH File Transfer Protocol v3 as defined in draft-ietf-secsh-filexfer-02.txt.

The sftp package extend the golang.org/x/crypto/ssh package by implementing "sftp" subsystem using the ssh.Client connection.

For information, even if scp working normally on server, this package functionalities will not working if the server disable or does not support the "sftp" subsystem. For reference, on openssh, the following configuration 

Subsystem sftp /usr/lib/sftp-server

should be un-commented on /etc/ssh/sshd_config if its exist.

Index

Constants 

const (
	// OpenFlagRead open remote file for read only.
	OpenFlagRead uint32 = 0x00000001

	// OpenFlagWrite open remote file for write only.
	OpenFlagWrite uint32 = 0x00000002

	// OpenFlagAppend any write to remote file handle opened with this
	// file will be appended at the end of the file.
	OpenFlagAppend uint32 = 0x00000004

	// OpenFlagCreate create new file on the server if it does not exist.
	OpenFlagCreate uint32 = 0x00000008

	// OpenFlagTruncate truncated the remote file.
	// OpenFlagCreate MUST also be specified.
	OpenFlagTruncate uint32 = 0x00000010

	// OpenFlagExcl passing this flag along OpenFlagCreate will fail the
	// remote file already exists.
	// OpenFlagCreate MUST also be specified.
	OpenFlagExcl uint32 = 0x00000020
)

List of valid values for OpenFile flag.

Variables 

var (
	// ErrFailure or SSH_FX_FAILURE(4) is a generic catch-all error
	// message; it should be returned if an error occurs for which there
	// is no more specific error code defined.
	ErrFailure = errors.New("sftp: failure")

	// ErrBadMessage or SSH_FX_BAD_MESSAGE(5) may be returned if a badly
	// formatted packet or protocol incompatibility is detected.
	ErrBadMessage = errors.New("sftp: bad message")

	// ErrNoConnection or SSH_FX_NO_CONNECTION(6) indicates that the
	// client has no connection to the server.
	// This error returned by client not server.
	ErrNoConnection = errors.New("sftp: no connection")

	// ErrConnectionLost or SSH_FX_CONNECTION_LOST(7) indicated that the
	// connection to the server has been lost.
	// This error returned by client not server.
	ErrConnectionLost = errors.New("sftp: connection lost")

	// ErrOpUnsupported or SSH_FX_OP_UNSUPPORTED(8) indicates that an
	// attempt was made to perform an operation which is not supported for
	// the server or the server does not implement an operation.
	ErrOpUnsupported = errors.New("sftp: operation unsupported")

	// ErrSubsystem indicates that the server does not support or enable
	// the Subsystem for sftp.
	// For reference, on openssh, the following configuration
	//
	//	Subsystem sftp /usr/lib/sftp-server
	//
	// maybe commented on /etc/ssh/sshd_config.
	//
	ErrSubsystem = errors.New("sftp: unsupported subsystem")

	// ErrVersion indicates that this client does not support the version
	// on server.
	ErrVersion = errors.New("sftp: unsupported version")
)

Some response status code from server is mapped to existing errors on standard packages,

Other errors is defined below,

Types

type Client 

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

Client for SFTP.

func NewClient 

func NewClient(sshc *ssh.Client) (cl *Client, err error)

NewClient create and initialize new client for SSH file transfer protocol.

On failure, it will return ErrSubsystem if the server does not support "sftp" subsystem, ErrVersion if the client does not support the server version, and other errors.

func (*Client) Close 

func (cl *Client) Close() (err error)

Close the client sftp session and release all resources.

func (*Client) CloseFile 

func (cl *Client) CloseFile(fh *FileHandle) (err error)

CloseFile close the remote file handle.

func (*Client) Create 

func (cl *Client) Create(remoteFile string, fa *FileAttrs) (*FileHandle, error)

Create creates or truncates the named file. If the remote file does not exist, it will be created. If the remote file already exists, it will be truncated. On success, it will return the remote FileHandle ready for write only.

func (*Client) Fsetstat 

func (cl *Client) Fsetstat(fh *FileHandle, fa *FileAttrs) (err error)

Fsetstat set the file attributes based on the opened remote file handle.

func (*Client) Fstat 

func (cl *Client) Fstat(fh *FileHandle) (fa *FileAttrs, err error)

Fstat get the file attributes based on the opened remote file handle.

func (*Client) Get 

func (cl *Client) Get(remoteFile, localFile string) (err error)

Get copy remote file to local. The local file will be created if its not exist; otherwise it will truncated.

func (*Client) Lstat 

func (cl *Client) Lstat(remoteFile string) (fa *FileAttrs, err error)

Lstat get the file attributes based on the remote file path. Unlike Client.Stat, the Lstat method does not follow symbolic links.

func (*Client) Mkdir 

func (cl *Client) Mkdir(path string, fa *FileAttrs) (err error)

Mkdir create new directory on the server.

func (*Client) MkdirAll 

func (cl *Client) MkdirAll(dir string, fa *FileAttrs) (err error)

MkdirAll create directory on the server, from left to right. Each directory is separated by '/', where the left part is the parent of the right part. This method is similar to os.MkdirAll.

Note that using `~` as home directory is not working. If you want to create directory under home, use relative path, for example "a/b/c" will create directory "~/a/b/c".

func (*Client) Open 

func (cl *Client) Open(remoteFile string) (fh *FileHandle, err error)

Open the remote file for read only.

func (*Client) OpenFile 

func (cl *Client) OpenFile(remoteFile string, flags uint32, fa *FileAttrs) (fh *FileHandle, err error)

OpenFile open remote file with custom open flag (OpenFlagRead, OpenFlagWrite, and so on) and with specific file attributes.

func (*Client) Opendir 

func (cl *Client) Opendir(path string) (fh *FileHandle, err error)

Opendir open the directory on the server.

func (*Client) Put 

func (cl *Client) Put(localFile, remoteFile string) (err error)

Put local file to remote file.

func (*Client) Read 

func (cl *Client) Read(fh *FileHandle, offset uint64) (data []byte, err error)

Read the remote file using handle on specific offset. On end-of-file it will return empty data with io.EOF.

func (*Client) Readdir 

func (cl *Client) Readdir(fh *FileHandle) (nodes []fs.DirEntry, err error)

Readdir list files and/or directories inside the handle. 

func (cl *Client) Readlink(linkPath string) (node fs.DirEntry, err error)

Readlink read the target of a symbolic link.

func (*Client) Realpath 

func (cl *Client) Realpath(path string) (node fs.DirEntry, err error)

Realpath 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 (cl *Client) Remove(remoteFile string) (err error)

Remove the remote file.

func (*Client) Rename 

func (cl *Client) Rename(oldPath, newPath string) (err error)

Rename the file, or move the file, from old path to new path.

func (*Client) Rmdir 

func (cl *Client) Rmdir(path string) (err error)

Rmdir remove the directory on the server.

func (*Client) Setstat 

func (cl *Client) Setstat(remoteFile string, fa *FileAttrs) (err error)

Setstat change the file attributes on remote file or directory. These request can be used for operations such as changing the ownership, permissions or access times, as well as for truncating a file.

func (*Client) Stat 

func (cl *Client) Stat(remoteFile string) (fa *FileAttrs, err error)

Stat get the file attributes based on the remote file path. This method follow symbolic links.

To stat the user's home directory pass empty string or '.' in remoteFile parameter. 

func (cl *Client) Symlink(targetPath, linkPath string) (err error)

Symlink create a symbolic link on the server. The `linkpath' specifies the path name of the symlink to be created and `targetpath' specifies the target of the symlink.

func (*Client) Write 

func (cl *Client) Write(fh *FileHandle, offset uint64, data []byte) (err error)

Write write the data into remote file at specific offset.

type FileAttrs 

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

FileAttrs define the attributes for opening or creating file on the remote.

func NewFileAttrs 

func NewFileAttrs(fi fs.FileInfo) (fa *FileAttrs)

NewFileAttrs create and initialize FileAttrs from fs.FileInfo.

func (*FileAttrs) AccessTime 

func (fa *FileAttrs) AccessTime() uint32

AccessTime return the remote file access time.

func (*FileAttrs) Extensions 

func (fa *FileAttrs) Extensions() map[string]string

Extensions return the remote file attribute extensions as map of type and data.

func (*FileAttrs) Gid 

func (fa *FileAttrs) Gid() uint32

Gid return the group ID attribute of file.

func (*FileAttrs) IsDir 

func (fa *FileAttrs) IsDir() bool

IsDir return true if the file is a directory.

func (*FileAttrs) ModTime 

func (fa *FileAttrs) ModTime() time.Time

ModTime return the remote file modified time.

func (*FileAttrs) Mode 

func (fa *FileAttrs) Mode() fs.FileMode

Mode return the file mode bits as standard fs.FileMode type.

func (*FileAttrs) Name 

func (fa *FileAttrs) Name() string

Name return the name of file.

func (*FileAttrs) Permissions 

func (fa *FileAttrs) Permissions() uint32

Permissions return the remote file mode and permissions.

func (*FileAttrs) SetAccessTime 

func (fa *FileAttrs) SetAccessTime(v uint32)

SetAccessTime set the file attribute access time.

func (*FileAttrs) SetExtension 

func (fa *FileAttrs) SetExtension(name, data string)

SetExtension set the file attribute extension.

func (*FileAttrs) SetGid 

func (fa *FileAttrs) SetGid(gid uint32)

SetGid set the file attribute group ID.

func (*FileAttrs) SetModifiedTime 

func (fa *FileAttrs) SetModifiedTime(v uint32)

SetModifiedTime set the file attribute modified time.

func (*FileAttrs) SetPermissions 

func (fa *FileAttrs) SetPermissions(v uint32)

SetPermissions set the remote file permission.

func (*FileAttrs) SetSize 

func (fa *FileAttrs) SetSize(v uint64)

SetSize set the remote file size.

func (*FileAttrs) SetUID 

func (fa *FileAttrs) SetUID(uid uint32)

SetUID set the file attribute user ID.

func (*FileAttrs) Size 

func (fa *FileAttrs) Size() int64

Size return the file size information.

func (*FileAttrs) Sys 

func (fa *FileAttrs) Sys() any

Sys return the pointer to FileAttrs itself. This method is added to comply with fs.FileInfo interface.

func (*FileAttrs) UID 

func (fa *FileAttrs) UID() uint32

UID return the user ID of file.

type FileHandle 

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

FileHandle define the container to store remote file.

Source Files

client.go dir_entry.go extensions.go file_attrs.go file_handle.go packet.go sftp.go

Version
v0.60.0 (latest)
Published
Feb 1, 2025
Platform
linux/amd64
Imports
12 packages
Last checked
1 minute ago –

Tools for package owners.