sftpshare

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package sftpshare serves a host directory to VM guests over SFTP.

The guest runs rclone mount against this server (WinFsp-backed, fixed-disk mode), which presents the share as DRIVE_FIXED — the drive type WSL1's drvfs can stat/read through, unlike the WebClient's DRIVE_REMOTE mounts (CELL-532). A plain loopback listener is enough: the guest reaches 127.0.0.1:<port> on the host as 10.0.2.2:<port> over QEMU user-mode networking.

SFTP over WebDAV, deliberately: rclone's SFTP backend streams uploads and reads ranges natively, while its WebDAV backend cannot stream and has a reported corruption bug under vfs-cache-mode full.

Sessions are jailed to Root via os.Root: path traversal and symlink escapes cannot reach the rest of the host filesystem.

Index

Constants

View Source
const (
	DefaultUser     = "winkit"
	DefaultPassword = "winkit"
)

DefaultUser and DefaultPassword are the share credentials. The listener binds loopback only; the credentials exist because SFTP requires an authenticated user, not as a security boundary.

View Source
const DefaultPort = 9844

DefaultPort is the conventional port for the share, one above the WebDAV share's 9843. Port 0 selects an ephemeral port.

View Source
const GuestHost = "10.0.2.2"

GuestHost is the address at which a QEMU user-net guest reaches the host.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// Root is the host directory to share. Required, must exist.
	Root string
	// Port to listen on (loopback only). 0 selects an ephemeral port.
	Port int
	// User and Password authenticate sessions. Default to DefaultUser and
	// DefaultPassword when empty.
	User     string
	Password string
	// Logger receives request-level debug logs. Optional.
	Logger *slog.Logger
}

Config configures a Server.

type DirShare

type DirShare struct {
	// HostPath is the absolute path on the macOS host, e.g.
	// /Users/dmitry/dev/devcell-sh/go-winkit.
	HostPath string
	// VMPath is the path inside the guest's WSL1 distro where the share
	// should appear. Typically the same as HostPath so configs work
	// unchanged across host and guest.
	VMPath string
	// Drive is the Windows drive letter (no colon) for the WinFsp mount.
	// Empty falls back to the next available letter starting from W.
	Drive string
	// Port is the SFTP server port on the host loopback. 0 selects
	// ephemeral; DefaultPort (9844) is used for the first share.
	Port int
}

DirShare describes a host directory shared with the guest VM. Each share gets its own SFTP server (port), WinFsp drive letter, and optional WSL1 symlink so the host path resolves identically inside the guest.

Single-mount today; the slice form ([]DirShare) is the multi-mount API.

func (DirShare) ServerConfig

func (s DirShare) ServerConfig(logger *slog.Logger) Config

ServerConfig returns an SFTP server Config rooted at the share's HostPath. The share's Port is used if non-zero, otherwise DefaultPort.

type Server

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

Server is a loopback SFTP server sharing a single directory tree.

func New

func New(cfg Config) (*Server, error)

New validates cfg and prepares a server. Call Start to begin serving.

func (*Server) Close

func (s *Server) Close() error

Close stops the listener and tears down active sessions.

func (*Server) Password

func (s *Server) Password() string

Password returns the configured password.

func (*Server) Port

func (s *Server) Port() int

Port returns the bound port, or 0 before Start.

func (*Server) Start

func (s *Server) Start() error

Start binds the loopback listener and serves in a background goroutine.

func (*Server) User

func (s *Server) User() string

User returns the configured username.

Jump to

Keyboard shortcuts

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