sftp

package
v0.49.0 Latest Latest
Warning

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

Go to latest
Published: Aug 4, 2023 License: BSD-3-Clause Imports: 10 Imported by: 1

Documentation

Overview

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

View Source
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

View Source
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,

SSH_FX_EOF               (1) = io.EOF
SSH_FX_NO_SUCH_FILE      (2) = fs.ErrNotExist
SSH_FX_PERMISSION_DENIED (3) = fs.ErrPermission

Other errors is defined below,

Functions

This section is empty.

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(fh *FileHandle) (err error)

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

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

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() interface{}

Sys return the pointer to FileAttrs itself.

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
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL