To retrieve the list of the existing Realms, use the following request:
<packet version="4.0.0" id="2">
<data>
<system>
<get_realm/>
</system>
</data>
</packet>
Once again, this call does not require you to be logged in. The Agent response will contain the list of the available Realms and will look similar to the following:
<packet xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/types" xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/dirm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="8c46e79de1t18ber68c" priority="0" version="4.0.0">
<origin>system</origin>
<target>vzclient121-4fce28dd-0cd3-1345-bb94-3192b940fb90</target>
<data>
<system>
<realms>
<realm xsi:type="ns1:dir_realmType">
<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 xsi:type="ns2:realmType">
<builtin/>
<name>System</name>
<type>0</type>
<id>00000000-0000-0000-0000-000000000000</id>
</realm>
<realm xsi:type="ns2:realmType">
<builtin/>
<name>Virtuozzo Container</name>
<type>1000</type>
<id>00000000-0000-0000-0100-000000000000</id>
</realm>
</realms>
</system>
</data>
</packet>
The message above contains three Realm entries: Parallels Internal, System, and Virtuozzo Container. The following describes each entry in detail.
Parallels Internal Realm
<realm xsi:type="ns1:dir_realmType">
<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>
The Parallels Internal Realm is an authentication database that is installed on the host server during the Virtuozzo Containers software installation. This database is used to store the Virtuozzo Containers specific authentication information. Let's take a look at the XML structure above. The type of the realm
element is dir_realmType
. It is a descendant of the base realmType
type and it is used to hold the information about an LDAP-compliant directory. The type
element specifies the Realm type -- the value of 1
(one) means LDAP directory. The name
element inside the login
node is the user name that Agent will use to bound to the directory instance. The name, in this case, is a distinguished name (DN) identifying the user object in the directory. The user password is not included in the Realm definition but is known to Agent. Agent uses this information to bound to the directory to perform user authentication. The empty builtin
element indicates that this is a built-in Parallels Internal Realm (as opposed to custom Realms created by users). In fact, the rest of the Realms in this example are built-in Realms. The address
, port
, base_dn
, and default_dn
parameters describe the directory in terms of connectivity. Again, all of these elements are used by Agent to bound to the directory instance. At this point they are of little interest to us. The id
element contains the Realm ID. This is the ID that you will use in all other calls that require it, such as the login
call that will be described later in this section. Please note that the ID of the Parallels Internal Realm in your Virtuozzo Containers installation may not be the same as the ID in our example. There can be only one Parallels Internal Realm on any given Hardware Node.
System Realm
<realm xsi:type="ns2:realmType">
<builtin/>
<name>System</name>
<type>0</type>
<id>00000000-0000-0000-0000-000000000000</id>
</realm>
The System Realm represents user registry of the host operating system. When Agent is first installed, you will not have any Agent-specific users in any of the other Realms except the System Realm. If you have just started with Agent programming, use the system administrator account to log in to it. Agent knows how to identify the user with system administrator privileges and by default grants her/him unlimited access to the host server and all of the Virtuozzo Containers hosted by it. The ID of the System Realm in your installation will probably be the same as in this example (all zeros) but it is not guaranteed, so you should obtain it from the Agent installed on your server. You find the System Realm record in the result set by looking at the Realm type, which should be 0
(zero).
Virtuozzo Container Realm
<realm xsi:type="ns2:realmType">
<builtin/>
<name>Virtuozzo Container</name>
<type>1000</type>
<id>00000000-0000-0000-0100-000000000000</id>
</realm>
This Realm represents an operating system user registry inside a Virtuozzo Container. Use this Realm if you would like to log in to Agent as a user of one of the Containers. Once again, the ID of this Realm in your Virtuozzo installation may not be the same as the ID you see in the example above. Always get the Realm ID from the Agent installed on your server.
External LDAP directories
In our example, we didn't have any Realms representing an external LDAP directory. These Realms are added by Virtuozzo Containers system administrators when they want to perform user authentications against an external LDAP directory. The Realm record would look similarly to the Virtuozzo Internal Realm described above except that the builtin
parameter would not be present.