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:
- SSH agent (if SSH_AUTH_SOCK is set and the key is loaded)
- Private key file (key_path config field or TIERFS_SFTP_KEY_PATH env var)
- 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 ¶
- func ParseURI(uri string) (hostPort, basePath, prefix, uriUser string, err error)
- type Backend
- func (b *Backend) Close() error
- func (b *Backend) Delete(ctx context.Context, relPath string) error
- func (b *Backend) Get(ctx context.Context, relPath string) (io.ReadCloser, int64, error)
- func (b *Backend) List(ctx context.Context, prefix string) ([]domain.FileInfo, error)
- func (b *Backend) LocalPath(_ string) (string, bool)
- func (b *Backend) Put(ctx context.Context, relPath string, r io.Reader, _ int64) error
- func (b *Backend) Rename(ctx context.Context, oldRel, newRel string) error
- func (b *Backend) Scheme() string
- func (b *Backend) Stat(ctx context.Context, relPath string) (*domain.FileInfo, error)
- func (b *Backend) URI(relPath string) string
- type Config
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 (*Backend) Get ¶
Get returns a reader for the file at relPath. The caller must close the returned ReadCloser.
func (*Backend) LocalPath ¶
LocalPath always returns ("", false) — SFTP files cannot be memory-mapped.
func (*Backend) Rename ¶
Rename moves oldRel to newRel on the server. Implements the optional Rename extension used by TierService.OnRename().
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.