Previous page

Next page

Locate page in Contents

Print this page

Request Routing

Request routing is an Agent feature that allows to specify the target server to which a request message should be sent. There are two types of request routing that you can use in your client applications:

Local Routing

Most of the XML API calls that deal with Virtuozzo Containers have an input parameter which is used to specify the Server ID on which the operation should be performed. For example, when you start or stop a Virtuozzo Container, you pass its Server ID to the call. In contrast, calls that allow to perform operations on both the Containers and the Hardware Node are usually missing this parameter. For example, the filer/list call (lists files and directories) does not have the Server ID parameter. So, how do you get file listing for a particular Virtuozzo Container? That's where request routing comes in. You can tell Agent to route the request to the specified Container and execute it there instead of executing it on the Hardware Node level. You accomplish this by including the dst/host (destination host) parameter in the Agent request message header to contain the Server ID of the target Container. By not including the dst/host parameter in the message header, you are instructing Agent to perform the operation on the Hardware Node itself. The following samples illustrate how to use the request routing feature.

In the first sample, the request message does not have the request routing information, so the response packet will contain a list of files located in the specified folder on the Hardware Node.

Input

<packet version="4.0.0">

  <target>filer</target>

  <data>

    <filer>

      <list>

        <cwd>Lw==</cwd>

        <path>Lw==</path>

      </list>

    </filer>

  </data>

</packet>

The request message in the second sample has the request routing information. The destination Server ID is included in the request using the dst/host element in the message header. As a result, the request will be sent to the specified Container. The result will then be routed back to the client and will contain a list of files located in the specified folder of the specified Virtuozzo Container.

<packet version="4.0.0">

  <dst>

    <host>3b8f950a-981d-b94d-bde1-647df39674f1</host>

  </dst>

  <target>filer</target>

  <data>

    <filer>

      <list>

        <cwd>Lw==</cwd>

        <path>Lw==</path>

      </list>

    </filer>

  </data>

</packet>

When exactly do you use request routing? Here are a few simple rules:

There are only a few interfaces in the Agent XML API that utilize the request routing functionality. Here's the list:

Class name

Description

computerm

Computer management. Provides methods for managing Hardware Nodes and Virtuozzo Containers as if they were regular physical machines.

filer

Provides methods for managing files and directories on Hardware Nodes and Virtuozzo Containers.

firewallm

Firewall management (Linux only).

processm

System processes management. Provides methods for managing system processes and for executing programs on Hardware Nodes and Virtuozzo Containers.

servicem

Services management. Provides calls for managing the operating system services on Hardware Nodes or Virtuozzo Containers.

userm

Provides calls for managing users and groups on Hardware Nodes and Virtuozzo Containers.

To use request routing in your client applications, you don't have to manually install Agent inside a Container. All the necessary Agent components are installed in a Container automatically when it is created.

Request routing in a Virtuozzo group

In a Virtuozzo group the request routing feature can be used to specify the target Slave Node or any of the Virtuozzo Containers. For example, if you are connected to the Master Node in a Virtuozzo group but would like to get the list of Virtuozzo Containers from a particular Slave Node, you can do that by routing the request to that Server using the dst/host parameter.

If the destination server is a Slave Node (physical machine), you can route any request to it. In this case the list of the interfaces that can utilize the request routing functionality is not limited to the short list that we've included earlier in this section. If the destination is a Virtuozzo Container, use request routing only with the interfaces listed in the table above.

Please note that you can only route Agent requests to other Nodes in a Virtuozzo group if you are connected to the Master Node. You cannot route requests between Slave Nodes. Please also note that request routing in a Virtuozzo group can be an expensive operation. The destination server can be located deep inside the group hierarchy, so by the time the message travels to its destination and back, a significant amount of the group resources may be used. Don't overuse it. Whenever possible, instead of using request routing in a Virtuozzo group, try connecting to a Slave Node directly and execute the call there.

Please send us your feedback on this help page