sshcommands

README

sshcommands

Repository: github.com/janmz/sshcommands

Go library for SSH/SFTP operations with a parameter-based API: upload (sync), list, delete, download, and fetch server host key. No config struct dependency; all options are passed as parameters. Optional AES-256-CTR encryption for upload/download.

Donationware for CFI Kinderhilfe. License: MIT with attribution.

Installation

go get github.com/janmz/sshcommands

Usage

Connection options

Build Opts with SSH connection parameters:

opts := &sshcommands.Opts{
    Host:     "example.com",
    Port:     22,
    User:     "deploy",
    KeyFile:  "/home/user/.ssh/id_ed25519",  // or Password: "secret"
    HostKey:  "ed25519 AAAAC3...",            // or path to known_hosts file
}

Use at least KeyFile or Password for authentication. HostKey is required for verified connections (path to a file or inline key line; multiple keys separated by ||).

Sync (upload and prune)

Upload local files that are missing or newer on the remote; remove remote files that are not in the local list. Optional AES password for encryption.

localFiles := []sshcommands.LocalFile{
    {Name: "file.zip", Path: "/local/file.zip", ModTime: t, Size: 1024},
}
err := sshcommands.Sync(opts, localFiles, "/remote/dir", "", log)

List

List all non-directory entries in a remote directory.

entries, err := sshcommands.List(opts, "/remote/dir", log)
// entries: []RemoteEntry{Name, ModTime, Size}

Delete

Remove given file names from the remote directory.

err := sshcommands.Delete(opts, "/remote/dir", []string{"old.zip"}, log)

Download

Download files matching a pattern (literal name or wildcards *, ?) into a local directory. Optional AES password for decryption.

paths, err := sshcommands.Download(opts, "backup_*.zip", "/local/dir",
    "/remote/dir", aesPassword, log)
// paths: []string of written local paths

Fetch server host key

Connect without host key verification and return the server's key line (e.g. for initial setup):

keyLine, err := sshcommands.FetchServerHostKey(opts)
// keyLine: "ed25519 AAAAC3..."

Host key already present

Check if a key line is already among the configured keys (inline or file):

ok, err := sshcommands.HostKeyAlreadyPresent(currentHostKeyValue, newKeyLine)

Logger

All functions accept an optional Logger interface (Info, Warn with format strings). Pass nil to disable logging.

Encryption

When aesPassword is non-empty, Sync encrypts and Download decrypts using AES-256-CTR with PBKDF2-derived keys (salt + nonce prefix). Format is compatible with streams written by this package.

Documentation

Overview

Package sshcommands provides SSH/SFTP operations (upload, list, delete, download, fetch host key) with parameter-based API, no config dependency.

Index

• Constants
• Variables
• func Delete(opts *Opts, remoteDir string, names []string, log Logger) error
• func Download(opts *Opts, pattern, destDir, remoteDir, aesPassword string, log Logger) ([]string, error)
• func FetchServerHostKey(opts *Opts) (keyLine string, err error)
• func HostKeyAlreadyPresent(currentValue, newKeyLine string) (bool, error)
• func NewSFTPClient(opts *Opts, log Logger) (*sftp.Client, *ssh.Client, error)
• func Sync(opts *Opts, localFiles []LocalFile, remoteDir, aesPassword string, log Logger) error
• func ValidDownloadPattern(pattern string) bool
• func ValidRemoteFileName(name string) bool
• type LocalFile
• type Logger
• type Opts
• type RemoteEntry
  • func List(opts *Opts, remoteDir string, log Logger) ([]RemoteEntry, error)

Constants

const DefaultSSHTimeout = 30 * time.Second

DefaultSSHTimeout is used when Opts.Timeout is zero.

const EncryptionOverhead = saltLen + nonceLen

EncryptionOverhead is the number of bytes added to an encrypted stream (salt + nonce).

Variables

var (
	Version   = "1.0.1.7" // Major, Minor, Patch, Build
	BuildTime = "2026-02-27 13:45:04"
)

Functions

func Delete

func Delete(opts *Opts, remoteDir string, names []string, log Logger) error

Delete removes the given file names from remoteDir.

func Download

func Download(opts *Opts, pattern, destDir, remoteDir, aesPassword string, log Logger) ([]string, error)

Download downloads files matching pattern from remoteDir into destDir. Pattern may be a literal filename or contain wildcards (*, ?). No path components. aesPassword empty = no decryption. Returns the list of local paths written.

func FetchServerHostKey

func FetchServerHostKey(opts *Opts) (keyLine string, err error)

FetchServerHostKey connects to the SSH server without host key verification, captures the server's host key, and returns it as a single line (key-type base64…). The client is closed immediately. Use for initial setup (e.g. -setup-ssh).

func HostKeyAlreadyPresent

func HostKeyAlreadyPresent(currentValue, newKeyLine string) (bool, error)

HostKeyAlreadyPresent returns true if newKeyLine is already among the keys in currentValue (inline " || "-separated keys or path to a file with one key per line).

func NewSFTPClient

func NewSFTPClient(opts *Opts, log Logger) (*sftp.Client, *ssh.Client, error)

NewSFTPClient returns an SFTP client; caller must call Close().

func Sync

func Sync(opts *Opts, localFiles []LocalFile, remoteDir, aesPassword string, log Logger) error

Sync uploads local files that are missing or newer on the remote, and deletes remote files that are not in localFiles. remoteDir is created if needed. aesPassword empty = no encryption.

func ValidDownloadPattern

func ValidDownloadPattern(pattern string) bool

ValidDownloadPattern returns false if pattern contains path components (no /, \, ..).

func ValidRemoteFileName

func ValidRemoteFileName(name string) bool

ValidRemoteFileName returns false if name contains path components or "..". Use for any remote or local filename that is joined to a base directory.

Types

type LocalFile

type LocalFile struct {
	Name    string
	Path    string
	ModTime time.Time
	Size    int64
}

LocalFile describes a local file for Sync (name, path, modtime, size).

type Logger

type Logger interface {
	Info(string, ...interface{})
	Warn(string, ...interface{})
}

Logger is optional for progress and host key mismatch messages; nil = no logging.

type Opts

type Opts struct {
	Host     string        // SSH host
	Port     int           // 0 => 22
	User     string        // SSH user
	KeyFile  string        // path to private key (optional)
	Password string        // plaintext password (optional); at least KeyFile or Password required
	HostKey  string        // path to known_hosts file or inline key(s), separated by " || "
	Timeout  time.Duration // SSH connect timeout; 0 => DefaultSSHTimeout (30s)
}

Opts holds SSH/SFTP connection parameters.

type RemoteEntry

type RemoteEntry struct {
	Name    string
	ModTime time.Time
	Size    int64
}

RemoteEntry describes a remote file (name, modtime, size).

func List

func List(opts *Opts, remoteDir string, log Logger) ([]RemoteEntry, error)

List returns all non-directory entries in remoteDir (name, modtime, size).