README
¶
sftp
The sftp package provides support for file system operations on remote ssh servers using the SFTP subsystem.
usage and examples
See godoc.org/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
- Currently all traffic with the server is serialized, this can be improved by allowing overlapping requests/responses.
- 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.
- Implement integration tests by talking directly to a real opensftp-server process. This shouldn't be too difficult to implement with a small refactoring to the sftp.NewClient method. These tests should be gated on an -sftp.integration test flag. in progress
contributing
We welcome pull requests, bug fixes and issue reports.
Before proposing a large change, first please discuss your change by raising an issue.
Documentation
¶
Overview ¶
Package sftp implements the SSH File Transfer Protocol as described in https://filezilla-project.org/specs/draft-ietf-secsh-filexfer-02.txt
Index ¶
- func MaxPacket(size int) func(*Client) error
- 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) Join(elem ...string) string
- func (c *Client) Lstat(p string) (os.FileInfo, error)
- func (c *Client) Mkdir(path string) error
- func (c *Client) Open(path string) (*File, error)
- func (c *Client) OpenFile(path string, f int) (*File, error)
- func (c *Client) ReadDir(p string) ([]os.FileInfo, error)
- func (c *Client) ReadLink(p string) (string, error)
- func (c *Client) Remove(path string) error
- func (c *Client) Rename(oldname, newname string) 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) Walk(root string) *fs.Walker
- 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) ReadFrom(r io.Reader) (int64, error)
- func (f *File) Seek(offset int64, whence int) (int64, error)
- func (f *File) Stat() (os.FileInfo, error)
- func (f *File) Truncate(size int64) error
- func (f *File) Write(b []byte) (int, error)
- func (f *File) WriteTo(w io.Writer) (int64, error)
- type FileStat
- type Server
- type ServerOption
- type StatExtended
- type StatVFS
- type StatusError
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 NewClientPipe ¶
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"
"golang.org/x/crypto/ssh"
)
func main(conn *ssh.Client) {
// open an SFTP session over an existing ssh connection.
sftp, err := sftp.NewClient(conn)
if err != nil {
log.Fatal(err)
}
defer sftp.Close()
// walk a directory
w := sftp.Walk("/home/user")
for w.Step() {
if w.Err() != nil {
continue
}
log.Println(w.Path())
}
// leave your mark
f, err := sftp.Create("hello.txt")
if err != nil {
log.Fatal(err)
}
if _, err := f.Write([]byte("Hello world!")); err != nil {
log.Fatal(err)
}
// check it's there
fi, err := sftp.Lstat("hello.txt")
if err != nil {
log.Fatal(err)
}
log.Println(fi)
}
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) 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.
func (*Client) Getwd ¶
Getwd returns the current working directory of the server. Operations involving relative paths will be based at this location.
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) 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).
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) ReadDir ¶
ReadDir reads the directory named by dirname and returns a list of directory entries.
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) 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.
type File ¶
type File struct {
// contains filtered or unexported fields
}
File represents a remote file.
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. EOF is signaled by a zero count with err set to io.EOF.
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.
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) 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.
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()
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(in io.Reader, out io.WriteCloser, 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 WithDebug ¶
func WithDebug(w io.Writer) ServerOption
WithDebug enables Server debugging output to the supplied io.Writer.
func WithRootDir ¶
func WithRootDir(rootDir string) ServerOption
WithRootDir configures a new location to be used as a root for file access. Setting root directory to an empty path results in unrestricted file access, when client works with absolute paths.
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) TotalSpace ¶
TotalSpace calculates the amount of total space in a filesystem.
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
Source Files
¶
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. |
|
sftp-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. |