Home

Overview

vSPC.py is a Virtual Serial Port Concentrator that makes use of the VMware telnet extensions, as documented here: http://www.vmware.com/support/developer/vc-sdk/visdk41pubs/vsp41_usingproxy_virtual_serial_ports.pdf

Features

• Point any number of virtual serial ports to a single vSPC.py server (great for cloned VMs)
• Multiplexed client connects: Multiple entities can interact with the same console. Also allows for gdb connections while monitoring the console.
• Port mappings are sticky - port number will stay constant as long as the VM or a client is connected, with a set expiration timer after all connections terminate
• vMotion is fully supported
• Query interface allows you to see VM name, UUID, port mappings on the vSPC.py server
• Clients can connect using standard telnet, binary mode is negotiated automatically

Getting vSPC.py

To start:

  git clone git://git.code.sf.net/p/vspcpy/code vSPC.py

  vSPC.py/vSPC.py

You should see the help text sampled below.

Pre-requisites

vSPC.py was developed on an Ubuntu Linux VM with Python 2.6 and tested on Python 2.5. None of the imports are terribly exotic, so it should work on just about any Linux/Unix variant. Windows has not been tested.

ESXi 4.1 and 5.0 were both tested. 4.1 is a requirement for vSPCs, though in theory anything that speaks the telnet extensions will behave.

Help Output

vSPC.py ($Id$)

Common options:
vSPC.py: [-h|--help] [-d|--debug] [-a|--admin-port P] -s|--server|hostname

Query (without --server): Connect to the --admin-port (default 13371) on
  the specified host and return a list of VMs. Output is colon
  delimited, vm-name:vm-uuid:port.

Server (with --server):
  Additional options:
    [-p|--proxy-port P] [-r|--port-range-start P] [--vm-expire-time seconds]
    [--backend Backend] [--backend-args 'arg string'] [--backend-help]
    [-f|--persist-file file]
    [--stdout] [--no-fork]

  Start Virtual Serial Port Concentrator. By default, vSPC listens on
  port 13370 for VMware virtual serial connections. Each new VM is
  assigned a listener, starting at port 50000. VM to port mappings may be
  queried using vSPC.py without the --server option (e.g. 'vSPC.py localhost').
  A standard 'telnet' may then be used to connect to the VM serial port.

  In order to configure a VM to use the vSPC, you must be running ESXi 4.1+.
  Add the serial port to the VM, then select:
    (*) Use Network
      (*) Server
      Port URI: vSPC.py
      [X] Use Virtual Serial Port Concentrator:
      vSPC: telnet://dispater:13370
  NOTE: Direction MUST be Server, and Port URI MUST be vSPC.py

  vSPC.py makes a best effort to keep VM to port number mappings stable,
  based on the UUID of the connecting VM. Even if a VM disconnects,
  client connections are maintained in anticipation of the VM
  reconnecting (e.g. if the VM is rebooting). The UUID<->port mapping
  is maintained as long as there are either client connections or as
  long as the VM is connected, and even after this condition is no
  longer met, the mapping is retained for --vm-expire-time seconds
  (default 86400).

  The backend of vSPC.py serves three major purposes: (a) On initial load,
  all port mappings are retrieved from the backend. The main thread
  maintains the port mappings after initial load, but the backend is
  responsible for setting the initial map. (This design was chosen to
  avoid blocking on the backend when a new VM connects.) (b) The
  backend serves all admin connections (because it has full knowledge
  of the mappings), (c) The backend can fire off customizable hooks as
  VMs come and go, allowing for persistence, or database tracking, or
  whatever.

  By default, vSPC.py uses the "Memory" backend, which really just
  means that no initial mappings are loaded on startup and all state
  is retained in memory alone. The other builtin backend is the "File"
  backend, which can be configured like so:
    --backend File --backend-args '-f /tmp/vSPC'.
  As a convenience, this same configuration can be accomplished using
  the top level parameter -f or --persist-file, i.e. '-f /tmp/vSPC' is
  synonymous with the previous set of arguments.

  If '--backend Foo' is given but no builtin backend Foo exists, vSPC.py
  tries to import module vSPCBackendFoo, looking for class vSPCBackendFoo.
  See --backend-help for programming details.

  Explanation of server options:
    -a|--admin-port: The port to listen/use for queries (default 13371)
    -p|--proxy-port: The proxy port to listen on (default 13370)
    -r|--port-range-start: What port to start port allocations from (default 50000)
    --vm-expire-time: How long to wait before expiring a mapping with no connections
    -f|--persist-file: DBM file prefix to persist mappings to (.dat/.dir may follow)
    --backend: Name of custom backend class (see above)
    --backend-args: Arguments to custom backend
    --stdout: Log to stdout instead of syslog
    --no-fork: Don't daemonize
    -d|--debug: Debug mode (turns up logging and implies --stdout --no-fork)