ssh

package
v0.12.3 Latest Latest
Warning

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

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

Documentation

Overview

Package ssh is the SFTP/exec side-channel for the few Proxmox operations the REST API cannot do — uploading snippets and backup archives to a node's storage via SFTP under a PAM account, and running the occasional command over SSH.

It is separate from the REST transport: the consumer supplies SSH credentials and host-key verification. Obtain a Client from the root client's SSH accessor (or NewClient), Connect to a node, use it, then Close:

sc := client.SSH(ssh.WithUser("root"), ssh.WithPassword(pw),
	ssh.WithKnownHostsFile("/home/me/.ssh/known_hosts"))
if err := sc.Connect(ctx, "pve.example.com"); err != nil {
	// ...
}
defer sc.Close()
err := sc.UploadSnippet(ctx, "/var/lib/vz/snippets/ci.yaml", r)

Host-key verification is mandatory: Connect fails unless one of WithKnownHostsFile, WithHostKey, or WithHostKeyCallback is configured.

A Client wraps a single connection and is not safe for concurrent use: Connect, use, then Close from one goroutine. Obtain a fresh Client per node.

Live behaviour (real PAM auth, writing under /var/lib/vz) cannot be verified without a reachable node; unit tests exercise the client against an in-process SFTP server. See docs/design/0001-proxmox-sdk-package-layout.md.

Example

Example shows the canonical side-channel flow: configure host-key verification and credentials, Connect to a node, upload a cloud-init snippet over SFTP, then Close. It has no Output directive because it needs a real PVE host; go test compiles it but does not run it.

package main

import (
	"context"
	"fmt"
	"strings"

	"github.com/donaldgifford/proxmox-go-sdk/proxmox/ssh"
)

func main() {
	ctx := context.Background()

	// Host-key verification is mandatory — here via the caller's known_hosts.
	c := ssh.NewClient(
		ssh.WithUser("root"),
		ssh.WithPassword("s3cret"),
		ssh.WithKnownHostsFile("/home/me/.ssh/known_hosts"),
	)
	if err := c.Connect(ctx, "pve.example.com"); err != nil {
		fmt.Println("connect:", err)
		return
	}
	defer c.Close()

	snippet := strings.NewReader("#cloud-config\nhostname: web-1\n")
	if err := c.UploadSnippet(ctx, "/var/lib/vz/snippets/web-1.yaml", snippet); err != nil {
		fmt.Println("upload:", err)
		return
	}
}

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

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

Client is an SSH/SFTP side-channel to one PVE node. It is not safe for concurrent use: Connect, use, then Close from a single goroutine. Construct it with NewClient (or the root client's SSH accessor).

func NewClient

func NewClient(opts ...Option) *Client

NewClient builds a disconnected Client. Call Connect before uploading.

func (*Client) Close

func (c *Client) Close() error

Close tears down the SFTP and SSH sessions. It is safe to call on a client that never connected.

func (*Client) Connect

func (c *Client) Connect(ctx context.Context, host string) error

Connect opens the SSH and SFTP sessions to host (port from WithPort). It must be called once before the upload/exec methods. ctx bounds the TCP dial.

func (*Client) Exec

func (c *Client) Exec(ctx context.Context, cmd string) ([]byte, error)

Exec runs cmd on the node over SSH and returns its combined stdout+stderr. Connect must have been called. It is intended for the rare host-level operation with no REST equivalent; prefer the typed REST services otherwise.

func (*Client) UploadBackup

func (c *Client) UploadBackup(ctx context.Context, destPath string, r io.Reader) error

UploadBackup streams r to destPath on the node over SFTP, e.g. a vzdump archive under "/var/lib/vz/dump/". Same contract as UploadSnippet.

func (*Client) UploadSnippet

func (c *Client) UploadSnippet(ctx context.Context, destPath string, r io.Reader) error

UploadSnippet streams r to destPath on the node over SFTP. destPath is the absolute path on the PVE host, e.g. "/var/lib/vz/snippets/cloud-init.yaml". Intermediate directories must already exist. Connect must have been called.

type Option

type Option func(*clientConfig)

Option configures a Client.

func WithHostKey

func WithHostKey(key gossh.PublicKey) Option

WithHostKey pins a single expected server public key. Useful when the key is known out of band (and in tests against an ephemeral server).

func WithHostKeyCallback

func WithHostKeyCallback(cb gossh.HostKeyCallback) Option

WithHostKeyCallback sets the host-key verification callback directly — the escape hatch for advanced policies. Supplying gossh.InsecureIgnoreHostKey here disables verification; that is the caller's explicit, auditable choice.

func WithKnownHostsFile

func WithKnownHostsFile(path string) Option

WithKnownHostsFile verifies the server against an OpenSSH known_hosts file. This is the recommended production setting.

func WithPassword

func WithPassword(password string) Option

WithPassword authenticates with a password (PAM).

func WithPort

func WithPort(port int) Option

WithPort overrides the SSH port (default 22).

func WithPrivateKey

func WithPrivateKey(pemBytes []byte) Option

WithPrivateKey authenticates with a PEM-encoded private key (OpenSSH or PKCS#8). The key is parsed at Connect time so a malformed key surfaces there.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout bounds the TCP dial and SSH handshake (default 30s).

func WithUser

func WithUser(user string) Option

WithUser sets the SSH username (typically a PAM account on the PVE node).

Jump to

Keyboard shortcuts

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