veeam-em

Manager

This module sends request to the Veeam Backup Enterprise Manager REST API.

Veeam Backup Enterprise Manager RESTful API, and process response in JSON format.

class veeam_em.manager.VeeamEm(tk: Optional[str] = None, api_endpoint: Optional[str] = None, ssl_verify: Optional[bool] = None, debug: Optional[bool] = False, timeout: Optional[int] = None, session: Optional[requests.sessions.Session] = None, content_type: Optional[str] = None, user_agent: Optional[str] = None, api_version: Optional[str] = None)[source]

Bases: object

Class containing methods to interact with the Veeam EM REST API.

Example:

em = VeeamEm(tk)
vss.get_accounts()

If tk is None it will get the token from the VEEAMEM_API_TOKEN environment variable or generate a new via get_token with the function arguments or VEEAMEM_API_USER and VEEAMEM_API_USER_PASS

Example:

em = VeeamEm(tk)
em.get_token()
DELETE = 'DELETE'
GET = 'GET'
OPTIONS = 'OPTIONS'
PATCH = 'PATCH'
POST = 'POST'
PUT = 'PUT'
add_role_to_account(uuid, account_uuid: str) → Dict[source]

Add role to account by role uuid and account uuid.

Assigns a Veeam Backup Enterprise Manager security role to the specified user account. :param uuid: :param account_uuid: :return:

add_scopes_to_account(account_uuid: str, h_objects_ref: List[Tuple])[source]

Add scopes to account.

Assigns a restore scope to the account having the specified ID. The account is added to Veeam Backup Enterprise Manager and has a specific security role.

Parameters

  • account_uuid – account identifier

  • h_objects_ref – Reference list to the objects (ref,name)

Returns

property api_token: str

Return API token.

property content_type: str

Return content_type set.

create_account(name: str, a_type: str, roles_uid: List[str], flr_settings=None, sql_settings=None, h_scope_objects: Optional[List[Tuple[str, str]]] = None, restore_all_vms: bool = False, content_type: str = 'json')[source]

Add a user or a group account with role and settings.

Parameters

  • name – Name of the account added to Veeam Backup Enterprise Manager. For a regular account, the name must be specified in the DOMAIN\\USERNAME format, for example: TECH\\william.fox. For accounts of the ExternalUser and ExternalGroup type, the name must be specified in the User Principal Name (UPN) format, for example: william.fox@tech.com.

  • a_type – Type of account added to Veeam Backup Enterprise Manager. Possible values: - User - Group - ExternalUser - ExternalGroup Accounts of the ExternalUser and ExternalGroup type must be created for users who will access Veeam Backup Enterprise Manager using a single sign-on service.

  • roles_uid – List of ID of the role assigned to the added account. To get a list of IDs for available roles, call get_roles().

  • h_scope_objects – Restore scope assigned to the added account see get_hierarchy_obj_ref_type() to generate each item in list. List of tuples i.e. [(hierarchy_object_ref, object_name)].

  • flr_settings – File-level restore restrictions assigned to the added account. see get_account_flr_settings_spec()

  • sql_settings – SQL restore restrictions assigned to the added account. see get_account_sql_settings_spec()

  • restore_all_vms – Defines whether the account must have permissions to restore all VMs or not. If this parameter is set to False, the client must provide the restore scope in the h_scope_objects element.

  • content_type – api format either json or xml

Returns

property debug: str

Get debug value.

delete_account(uuid: str)[source]

Remove account from system.

Removes an account having the specified ID and a specific security role from Veeam Backup Enterprise Manager. :param uuid: account identifier :return:

disable_all_vms_restore_scope_account(uuid: str) → bool[source]

Disable All virtual machines option specified for the account.

Remove permission to restore all VMs in the virtual infrastructure.

enable_all_vms_restore_scope_account(uuid: str) → bool[source]

Enable All virtual machines option specified for the account.

Assign permission to restore all VMs in the virtual infrastructure.

get_account(uuid: str)[source]

Get account by uuid.

Represents an account having the specified ID. The account is added to Veeam Backup Enterprise Manager and is assigned a specific security role.

Parameters

uuid – item unique identifier

Returns

static get_account_flr_settings_spec(in_place_only: bool = False, ext_restriction: Optional[str] = None) → Dict[source]

Get File-level restore restrictions assigned to the added account.

Parameters

  • in_place_only – Defines whether the account must have permissions to restore only files with specific filename extensions or not. If this parameter is set to True, the client must provide filename extensions for files that are permitted for restore in the ext_restriction element.

  • ext_restriction – Filename extensions for files that are permitted for restore separated by ‘,’ (comma), for example: doc,pptx,pdf.

Returns

dict

static get_account_role_spec(uid)[source]

Get account role specification.

get_account_roles(uuid: str) → Dict[source]

Get account roles by user uuid.

Represents a security role or a collection of security roles assigned to the specified account that is added to Veeam Backup Enterprise Manager.

Parameters

uuid – item unique identifier

Returns

get_account_scope(uuid: str, scope_uuid: str) → Dict[source]

Get Account scope.

Represents a specific restore scope defined for the specified account. The account is added to Veeam Backup Enterprise Manager and is assigned a specific security role.

Returns

get_account_scopes(uuid: str) → Dict[source]

Get Account Scopes.

Represents a restore scope defined for the specified account that is added to Veeam Backup Enterprise Manager and is assigned a specific security role.

Parameters

uuid – item unique identifier

Returns

static get_account_sql_settings_spec(deny_in_place_restore: bool) → Dict[source]

Get SQL restore restrictions assigned to the added account.

Parameters

deny_in_place_restore – Defines whether you want to prevent user account from overriding production databases at restore.

Returns

dict

get_accounts() → List[Dict][source]

Get available accounts.

Represents a collection of accounts having specific security roles in Veeam Backup Enterprise Manager.

Returns

get_accounts_by_name(name: str) → List[Dict][source]

Filter account by name.

Parameters

name – account name or substring

Returns

list of items

get_backup_task_sessions(page_size: int = 2000, **kwargs) → List[Dict][source]

Get backup task sessions using the query service.

{‘CreationTimeUTC’: ‘2020-12-10T15:06:21.363Z’,

‘Href’: ‘/api/backupTaskSessions/…?format=Entity’, ‘JobSessionUid’: ‘urn:veeam:BackupJobSession:…’, ‘Links’: [{‘Href’: ‘h/api/backupServers/-…’,

‘Name’: ‘host.domain.ca’, ‘Rel’: ‘Up’, ‘Type’: ‘BackupServerReference’},

{‘Href’: ‘/api/backupSessions/…’,

‘Name’: ‘Backup Job Folder vm@2020-12-10 15:05:12’, ‘Rel’: ‘Up’, ‘Type’: ‘BackupJobSessionReference’},

{‘Href’: ‘/api/backupTaskSessions/…’,

‘Name’: ‘vm-3@2020-12-10 15:06:21’, ‘Rel’: ‘Alternate’, ‘Type’: ‘BackupTaskSessionReference’}],

‘Name’: ‘vn-3@2020-12-10 15:06:21’, ‘Reason’: ‘’, ‘Result’: ‘Success’, ‘State’: ‘InProgress’, ‘TotalSize’: 42949672960, ‘Type’: ‘BackupTaskSession’, ‘UID’: ‘urn:veeam:BackupTaskSession:…’, ‘VmDisplayName’: ‘vm-3’, ‘VmUid’: ‘urn:VMware:Vm:….vm-13587’}

get_hierarchy_obj_ref_platform(platform_name: str) → Optional[Dict][source]

Get Hierarchy Object Reference by platform name.

Platform is the platform on which the virtual infrastructure object is created: VMware, Hyperv or vCloud :param platform_name: VMware, Hyperv or vCloud :return: dict

get_hierarchy_obj_ref_platforms() → List[source]

Get Hierarchy Object Reference Platforms.

Platform is the platform on which the virtual infrastructure object is created: VMware, Hyperv or vCloud :return:

get_hierarchy_obj_ref_type(ref_platform: str, ref_type: str, ref_h_root_id: str, object_ref: str, validate_h_root: bool = False) → str[source]

Get Hierarchy object reference type.

The HierarchyObjRefType object describes a specific node in the virtual infrastructure hierarchy. This object must be constructed for requests that refer to some node or level in the virtual infrastructure hierarchy, for example, a request editing a job or assigning a restore scope to the account in Veeam Backup Enterprise Manager.

The HierarchyObjRefType object is constructed as a string that has the following pattern:

urn:<ref_platform>:<ref_type>:<ref_h_root_id>.<object_ref>

Parameters

  • ref_platform – is the platform on which the virtual infrastructure object is created: VMware, Hyperv or vCloud.

  • ref_type – Type is the object type.

  • ref_h_root_id – is an ID of the host on which the virtual infrastructure object resides. The HierarchyRootID can be obtained using the get_hierarchy_roots() or get_hierarchy_root() methods. is an ID of the host on which the virtual infrastructure object resides.

  • object_ref – ObjectRef is an ID of the virtual infrastructure object itself: mo-ref or ID, depending on the virtualization platform.

  • validate_h_root – whether to validate if provided root exists

Returns

str

get_hierarchy_root(uuid: str) → Dict[source]

Get Hierarchy Root by UUID.

Represents a virtualization host having the specified ID. The virtualization host is added to the Veeam backup server connected to Veeam Backup Enterprise Manager.

Parameters

uuid – item unique identifier

Returns

get_hierarchy_roots()[source]

Get Hierarchy Roots.

Represents a collection of all virtualization hosts added to the Veeam backup servers connected to Veeam Backup Enterprise Manager. :return: list

get_hierarchy_roots_by_name(name: str) → List[Dict][source]

Filter Hierarchy root by name.

Parameters

name – hierarchy root name or substring

Returns

list of items

static get_hierarchy_scope_object(h_object_ref: str, object_name: str) → Dict[source]

Get Hierarchy scope object.

Parameters

  • h_object_ref – Reference to the object in the virtual infrastructure hierarchy.

  • object_name – Name of the object in the virtual infrastructure hierarchy.

Returns

static get_hierarchy_scope_objects(objects: List[Tuple]) → Dict[source]

Get Hierarchy scope objects.

Parameters

objects – list of tuples. first item is HierarchyObjRef:

Reference to the object in the virtual infrastructure hierarchy. see get_hierarchy_obj_ref_type(). Second item is ObjectName: Name of the object in the virtual infrastructure hierarchy. :return: list of dictionaries

get_logon_session(session_id: str) → Optional[Dict][source]

Get logon session by session_id.

Represents a currently existing logon session having the specified ID.

Note:: returns 500 error if session

does not exist. This may be a bug.

Parameters

session_id –

Returns

get_logon_sessions() → Optional[List[Dict]][source]

Get logon sessions.

Represents a collection of currently existing logon sessions for Veeam Backup Enterprise Manager RESTful API. :return:

get_lookup_service(host_uid: str, h_ref: str, obj_type: Optional[str] = None, obj_name: Optional[str] = None)[source]

Get a resource of a specific virtual infrastructure object.

/lookup?host={hostUID}&hierachyRef={hierachyRef}&name={objName}&type={objType} :param host_uid: hierarchy root id get_hierarchy_root() :param h_ref: hierachy reference get_hierarchy_obj_ref_type() :param obj_type: object type (optional) :param obj_name: object name. ‘*’ to search by any name :return:

get_role(uuid: str) → Dict[source]

Get role by UUID.

Represents a Veeam Backup Enterprise Manager security role having the specified ID.

Parameters

uuid – item unique identifier

Returns

dict

get_roles() → List[Dict][source]

Get available Roles.

Represents a collection of security roles used in Veeam Backup Enterprise Manager.

Veeam Backup Enterprise Manager RESTful API exposes the following security roles:

  • Portal User

  • Portal Administrator

  • VM Restore Operator

  • File Restore Operator

  • Exchange Restore Operator

  • SQL Restore Operator

Returns

list

get_roles_by_name(name: str) → List[Optional[Dict]][source]

Get Roles by name.

Returns Veeam Backup Enterprise Manager security roles with the provided name string :param name: name to filter :return:

get_token(user: Optional[str] = None, password: Optional[str] = None) → str[source]

Generate a new access token based on user/pass.

process_rv(response)[source]

Process response data and code.

Parameters

response – request.response object

Returns

dict

remove_role_from_account(uuid: str, account_uuid: str) → Optional[Dict][source]

Remove role from account by role uuid and account uuid.

Removes the Veeam Backup Enterprise Manager security role from the account having the specified ID.

Parameters

  • uuid – role identifier

  • account_uuid – account identifier

Returns

remove_scope_from_account(scope_uuid: str, account_uuid: str) → Optional[Dict][source]

Remove scope from account.

Removes a restore scope having the specified ID from the account having the specified ID. The account is added to Veeam Backup Enterprise Manager and is assigned a specific security role.

Parameters

  • scope_uuid – scope identifier

  • account_uuid – account identifier

Returns

request(url: str, headers: Optional[Dict] = None, params: Optional[Dict] = None, payload: Optional[Dict] = None, method: Optional[str] = None, auth: Optional[requests.auth.HTTPBasicAuth] = None, data: Optional[str] = None) → Optional[Dict][source]

Make request to given endpoint.

property ssl_verify: bool

Get ssl_verify value in class.

update_all_vms_restore_scope_account(uuid: str, value: bool) → bool[source]

Enable or Disable All virtual machines option for the account.

The account added to Veeam Backup Enterprise Manager can be assigned a permission to restore all VMs in the virtual infrastructure or only those VMs that belong to a specific level: for example, VMs that reside in a specific resource pool. By sending the POST HTTP request to the /security/accounts/{ID} URL, the client can toggle this setting to enabled or disabled.

Parameters

  • uuid – Account uuid

  • value – Enable true, disable false.

Returns

property user_agent: str

Return user_agent.

whoami() → Optional[Dict][source]

Check if sessionId is valid.

Helper

Contain complimentary functions to veeam_em.manager module.

class veeam_em.helper.HTTPBasicAuth(username, password)[source]

Bases: requests.auth.HTTPBasicAuth

Custom class to allow unicode in username and password.

static make_header(username, password)[source]

Make header based on username and password.

veeam_em.helper.debug_requests() → collections.abc.Generator[source]

Yieldable way to turn on debugs for requests.

with debug_requests(): <do things>

veeam_em.helper.debug_requests_off() → None[source]

Switch off logging of the requests module.

Might have some side-effects.

veeam_em.helper.debug_requests_on() → None[source]

Switch on logging of the requests module.

Exceptions