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:
Ways to send an XML API request
An XML API request can be sent to VA XML API service in several different ways:
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
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.
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.
- 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/