When you execute the system/login
call, a permanent session is created for the user whose credentials were included in the request. A permanent session is associated with the physical connection to Agent that your client is using. If you are not planning on logging in multiple users from the same program, you may simply use this session to execute your requests. A permanent session never expires, which means that even if your client program doesn't send any requests to Agent for a long time, the session will still stay active. When you are done working with Agent, you may simply exit and the session will be terminated automatically.
Optionally, you may create additional sessions using the sessionm
interface. This interface allows to log in additional clients or create additional sessions for the clients that are already logged in. Please note that you can use the sessionm
interface only after you've logged in using the system/login
call. The following request logs the user in and creates a temporary session:
<packet version="4.0.0" id="2">
<target>sessionm</target>
<data>
<sessionm>
<login>
<name>cm9vdA==</name>
<realm>00000000-0000-0000-0000-000000000000</realm>
<password>bXlwYXNz</password>
<expiration>1200</expiration>
</login>
</sessionm>
</data>
</packet>
The parameters in this call are used similarly to the system/login
call described in the previous section. The output will contain the SIDs plus the ID of the new session that was created:
<packet id="2" time="2007-09-10T09:42:13+0000" priority="0" version="4.0.0">
<origin>sessionm</origin>
<target>vzclient133-4fce28dd-0cd3-1345-bb94-3192b940fb90</target>
<dst>
<director>gend</director>
</dst>
<data>
<sessionm>
<session_id>vzl.40000.4.4fce28dd-0cd3-1345-bb94-3192b940fb90..f7c46e51175t321d6069r202d</session_id>
<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>
</sessionm>
</data>
<src>
<director>gend</director>
</src>
</packet>
In the output above, the session_id
element contains the new session ID. You must include this ID in every Agent request in order for the request to be processed within the contexts of the session. Failure to do so will result in the message being sent and processed using the default session created by the system/login
call. The following example shows how to include the session ID in an Agent request message.
<packet version="4.0.0" id="23">
<session>your_session_id_goes_here</session>
<data>
............
</data>
</packet>
User sessions expire after some predefined period of inactivity or after the timeout limit specified in the expiration
parameter is reached. The default session timeout value is specified in the Agent configuration. If the expiration
element is included in the request then its value overrides the default timeout value. Each request sent while a temporary session is still active resets the session timeout to its initial state. For the complete list of calls provided by the sessionm
interface, please see the Parallels Agent XML API Reference guide.