sftp

package
Version: v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Aug 21, 2015 License: BSD-2-Clause, BSD-2-Clause Imports: 15 Imported by: 0

README

sftp

The sftp package provides support for file system operations on remote ssh servers using the SFTP subsystem.

Build Status

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

Features, Issues, and Pull Requests are always welcome.

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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func MaxPacket

func MaxPacket(size int) func(*Client) error

MaxPacket sets the maximum size of the payload.

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 NewClient

func NewClient(conn *ssh.Client, opts ...func(*Client) error) (*Client, error)

New creates a new SFTP client on conn.

func NewClientPipe

func NewClientPipe(rd io.Reader, wr io.WriteCloser, opts ...func(*Client) error) (*Client, error)

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"

	"golang.org/x/crypto/ssh"

	"github.com/pkg/sftp"
)

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

func (c *Client) Chmod(path string, mode os.FileMode) error

Chmod changes the permissions of the named file.

func (*Client) Chown

func (c *Client) Chown(path string, uid, gid int) error

Chown changes the user and group owners of the named file.

func (*Client) Chtimes

func (c *Client) Chtimes(path string, atime time.Time, mtime time.Time) error

Chtimes changes the access and modification times of the named file.

func (*Client) Close

func (c *Client) Close() error

Close closes the SFTP session.

func (*Client) Create

func (c *Client) Create(path string) (*File, error)

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

func (c *Client) Join(elem ...string) string

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

func (c *Client) Lstat(p string) (os.FileInfo, error)

func (*Client) Mkdir

func (c *Client) Mkdir(path string) error

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

func (c *Client) Open(path 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 descriptor has mode O_RDONLY.

func (*Client) OpenFile

func (c *Client) OpenFile(path string, f int) (*File, error)

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

func (c *Client) ReadDir(p string) ([]os.FileInfo, error)

ReadDir reads the directory named by dirname and returns a list of directory entries.

func (c *Client) ReadLink(p string) (string, error)

ReadLink reads the target of a symbolic link.

func (*Client) Remove

func (c *Client) Remove(path string) error

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

func (c *Client) Rename(oldname, newname string) error

Rename renames a file.

func (*Client) StatVFS

func (c *Client) StatVFS(path string) (*StatVFS, error)

Get vfs stats from remote host. Implementing statvfs@openssh.com SSH_FXP_EXTENDED feature from http://www.opensource.apple.com/source/OpenSSH/OpenSSH-175/openssh/PROTOCOL?txt

func (*Client) Truncate

func (c *Client) Truncate(path string, size int64) error

Truncate sets the size of the named 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.

func (*Client) Walk

func (c *Client) Walk(root string) *fs.Walker

Walk returns a new Walker rooted at root.

type File

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

File represents a remote file.

func (*File) Chmod

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

Chmod changes the permissions of the current file.

func (*File) Chown

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

Chown changes the uid/gid of the current file.

func (*File) Close

func (f *File) Close() error

Close closes the File, rendering it unusable for I/O. It returns an error, if any.

func (*File) Read

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

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

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

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

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

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

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

Stat returns the FileInfo structure describing file. If there is an error.

func (*File) Truncate

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

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.

func (*File) Write

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

Write writes len(b) bytes 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) WriteTo

func (f *File) WriteTo(w io.Writer) (int64, error)

WriteTo writes the file to w. The return value is the number of bytes written. Any error encountered during the write is also returned.

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 StatExtended

type StatExtended struct {
	ExtType string
	ExtData string
}

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 */
}

func (*StatVFS) FreeSpace

func (p *StatVFS) FreeSpace() uint64

func (*StatVFS) TotalSpace

func (p *StatVFS) TotalSpace() uint64

type StatusError

type StatusError struct {
	Code uint32
	// contains filtered or unexported fields
}

func (*StatusError) Error

func (s *StatusError) Error() string

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

Jump to

Keyboard shortcuts

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