Once you are connected to Agent, the first thing that you have to do is log in. You do that by executing the login
API call from the system
interface supplying the user credentials, which includes a user name, a password, and a Realm ID. Since you may not know the Realm ID in advance, you would normally retrieve the list of Realms using the system/get_realm
call. This is the only call that can be executed without being logged in. First, we have to compose our message:
#XML message. Retrieving the list of realms from the Hardware Node.
my $request=qq~
<packet version="4.0.0" id="2">
<data>
<system>
<get_realm/>
</system>
</data>
</packet>
~;
The $request
variable in the code above now contains our XML message. The next code segment will write the XML message to the socket that we created earlier:
#Write the XML message to the socket.
$socket->printflush($request.&MSG_TERMINATOR);
Please note that we appended the binary zero character contained in the MSG_TERMINATOR
constant to the message. Failure to do so will make the request unrecognizable to Agent. Once again, we will read the output from the socket and will display it on the screen.
#Read the response and display it on the screen.
my $response = $socket->getline;
chomp($response);
print $response;
The response to this message will contain the complete list of Realms defined in the Agent configuration on the Hardware Node. It will look similar to the following:
<packet id="2" version="4.0.0" priority="0">
<origin>system</origin>
<target>vzclient8-4fce28dd-0cd3-1345-bb94-3192b940fb90</target>
<data>
<system>
<realms>
<realm>
<login>
<name>Y249dnphZ2VudCxkYz1WWkw=</name>
<realm>458d583f-f2d8-7940-a9d3-a9a3d2ec1509</realm>
</login>
<builtin/>
<name>Parallels Internal</name>
<type>1</type>
<id>458d583f-f2d8-7940-a9d3-a9a3d2ec1509</id>
<address>vzsveaddress</address>
<port>389</port>
<base_dn>ou=4fce28dd-0cd3-1345-bb94-3192b940fb90,dc=vzl</base_dn>
<default_dn>cn=users,ou=4fce28dd-0cd3-1345-bb94-3192b940fb90,dc=vzl</default_dn>
</realm>
<realm>
<builtin/>
<name>System</name>
<type>0</type>
<id>00000000-0000-0000-0000-000000000000</id>
</realm>
<realm>
<builtin/>
<name>Virtuozzo Container</name>
<type>1000</type>
<id>00000000-0000-0000-0100-000000000000</id>
</realm>
</realms>
</system>
</data>
</packet>
Assuming that Virtuozzo Containers software has just been installed on our system, we will use the system administrator account to log in to Agent (see Installation for more info). The System Realm from the output above refers to the user registry on the host OS, so this is the Realm that we want. In order to log in, you will also need to know the administrator password. In the following example, we are logging in to Agent installed on a Linux system using the root
account. Don't forget to substitute the password value with your root
password. If you are using a Windows-based system, use your Windows administrator account. Please note that the name, realm, and password values are Base64-encoded in accordance with the schema.
#XML message. Logging in.
$request=qq~
<packet version="4.0.0" id="3">
<data>
<system>
<login>
<name>cm9vdA==</name>
<realm>00000000-0000-0000-0000-000000000000</realm>
<password>bXlwYXNz</password>
</login>
</system>
</data>
</packet>
~;
We will now write the XML message to the socket the same way we did when we were retrieving Realms in the previous step.
#Write the XML message to the socket.
$socket->printflush($request.&MSG_TERMINATOR);
Once again, we are reading the output from the socket and displaying it on the screen.
#Read the response and display it on the screen.
$response = $socket->getline;
chomp($response);
print $response;
If the supplied credentials were valid, the response message will contain the user security information, and will look similar to the following example:
<packet id="3" priority="0" version="4.0.0">
<origin>system</origin>
<target>vzclient19-4fce28dd-0cd3-1345-bb94-3192b940fb90</target>
<data>
<system>
<token>
<user>AQUAAAAAIAHdKM5P0wxFE7uUMZK5QPuQAAAAAA==</user>
<groups>
<sid>AQUAAAAAIADdKM5P0wxFE7uUMZK5QPuQAAAAAA==</sid>
<sid>AQUAAAAAIADdKM5P0wxFE7uUMZK5QPuQAQAAAA==</sid>
<sid>AQUAAAAAIADdKM5P0wxFE7uUMZK5QPuQCgAAAA==</sid>
<sid>AQUAAAAAIADdKM5P0wxFE7uUMZK5QPuQAgAAAA==</sid>
<sid>AQUAAAAAIADdKM5P0wxFE7uUMZK5QPuQAwAAAA==</sid>
<sid>AQUAAAAAIADdKM5P0wxFE7uUMZK5QPuQBAAAAA==</sid>
<sid>AQUAAAAAIADdKM5P0wxFE7uUMZK5QPuQBgAAAA==</sid>
<sid>AQUAAAAAIAHdKM5P0wxFE7uUMZK5QPuQAAAAAA==</sid>
</groups>
<deny_only_sids/>
<privileges/>
</token>
</system>
</data>
</packet>
If you see a message like that on your screen, it means that you are now logged in to Agent and that a permanent session has been created for the user. A permanent session is associated with the physical connection that we've established earlier and it never expires.
Let's examine the rest of the elements in the response message. The packet
element contains the message ID, which, as you can see, is the same as the one we specified in the request message. The target
element contains the ID of our client connection (the value is assigned and used by Agent internally). The origin
element contains the name of the Agent operator that processed the request on the server side. The user
element contains the SID (security ID) of the user. The sid
elements within the groups
element contain the security IDs of the groups to which the user belongs as a member.
The next request that we are going to send to Agent will retrieve a list of the Virtuozzo Containers from the Hardware Node.