sftp

func (*Client) Chmod ¶

func (cl *Client) Chmod(name string, mode fs.FileMode) error

Chmod changes the mode of the named file to mode. If the file is a symbolic link, it changes the mode of the link's target.

The Go FileMdoe, will be converted to a "portable" POSIX file permission, and then sent to the server. The server is then responsible for interpreting that permission. It is possible the server and this client disagree on what some flags mean.

func (*Client) Chown ¶

func (cl *Client) Chown(name string, uid, gid int) error

Chown changes the numeric uid and gid of the named file. If the file is a symbolic link, it changes the uid and gid of the link's target.

os.Chown provides that a uid or gid of -1 means to not change that value, but we cannot guarantee the same semantics here. The server is told to set the uid and gid as given, and it is up to the server to define that behavior.

func (*Client) Chtimes ¶

func (cl *Client) Chtimes(name string, atime, mtime time.Time) error

Chtimes changes the access and modification times of the named file, similar to the Unix utime() or utimes() functions.

The SFTP protocol only supports an accuracy to the second, so these times will be truncated to the second before being sent to the server. The server may additional truncate or round the values to an even less precise time unit.

os.Chtimes provides that a zero time.Time value will leave the corresponding file time unchanged, but we cannot guarantee the same semantics here. The server is told to set the atime and mtime as given, and it is up to the server to define that behavior.

func (*Client) Close ¶

func (cl *Client) Close() error

Close closes the SFTP session.

func (*Client) Create ¶

func (cl *Client) Create(name string) (*File, error)

Create creates of truncates the named file. If the file already exists, it is truncated. If the file does not exist, it is created with mode 0o666 (before umask). If successful, methods on the returned File can be used for I/O; the associated file handle has mode OpenFlagReadWrite.

func (*Client) DirFS ¶

func (cl *Client) DirFS(dir string) fs.FS

DirFS returns a file system (an fs.FS) for the tree of files rooted at the directory dir.

Note that cl.DirFS("/prefix") only guarantees that the Open calls it makes to the remote system will begin with "/prefix": cl.DirFS("/prefix").Open("file") is the same as cl.Open("/prefix/file"). So, if /prefix/file is a symbolic link pointing outside the /prefix tree, then using DirFS does not stop the access any more than using cl.Open does. DirFS is therefore not a general substitute for a chroot-style security mechanism when the directory tree contains arbitrary content.

The directory dir must not be "".

The result implements io/fs.StatFS, io/fs.ReadFileFS, and io/fs.ReadDirFS.

func (*Client) LStat ¶

func (cl *Client) LStat(name string) (fs.FileInfo, error)

LStat returns a FileInfo describing the named file. If the file is a symbolic link, the returned FileInfo describes the symbolic link LStat makes no attempte to follow the link.

The description returned may have server specific caveats and special cases that cannot be covered here.

func (*Client) Link ¶

func (cl *Client) Link(oldname, newname string) error

Link creates newname as a hard link to oldname file.

If the server did not announce support for the "[email protected]" extension, then no request will be sent, and Link returns an *fs.LinkError wrapping sshfx.StatusOpUnsupported.

func (*Client) Mkdir ¶

func (cl *Client) Mkdir(name string, perm fs.FileMode) 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.

func (*Client) MkdirAll ¶

func (cl *Client) MkdirAll(name string, perm fs.FileMode) error

MkdirAll creates a directory named path, along with any necessary parents. If a path is already a directory, MkdirAll does nothing and returns nil.

func (*Client) Open ¶

func (cl *Client) Open(name 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 handle has mode OpenFlagReadOnly.

func (*Client) OpenDir ¶

func (cl *Client) OpenDir(name string) (*Dir, error)

OpenDir opens the named directory for reading. If successful, methods on the returned Dir can be used for reading.

The semantics of SSH_FX_OPENDIR is such that the associated file handle is in a read-only mode.

func (*Client) OpenFile ¶

func (cl *Client) OpenFile(name string, flag int, perm fs.FileMode) (*File, error)

OpenFile is the generalized open call; most users can use the simplified Open or Create methods instead. It opens the named file with the specified flag (OpenFlagReadOnly, etc.). If the file does not exist, and the OpenFileCreate flag is passed, it is created with mode perm (before umask). If successful, methods on the returned File can be used for I/O.

Note well: since all Write operations are down through an offset-specifying operation, the OpenFlagAppend flag is currently ignored.

func (*Client) ReadDir ¶

func (cl *Client) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir reads the named directory, returning all its directory entries sorted by filename. If an error occurs reading the directory, ReadDir returns the entries it was able to read before the error, along with the error.

func (*Client) ReadDirContext ¶

func (cl *Client) ReadDirContext(ctx context.Context, name string) ([]fs.DirEntry, error)

ReadDirContext reads the named directory, returning all its directory entries sorted by filename. If an error occurs reading the directory, including the context being canceled, ReadDir returns the entries is was able to read before the error, along with the error.

func (*Client) ReadFile ¶

func (cl *Client) ReadFile(name string) ([]byte, error)

ReadFile reads the named file and returns the contents. A successful call returns err == nil, not err == EOF. Because ReadFile reads the whole file, it does not treat an EOF from Read as an error to be reported.

Note that ReadFile will call Stat on the file to get the file size, in order to avoid unnecessary allocations before reading in all the data. Some "read once" servers will delete the file if they recceive a stat call on an open file, and then the download will fail.

TODO(puellannivis): Before release, we should resolve this, or have knobs to prevent it.

func (*Client) ReadLink ¶

func (cl *Client) ReadLink(name string) (string, error)

ReadLink returns the destination of the named symbolic link.

The client cannot guarantee any specific way that a server handles a relative link destination. That is, you may receive a relative link destination, one that has been converted to an absolute path.

func (*Client) Readdir ¶

func (cl *Client) Readdir(name string) ([]fs.FileInfo, error)

Readdir reads the named directory, returning all its directory entries as fs.FileInfo sorted by filename. If an error occurs reading the directory, Readdir returns the entries it was able to read before the error, along with the error.

func (*Client) RealPath ¶

func (cl *Client) RealPath(name string) (string, error)

RealPath returns the server canonicalized absolute path for the given path name. 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(name string) error

Remove removes the named file or (empty) directory.

If both operations fail, then Remove will stat the named filesystem object. It then returns the error from that SSH_FX_STAT request if one occurs, or the error from the SSH_FX_RMDIR request if it is a directory, otherwise returning the error from the SSH_FX_REMOVE request.

func (*Client) Rename ¶

func (cl *Client) Rename(oldpath, newpath string) error

Rename renames (moves) oldpath to newpath. If newpath already exists and is not a directory, Rename replaces it. Server-specific restrictions may apply when old path and new path are in different directories. Even within the same directory, on non-Unix servers Rename is not guaranteed to be an atomic operation.

func (*Client) ReportPoolMetrics ¶

func (cl *Client) ReportPoolMetrics(wr io.Writer)

ReportPoolMetrics writes buffer pool metrics to the given writer, if pool metrics are enabled. It is expected that this is only useful during testing, and benchmarking.

To enable you must include `-tag sftp.sync.metrics` to your go command-line.

func (*Client) Stat ¶

func (cl *Client) Stat(name string) (fs.FileInfo, error)

Stat returns a FileInfo describing the named file. If the file is a symbolic link, the returned FileInfo describes the link's target.

func (*Client) StatVFS ¶

func (cl *Client) StatVFS(path string) (*openssh.StatVFSExtendedReplyPacket, error)

StatVFS retrieves VFS statistics from a remote host.

It implements the [email protected] SSH_FXP_EXTENDED feature from https://github.com/openssh/openssh-portable/blob/master/PROTOCOL

func (*Client) Symlink ¶

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

Symlink creates newname as a symbolic link to oldname. There is no guarantee for how a server may handle the request if oldname does not exist.

func (*Client) Truncate ¶

func (cl *Client) Truncate(name string, size int64) error

Truncate changes the size of the named file. If the file is a symbolic link, it changes the size of the link's target.

func (*Client) WriteFile ¶

func (cl *Client) WriteFile(name string, data []byte, perm fs.FileMode) error

WriteFile writes data to the named file, creating it if neccessary. If the file does not exist, WriteFile creates it with permissions perm (before umask); otherwise WriteFile truncates it before writing, without changing permissions. Since WriteFile requires multiple system calls to complete, a failure mid-operation can leave the file in a partially written state.

func (*Dir) Close ¶

func (d *Dir) Close() error

Close closes the Dir, rendering it unusable for I/O. Close will not send any request, and return an error if it has already been called.

func (*Dir) Name ¶

func (d *Dir) Name() string

Name returns the name of the directory as presented to OpenDir.

func (*Dir) ReadDir ¶

func (d *Dir) ReadDir(n int) ([]fs.DirEntry, error)

ReadDir calls [ReadDirContext] with the background context.

func (*Dir) ReadDirContext ¶

func (d *Dir) ReadDirContext(ctx context.Context, n int) ([]fs.DirEntry, error)

ReadDirContext reads the contents of the directory and returns a slice of up to n fs.DirEntry values, as they were returned from the server, in directory order. Subsequent calls to the same file will yield later DirEntry records in the directory.

If n > 0, ReadDirContext returns as most n DirEntry records. In this case, if ReadDirContext returns an empty slice, it will return an error explaining why. At the end of a directory, the error is io.EOF.

If n <= 0, ReadDirContext returns all the DirEntry records remaining in the directory. When it succeeds, it returns a nil error (not io.EOF).

func (*Dir) Readdir ¶

func (d *Dir) Readdir(n int) ([]fs.FileInfo, error)

Readdir calls [ReaddirContext] with the background context.

func (*Dir) ReaddirContext ¶

func (d *Dir) ReaddirContext(ctx context.Context, n int) ([]fs.FileInfo, error)

ReaddirContext reads the contents of the directory and returns a slice of up to n fs.FileInfo values, as they were returned from the server, in directory order. Subsequent calls to the same file will yield later FileInfo records in the directory.

If n > 0, ReaddirContext returns as most n FileInfo records. In this case, if ReadDirContext returns an empty slice, it will return an error explaining why. At the end of a directory, the error is io.EOF.

If n <= 0, ReaddirContext returns all the FileInfo records remaining in the directory. When it succeeds, it returns a nil error (not io.EOF).

func (*File) Chmod ¶

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

Chmod changes the mode of the file to mode.

The Go FileMode will be converted to a "portable" POSIX file permission, and then sent to the server. The server is then responsible for interpreting that permission. It is possible the server and this client disagree on what some flags mean.

func (*File) Chown ¶

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

Chown changes the numeric uid and gid of the named file. The server is told to set the uid and gid as given, and it is up to the server to define that behavior.

func (*File) Chtimes ¶

func (f *File) Chtimes(atime, mtime time.Time) error

Chtimes sends a request to change the access and modification times of the file.

Be careful, the server may later alter the access or modification time upon Close of this file. To ensure the times stick, you should Close the file, and then use Client.Chtimes to update the times.

func (*File) Close ¶

func (f *File) Close() error

Close closes the File, rendering it unusable for I/O. Close will not send any request, and return an error if it has already been called.

func (*File) Name ¶

func (f *File) Name() string

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

It is safe to call Name after Close.

func (*File) Read ¶

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

Read reads up to len(b) bytes from the File and stores them in b. It returns the number of bytes read and any error encountered. At end of file, Read returns 0, io.EOF.

func (*File) ReadAt ¶

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

ReadAt reads len(b) bytes from the File starting at byte offset off. It returns the number of bytes read and the error, if any. ReadAt always returns a non-nil error when n < len(b). At the end of file, the error is io.EOF.

func (*File) ReadFrom ¶

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

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

This method is prefered over calling Write multiple times to maximize throughput when transferring an entire file, especially over high-latency links.

func (*File) Seek ¶

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

Seek sets the offset for the next Read or Write on file to offset, interpreted accoreding to whence: SeekStart means relative to the origin of the file, SeekCurrent means relative to the current offset, and SeekEnd means relative to the end. It returns the new offset and an error, if any.

Note well, a whence of SeekEnd will make an SSH_FX_FSTAT request on the file handle. In some cases, this may mark a "mailbox"-style file as successfuly read, and the server will delete the file, and return an error for all later operations.

func (*File) Stat ¶

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

Stat returns the FileInfo structure describing file.

func (*File) Sync ¶

func (f *File) Sync() error

Sync commits the current contents of the file to stable storage. Typically, this means flushing the file system's in-memory copy of recently written data to disk.

If the server did not announce support for the "[email protected]" extension, then no request will be sent, and Sync returns an *fs.PathError wrapping sshfx.StatusOpUnsupported.

func (*File) Truncate ¶

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

Truncate changes the size of the file. It does not change the I/O offset.

func (*File) Write ¶

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

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

func (*File) WriteAt ¶

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

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

func (*File) WriteString ¶

func (f *File) WriteString(s string) (n int, err error)

WriteString is like Write, but writes the contents of the string s rather than a slice of bytes.

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, which may be different than the bytes read. Any error encountered during the write is also returned.

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

func (*Server) DirFromHandle ¶

func (srv *Server) DirFromHandle(handle string) (DirHandler, error)

DirFromHandle returns the DirHandler associated with the given handle. It returns an error if there is no handler associated with the handle, or if the handler is not a FileHandler.

func (*Server) FileFromHandle ¶

func (srv *Server) FileFromHandle(handle string) (FileHandler, error)

FileFromHandle returns the FileHandler associated with the given handle. It returns an error if there is no handler associated with the handle, or if the handler is not a FileHandler.

func (*Server) GracefulStop ¶

func (srv *Server) GracefulStop() error

GracefulStop stops the SFTP server gracefully.

func (*Server) Serve ¶

func (srv *Server) Serve(conn io.ReadWriteCloser) error

Serve accepts incoming connections on the socket conn. The server reads SFTP requests and then calls the registered handlers to reply to them. Serve returns when a read returns any error other than sshfx.ErrBadMessage, or a write returns any error. conn will be closed when this method returns. Serve will return a non-nil error unless GracefulStop is called, or an EOF is encountered at the end of a complete packet.

func (UnimplementedServerHandler) LStat ¶

func (UnimplementedServerHandler) LStat(_ context.Context, req *sshfx.LStatPacket) (*sshfx.Attributes, error)

LStat returns an sshfx.StatusOpUnsupported error.

func (UnimplementedServerHandler) Mkdir ¶

func (UnimplementedServerHandler) Mkdir(_ context.Context, req *sshfx.MkdirPacket) error

Mkdir returns an sshfx.StatusOpUnsupported error.

func (UnimplementedServerHandler) Open ¶

func (UnimplementedServerHandler) Open(_ context.Context, req *sshfx.OpenPacket) (FileHandler, error)

Open returns an sshfx.StatusOpUnsupported error.

func (UnimplementedServerHandler) OpenDir ¶

func (UnimplementedServerHandler) OpenDir(_ context.Context, req *sshfx.OpenDirPacket) (DirHandler, error)

OpenDir returns an sshfx.StatusOpUnsupported error.

func (UnimplementedServerHandler) ReadLink ¶

func (UnimplementedServerHandler) ReadLink(_ context.Context, req *sshfx.ReadLinkPacket) (string, error)

ReadLink returns an sshfx.StatusOpUnsupported error.

func (UnimplementedServerHandler) RealPath ¶

func (UnimplementedServerHandler) RealPath(_ context.Context, req *sshfx.RealPathPacket) (string, error)

RealPath returns an sshfx.StatusOpUnsupported error.

func (UnimplementedServerHandler) Remove ¶

func (UnimplementedServerHandler) Remove(_ context.Context, req *sshfx.RemovePacket) error

Remove returns an sshfx.StatusOpUnsupported error.

func (UnimplementedServerHandler) Rename ¶

func (UnimplementedServerHandler) Rename(_ context.Context, req *sshfx.RenamePacket) error

Rename returns an sshfx.StatusOpUnsupported error.

func (UnimplementedServerHandler) Rmdir ¶

func (UnimplementedServerHandler) Rmdir(_ context.Context, req *sshfx.RmdirPacket) error

Rmdir returns an sshfx.StatusOpUnsupported error.

func (UnimplementedServerHandler) SetStat ¶

func (UnimplementedServerHandler) SetStat(_ context.Context, req *sshfx.SetStatPacket) error

SetStat returns an sshfx.StatusOpUnsupported error.

func (UnimplementedServerHandler) Stat ¶

func (UnimplementedServerHandler) Stat(_ context.Context, req *sshfx.StatPacket) (*sshfx.Attributes, error)

Stat returns an sshfx.StatusOpUnsupported error.

func (UnimplementedServerHandler) Symlink ¶

func (UnimplementedServerHandler) Symlink(_ context.Context, req *sshfx.SymlinkPacket) error

Symlink returns an sshfx.StatusOpUnsupported error.