Search Engine: Elastic
  • Article for your preferred language does not exist. Below is international version of the article.

Article ID: 111220, created on May 3, 2011, last review on Feb 14, 2018

  • Applies to:
  • Odin Business Automation Standard 4.5

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 Perl client attached to this article:

    ~# ./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/

Attachments

2897d76d56d2010f4e3a28f864d69223 400e18f6ede9f8be5575a475d2d6b0a6 caea8340e2d186a540518d08602aa065 624ca542e40215e6f1d39170d8e7ec75 70a5401e8b9354cd1d64d0346f2c4a3e 0efe2234e2ce513f2186f26c68447702

Email subscription for changes to this article
Save as PDF