guestfile

package
v0.18.6 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package guestfile reads and writes files inside a running VM over SFTP.

It is used by the web UI's file browser. Paths are always absolute guest paths; the guest user is whoever the SSH connection authenticated as.

Index

Constants

View Source
const DialTimeout = 10 * time.Second

DialTimeout bounds how long connecting to a VM's SSH server may take.

Variables

View Source
var (
	// ErrTooLarge is returned by Upload when the data exceeds the size limit.
	ErrTooLarge = errors.New("upload exceeds the size limit")
	// ErrIsDir is returned when a file operation names a directory.
	ErrIsDir = errors.New("is a directory")
	// ErrNotRegular is returned when downloading a device, socket or FIFO.
	ErrNotRegular = errors.New("is not a regular file")
)

Functions

func CleanName

func CleanName(name string) (string, error)

CleanName validates a file name for an upload: a single path element that is not "." or "..".

func CleanPath

func CleanPath(p string) (string, error)

CleanPath validates a guest path from a request: it must be absolute and contain no NUL bytes. The result is lexically cleaned.

Types

type Client

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

Client is an SFTP session to one VM.

func Dial

func Dial(ip, user string, auth []ssh.AuthMethod) (*Client, error)

Dial opens an SFTP session to the guest at ip as user.

func (*Client) Close

func (c *Client) Close() error

Close ends the SFTP session and the SSH connection under it.

func (*Client) Home

func (c *Client) Home() string

Home returns the guest user's working directory, used as the default directory when none is given.

func (*Client) IsDir

func (c *Client) IsDir(p string) (bool, error)

IsDir reports whether p is a directory (following symlinks).

func (*Client) List

func (c *Client) List(dir string, limit int) (entries []Entry, truncated bool, err error)

List returns the entries in dir: directories first, then by name. At most limit entries are returned (0 means no limit); truncated reports whether any were left out.

func (*Client) Open

func (c *Client) Open(p string) (*sftp.File, fs.FileInfo, error)

Open opens a regular file for download. It refuses directories and special files, since reading something like /dev/zero would never finish.

func (*Client) Upload

func (c *Client) Upload(dest string, r io.Reader, maxBytes int64) (int64, error)

Upload writes r to dest, replacing any existing file. Data goes to a temporary file in the same directory first and is renamed into place, so a failed or oversized upload never leaves a truncated file behind. An existing file's permissions are kept. It returns the bytes written.

type Crumb

type Crumb struct {
	Name string
	Path string
}

Crumb is one segment of a breadcrumb trail for a guest path.

func Breadcrumbs(p string) []Crumb

Breadcrumbs splits an absolute path into its ancestors, starting at "/".

type Entry

type Entry struct {
	Name    string      `json:"name"`
	Path    string      `json:"path"`
	Size    int64       `json:"size"`
	Mode    fs.FileMode `json:"-"`
	ModeStr string      `json:"mode"`
	ModTime time.Time   `json:"mod_time"`
	IsDir   bool        `json:"is_dir"`
	IsLink  bool        `json:"is_link"`
	// Regular is true for files that can be downloaded. Devices, sockets and
	// FIFOs are listed but not offered for download.
	Regular bool `json:"regular"`
}

Entry is one item in a guest directory listing.

Jump to

Keyboard shortcuts

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