Documentation
¶
Overview ¶
Package sftp is a generated GoMock package.
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/Clever/sftp"
"golang.org/x/crypto/ssh"
)
func main() {
var 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)
}
Index ¶
- Variables
- func MaxPacket(size int) func(*Client) error
- func TranslatePath(prefix, home, path string) (string, error)
- type Alerter
- 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 Conn
- func (p *Conn) Close() error
- func (p *Conn) LocalAddr() net.Addr
- func (p *Conn) Read(b []byte) (int, error)
- func (p *Conn) RemoteAddr() net.Addr
- func (p *Conn) SetDeadline(t time.Time) error
- func (p *Conn) SetReadDeadline(t time.Time) error
- func (p *Conn) SetWriteDeadline(t time.Time) error
- func (p *Conn) Write(b []byte) (int, error)
- type DriverGenerator
- 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 Listener
- type Logger
- type LoginRequest
- type ManagedServer
- type MockS3API
- func (m *MockS3API) CopyObject(ctx context.Context, input *s3.CopyObjectInput, opts ...func(*s3.Options)) (*s3.CopyObjectOutput, error)
- func (m *MockS3API) DeleteObject(ctx context.Context, input *s3.DeleteObjectInput, opts ...func(*s3.Options)) (*s3.DeleteObjectOutput, error)
- func (m *MockS3API) EXPECT() *MockS3APIMockRecorder
- func (m *MockS3API) GetObject(ctx context.Context, input *s3.GetObjectInput, opts ...func(*s3.Options)) (*s3.GetObjectOutput, error)
- func (m *MockS3API) ListObjectsV2(ctx context.Context, input *s3.ListObjectsV2Input, opts ...func(*s3.Options)) (*s3.ListObjectsV2Output, error)
- func (m *MockS3API) PutObject(ctx context.Context, input *s3.PutObjectInput, opts ...func(*s3.Options)) (*s3.PutObjectOutput, error)
- type MockS3APIMockRecorder
- func (mr *MockS3APIMockRecorder) CopyObject(ctx, input interface{}, opts ...interface{}) *gomock.Call
- func (mr *MockS3APIMockRecorder) DeleteObject(ctx, input interface{}, opts ...interface{}) *gomock.Call
- func (mr *MockS3APIMockRecorder) GetObject(ctx, input interface{}, opts ...interface{}) *gomock.Call
- func (mr *MockS3APIMockRecorder) ListObjectsV2(ctx, input interface{}, opts ...interface{}) *gomock.Call
- func (mr *MockS3APIMockRecorder) PutObject(ctx, input interface{}, opts ...interface{}) *gomock.Call
- type S3
- type S3Driver
- func (d S3Driver) DeleteDir(path string) error
- func (d S3Driver) DeleteFile(path string) error
- func (d S3Driver) GetFile(path string) (io.ReadCloser, error)
- func (d S3Driver) ListDir(path string) ([]os.FileInfo, error)
- func (d S3Driver) MakeDir(path string) error
- func (d S3Driver) PutFile(path string, r io.Reader) error
- func (d S3Driver) RealPath(path string) string
- func (d S3Driver) Rename(oldpath string, newpath string) error
- func (d S3Driver) Stat(path string) (os.FileInfo, error)
- type Server
- type ServerDriver
- type ServerOption
- type SourceChecker
- type StatExtended
- type StatVFS
- type StatusError
- type TestFileDriver
- func (d TestFileDriver) DeleteDir(path string) error
- func (d TestFileDriver) DeleteFile(path string) error
- func (d TestFileDriver) GetFile(path string) (io.ReadCloser, error)
- func (d TestFileDriver) ListDir(path string) ([]os.FileInfo, error)
- func (d TestFileDriver) MakeDir(path string) error
- func (d TestFileDriver) PutFile(path string, r io.Reader) error
- func (d TestFileDriver) RealPath(path string) string
- func (d TestFileDriver) Rename(oldpath string, newpath string) error
- func (d TestFileDriver) Stat(path string) (os.FileInfo, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var BLOCK_DOWNLOADS_IP_ADDRESSES []string
var ( // ErrInvalidUpstream returned if connection fails or is not accepted ErrInvalidUpstream = errors.New("upstream connection address not trusted for PROXY information") )
Functions ¶
func TranslatePath ¶
translatePath takes in a S3 root prefix, a home directory, and either an absolute or relative path to append, and returns a cleaned and validated path. It will resolve things like '..' while disallowing the prefix to be escaped. It also preserves a single trailing slash if one is present, so it can be used on both directories and files.
Types ¶
type Alerter ¶
Alerter is the function signature for an optional alerting function to be called in error cases.
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/Clever/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()
}
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 Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn is used to wrap and underlying connection which may be speaking the Proxy Protocol. If it is, the RemoteAddr() will return the address of the client instead of the proxy address.
func NewConn ¶
NewConn is used to wrap a net.Conn that may be speaking the proxy protocol into a proxyproto.Conn
func (*Conn) Read ¶
Read is check for the proxy protocol header when doing the initial scan. If there is an error parsing the header, it is returned and the socket is closed.
func (*Conn) RemoteAddr ¶
RemoteAddr returns the address of the client if the proxy protocol is being used, otherwise just returns the address of the socket peer. If there is an error parsing the header, the address of the client is not returned, and the socket is closed. Once implication of this is that the call could block if the client is slow. Using a Deadline is recommended if this is called before Read()
func (*Conn) SetReadDeadline ¶
SetReadDeadline sets a timeout for reads
func (*Conn) SetWriteDeadline ¶
SetWriteDeadline sets a timeout for writes
type DriverGenerator ¶
type DriverGenerator func(LoginRequest) ServerDriver
DriverGenerator is a function that creates an SFTP ServerDriver if the login request is valid.
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 Listener ¶
type Listener struct {
Listener net.Listener
ProxyHeaderTimeout time.Duration
SourceCheck SourceChecker
}
Listener is used to wrap an underlying listener, whose connections may be using the HAProxy Proxy Protocol (version 1). If the connection is using the protocol, the RemoteAddr() will return the correct client address.
Optionally define ProxyHeaderTimeout to set a maximum time to receive the Proxy Protocol Header. Zero means no timeout.
type Logger ¶
type Logger interface {
InfoD(title string, meta map[string]interface{})
ErrorD(title string, meta map[string]interface{})
}
Logger is an abstraction for how logging will be performed by the server. It matches a subset of the Clever/kayvee-go library.
type LoginRequest ¶
LoginRequest is the metadata associated with a login request that is passed to the driverGenerator function in order for it to approve/deny the request.
type ManagedServer ¶
type ManagedServer struct {
// contains filtered or unexported fields
}
ManagedServer is our term for the SFTP server.
func NewManagedServer ¶
func NewManagedServer(driverGenerator DriverGenerator, lg Logger, alertFn Alerter) *ManagedServer
NewManagedServer creates a new ManagedServer which conditionally serves requests based on the output of driverGenerator.
type MockS3API ¶
type MockS3API struct {
// contains filtered or unexported fields
}
MockS3API is a mock of S3 interface.
func NewMockS3API ¶
func NewMockS3API(ctrl *gomock.Controller) *MockS3API
NewMockS3API creates a new mock instance.
func (*MockS3API) CopyObject ¶
func (m *MockS3API) CopyObject(ctx context.Context, input *s3.CopyObjectInput, opts ...func(*s3.Options)) (*s3.CopyObjectOutput, error)
CopyObject mocks base method.
func (*MockS3API) DeleteObject ¶
func (m *MockS3API) DeleteObject(ctx context.Context, input *s3.DeleteObjectInput, opts ...func(*s3.Options)) (*s3.DeleteObjectOutput, error)
DeleteObject mocks base method.
func (*MockS3API) EXPECT ¶
func (m *MockS3API) EXPECT() *MockS3APIMockRecorder
EXPECT returns an object that allows the caller to indicate expected use.
func (*MockS3API) GetObject ¶
func (m *MockS3API) GetObject(ctx context.Context, input *s3.GetObjectInput, opts ...func(*s3.Options)) (*s3.GetObjectOutput, error)
GetObject mocks base method.
func (*MockS3API) ListObjectsV2 ¶
func (m *MockS3API) ListObjectsV2(ctx context.Context, input *s3.ListObjectsV2Input, opts ...func(*s3.Options)) (*s3.ListObjectsV2Output, error)
ListObjectsV2 mocks base method.
type MockS3APIMockRecorder ¶
type MockS3APIMockRecorder struct {
// contains filtered or unexported fields
}
MockS3APIMockRecorder is the mock recorder for MockS3API.
func (*MockS3APIMockRecorder) CopyObject ¶
func (mr *MockS3APIMockRecorder) CopyObject(ctx, input interface{}, opts ...interface{}) *gomock.Call
CopyObject indicates an expected call of CopyObject.
func (*MockS3APIMockRecorder) DeleteObject ¶
func (mr *MockS3APIMockRecorder) DeleteObject(ctx, input interface{}, opts ...interface{}) *gomock.Call
DeleteObject indicates an expected call of DeleteObject.
func (*MockS3APIMockRecorder) GetObject ¶
func (mr *MockS3APIMockRecorder) GetObject(ctx, input interface{}, opts ...interface{}) *gomock.Call
GetObject indicates an expected call of GetObject.
func (*MockS3APIMockRecorder) ListObjectsV2 ¶
func (mr *MockS3APIMockRecorder) ListObjectsV2(ctx, input interface{}, opts ...interface{}) *gomock.Call
ListObjectsV2 indicates an expected call of ListObjectsV2.
func (*MockS3APIMockRecorder) PutObject ¶
func (mr *MockS3APIMockRecorder) PutObject(ctx, input interface{}, opts ...interface{}) *gomock.Call
PutObject indicates an expected call of PutObject.
type S3 ¶
type S3 interface {
ListObjectsV2(ctx context.Context, input *s3.ListObjectsV2Input, opts ...func(*s3.Options)) (*s3.ListObjectsV2Output, error)
DeleteObject(ctx context.Context, input *s3.DeleteObjectInput, opts ...func(*s3.Options)) (*s3.DeleteObjectOutput, error)
CopyObject(ctx context.Context, input *s3.CopyObjectInput, opts ...func(*s3.Options)) (*s3.CopyObjectOutput, error)
PutObject(ctx context.Context, input *s3.PutObjectInput, opts ...func(*s3.Options)) (*s3.PutObjectOutput, error)
GetObject(ctx context.Context, input *s3.GetObjectInput, opts ...func(*s3.Options)) (*s3.GetObjectOutput, error)
}
type S3Driver ¶
type S3Driver struct {
// contains filtered or unexported fields
}
func NewS3Driver ¶
func NewS3Driver( bucket, prefix, homePath, region, awsAccessKeyID, awsSecretKey, awsToken, remoteIPAddress string, kmsKeyID *string, lg Logger, ) *S3Driver
NewS3Driver creates a new S3Driver with the AWS credentials and S3 parameters. bucket: name of S3 bucket prefix: key within the S3 bucket, if applicable homePath: default home directory for user (can be different from prefix)
func (S3Driver) DeleteFile ¶
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(rwc io.ReadWriteCloser, driver ServerDriver, 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 ServerDriver ¶
type ServerDriver interface {
Stat(path string) (os.FileInfo, error)
ListDir(path string) ([]os.FileInfo, error)
DeleteDir(path string) error
DeleteFile(path string) error
Rename(oldPath string, newPath string) error
MakeDir(path string) error
GetFile(path string) (io.ReadCloser, error)
PutFile(path string, reader io.Reader) error
RealPath(path string) string
}
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.
type SourceChecker ¶
SourceChecker can be used to decide whether to trust the PROXY info or pass the original connection address through. If set, the connecting address is passed in as an argument. If the function returns an error due to the source being disallowed, it should return ErrInvalidUpstream.
If error is not nil, the call to Accept() will fail. If the reason for triggering this failure is due to a disallowed source, it should return ErrInvalidUpstream.
If bool is true, the PROXY-set address is used.
If bool is false, the connection's remote address is used, rather than the address claimed in the PROXY info.
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 converts the packet to ssh_FXP_EXTENDED_REPLY packet binary format
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
type TestFileDriver ¶
type TestFileDriver struct{}
func (TestFileDriver) DeleteDir ¶
func (d TestFileDriver) DeleteDir(path string) error
func (TestFileDriver) DeleteFile ¶
func (d TestFileDriver) DeleteFile(path string) error
func (TestFileDriver) GetFile ¶
func (d TestFileDriver) GetFile(path string) (io.ReadCloser, error)
func (TestFileDriver) MakeDir ¶
func (d TestFileDriver) MakeDir(path string) error
func (TestFileDriver) RealPath ¶
func (d TestFileDriver) RealPath(path string) string
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
buffered-read-benchmark
command
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
command
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
command
An example SFTP server implementation using the golang SSH package.
|
An example SFTP server implementation using the golang SSH package. |
|
streaming-read-benchmark
command
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
command
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. |