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 PHostLockdownMode

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

NameTypeDescription
_thisManagedObjectReference A reference to the HostAccessManager used to make the method call.
principalxsd:string

The affected user or group.
isGroupxsd:boolean

True if principal refers to a group account, false otherwise.
accessModeHostAccessMode

AccessMode to be granted. AccessMode#accessOther is meaningless and will result in InvalidArgument exception.

Return Value

Type Description
None

Faults

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

Events

Type
None

Show WSDL type definition



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

NameTypeDescription
_thisManagedObjectReference A reference to the HostAccessManager used to make the method call.
modeHostLockdownMode

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
AuthMinimumAdminPermissionThrown if the user invoking the operation is not in the exceptions list - see QueryLockdownExceptions.
NoPermissionThrown if the current session does not have enough permissions to perform the operation.
RuntimeFaultThrown 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



QueryLockdownExceptions(queryLockdownExceptions)

Get the list of users which are exceptions for lockdown mode. See UpdateLockdownExceptions.
Required Privileges
Global.Settings

Parameters

NameTypeDescription
_thisManagedObjectReference 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
RuntimeFaultThrown 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



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

NameTypeDescription
_thisManagedObjectReference 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
RuntimeFaultThrown 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



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

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

Return Value

Type Description
HostAccessControlEntry[]A list of AccessEntry objects.

Faults

Type Description
RuntimeFaultThrown 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



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

    NameTypeDescription
    _thisManagedObjectReference 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
    AuthMinimumAdminPermissionThrown if the user invoking the operation is not present in the new list of exceptions.
    RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
    UserNotFoundThrown if one of the specified users is not found.

    Events

    Type
    None

    Show WSDL type definition



    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

    NameTypeDescription
    _thisManagedObjectReference 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
    InvalidArgumentThrown if one of the specified user names is not valid, or is in Active Directory domain format.
    RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
    UserNotFoundThrown if one of the specified users is not found.

    Events

    Type
    None

    Show WSDL type definition