Help us shape the future of Go! Take the 2026 Go Developer Survey

ssh

package
v1.27.0-beta.2 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: MPL-2.0 Imports: 41 Imported by: 4

Documentation

Index

Constants

View Source 
const HandshakeIdleTimeout = 15 * time.Second

HandshakeIdleTimeout fails a handshake that makes no progress for this long. Progress-based instead of absolute so slow-but-alive links (high latency is the norm for tunneled handshakes) always complete while a peer that stops sending entirely surfaces an error to callers. Zero disables.

View Source 
const (
	OwnerLinePrefix = "# Devsy Owner "
)

Variables

View Source 
var (
	MarkerStartPrefix = "# Devsy Start "
	MarkerEndPrefix   = "# Devsy End "
)
View Source 
var (
	DevsySSHHostKeyFile    = "id_" + config.BinaryName + "_rsa_host"
	DevsySSHPrivateKeyFile = "id_" + config.BinaryName + "_rsa"
	DevsySSHPublicKeyFile  = "id_" + config.BinaryName + "_rsa.pub"
)
View Source 
var ErrIdleTimeout = errors.New("port forward idle timeout")

ErrIdleTimeout is returned by PortForward / ReversePortForward when the forwarder shuts down because it stayed idle longer than the configured EXIT_AFTER_TIMEOUT. Callers that want to treat idle-timeout as a clean exit should check for this error with errors.Is.

View Source 
var ErrTransportClosed = errors.New("ssh transport closed")

Functions

func AddPrivateKeysToAgent 

func AddPrivateKeysToAgent(ctx context.Context) error

func ClientFromConn added in v1.17.0 

func ClientFromConn(conn net.Conn, user string, keyBytes []byte) (*ssh.Client, error)

ClientFromConn creates an SSH client over an existing network connection. The handshake is bounded by HandshakeIdleTimeout so a stalled peer surfaces an error instead of blocking the tunnel forever. No deadlines are set on the conn, so the established session is unaffected.

func ClientFromManagedConn added in v1.20.0 

func ClientFromManagedConn(
	ctx context.Context,
	conn transport.ManagedConn,
	opts ManagedClientOptions,
) (*xssh.Client, error)

ClientFromManagedConn starts the SSH client immediately, allowing its local identification write during bootstrap. Handshake limits begin only when the managed peer first sends protocol bytes.

func ConfigFromKeyBytes 

func ConfigFromKeyBytes(keyBytes []byte) (*ssh.ClientConfig, error)

func ConfigureSSHConfig 

func ConfigureSSHConfig(params SSHConfigParams) error

func FindPrivateKeys 

func FindPrivateKeys() ([]string, error)

func GetDevsyHostKey 

func GetDevsyHostKey() (string, error)

func GetDevsyKeysDir 

func GetDevsyKeysDir() (string, error)

func GetDevsyPrivateKeyRaw 

func GetDevsyPrivateKeyRaw() ([]byte, error)

func GetDevsyPublicKey 

func GetDevsyPublicKey() (string, error)

func GetHostKey 

func GetHostKey(context, workspaceID string) (string, error)

func GetHostKeyBase 

func GetHostKeyBase(dir string) (string, error)

func GetPrivateKeyRaw 

func GetPrivateKeyRaw(context, workspaceID string) ([]byte, error)

func GetPrivateKeyRawBase 

func GetPrivateKeyRawBase(dir string) ([]byte, error)

func GetPublicKey 

func GetPublicKey(context, workspaceID string) (string, error)

func GetPublicKeyBase 

func GetPublicKeyBase(dir string) (string, error)

func GetUser 

func GetUser(
	workspaceID string,
	sshConfigPath string,
	sshConfigIncludePath string,
) (string, error)

func NewSSHClient 

func NewSSHClient(user, addr string, keyBytes []byte) (*ssh.Client, error)

func NewSSHPassClient 

func NewSSHPassClient(user, addr, password string) (*ssh.Client, error)

func OpenSessionConn added in v1.17.0 

func OpenSessionConn(
	ctx context.Context,
	client *xssh.Client,
	opts SessionConnOptions,
) (transport.ManagedConn, error)

OpenSessionConn exposes a long-lived command on an existing SSH client as a managed connection. Closing it never closes the parent client.

func PortForward 

func PortForward(
	ctx context.Context,
	client *ssh.Client,
	opts PortForwardOpts,
) error

func PortForwardWithListener added in v1.3.1 

func PortForwardWithListener(
	ctx context.Context,
	client *ssh.Client,
	opts ForwardOpts,
) error

PortForwardWithListener is like PortForward, but uses a caller-supplied listener instead of binding one internally. This lets the caller reserve the local port before forking, eliminating a TOCTOU race between port probe and net.Listen in a detached child. The remote network is always "tcp".

func RemoveFromConfig 

func RemoveFromConfig(
	workspaceID string,
	sshConfigPath string,
	sshConfigIncludePath string,
) error

RemoveFromConfig removes the managed block for workspaceID without checking ownership.

func RemoveFromConfigForOwner 

func RemoveFromConfigForOwner(
	owner Owner,
	workspaceID string,
	sshConfigPath string,
	sshConfigIncludePath string,
) error

RemoveFromConfigForOwner removes only blocks owned by owner and fails on foreign blocks.

func ReplaceHostAliasesForOwner 

func ReplaceHostAliasesForOwner(
	r AliasReplacement,
	owner Owner,
	commit func() error,
) (bool, error)

ReplaceHostAliasesForOwner rewrites the canonical host block only when owner owns it.

func ReplaceHostAliasesWithCommit 

func ReplaceHostAliasesWithCommit(r AliasReplacement, commit func() error) (bool, error)

ReplaceHostAliasesWithCommit rewrites the canonical host block without checking ownership.

func ResolveSSHConfigPath 

func ResolveSSHConfigPath(sshConfigPath string) (string, error)

func ReverseListen added in v1.12.1 

func ReverseListen(client *ssh.Client, remoteNetwork, remoteAddr string) (net.Listener, error)

ReverseListen binds the remote listener; pair with RunReverseForward.

func ReversePortForward 

func ReversePortForward(
	ctx context.Context,
	client *ssh.Client,
	opts PortForwardOpts,
) error

func Run 

func Run(ctx context.Context, opts RunOptions) error

func RunReverseForward added in v1.12.1 

func RunReverseForward(ctx context.Context, client *ssh.Client, opts ReverseForwardOpts) error

RunReverseForward runs the forwarding loop for a listener obtained via ReverseListen, closing it on return.

func RunSession added in v1.18.0 

func RunSession(ctx context.Context, sess *ssh.Session, opts RunSessionOptions) error

RunSession executes a command on a caller-owned SSH session. It never closes the session; callers retain ownership and are responsible for cleanup.

func StdioClient 

func StdioClient(reader io.Reader, writer io.WriteCloser) (*ssh.Client, error)

func StdioClientFromKeyBytesWithUser 

func StdioClientFromKeyBytesWithUser(
	keyBytes []byte,
	reader io.Reader,
	writer io.WriteCloser,
	user string,
) (*ssh.Client, error)

func StdioClientWithUser 

func StdioClientWithUser(
	reader io.Reader,
	writer io.WriteCloser,
	user string,
) (*ssh.Client, error)

func WatchWindowSize 

func WatchWindowSize(ctx context.Context) <-chan os.Signal

Types

type AliasReplacement 

type AliasReplacement struct {
	ConfigPath    string
	IncludePath   string
	CanonicalHost string
	PreferredHost string
	Verify        func() error
}

type BlockOwnershipError 

type BlockOwnershipError struct {
	Host   string
	File   string
	Reason string
}

func (*BlockOwnershipError) Error 

func (e *BlockOwnershipError) Error() string

type DevsySSHEntry 

type DevsySSHEntry struct {
	Host      string
	User      string
	Workspace string
}

type ExitError 

type ExitError struct {
	ExitCode int
	Err      error
}

ExitError wraps an SSH exit error with the exit code.

func (*ExitError) Error 

func (e *ExitError) Error() string

func (*ExitError) Unwrap 

func (e *ExitError) Unwrap() error

type ForwardOpts added in v1.3.1 

type ForwardOpts struct {
	Listener         net.Listener
	RemoteAddr       string
	ExitAfterTimeout time.Duration
}

ForwardOpts groups the parameters for PortForwardWithListener so callers don't have to thread a long positional argument list.

type ForwardingFunction 

type ForwardingFunction func(context.Context, net.Conn, *ssh.Client, forwardTarget)

type HandshakeTimeoutError added in v1.20.0 

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

HandshakeTimeoutError reports a handshake that stopped making progress.

func (*HandshakeTimeoutError) Error added in v1.20.0 

func (e *HandshakeTimeoutError) Error() string

func (*HandshakeTimeoutError) Temporary added in v1.20.0 

func (e *HandshakeTimeoutError) Temporary() bool

Temporary reports the error as transient so callers with net.Error retry handling treat it as worth retrying.

func (*HandshakeTimeoutError) Timeout added in v1.20.0 

func (e *HandshakeTimeoutError) Timeout() bool

type HostConflict 

type HostConflict struct {
	Host string
	File string
}

func FindHostConflicts 

func FindHostConflicts(
	sshConfigPath, sshConfigIncludePath string,
	hosts []string,
	ownCanonicalHost string,
) ([]HostConflict, error)

FindHostConflicts excludes any block for ownCanonicalHost without checking ownership.

func FindHostConflictsForOwner 

func FindHostConflictsForOwner(query HostConflictQuery) ([]HostConflict, error)

FindHostConflictsForOwner excludes only blocks for the canonical host that owner owns.

type HostConflictQuery 

type HostConflictQuery struct {
	ConfigPath    string
	IncludePath   string
	Hosts         []string
	CanonicalHost string
	Owner         Owner
}

type ManagedClientOptions added in v1.20.0 

type ManagedClientOptions struct {
	User                 string
	KeyBytes             []byte
	HandshakeIdleTimeout time.Duration
	HandshakeMaxTimeout  time.Duration
}

ManagedClientOptions configures SSH over a transport whose peer may still be starting. Zero timeout values use the standard SSH handshake limits.

type Owner 

type Owner struct {
	Home    string
	Context string
	UID     string
}

func NewOwner 

func NewOwner(contextName, uid string) (Owner, error)

func (Owner) Hash 

func (o Owner) Hash() string

func (Owner) Line 

func (o Owner) Line() string

type PortForwardOpts 

type PortForwardOpts struct {
	LocalNetwork     string
	LocalAddr        string
	RemoteNetwork    string
	RemoteAddr       string
	ExitAfterTimeout time.Duration
}

PortForwardOpts names both ends of a forwarded connection. For a reverse forward the local end is the one dialed and the remote end is the one listened on.

type ReverseForwardOpts added in v1.12.1 

type ReverseForwardOpts struct {
	Listener         net.Listener
	RemoteAddr       string
	LocalNetwork     string
	LocalAddr        string
	ExitAfterTimeout time.Duration
}

ReverseForwardOpts groups the parameters for RunReverseForward.

type RunOptions 

type RunOptions struct {
	Client  *ssh.Client
	Command string
	Stdin   io.Reader
	Stdout  io.Writer
	Stderr  io.Writer
	EnvVars map[string]string
}

type RunSessionOptions added in v1.18.0 

type RunSessionOptions struct {
	Command string
	Stdin   io.Reader
	Stdout  io.Writer
	Stderr  io.Writer
	EnvVars map[string]string
}

type SSHConfigParams 

type SSHConfigParams struct {
	SSHConfigPath        string
	SSHConfigIncludePath string
	Context              string
	Workspace            string
	User                 string
	Workdir              string
	Command              string
	GPGAgent             bool
	AgentForwarding      bool
	DevsyHome            string
	Provider             string
	TunnelPort           int // If > 0, use TCP tunnel mode instead of ProxyCommand
	PreferredHost        string
	ResolvePreferredHost func() string
	Owner                Owner
}

type SessionConnOptions added in v1.17.0 

type SessionConnOptions struct {
	Command string
	Env     map[string]string
	Stderr  io.Writer
}

Source Files

View all Source files

Directories

Path Synopsis
port

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.