vmware.vmware_rest.vcenter_vm_hardware_serial module – Manage virtual serial ports on a virtual machine.

Note

This module is part of the vmware.vmware_rest collection (version 5.0.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install vmware.vmware_rest.

To use it in a playbook, specify: vmware.vmware_rest.vcenter_vm_hardware_serial.

New in vmware.vmware_rest 5.0.0

Synopsis

• Create, update, and delete virtual serial ports attached to a VMware virtual machine.

• A virtual serial port can be backed by a file on a datastore, a physical serial port device on the ESXi host, a named pipe, or a network location.

• This module also supports connecting and disconnecting an existing virtual serial port at runtime using the connect and disconnect states.

• Only present and absent states are idempotent.

Parameters

Parameter	Comments
allow_guest_control boolean	Flag indicating whether the guest can connect and disconnect the device. Defaults to false if omitted. Choices: false true
backing dictionary	Physical resource backing for the virtual serial port. If omitted, defaults to automatic detection of a suitable host device.
file string	Path of the file that should be used as the virtual serial port backing. Only relevant when type is FILE.
host_device string	Name of the host device that should be used as the virtual serial port backing. If omitted, the virtual serial port will be configured to automatically detect a suitable host device. Only relevant when type is HOST_DEVICE.
network_location string	URI specifying the location of the network service backing the virtual serial port. When type is NETWORK_SERVER, this is the location used by clients to connect to the server. The hostname part of the URI should either be empty or specify the address of the host on which the virtual machine is running. When type is NETWORK_CLIENT, this is the location used by the virtual machine to connect to the remote server. Only relevant when type is NETWORK_SERVER or NETWORK_CLIENT.
no_rx_loss boolean	Flag that enables optimized data transfer over the pipe. When set to true, the host buffers data to prevent data overrun, allowing the virtual machine to read all of the data transferred over the pipe with no data loss. Defaults to false if omitted. Only relevant when type is PIPE_SERVER or PIPE_CLIENT. Choices: false true
pipe string	Name of the pipe that should be used as the virtual serial port backing. Only relevant when type is PIPE_SERVER or PIPE_CLIENT.
proxy string	Proxy service that provides network access to the network backing. If set, the virtual machine initiates a connection with the proxy service and forwards the traffic to the proxy. If omitted, no proxy service is used.
type string	Backing type for the virtual serial port. FILE - The virtual serial port is backed by a file on a datastore. HOST_DEVICE - The virtual serial port is backed by a physical serial device on the ESXi host where the virtual machine is running. PIPE_SERVER - The virtual serial port is backed by a named pipe server. The virtual machine accepts a connection from a host application or another virtual machine on the same host. This is useful for capturing debugging information sent through the virtual serial port. PIPE_CLIENT - The virtual serial port is backed by a named pipe client. The virtual machine connects to the named pipe provided by a host application or another virtual machine on the same host. NETWORK_SERVER - The virtual serial port is backed by a network server, creating a network-accessible serial port that accepts a connection from a remote system. NETWORK_CLIENT - The virtual serial port is backed by a network client, creating a network-accessible serial port that initiates a connection to a remote system. Choices: "FILE" "HOST_DEVICE" "PIPE_SERVER" "PIPE_CLIENT" "NETWORK_SERVER" "NETWORK_CLIENT"
port string	Identifier of the virtual serial port to manage. Must be an identifier (MOID) for a SerialPort resource, for example 9000. Required when state is absent, connect, or disconnect. When state is present, omit to create a new serial port or provide to update an existing one.
session_timeout float	Timeout in seconds for the whole operation including connection establishment, request sending, and response. Default: 300.0
start_connected boolean	Flag indicating whether the virtual device should be connected whenever the virtual machine is powered on. Defaults to false if omitted. Choices: false true
state string	The desired state of the resource. Use present to create or update the resource. Use absent to delete the resource. Use connect to connect the virtual serial port to its backing. Use disconnect to disconnect the virtual serial port from its backing. Only present and absent support idempotence. Choices: "present" ← (default) "absent" "connect" "disconnect"
vcenter_hostname string / required	The hostname or IP address of the vSphere vCenter. If the value is not specified in the task, the value of environment variable VMWARE_HOST will be used instead.
vcenter_password string / required	The vSphere vCenter password. If the value is not specified in the task, the value of environment variable VMWARE_PASSWORD will be used instead.
vcenter_port integer	The port number of the vSphere vCenter. If the value is not specified in the task, the value of environment variable VMWARE_PORT will be used instead.
vcenter_rest_log_file string	Optional path to a log file for HTTP REST interaction. If the value is not specified in the task, the value of environment variable VMWARE_REST_LOG_FILE will be used instead.
vcenter_username string / required	The vSphere vCenter username. If the value is not specified in the task, the value of environment variable VMWARE_USER will be used instead.
vcenter_validate_certs boolean	Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted. If the value is not specified in the task, the value of environment variable VMWARE_VALIDATE_CERTS will be used instead. Choices: false true ← (default)
vm string / required	Identifier of the virtual machine that owns the serial port. Must be an identifier (MOID) for a Vm resource.
yield_on_poll boolean	CPU yield behavior. If set to true, the virtual machine will periodically relinquish the processor if its sole task is polling the virtual serial port. The amount of time it takes to regain the processor depends on the degree of other virtual machine activity on the host. Defaults to false if omitted. Choices: false true

Notes

Note

• Generated from vSphere API spec 9.1.0.

• Compatible with vSphere API 7.0.3.

• Compatible with vSphere API 8.0.2.

Examples

- name: Add a virtual serial port backed by a file
  vmware.vmware_rest.vcenter_vm_hardware_serial:
    vm: vm-1001
    backing:
      type: FILE
      file: "[datastore1] serial/port1.log"
    start_connected: true
    allow_guest_control: true
    state: present
  register: serial_result

- name: Add a virtual serial port backed by a host device
  vmware.vmware_rest.vcenter_vm_hardware_serial:
    vm: vm-1001
    backing:
      type: HOST_DEVICE
      host_device: /dev/ttyS0
    state: present

- name: Add a network-backed virtual serial port acting as a server
  vmware.vmware_rest.vcenter_vm_hardware_serial:
    vm: vm-1001
    backing:
      type: NETWORK_SERVER
      network_location: telnet://:12345
    yield_on_poll: true
    state: present

- name: Update an existing virtual serial port
  vmware.vmware_rest.vcenter_vm_hardware_serial:
    vm: vm-1001
    port: '{{ serial_result.id }}'
    allow_guest_control: false
    state: present

- name: Connect a virtual serial port
  vmware.vmware_rest.vcenter_vm_hardware_serial:
    vm: vm-1001
    port: '{{ serial_result.id }}'
    state: connect

- name: Disconnect a virtual serial port
  vmware.vmware_rest.vcenter_vm_hardware_serial:
    vm: vm-1001
    port: '{{ serial_result.id }}'
    state: disconnect

- name: Remove a virtual serial port
  vmware.vmware_rest.vcenter_vm_hardware_serial:
    vm: vm-1001
    port: '{{ serial_result.id }}'
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
id string	MOID of the managed virtual serial port. Returned: When state is present, or when a resource is deleted, or when state is set to a supported action. Sample: "9000"
value any	The raw API response body from the vCenter operation. Returned: On success Sample: {"allow_guest_control": true, "backing": {"file": "[datastore1] serial/port1.log", "type": "FILE"}, "label": "Serial port 1", "start_connected": true, "state": "CONNECTED", "yield_on_poll": false}

Authors

• Ansible Eco Content Team (@eco-ansible-content)

Collection links

• Issue Tracker
• Repository (Sources)