.. _community.vmware.vmware_guest_serial_port_module:


*****************************************
community.vmware.vmware_guest_serial_port
*****************************************

**Manage serial ports on an existing VM**



.. contents::
   :local:
   :depth: 1


Synopsis
--------
- This module can be used to manage serial ports on an existing VM




Parameters
----------

.. raw:: html

    <table  border=0 cellpadding=0 class="documentation-table">
        <tr>
            <th colspan="1">Parameter</th>
            <th>Choices/<font color="blue">Defaults</font></th>
                        <th width="100%">Comments</th>
        </tr>
                    <tr>
                                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                    <b>backings</b>
                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">list</span>
                         / <span style="color: purple">elements=dictionary</span>                                            </div>
                                    </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>A list of backings for serial ports.</div>
                                            <div><code>backing_type</code> (str): is required to add or reconfigure or remove an existing serial port.</div>
                                            <div>Valid attributes are:</div>
                                            <div>- <code>backing_type</code> (str): Backing type is required for the serial ports to be added or reconfigured or removed.</div>
                                            <div>- <code>state</code> (str): is required to identify whether we are adding, modifying or removing the serial port. - choices: - <code>present</code>: modify an existing serial port. <code>backing_type</code> is required to determine the port. The first matching <code>backing_type</code> and either of <code>service_uri</code> or <code>pipe_name</code> or <code>device_name</code> or <code>file_path</code> will be modified. If there is only one device with a backing type, the secondary details are not needed. We will match the last such device with the given backing type. - <code>absent</code>: remove an existing serial port. <code>backing_type</code> is required to determine the port. The first matching <code>backing_type</code> and either of <code>service_uri</code> or <code>pipe_name</code> or <code>device_name</code> or <code>file_path</code> will be removed. If there is only one device with a backing type, the secondary details are not needed. We will match the last such device with the given backing type.</div>
                                            <div>- <code>yield_on_poll</code> (bool): Enables CPU yield behavior. Default value is true.</div>
                                            <div>- <code>direction</code> (str): Required when <em>backing_type=network</em>. The direction of the connection. - choices: - client - server</div>
                                            <div>- <code>service_uri</code> (str): Required when <em>backing_type=network</em>. Identifies the local host or a system on the network, depending on the value of <em>direction</em>. If you use the virtual machine as a server, the URI identifies the host on which the virtual machine runs. In this case, the host name part of the URI should be empty, or it should specify the address of the local host. If you use the virtual machine as a client, the URI identifies the remote system on the network.</div>
                                            <div>- <code>endpoint</code> (str): Required when <em>backing_type=pipe</em>. When you use serial port pipe backing to connect a virtual machine to another process, you must define the endpoints.</div>
                                            <div>- <code>no_rx_loss</code> (bool): Required when <em>backing_type=pipe</em>. Enables optimized data transfer over the pipe. - choices: - client - server</div>
                                            <div>- <code>pipe_name</code> (str): Required when <em>backing_type=pipe</em>.</div>
                                            <div>- <code>device_name</code> (str): Required when <em>backing_type=device</em>.</div>
                                            <div>- <code>file_path</code> (str): Required when <em>backing_type=file</em>. File path for the host file used in this backing. Fully qualified path is required, like &lt;datastore_name&gt;/&lt;file_name&gt;</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                    <b>hostname</b>
                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                    </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>The hostname or IP address of the vSphere vCenter or ESXi server.</div>
                                            <div>If the value is not specified in the task, the value of environment variable <code>VMWARE_HOST</code> will be used instead.</div>
                                            <div>Environment variable support added in Ansible 2.6.</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                    <b>moid</b>
                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                    </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>Managed Object ID of the instance to manage if known, this is a unique identifier only within a single vCenter instance.</div>
                                            <div>This is required if <code>name</code> or <code>uuid</code> is not supplied.</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                    <b>name</b>
                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                    </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>Name of the virtual machine.</div>
                                            <div>This is a required parameter, if parameter <code>uuid</code> or <code>moid</code> is not supplied.</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                    <b>password</b>
                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                    </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>The password of the vSphere vCenter or ESXi server.</div>
                                            <div>If the value is not specified in the task, the value of environment variable <code>VMWARE_PASSWORD</code> will be used instead.</div>
                                            <div>Environment variable support added in Ansible 2.6.</div>
                                                                <div style="font-size: small; color: darkgreen"><br/>aliases: pass, pwd</div>
                                    </td>
            </tr>
                                <tr>
                                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                    <b>port</b>
                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">integer</span>
                                                                    </div>
                                    </td>
                                <td>
                                                                                                                                                                    <b>Default:</b><br/><div style="color: blue">443</div>
                                    </td>
                                                                <td>
                                            <div>The port number of the vSphere vCenter or ESXi server.</div>
                                            <div>If the value is not specified in the task, the value of environment variable <code>VMWARE_PORT</code> will be used instead.</div>
                                            <div>Environment variable support added in Ansible 2.6.</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                    <b>proxy_host</b>
                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                    </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>Address of a proxy that will receive all HTTPS requests and relay them.</div>
                                            <div>The format is a hostname or a IP.</div>
                                            <div>If the value is not specified in the task, the value of environment variable <code>VMWARE_PROXY_HOST</code> will be used instead.</div>
                                            <div>This feature depends on a version of pyvmomi greater than v6.7.1.2018.12</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                    <b>proxy_port</b>
                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">integer</span>
                                                                    </div>
                                    </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>Port of the HTTP proxy that will receive all HTTPS requests and relay them.</div>
                                            <div>If the value is not specified in the task, the value of environment variable <code>VMWARE_PROXY_PORT</code> will be used instead.</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                    <b>use_instance_uuid</b>
                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">boolean</span>
                                                                    </div>
                                    </td>
                                <td>
                                                                                                                                                                                                                    <ul style="margin: 0; padding: 0"><b>Choices:</b>
                                                                                                                                                                <li><div style="color: blue"><b>no</b>&nbsp;&larr;</div></li>
                                                                                                                                                                                                <li>yes</li>
                                                                                    </ul>
                                                                            </td>
                                                                <td>
                                            <div>Whether to use the VMware instance UUID rather than the BIOS UUID.</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                    <b>username</b>
                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                    </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>The username of the vSphere vCenter or ESXi server.</div>
                                            <div>If the value is not specified in the task, the value of environment variable <code>VMWARE_USER</code> will be used instead.</div>
                                            <div>Environment variable support added in Ansible 2.6.</div>
                                                                <div style="font-size: small; color: darkgreen"><br/>aliases: admin, user</div>
                                    </td>
            </tr>
                                <tr>
                                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                    <b>uuid</b>
                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">string</span>
                                                                    </div>
                                    </td>
                                <td>
                                                                                                                                                            </td>
                                                                <td>
                                            <div>UUID of the instance to manage the serial ports, this is VMware&#x27;s unique identifier.</div>
                                            <div>This is a required parameter, if parameter <code>name</code> or <code>moid</code> is not supplied.</div>
                                                        </td>
            </tr>
                                <tr>
                                                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="parameter-"></div>
                    <b>validate_certs</b>
                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
                    <div style="font-size: small">
                        <span style="color: purple">boolean</span>
                                                                    </div>
                                    </td>
                                <td>
                                                                                                                                                                                                                    <ul style="margin: 0; padding: 0"><b>Choices:</b>
                                                                                                                                                                <li>no</li>
                                                                                                                                                                                                <li><div style="color: blue"><b>yes</b>&nbsp;&larr;</div></li>
                                                                                    </ul>
                                                                            </td>
                                                                <td>
                                            <div>Allows connection when SSL certificates are not valid. Set to <code>false</code> when certificates are not trusted.</div>
                                            <div>If the value is not specified in the task, the value of environment variable <code>VMWARE_VALIDATE_CERTS</code> will be used instead.</div>
                                            <div>Environment variable support added in Ansible 2.6.</div>
                                            <div>If set to <code>yes</code>, please make sure Python &gt;= 2.7.9 is installed on the given machine.</div>
                                                        </td>
            </tr>
                        </table>
    <br/>




Examples
--------

.. code-block:: yaml+jinja

    
    # Create serial ports
    - name: Create multiple serial ports with Backing type - network, pipe, device and file
      community.vmware.vmware_guest_serial_port:
        hostname: "{{ vcenter_hostname }}"
        username: "{{ vcenter_username }}"
        password: "{{ vcenter_password }}"
        validate_certs: no
        name: "test_vm1"
        backings:
        - type: 'network'
          direction: 'client'
          service_uri: 'tcp://6000'
          yield_on_poll: True
        - type: 'pipe'
          pipe_name: 'serial_pipe'
          endpoint: 'client'
        - type: 'device'
          device_name: '/dev/char/serial/uart0'
        - type: 'file'
          file_path: '[datastore1]/file1'
          yield_on_poll:  True
        register: create_multiple_ports

    # Modify existing serial port
    - name: Modify Network backing type
      community.vmware.vmware_guest_serial_port:
        hostname: '{{ vcenter_hostname }}'
        username: '{{ vcenter_username }}'
        password: '{{ vcenter_password }}'
        name: '{{ name }}'
        backings:
        - type: 'network'
          state: 'present'
          direction: 'server'
          service_uri: 'tcp://6000'
      delegate_to: localhost

    # Remove serial port
    - name: Remove pipe backing type
      community.vmware.vmware_guest_serial_port:
        hostname: '{{ vcenter_hostname }}'
        username: '{{ vcenter_username }}'
        password: '{{ vcenter_password }}'
        name: '{{ name }}'
        backings:
        - type: 'pipe'
          state: 'absent'
      delegate_to: localhost





Return Values
-------------
Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module:

.. raw:: html

    <table border=0 cellpadding=0 class="documentation-table">
        <tr>
            <th colspan="1">Key</th>
            <th>Returned</th>
            <th width="100%">Description</th>
        </tr>
                    <tr>
                                <td colspan="1">
                    <div class="ansibleOptionAnchor" id="return-"></div>
                    <b>serial_port_data</b>
                    <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
                    <div style="font-size: small">
                      <span style="color: purple">dictionary</span>
                                          </div>
                                    </td>
                <td>always</td>
                <td>
                                                                        <div>metadata about the virtual machine&#x27;s serial ports after managing them</div>
                                                                <br/>
                                            <div style="font-size: smaller"><b>Sample:</b></div>
                                                <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[{&#x27;backing_type&#x27;: &#x27;network&#x27;, &#x27;direction&#x27;: &#x27;client&#x27;, &#x27;service_uri&#x27;: &#x27;tcp://6000&#x27;}, {&#x27;backing_type&#x27;: &#x27;pipe&#x27;, &#x27;direction&#x27;: &#x27;server&#x27;, &#x27;pipe_name&#x27;: &#x27;serial pipe&#x27;}]</div>
                                    </td>
            </tr>
                        </table>
    <br/><br/>


Status
------


Authors
~~~~~~~

- Anusha Hegde (@anusha94)


