Managed Object - HostAccessManager(vim.host.HostAccessManager)

Property of: HostConfigManager
See also: HostAccessControlEntry, HostAccessMode, HostLockdownMode
Since: vSphere API 6.0

Managed Object Description

Managed object used to control direct access to the host.

This should be used to control users and privileges on the host directly, which are different from the users and privileges defined in vCenter.

See AuthorizationManager for more information on permissions.

Properties

Name	Type	Description
lockdownMode P	HostLockdownMode	Current lockdown state of the host.

P Required privilege: System.View

Methods

Methods defined in this Managed Object
ChangeAccessMode, ChangeLockdownMode, QueryLockdownExceptions, QuerySystemUsers, RetrieveHostAccessControlEntries, UpdateLockdownExceptions, UpdateSystemUsers

ChangeAccessMode(changeAccessMode)

Update the access mode for a user or group.

If the host is in lockdown mode, this operation is allowed only on users in the exceptions list - see QueryLockdownExceptions, and trying to change the access mode of other users or groups will fail with SecurityError.

Required Privileges: Global.Settings

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostAccessManager used to make the method call.
principal	xsd:string	The affected user or group.
isGroup	xsd:boolean	True if principal refers to a group account, false otherwise.
accessMode	HostAccessMode	AccessMode to be granted. AccessMode#accessOther is meaningless and will result in InvalidArgument exception.

Return Value

Type	Description
None

Faults

Type	Description
AuthMinimumAdminPermission
InvalidArgument	Thrown if accessMode is not valid.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SecurityError	Thrown if the host is in lockdown mode and 'principal' is not in the exceptions list.
UserNotFound	Thrown if the specified user is not found.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ChangeAccessMode" type="vim25:ChangeAccessModeRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ChangeAccessModeResponse">
            <complexType/>
         </element>

ChangeLockdownMode(changeLockdownMode)

Changes the lockdown state of the ESXi host.

This operation will do nothing if the host is already in the desired lockdown state.

When the host is in lockdown mode it can be managed only through vCenter and through DCUI (Direct Console User Interface) if the DCUI service is running. This is achieved by removing all permissions on the host, except those of the exception users defined with UpdateLockdownExceptions.

In addition, the permissions for users 'dcui', 'vpxuser' and 'vslauser' are always preserved.

When lockdown mode is disabled, the system will try to restore all permissions that have been removed when lockdown mode was enabled. It is possible that not all permissions may be restored and this is not an error, e.g. if in the meantime some user or managed object was deleted.

It may be possible that after exiting lockdown mode the only permissions on the host will be those of users 'dcui' and 'vpxuser'. This will render the host unmanageable if it is not already managed by vCenter, or if the connection to vCenter is lost. To prevent this, the users in the "DCUI.Access" list will be assigned Admin roles.

While the host is in lockdown mode, some operations will fail with SecurityError. This ensures that the conditions for lockdown mode cannot be changed. For example it is allowed to change the access mode only for users in the exceptions list.

When the host is in lockdown mode, changing the running state of service DCUI through HostServiceSystem will also fail with SecurityError accompanied with an appropriate localizeable message.

Required Privileges: Host.Config.Settings

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostAccessManager used to make the method call.

mode

HostLockdownMode

The new desired lockdown mode.

If this is the same as the current lockdown mode state, the operation will silently succeed and nothing will be changed.

If this is LockdownMode#lockdownDisabled then lockdown mode will be disabled and the system will start service DCUI if it is not running.

If this is LockdownMode#lockdownNormal then lockdown mode will be enabled and the system will start service DCUI if it is not running.

If this is LockdownMode#lockdownStrict then lockdown mode will be enabled and the system will stop service DCUI if it is running.

Return Value

Type	Description
None

Faults

Type	Description
AuthMinimumAdminPermission	Thrown if the user invoking the operation is not in the exceptions list - see QueryLockdownExceptions.
NoPermission	Thrown if the current session does not have enough permissions to perform the operation.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ChangeLockdownMode" type="vim25:ChangeLockdownModeRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ChangeLockdownModeResponse">
            <complexType/>
         </element>

QueryLockdownExceptions(queryLockdownExceptions)

Get the list of users which are exceptions for lockdown mode. See UpdateLockdownExceptions.

Required Privileges: Global.Settings

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostAccessManager used to make the method call.

Return Value

Type	Description
xsd:string[]	The list of users which will not lose their permissions when the host enters lockdown mode.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryLockdownExceptions" type="vim25:QueryLockdownExceptionsRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryLockdownExceptionsResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

QuerySystemUsers(querySystemUsers)

Get the list of local system users.

These are special users like 'vpxuser', 'vslauser' and 'dcui', which may be used for authenticating different sub-components of the vSphere system and may be essential for its correct functioning.

Usually these users may not be used by human operators to connect directly to the host and the UI may choose to show them only in some "advanced" UI view.

Required Privileges: Global.Settings

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostAccessManager used to make the method call.

Return Value

Type	Description
xsd:string[]	The list of local system users.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QuerySystemUsers" type="vim25:QuerySystemUsersRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QuerySystemUsersResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

RetrieveHostAccessControlEntries(retrieveAccessEntries)

Retrieve access entries. Returns a list of AccessEntry objects for each VIM user or group which have explicitly assigned permissions on the host. This means that AccessMode#accessNone will not be present in the result.

Required Privileges: Global.Settings

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostAccessManager used to make the method call.

Return Value

Type	Description
HostAccessControlEntry[]	A list of AccessEntry objects.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrieveHostAccessControlEntries" type="vim25:RetrieveHostAccessControlEntriesRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrieveHostAccessControlEntriesResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:HostAccessControlEntry" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

UpdateLockdownExceptions(updateLockdownExceptions)

Update the list of users which are exceptions for lockdown mode.

Usually these are user accounts used by third party solutions and external applications which need to continue to function in lockdown mode. It is not advised to add user accounts used by human operators, because this will compromise the purpose of lockdown mode.

Both local and domain users are supported. The format for domain accounts is "DOMAIN\login".

When this API is called when the host is in lockdown mode, the behaviour is as follows:

if a user is removed from the exceptions list, then the permissions of that user are removed.

if a user is added to the exceptions list, then the permissions of that user are restored.

Required Privileges: Global.Settings

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostAccessManager used to make the method call.
users*	xsd:string[]	the new list of lockdown mode exceptions.

*Need not be set

Return Value

Type	Description
None

Faults

Type	Description
AuthMinimumAdminPermission	Thrown if the user invoking the operation is not present in the new list of exceptions.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
UserNotFound	Thrown if one of the specified users is not found.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateLockdownExceptions" type="vim25:UpdateLockdownExceptionsRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateLockdownExceptionsResponse">
            <complexType/>
         </element>

UpdateSystemUsers(updateSystemUsers)

Update the list of local system users. The special users 'dcui', 'vpxuser' and 'vslauser' need not be specified. They are always reported in the list of system users.

Required Privileges: Global.Settings

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostAccessManager used to make the method call.
users*	xsd:string[]	the new list of local system users.

*Need not be set

Return Value

Type	Description
None

Faults

Type	Description
InvalidArgument	Thrown if one of the specified user names is not valid, or is in Active Directory domain format.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
UserNotFound	Thrown if one of the specified users is not found.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateSystemUsers" type="vim25:UpdateSystemUsersRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateSystemUsersResponse">
            <complexType/>
         </element>