General notes

Virtual Automation (VA) has different API ports depending on the version and type of the VA host.

Virtual Automation 4.0 (PIM, Parallels Infrastructure Manager, VZAgent):

  • 4433 - non-SSL XML API service
  • 4434 - SSL XML API service
  • 4646 - SOAP API service

Virtual Automation Management Node 4.5, 4.6 and 6.0 (Replacement for 4.0 PIM Master Node):

  • 4533 - non-SSL XML API service
  • 4534 - SSL XML API service

* Virtual Automation Agent 4.5, 4.6* and 6.0 (Replacement for VZAgent 3.0 and 4.0 on Slave Nodes in PIM group. The VA Agent is installed directly onto the host when Containers or Virtuozzo is installed):

  • 4433 - non-SSL XML API service
  • 4434 - SSL XML API service
  • 4646 - SOAP API service

The VA API service can work in compatibility mode with previous versions, which is why the API version is typically set to 4.0.0. However, this setting can be changed if required.

In order to use a previous version of the VA API, you must follow the corresponding API guide and set the appropriate API protocol version in the XML header. For example:

<packet id="1" version="4.0.0"> or <packet id="1" version="4.5.0">

Find the references for each version of the XML API protocol in the corresponding manual:

VZAgent 3.0 XML API Reference

PIM 4.0 XML API Reference

VA 6.0 XML API Reference, PDF

Ways to send an XML API request

An XML API request can be sent to VA XML API service in several different ways:

  1. API requests to a local VA Agent can be sent using the vzlcon tool:

    • On Windows:

      vzlcon
      
    • On Linux\Bare Metal:

      /opt/pva/agent/bin/vzlcon
      

    NOTE: Packets are separated by a ctrl+shift+2 combination:

    [root@myserver ~]# /opt/pva/agent/bin/vzlcon
    <packet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="0" priority="0" version="4.5.0">
    <origin>vzclient2-4a7e18fd-c53a-a048-af57-06602fbb8317</origin>
    <target>agent</target>
    <data>
    <ok/>
    <eid>4a7e18fd-c53a-a048-af57-06602fbb8317</eid>
    </data>
    </packet>
    <packet version="4.0.0"><data><system><get_version/></system></data></packet>
    ^@  <==Here CTRL+SHIFT+2 was pressed
    <packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol" xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/system" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" priority="0" version="4.0.0">
    <ns1:origin>gend</ns1:origin>
    <ns1:target>vzclient2-4a7e18fd-c53a-a048-af57-06602fbb8317</ns1:target>
    <ns1:dst>
    <director>gend</director>
    </ns1:dst>
    <ns1:data>
    <ns2:system>
    <ns2:version>vzagent-4.6.843</ns2:version>
    <ns2:pva_version>4.6</ns2:pva_version>
    <ns2:pva_release>1764</ns2:pva_release>
    </ns2:system>
    </ns1:data>
    </packet>
    ^C
    
  2. Using the openssl tool:

    ~# echo -ne '<packet id="1" version="4.0.0"><data><system><login><name>BASE 64 ENCRYPTED USER NAME</name><realm>00000000-0000-0000-0000-000000000000</realm><password>BASE64 ENCRYPTED PASSWORD</password></login></system></data></packet>\0<packet id="2" version="4.0.0">YOUR XML API REQUEST</packet>\0' | openssl s_client -connect HOSTNAME:4434 -cipher ADH-AES256-SHA -quiet
    

    In this example, you need to specify the base64 encrypted login and password to authenticate to the XML API service. This can be done using perl:

    ~# perl -MMIME::Base64 -e "print(encode_base64('YOUR PLAIN TEXT PASSWORD'))"
    WU9VUiBQTEFJTiBURVhUIFBBU1NXT1JE
    

    Your XML API request goes in the second packet. You can send several packets in a sequence terminated by '\0' after the authentication packet.

  3. Using the pva_api.pl:

    ~# ./pva_api.pl -name=root -password='PASSWORD' -host=HOSTNAME -packet='<packet version="4.0.0"><data><system><get_version/></system></data></packet>'
    <packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol" xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/system" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" priority="0" version="4.0.0">
    <ns1:origin>gend</ns1:origin>
    <ns1:target>vzclient25401-057cfcc0-18b0-e44b-9730-ba41ac7c877a</ns1:target>
    <ns1:dst>
    <director>gend</director>
    </ns1:dst>
    <ns1:data>
    <ns2:system>
    <ns2:version>vzagent-4.0.0.483.swsoft</ns2:version>
    <ns2:pva_version></ns2:pva_version>
    <ns2:pva_release></ns2:pva_release>
    </ns2:system>
    </ns1:data>
    </packet>
    

    Use the same script pva_api.pl to send a long packet by specifying a file in the command line or redirecting the standard input:

    ~# ./pva_api.pl -name=root -password='PASSWORD' -host=HOSTNAME long_package.xml
    ~# ./pva_api.pl -name=root -password='PASSWORD' -host=HOSTNAME < long_package.xml
    

    The script can be used to send packets to VA MN, and it works via SSL connection by default:

    # ./pva_api.pl 
    Usage: pva_api.pl -name=LOGIN -password=PASSWD -host=HOST [-nossl] [-mn] [-packet=PACKET | packet.xml]
    
    If -packet is omitted, it is read from the standard input.
    By default, the connection is done to VA Agent via SSL.
    Specify -nossl to turn off SSL, -mn to connect to PVA MN.
    
  4. Using a custom XML API client.

Additional information

Related articles:

6981 VA troubleshooting.

111223 How to find XML API requests sent to VA Agent by the VA Management Node or Power Panel

9216 VZagent API compatibility (Windows)

111821 VZagent API compatibility (Linux)

NOTE: More information about VA API versions, changes, and switching client applications can be found at the Parallels Developers Network site: http://www.odin.com/ptn/documentation/virtuozzo/

Internal content