Documentation
¶
Overview ¶
Package xssh provides a symmetric SSH connection handler that works for both server and client connections. It abstracts the handling of global requests, channels, and sessions so that either side of an SSH connection can offer services to the other.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SetWinsize ¶
SetWinsize sets the size of the given pty.
Types ¶
type ChannelHandler ¶
type ChannelHandler func(conn Conn, ch ssh.NewChannel) error
ChannelHandler handles new SSH channel requests. Return an error to reject the channel; return nil to accept.
type Config ¶
type Config struct {
// Logger for debug and error messages. If nil, logging is disabled.
Logger *slog.Logger
// KeepAlive interval in seconds. If > 0, sends periodic ping requests.
KeepAlive int
// IgnoreEnv if true, ignores environment variables from "env" requests.
IgnoreEnv bool
// WorkingDirectory sets the initial working directory for sessions and sftp.
WorkingDirectory string
// Shell is the shell executable to use for sessions. Defaults to "bash".
Shell string
// Session enables the built-in session handling (shell, exec, PTY).
Session bool
// Handlers for different SSH protocol elements
GlobalRequestHandlers map[string]GlobalRequestHandler
ChannelHandlers map[string]ChannelHandler
SessionRequestHandlers map[string]SessionRequestHandler
SubsystemHandlers map[string]SubsystemHandler
// SFTP enables the SFTP subsystem handler.
SFTP bool
// LocalForwarding enables direct-tcpip channel handling (client requests server to connect).
LocalForwarding bool
// RemoteForwarding enables tcpip-forward global request handling (client requests server to listen).
RemoteForwarding bool
}
Config is the configuration for an xssh.Conn. It provides handlers for global requests, channels, and session requests.
type Conn ¶
type Conn interface {
ssh.Conn
// Serve starts handling global requests and channels.
// This method blocks until the connection is closed.
Serve()
// HandleSessionChannel handles the "session" channel type.
// This is the default handler for "session" channels.
HandleSessionChannel(newChannel ssh.NewChannel) error
// Config returns the connection configuration.
Config() *Config
// contains filtered or unexported methods
}
Conn wraps an ssh.Conn and handles global requests, channels, and sessions. It can be used for both server-side and client-side connections, enabling symmetric SSH where either party can offer services to the other.
func NewConn ¶
func NewConn(sshConn ssh.Conn, channels <-chan ssh.NewChannel, requests <-chan *ssh.Request, config *Config) Conn
NewConn creates a new xssh.Conn from an established SSH connection. The channels and requests parameters are the channels returned by ssh.NewServerConn or ssh.NewClientConn.
type FdHolder ¶
type FdHolder interface {
Fd() uintptr
}
FdHolder is an interface for types that can return their file descriptor.
type GlobalRequestHandler ¶
GlobalRequestHandler handles global (connection-level) SSH requests. Return an error to reject the request; return nil to accept. Call req.Reply() to send a custom reply; otherwise auto-reply is sent.
type PTY ¶
type PTY interface {
io.ReadWriteCloser
FdHolder
}
PTY is an interface that abstracts platform-specific PTY implementations. It provides read/write capabilities and a file descriptor holder for resizing.
type Request ¶
Request wraps ssh.Request to track whether Reply was called.
func WrapRequest ¶
WrapRequest creates a wrapped request that tracks whether Reply was called.
type SFTPConfig ¶
type SFTPConfig struct {
// WorkDir is the working directory for SFTP. Defaults to user home.
WorkDir string
// Logger enables debug logger
Logger *slog.Logger
}
SFTPConfig configures the SFTP subsystem handler.
type Session ¶
type Session struct {
// Channel is the underlying SSH "session" channel.
Channel ssh.Channel
// Env contains environment variables for this session.
Env []string
// Resizes receives terminal resize events (window-change requests).
// Each payload contains width and height as uint32 big-endian values.
Resizes chan []byte
// Logger for session-specific logging. If nil, uses connection logger.
Logger *slog.Logger
// contains filtered or unexported fields
}
Session represents an active SSH session with its associated state. A session is created when a "session" channel is accepted.
type SessionRequestHandler ¶
SessionRequestHandler handles requests within an SSH session. Return an error to reject the request; return nil to accept. Call req.Reply() to send a custom reply; otherwise auto-reply is sent.
type SubsystemHandler ¶
SubsystemHandler handles subsystem requests (e.g., sftp). Return an error to reject the request; return nil to accept.
func NewSFTPHandler ¶
func NewSFTPHandler(cfg SFTPConfig) SubsystemHandler
NewSFTPHandler creates a new SFTP subsystem handler. Register this as the handler for the "sftp" subsystem.
type TCPForwardingHandler ¶
type TCPForwardingHandler struct {
// contains filtered or unexported fields
}
TCPForwardingHandler manages TCP forwarding functionality. It can be used with any xssh.Conn to enable TCP forwarding.
func NewTCPForwardingHandler ¶
func NewTCPForwardingHandler() *TCPForwardingHandler
NewTCPForwardingHandler creates a new TCP forwarding handler.
func (*TCPForwardingHandler) Close ¶
func (h *TCPForwardingHandler) Close()
Close closes all active listeners
func (*TCPForwardingHandler) HandleCancelTCPIPForward ¶
func (h *TCPForwardingHandler) HandleCancelTCPIPForward(conn Conn, req *Request) error
HandleCancelTCPIPForward handles cancellation of reverse port forwarding (global request). Register this as the handler for "cancel-tcpip-forward" global requests.
func (*TCPForwardingHandler) HandleDirectTCPIP ¶
func (h *TCPForwardingHandler) HandleDirectTCPIP(conn Conn, newChannel ssh.NewChannel) error
HandleDirectTCPIP handles direct TCP/IP forwarding (local forwarding) - channel handler. Register this as the handler for "direct-tcpip" channels.
func (*TCPForwardingHandler) HandleTCPIPForward ¶
func (h *TCPForwardingHandler) HandleTCPIPForward(conn Conn, req *Request) error
HandleTCPIPForward handles reverse port forwarding requests (global request). Register this as the handler for "tcpip-forward" global requests.
Source Files