Class: session

Last published : Oct 01, 2026
A session
Related information
XenServer 9 Management API

Fields for class: session

Field Type Qualifier Description
auth_user_name string RO/runtime the subject name of the user that was externally authenticated. If a session instance has is_local_superuser set, then the value of this field is undefined.
auth_user_sid string RO/runtime the subject identifier of the user that was externally authenticated. If a session instance has is_local_superuser set, then the value of this field is undefined.
client_certificate bool RO/runtime indicates whether this session was authenticated using a client certificate
is_local_superuser bool RO/runtime true iff this session was created using local superuser credentials
last_active datetime RO/runtime Timestamp for last time session was active
originator string RO/runtime a key string provided by a API user to distinguish itself from other users sharing the same login name
other_config (string -> string) map RW additional configuration
parent session ref RO/constructor references the parent session that created this session
pool bool RO/runtime True if this session relates to a intra-pool login, false otherwise
rbac_permissions string set RO/constructor list with all RBAC permissions for this session
subject subject ref RO/runtime references the subject instance that created the session. If a session instance has is_local_superuser set, then the value of this field is undefined.
tasks task ref set RO/runtime list of tasks created using the current session
this_host host ref RO/runtime Currently connected host
this_user user ref RO/runtime Currently connected user
uuid string RO/runtime Unique identifier/object reference
validation_time datetime RO/runtime time when session was last validated

RPCs associated with class: session

RPC name: addtootherconfig

Overview:
Add the given keyvalue pair to the otherconfig field of the given session.
Signature:
void add_to_other_config (session ref session_ref, session ref self, string key, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
string key Key to add
string value Value to add
Minimum Role: pool-admin
Return Type: void

RPC name: changepassword

Overview:
Change the account password; if your session is authenticated with root privileges then the oldpwd is validated and the newpwd is set regardless
Signature:
void change_password (session ref session_ref, string old_pwd, string new_pwd)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string old_pwd Old password for account
string new_pwd New password for account
Return Type: void

RPC name: createfromdbfile

Overview:
Signature:
session ref create_from_db_file (session ref session_ref, string filename)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string filename Database dump filename.
Return Type: session ref
ID of newly created session

RPC name: getallsubjectidentifiers

Overview:
Return a list of all the user subjectidentifiers of all existing sessions
Signature:
string set get_all_subject_identifiers (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: string set
The list of user subjectidentifiers of all existing sessions

RPC name: getauthusername

Overview:
Get the authusername field of the given session.
Signature:
string get_auth_user_name (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getauthusersid

Overview:
Get the authusersid field of the given session.
Signature:
string get_auth_user_sid (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getbyuuid

Overview:
Get a reference to the session instance with the specified UUID.
Signature:
session ref get_by_uuid (session ref session_ref, string uuid)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string uuid UUID of object to return
Minimum Role: read-only
Return Type: session ref
reference to the object

RPC name: getclientcertificate

Overview:
Get the clientcertificate field of the given session.
Signature:
bool get_client_certificate (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getislocalsuperuser

Overview:
Get the islocalsuperuser field of the given session.
Signature:
bool get_is_local_superuser (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getlastactive

Overview:
Get the lastactive field of the given session.
Signature:
datetime get_last_active (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: datetime
value of the field

RPC name: getoriginator

Overview:
Get the originator field of the given session.
Signature:
string get_originator (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getotherconfig

Overview:
Get the otherconfig field of the given session.
Signature:
(string -> string) map get_other_config (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: (string -> string) map
value of the field

RPC name: getparent

Overview:
Get the parent field of the given session.
Signature:
session ref get_parent (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: session ref
value of the field

RPC name: getpool

Overview:
Get the pool field of the given session.
Signature:
bool get_pool (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getrbacpermissions

Overview:
Get the rbacpermissions field of the given session.
Signature:
string set get_rbac_permissions (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: string set
value of the field

RPC name: getrecord

Overview:
Get a record containing the current state of the given session.
Signature:
session record get_record (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: session record
all fields from the object

RPC name: getsubject

Overview:
Get the subject field of the given session.
Signature:
subject ref get_subject (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: subject ref
value of the field

RPC name: gettasks

Overview:
Get the tasks field of the given session.
Signature:
task ref set get_tasks (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: task ref set
value of the field

RPC name: getthishost

Overview:
Get the thishost field of the given session.
Signature:
host ref get_this_host (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: host ref
value of the field

RPC name: getthisuser

Overview:
Get the thisuser field of the given session.
Signature:
user ref get_this_user (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: user ref
value of the field

RPC name: getuuid

Overview:
Get the uuid field of the given session.
Signature:
string get_uuid (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getvalidationtime

Overview:
Get the validationtime field of the given session.
Signature:
datetime get_validation_time (session ref session_ref, session ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
Minimum Role: read-only
Return Type: datetime
value of the field

RPC name: locallogout

Overview:
Log out of local session.
Signature:
void local_logout (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: pool-admin
Return Type: void

RPC name: loginwithpassword

Overview:
Attempt to authenticate the user, returning a session reference if successful
Signature:
session ref login_with_password (string uname, string pwd, string version, string originator)
Arguments:
Type Name Description
string uname Username for login.
string pwd Password for login.
string version Client API version.
string originator Key string for distinguishing different API users sharing the same login name.
Minimum Role: read-only
Return Type: session ref
reference of newly created session
Possible Error Codes: SESSION_AUTHENTICATION_FAILED, HOST_IS_SLAVE

RPC name: logout

Overview:
Log out of a session
Signature:
void logout (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: void

RPC name: logoutsubjectidentifier

Overview:
Log out all sessions associated to a user subjectidentifier, except the session associated with the context calling this function
Signature:
void logout_subject_identifier (session ref session_ref, string subject_identifier)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string subject_identifier User subject-identifier of the sessions to be destroyed
Minimum Role: pool-operator
Return Type: void

RPC name: removefromotherconfig

Overview:
Remove the given key and its corresponding value from the otherconfig field of the given session. If the key is not in that Map, then do nothing.
Signature:
void remove_from_other_config (session ref session_ref, session ref self, string key)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
string key Key to remove
Minimum Role: pool-admin
Return Type: void

RPC name: setotherconfig

Overview:
Set the otherconfig field of the given session.
Signature:
void set_other_config (session ref session_ref, session ref self, (string -> string) map value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
(string -> string) map value New value to set
Minimum Role: pool-admin
Return Type: void

RPC name: slavelocalloginwithpassword

Overview:
Authenticate locally against a slave in emergency mode. Note the resulting sessions are only good for use on this host.
Signature:
session ref slave_local_login_with_password (string uname, string pwd)
Arguments:
Type Name Description
string uname Username for login.
string pwd Password for login.
Minimum Role: pool-admin
Return Type: session ref
ID of newly created session