sftp

package
v0.0.0-...-1c78fd5 Latest Latest
Warning

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

Go to latest
Published: Mar 15, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package sftp implements a domain.Backend for SFTP (SSH File Transfer Protocol) using a pure-Go SSH client. No native ssh binary, no known_hosts requirement (host key verification is configurable), no kernel mount.

URI format

sftp://[user@]host[:port]/absolute/base/path[/optional/prefix]

Examples:

sftp://nas.lan/mnt/storage/cctv
sftp://admin@192.168.1.10:22/data/frigate
sftp://backup@offsite.example.com:2222/backups/tier2

Authentication

Three methods are supported, tried in this order:

  1. SSH agent (if SSH_AUTH_SOCK is set and the key is loaded)
  2. Private key file (key_path config field or TIERFS_SFTP_KEY_PATH env var)
  3. Password (password config field or TIERFS_SFTP_PASS env var)

Connection model

Each Backend holds a single *sftp.Client protected by a sync.RWMutex. On any transport error (io.EOF, net.Error, "connection lost" etc.) the backend reconnects once and retries the operation. Concurrent reads and writes are safe — pkg/sftp multiplexes requests over the SSH channel.

Atomic writes

Put writes to a hidden temp file (<path>.tierfs-tmp-<random>) then calls Rename. SFTP rename is atomic on POSIX servers (Linux, *BSD, macOS). On Windows SFTP servers rename may fail if the destination exists — the backend falls back to Remove+Rename in that case.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ParseURI

func ParseURI(uri string) (hostPort, basePath, prefix, uriUser string, err error)

ParseURI extracts connection parameters from an SFTP URI for use by main.go.

Types

type Backend

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

Backend is a domain.Backend backed by an SFTP server. All exported methods are safe for concurrent use.

func New

func New(cfg Config, log *zap.Logger) (*Backend, error)

New creates an SFTP Backend from cfg and establishes the initial connection.

func (*Backend) Close

func (b *Backend) Close() error

Close disconnects cleanly.

func (*Backend) Delete

func (b *Backend) Delete(ctx context.Context, relPath string) error

Delete removes the file at relPath. Returns nil if not found.

func (*Backend) Get

func (b *Backend) Get(ctx context.Context, relPath string) (io.ReadCloser, int64, error)

Get returns a reader for the file at relPath. The caller must close the returned ReadCloser.

func (*Backend) List

func (b *Backend) List(ctx context.Context, prefix string) ([]domain.FileInfo, error)

List returns all files recursively under prefix.

func (*Backend) LocalPath

func (b *Backend) LocalPath(_ string) (string, bool)

LocalPath always returns ("", false) — SFTP files cannot be memory-mapped.

func (*Backend) Put

func (b *Backend) Put(ctx context.Context, relPath string, r io.Reader, _ int64) error

Put writes r to the SFTP server at relPath using atomic temp-file + rename.

func (*Backend) Rename

func (b *Backend) Rename(ctx context.Context, oldRel, newRel string) error

Rename moves oldRel to newRel on the server. Implements the optional Rename extension used by TierService.OnRename().

func (*Backend) Scheme

func (b *Backend) Scheme() string

Scheme returns "sftp".

func (*Backend) Stat

func (b *Backend) Stat(ctx context.Context, relPath string) (*domain.FileInfo, error)

Stat returns metadata for the file at relPath.

func (*Backend) URI

func (b *Backend) URI(relPath string) string

URI returns the display URI for relPath (no credentials).

type Config

type Config struct {
	// Name is the tier name, used in log messages.
	Name string

	// URI is the SFTP URI: sftp://[user@]host[:port]/base/path[/prefix]
	URI string

	// Username for SSH authentication.
	// Falls back to TIERFS_SFTP_USER env var, then URI userinfo, then current OS user.
	Username string

	// Password for SSH password authentication.
	// Falls back to TIERFS_SFTP_PASS env var.
	// Leave empty to use key-based or agent auth.
	Password string

	// KeyPath is the absolute path to a PEM-encoded SSH private key file.
	// Falls back to TIERFS_SFTP_KEY_PATH env var, then ~/.ssh/id_ed25519,
	// ~/.ssh/id_rsa in that order.
	KeyPath string

	// KeyPassphrase decrypts an encrypted private key.
	// Falls back to TIERFS_SFTP_KEY_PASSPHRASE env var.
	KeyPassphrase string

	// HostKey is the expected host public key in authorized_keys format, e.g.:
	//   "ssh-ed25519 AAAA..."
	// If empty, host key verification is skipped (InsecureIgnoreHostKey).
	// In production, always set this or use KnownHostsFile.
	HostKey string

	// KnownHostsFile is the path to a known_hosts file. Takes precedence over
	// HostKey if both are set.
	KnownHostsFile string

	// InsecureIgnoreHostKey, when true, disables host key verification entirely.
	// Must be set explicitly in the config file; the default is to refuse connection
	// if no HostKey or KnownHostsFile is provided.
	InsecureIgnoreHostKey bool
}

Config holds all configuration for an SFTP backend. Credentials are resolved: env vars > config fields > URI userinfo.

Jump to

Keyboard shortcuts

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