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
}
}
Output:
Index ¶
- type Client
- func (c *Client) Close() error
- func (c *Client) Connect(ctx context.Context, host string) error
- func (c *Client) Exec(ctx context.Context, cmd string) ([]byte, error)
- func (c *Client) UploadBackup(ctx context.Context, destPath string, r io.Reader) error
- func (c *Client) UploadSnippet(ctx context.Context, destPath string, r io.Reader) error
- type Option
- func WithHostKey(key gossh.PublicKey) Option
- func WithHostKeyCallback(cb gossh.HostKeyCallback) Option
- func WithKnownHostsFile(path string) Option
- func WithPassword(password string) Option
- func WithPort(port int) Option
- func WithPrivateKey(pemBytes []byte) Option
- func WithTimeout(d time.Duration) Option
- func WithUser(user string) Option
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 (*Client) Close ¶
Close tears down the SFTP and SSH sessions. It is safe to call on a client that never connected.
func (*Client) Connect ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
WithKnownHostsFile verifies the server against an OpenSSH known_hosts file. This is the recommended production setting.
func WithPassword ¶
WithPassword authenticates with a password (PAM).
func WithPrivateKey ¶
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 ¶
WithTimeout bounds the TCP dial and SSH handshake (default 30s).