Class: Pvectl::Console::TerminalSession

Inherits:
Object
  • Object
show all
Defined in:
lib/pvectl/console/terminal_session.rb

Overview

Manages an interactive terminal session over a Proxmox VNC WebSocket.

TerminalSession handles the full lifecycle of a console connection:

  1. Opens a raw TCP/SSL socket to the Proxmox host

  2. Performs a WebSocket handshake with authentication

  3. Bridges local stdin/stdout with the remote terminal via the xtermjs wire protocol

  4. Manages raw terminal mode and signal handling (SIGWINCH for resize)

The xtermjs protocol uses numbered message types:

  • Type 0: input data — 0:<bytesize>:<data>

  • Type 1: terminal resize — 1:<cols>:<rows>:

  • Type 2: ping — 2

Examples:

Basic usage (called by Console::Command)

session = Pvectl::Console::TerminalSession.new(
  url: "wss://pve1:8006/api2/json/nodes/pve1/qemu/100/vncwebsocket?port=5900&vncticket=TICKET",
  cookie: "PVEAuthCookie=PVE:root@pam:abc",
  user: "root@pam",
  ticket: "PVEVNC:abc123",
  verify_ssl: true
)
session.run

See Also:

Defined Under Namespace

Classes: SocketAdapter

Constant Summary collapse

CTRL_CLOSE_BRACKET =

Ctrl+] — standard disconnect key (same as telnet/SSH escape)

"\x1d"
PING_INTERVAL =

Seconds between keepalive pings sent to the server

120
READ_CHUNK_SIZE =

Bytes to read per socket read call

4096

Instance Method Summary collapse

Constructor Details

#initialize(url:, cookie:, user:, ticket:, verify_ssl:) ⇒ TerminalSession

Creates a new terminal session.

Parameters:

  • url (String) —

    WebSocket URL for the VNC proxy endpoint

  • cookie (String) —

    PVEAuthCookie header value for authentication

  • user (String) —

    Proxmox user identifier (e.g., “root@pam”)

  • ticket (String) —

    VNC ticket for the handshake (e.g., “PVEVNC:abc123”)

  • verify_ssl (Boolean) —

    whether to verify the server’s SSL certificate



54
55
56
57
58
59
60
61
62
 
# File 'lib/pvectl/console/terminal_session.rb', line 54

def initialize(url:, cookie:, user:, ticket:, verify_ssl:)
  @url = url
  @cookie = cookie
  @user = user
  @ticket = ticket
  @verify_ssl = verify_ssl
  @running = false
  @saved_stty = nil
end

Instance Method Details

#run ⇒ void

This method returns an undefined value.

Runs the interactive terminal session.

Opens the WebSocket connection, performs the handshake, and enters the I/O loop bridging stdin to the remote terminal. Restores the local terminal state on exit (even on error).

Raises:

  • (RuntimeError) —

    if the WebSocket handshake fails



73
74
75
76
77
78
79
80
81
82
 
# File 'lib/pvectl/console/terminal_session.rb', line 73

def run
  uri = URI.parse(@url)
  socket = open_socket(uri)
  driver = create_driver(uri, socket)
  perform_websocket_handshake(driver, socket)
  run_io_loop(driver, socket)
ensure
  restore_terminal
  socket&.close
end