Network Serial Ports

A network serial port is a virtual serial port that uses a network socket on the host computer. A network socket is the endpoint of a network connection and is represented by an IP address and a port number. The vSphere API uses Uniform Resource Identifiers (URI) to identify the protocol, IP address, and port number for endpoints of network serial port connections. See RFC3986 for information about Uniform Resource Identifiers.

To use a network serial port, you must verify that the ESX host supports the feature and then create or reconfigure a virtual machine to configure the port. For information about writing an application that uses the vSphere API, see the vSphere Web Services SDK Programming Guide. As an alternative, you can use the vSphere Client to configure a network serial port. For more information, see the online help for the VMware vSphere Client.

Backing Options and Backing Information for Network Serial Ports

The vSphere API uses backing objects to represent the host device that is associated with a virtual device. The types of backing objects for virtual devices are option objects and information objects.

Backing option objects identify host device support for virtual machines. An ESX host defines the set of virtual device backing options that are available for virtual machines. To use a network serial port, the ESX host must provide the virtual serial port URI backing option, which is represented by the VirtualSerialPortURIBackingOption object. For information about how to find out if the host supports the URI backing option, see Determining Backing Options.

Backing information objects supply data for virtual device configuration. Use a VirtualSerialPortURIBackingInfo object to bind a virtual serial port to a network socket. You can configure a virtual serial port to use URI backing when you create or reconfigure a virtual machine. For a description of how to configure URI backing for a network serial port, see Creating a Virtual Machine with a Network Serial Port.

When you specify URI backing for the network serial port connection, you define these characteristics.

■

Direction – defines the role that the virtual machine plays in a connection with a remote system (client or server). When a virtual machine acts as a serial port client, it initiates the connection with the remote system. When a virtual machine acts as a serial port server, it listens for connections that are initiated by remote clients.

■

Service URI – identifies the target of connections. When the virtual machine acts as a client, the service URI identifies the remote system. When the virtual machine acts as a server, the service URI identifies proxy access to the host on which the virtual machine runs. See RFC3986 for information about URI syntax.

■	Proxy URI – identifies the virtual serial port proxy. The presence of the proxy URI directs the virtual machine to establish a connection with the proxy. The virtual machine always initiates the connection with the proxy.

You can use either telnet or secure telnet (telnets) for the proxy connection. The proxy URI specification must use one of the following formats. See RFC3986 for information about URI syntax. See the description of the VirtualSerialPortURIBackingInfo data object in the vSphere API Reference for information about URI schemes and authentication parameters for network serial port configuration.

■	telnet://<host>:<port>[#key[=value][&key[=value] ...]]

■	telnets://<host>:<port>[#key[=value][&key[=value] ...]]

When the virtual machine performs telnet negotiation with the proxy, it sends the direction and service URI information to the proxy. (See the description of the DO-PROXY command in Proxy Operation.)

Network Connections Between a Virtual Machine, a Proxy, and a Remote System

Virtual Serial Port Connections to a Remote System Through a Proxy shows two virtual machines. Each machine uses a proxy for its connection to a remote system.

■

One virtual machine acts as a virtual serial port server. This virtual machine uses the service URI to identify proxy access to the host machine. The virtual machine initiates a telnet connection with the proxy. The proxy, on behalf of the virtual machine, listens for connection requests from remote systems and forwards the requests to the virtual machine.

■	One virtual machine acts as a virtual serial port client. This virtual machine uses the service URI to identify the remote system. The virtual machine initiates a telnet connection with the proxy. The proxy forwards the connection request to the remote system.

The proxy has two network sockets. It uses one socket (proxy URI) for the telnet connections with the virtual machine and the other for the connection with the remote system. The external connection between the proxy and a remote system uses the mutually agreed upon protocol. For a connection initiated by the remote system, the person operating the remote system must obtain the service URI by email or other independent communication.

Virtual Serial Port Connections to a Remote System Through a Proxy

Determining Backing Options

You use the QueryConfigOption method to determine the backing options that are available on the host on which you will create the virtual machine. The method returns a VirtualMachineConfigOption data object. The virtual machine configuration data includes a a list of virtual device options and a list of backing options. The following pseudocode shows the path to the backing options.

VirtualMachineConfigOption.hardwareOptions.VirtualDeviceOption[].backingOption[]

The virtual device option array must include the VirtualSerialPortOption data object. For network backing, the array of serial port backing options must include the VirtualDeviceURIBackingOption data object. The VirtualDeviceURIBackingOption.type property specifies the name of the backing object you should create when you configure network backing.

Creating a Virtual Machine with a Network Serial Port

You can use the CreateVM_Task method to create a virtual machine and configure a network serial port. The virtual machine uses the virtual serial port configuration to connect to a proxy and to accept a connection from a remote system.

1	Create a VirtualMachineConfigSpec object for the method's config parameter.

2	Create a VirtualDeviceConfigSpec object for the deviceChange array in the VirtualMachineConfigSpec object.

3	Create a VirtualSerialPort object for the device property in the VirtualDeviceConfigSpec object.

4	To control proxy connection behavior, create a VirtualDeviceConnectInfo data object for the VirtualSerialPort.connectable property.

The following pseudocode shows the resulting path to the connection information.

VirtualMachineConfigSpec.deviceChange[].device.connectable

5	Set the startConnected property in the connectable object to TRUE.

The startConnected property determines whether the virtual machine will open a connection with the proxy when the virtual machine starts. When the virtual machine powers on, it copies the startConnected value to the VirtualDeviceConnectInfo.connected property. While the virtual machine is running, you can use the ReconfigVM_Task method to set the connected property to open or close the proxy connection. If you reconfigure a port with connected set to TRUE, the virtual machine closes the existing connection and opens a new one.

6	Create a VirtualDeviceURIBackingInfo object for the backing property in the VirtualSerialPort object.

The following pseudocode shows the resulting path to the backing information.

VirtualMachineConfigSpec.deviceChange[].device.backing

Use the backing information object to supply the following information:

■	Set the direction property to “server” to direct the virtual machine to accept remote connections.

■	Set the serviceURI property to the URI for the host on which the virtual machine runs.

■	Set the proxyURI property to the URI for the virtual serial port concentrator. You cannot include a user/password sequence in the proxy URI.