Previous page

Next page

Locate page in Contents

Print this page

Identifying Hardware Nodes and VPSs

Prior to VZAgent v.4.0.0, a Hardware Node was identified just like any other computer on a network -- by IP address or hostname. A VPS was identified by an internal Virtuozzo ID, which was assigned to every VPS at the time of creation. The Hardware Node and VPSs were two completely different and separate entities. In VZAgent 4.0.0, every participating machine (physical or virtual) is automatically assigned a universally unique ID (called Environment ID or EID for short) and is identified within VZAgent infrastructure by this ID alone. Every Hardware Node has an EID which is assigned to it as soon as VZAgent is installed on it. Every Virtuozzo VE (formerly VPS) also has an EID, which is assigned to to it at the time the VE is created. In VZAgent 4.0.0 it doesn't matter whether a machine is a physical server (Hardware Node) or a virtual server (VE) -- all that is needed to access a server and perform administration tasks on it is the EID.

What this means to you is that most API calls use this ID now instead of Virtuozzo internal VPS ID, so you will have to update your code accordingly. In addition, new functions were added to get the list of EIDs from a particular Hardware Node or from a Virtuozzo group (formerly Virtuozzo cluster). You will have to use these functions to get the list of the available EIDs when needed.

The following example demonstrates how a VE is started using the two VZAgent API versions. Note the <veid> parameter in v. 3.0.3 and the <eid> parameter in v. 4.0.0

VZAgent 3.0.3 and earlier

<packet version="3.0.3" id="611">

<target>vem</target>

<data>

<vem>

<start>

<veid>103</veid>

</start>

</vem>

</data>

</packet>

VZAgent 4.0.0

<packet version="4.0.0" id="2">

<target>vzaenvm</target>

<data>

<vzaenvm>

<start>

<eid>ba17a0c5-9036-473c-a813-aa6f5b36cf16</eid>

</start>

</vzaenvm>

</data>

</packet>

The Virtuozzo-level VPS ID (or VEID for short) still exists in the current Virtuozzo version but from the VZAgent API point of view, the significance of this ID has been reduced to the point where only a very few calls actually use it.

The other important difference is that many API calls don't have a parameter that would identify a VE the call is targeted at. This means that they have neither the old-style VEID nor the new-style EID parameter. By default, these calls are processed at the Hardware Node level and perform operations on the Node itself. In order for a call like that to perform its operation on a particular Virtuozzo VE, you will have to use the call forwarding feature (see the example below). In comparison, all similar calls in VZAgent v. 3.0.x always had a veid (VPS ID) parameter. Consider the following example:

VZAgent 3.0.0

Note the veid parameter specifying the VPS ID to get the list of files from.

<packet version="3.0.0">

<target>filem</target>

<data>

<filem>

<list>

<veid>777</veid>

<cwd>Lw==</cwd>

<path>Lw==</path>

</list>

</filem>

</data>

</packet>

VZAgent 4.0.0

The same call in VZAgent 4.0.0 doesn't have the veid parameter. To get the same results as in the call above, we use the dst/host element in the message header to forward the call to the Virtuozzo VE specified by its VEID. Without call forwarding we would receive the list of files from the Hardware Node that we are currently connected to. The calls like that will have to be identified in your existing code and the necessary changes will have to be made.

<packet version="4.0.0">

<dst>

<host>24b9acf5-8ca5-49c9-b7b1-4c93fe048389</host>

</dst>

<target>filer</target>

<data>

<filer>

<list>

<cwd>Lw==</cwd>

<path>Lw==</path>

</list>

</filer>

</data>

</packet>

Please send us your feedback on this help page