PyU4V

https://pyu4v.readthedocs.io/en/latest/
Admin
PyU4V is a Python module that simplifies interaction with the Dell Unisphere for PowerMax REST API...
Tokens:114,058
Snippets:574
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Configure [setup] section in PyU4V.conf

Source: https://pyu4v.readthedocs.io/en/latest/configuration.html

Example [setup] section in PyU4V.conf. Replace the values with your environment: username and password for Unisphere REST login, server_ip and port for the Unisphere server, array for the 12-digit serial, and verify for SSL verification (True, a file path, or False).

```ini
[setup]
username=pyu4v-user
password=secret-pass
server_ip=10.0.0.75
port=8443
array=00012345678
verify=/path-to-file/server_hostname.pem

```

--------------------------------

### Edit PyU4V.conf [setup] section

Source: https://pyu4v.readthedocs.io/en/latest/_sources/configuration.rst.txt

Example configuration settings for the [setup] section of PyU4V.conf. Replace the values with your environment: username, password, server_ip, port, array (12-digit serial), and verify (True, file path, or False).

```bash
[setup]
username=pyu4v-user
password=secret-pass
server_ip=10.0.0.75
port=8443
array=00012345678
verify=/path-to-file/server_hostname.pem
```

--------------------------------

### Create and Manage Clones (clone.py)

Source: https://pyu4v.readthedocs.io/en/latest/_sources/programmers_guide_src/clone.rst.txt

Example of replication calls to create independent copies of data using clone technology. Referenced from the Dell Solutions Enabler TimeFinder/Clone CLI User Guide.

```python
.. literalinclude:: code/clone.py
    :linenos:
    :language: python
    :lines: 14-34
```

--------------------------------

### Install PyU4V from source using git and pip

Source: https://pyu4v.readthedocs.io/en/latest/_sources/installation.rst.txt

Clones the PyU4V repository from GitHub and installs it using pip. Run these commands in a terminal.

```bash
$ git clone https://github.com/dell/PyU4V
$ cd PyU4V/
$ pip install .
```

--------------------------------

### Build PyU4V documentation with Sphinx

Source: https://pyu4v.readthedocs.io/en/latest/_sources/index.rst.txt

Commands to install Sphinx and the Read the Docs theme, then build the HTML documentation. Run from the PyU4V/docs directory. Output is generated in /PyU4V/docs/build.

```bash
$ pip install sphinx
$ pip install sphinx-rtd-theme
$ cd PyU4V/docs
$ make clean && make html
```

--------------------------------

### Perform System Health Check and Retrieve Disk Details

Source: https://pyu4v.readthedocs.io/en/latest/programmers_guide_src/system.html

Demonstrates performing a system health check, retrieving the last check's details, and iterating through installed disk IDs to get their specific information.

```python
 1"""docs/source/programmers_guide_src/code/system-health_check.py."""
 2
 3import PyU4V
 4
 5# Initialise PyU4V connection to Unisphere
 6conn = PyU4V.U4VConn()
 7
 8# Perform a system health check, this call can take 15-20 minutes to
 9# complete in Unisphere due to the nature of the checks performed
10conn.system.perform_health_check(description='test-hc-dec19')
11
12# Get details of the last system health check
13health_check = conn.system.get_system_health()
14
15# Get a list of physical disks installed in the array
16disk_list = conn.system.get_disk_id_list()
17# Get disk information for each disk installed
18for disk in disk_list.get('disk_ids'):
19    disk_info = conn.system.get_disk_details(disk_id=disk)
20
21# Close the session
22conn.close_session()
```

--------------------------------

### Check PyU4V installation with pip show

Source: https://pyu4v.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Verifies that PyU4V is installed before initialising a connection. Run this command in a terminal after following the installation instructions.

```bash
$ pip show PyU4V
```

--------------------------------

### Pass configuration directly to U4VConn()

Source: https://pyu4v.readthedocs.io/en/latest/_sources/configuration.rst.txt

Initializes U4VConn() with environment settings passed as keyword arguments, overriding any PyU4V.conf settings. The example shows a successful call to get_unisphere_version() returning a version dictionary.

```Python
>>> import PyU4V
>>> conn = U4VConn(
        username='pyu4v-user', password='secret-pass',
        server_ip='10.0.0.75', port='8443', verify=True,
        array_id='00012345678')
>>> conn.common.get_unisphere_version()
{'version': 'V9.1.0.5'}
```

--------------------------------

### Install PyU4V via pip

Source: https://pyu4v.readthedocs.io/en/latest/_sources/installation.rst.txt

Installs PyU4V directly from PyPI using pip. The second command installs a specific version (10.4.0.0).

```bash
$ pip install PyU4V
# Install a specific version
$ pip install PyU4V==10.4.0.0
```

--------------------------------

### Restore Clone (restoreclone.py)

Source: https://pyu4v.readthedocs.io/en/latest/_sources/programmers_guide_src/clone.rst.txt

Example of restoring a clone, as part of the clone management workflow.

```python
.. literalinclude:: code/restoreclone.py
    :linenos:
    :language: python
    :lines: 14-18
```

--------------------------------

### Create, modify, and delete a snapshot policy with PyU4V

Source: https://pyu4v.readthedocs.io/en/latest/programmers_guide_src/replication.html

Connects to Unisphere for PowerMax, creates a storage group, creates a snapshot policy, modifies it, and deletes it. The example asserts the policy is created and renamed, then closes the session.

```python
1"""docs/source/programmers_guide_src/code/replication-snapshot_policy.py"""
2
3import PyU4V
4
5# Set up connection to Unisphere for PowerMax Server, details collected
6# from configuration file in working directory where script is stored.
7conn = PyU4V.U4VConn()
8
9# Create storage Group with one volume
10storage_group = conn.provisioning.create_non_empty_storage_group(
11    srp_id='SRP_1', storage_group_id='PyU4V_SG', service_level='Diamond',
12    workload=None, num_vols=1, vol_size=1, cap_unit='GB')
13
14# Create a snapshot policy for the new storage group
15policy_name = 'PyU4V-Test_Policy'
16snap_policy = conn.snapshot_policy.create_snapshot_policy(
17    snapshot_policy_name=policy_name, interval='1 Day',
18    cloud_retention_days=7, cloud_provider_name='Generic_Provider',
19    local_snapshot_policy_snapshot_count=5)
20
21# Confirm the snapshot policy was created successfully
22assert policy_name in conn.snapshot_policy.get_snapshot_policy_list()
23
24# Get snapshot policy detailed info
25snap_policy_details = conn.snapshot_policy.get_snapshot_policy(
26    snapshot_policy_name=policy_name)
27
28# Modify the snapshot policy
29new_policy_name = 'PyU4V-Test_Policy-5mins'
30new_snap_policy = conn.snapshot_policy.modify_snapshot_policy(
31    snapshot_policy_name=policy_name, action='Modify',
32    new_snapshot_policy_name=new_policy_name, interval_mins=5)
33
34# Confirm the snapshot policy was renamed successfully
35assert new_policy_name in conn.snapshot_policy.get_snapshot_policy_list()
36assert policy_name not in conn.snapshot_policy.get_snapshot_policy_list()
37
38# Delete the snapshot policy
39conn.snapshot_policy.delete_snapshot_policy(
40    snapshot_policy_name=new_policy_name)
41
42# Close the session
43conn.close_session()
```

--------------------------------

### Copy sample PyU4V.conf to home directory

Source: https://pyu4v.readthedocs.io/en/latest/_sources/configuration.rst.txt

Creates the ~/.PyU4V directory and copies the sample configuration file to it, renaming it to PyU4V.conf. The ~ symbol represents the user's home directory; on Windows use the full path like C:\Users\{user}\.PyU4V.

```bash
$ mkdir ~/.PyU4V
$ cp PyU4V/PyU4V.conf.sample ~/.PyU4V/PyU4V.conf
```

--------------------------------

### Asynchronous storage provisioning with PyU4V: check headroom, create SG, host, port group, masking view

Source: https://pyu4v.readthedocs.io/en/latest/programmers_guide_src/provisioning.html

Use this script to asynchronously provision storage on a Unisphere array. It first checks available headroom via conn.wlp.get_headroom() and only proceeds if the requested capacity (10GB) fits. It then creates a storage group asynchronously, waits for the job, creates a host, port group, and masking view, and finally closes the session. The example uses hard-coded initiator IDs and port IDs; these can be retrieved via conn.provisioning.get_available_initiator() and conn.provisioning.get_port_list().

```python
1"""docs/source/programmers_guide_src/code/provision-async_create_storage.py"""
2
3import PyU4V
4
5# Initialise PyU4V connection to Unisphere
6conn = PyU4V.U4VConn()
7
8# Before provisioning storage we are going to check that there is enough
9# headroom left on the array for our provisioning operations
10REQUESTED_CAPACITY = 10
11
12# Get the available headroom for the SRP and service level required
13headroom_info = conn.wlp.get_headroom(array_id=conn.array_id,
14                                      srp='SRP_1', slo='Diamond')
15
16# Extract the capacity value from the headroom_info REST response
17headroom_capacity = headroom_info[
18    'OLTP'][0]['headroom'][0]['headroomCapacity']
19
20# If the requested capacity of 10GB is less than or equal to the available
21# capacity proceed with the provisioning operations
22if REQUESTED_CAPACITY <= int(headroom_capacity):
23    # Create a non-empty storage group using asynchronous request - we can
24    # wait until the job completes or proceed with operations and check
25    # back at a later time
26    storage_group_async_job = (
27        conn.provisioning.create_non_empty_storage_group(
28            srp_id='SRP_1', storage_group_id='example-sg',
29            service_level='Diamond', num_vols=1,
30            vol_size=REQUESTED_CAPACITY, cap_unit='GB', _async=True))
31
32    # We will wait this time on the results of the storage group create
33    # request
34    conn.common.wait_for_job(operation='Create SG with volume',
35                             job=storage_group_async_job)
36    print('Storage Group created successfully...')
37
38    # Get information on our new storage group
39    storage_group_info = conn.provisioning.get_storage_group(
40        storage_group_name='Example-SG')
41    print('Storage Group details: {details}'.format(
42        details=storage_group_info))
43
44    # Create a Host using supplied initiator IDs, these can be also be
45    # retrieved via the call conn.provisioning.get_available_initiator()
46    initiator_list = ['iqn:2020-test1', 'iqn:2020-test1']
47    host_info = conn.provisioning.create_host(
48        host_name='Example-Host', initiator_list=initiator_list)
49    print('Host created successfully...')
50    print('New Host details: {details}'.format(details=host_info))
51
52    # Create a Port Group using supplied ports, these could be also be
53    # retrieved via the call conn.provisioning.get_port_list()
54    port_group_info = conn.provisioning.create_port_group(
55        port_group_id='Example-PG', director_id='SE-01', port_id='1')
56    print('Port Group created successfully...')
57    print('Port Group details: {details}'.format(details=port_group_info))
58
59    # Create a Masking View and tie all the elements we have created
60    # together
61    masking_view_info = (
62        conn.provisioning.create_masking_view_existing_components(
63            port_group_name='Example-PG', masking_view_name='Example-MV',
64            storage_group_name='Example-SG', host_name='Example-Host'))
65    print('Masking View created...')
66    print('Masking View details: {details}'.format(
67        details=masking_view_info))
68
69# Close the session
70conn.close_session()

```

--------------------------------

### Download and upload system settings with PyU4V

Source: https://pyu4v.readthedocs.io/en/latest/programmers_guide_src/system.html

Downloads system settings from the primary array, excluding system thresholds, then uploads and applies them to a target array. Requires a file_password to verify settings when applying them elsewhere, preventing unauthorized changes. The example prints the saved settings location and closes the session.

```python
 1"""docs/source/programmers_guide_src/code/system-settings_management.py."""
 2
 3import PyU4V
 4
 5# Initialise PyU4V connection to Unisphere
 6conn = PyU4V.U4VConn()
 7
 8# Download system settings for primary array defined in PyU4V.conf, exclude the
 9# system thresholds settings
10settings_info = conn.system.download_system_settings(
11    file_password='PyU4V', dir_path='~/datastore/system_settings',
12    file_name='settings_gold_master', exclude_system_threshold_settings=True)
13
14# Assert the download operation was successful and print the location of the
15# downloaded file
16assert settings_info.get('success') is True
17print('The system settings for {array} are saved to: {loc}'.format(
18    array=conn.array_id, loc=settings_info.get('settings_path')))
19
20# Upload the settings and apply to target array
21upload_details = conn.system.upload_settings(
22    file_password='PyU4V', file_path=settings_info.get('settings_path'),
23    array_id='000111222333')
24
25# Close the session
26conn.close_session()

```

--------------------------------

### Get CloudIQ Data Collection Configuration

Source: https://pyu4v.readthedocs.io/en/latest/_modules/PyU4V/settings.html

Retrieves the CloudIQ data collection configuration by sending a GET request to the settings registration cloudiq endpoint. No query parameters are passed.

```python
query_params = {}
return self.common.get_request(
    target_uri=f"/{self.common.UNI_VERSION}/settings/"
               f"registration/cloudiq", resource_type=None,
    params=query_params)
```

--------------------------------

### Connect to Unisphere with PyU4V and retrieve version and arrays

Source: https://pyu4v.readthedocs.io/en/latest/programmers_guide_src/basic_operations.html

Initialises a PyU4V connection to Unisphere using U4VConn with server IP, port, certificate path, and credentials. Retrieves the Unisphere version and array list, filters for local arrays, prints results, and closes the session. Requires a valid Unisphere instance and the specified certificate file.

```python
 1"""docs/source/programmers_guide_src/code/basic-unisphere_connect.py."""
 2
 3import PyU4V
 4
 5# Initialise PyU4V connection to Unisphere
 6conn = PyU4V.U4VConn(
 7    server_ip='10.0.0.75', port=8443, verify='~/.PyU4V/Unisphere91.pem',
 8    username='pyu4v-user', password='secret-pass')
 9
10# Get the Unisphere version
11version = conn.common.get_uni_version()
12
13# Retrieve a list of arrays managed by your instance of Unisphere
14array_list = conn.common.get_array_list()
15
16# Output results to screen
17print('Congratulations on your first connection to Unisphere, your '
18      'version is: {ver}'.format(ver=version[0]))
19print('This instance of Unisphere instance manages the following arrays: '
20      '{arr_list}'.format(arr_list=array_list))
21
22# GET those arrays which are local to this instance of Unisphere
23local_array_list = list()
24for array_id in array_list:
25    array_details = conn.common.get_array(array_id)
26    if array_details['local']:
27        local_array_list.append(array_id)
28
29# Output results to screen
30print('The following arrays are local to this Unisphere instance: '
31      '{arr_list}'.format(arr_list=local_array_list))
32
33# Close the session
34conn.close_session()
```

--------------------------------

### GET /{UNI_VERSION}/settings/alert/performance_threshold

Source: https://pyu4v.readthedocs.io/en/latest/_modules/PyU4V/settings.html

Lists Global Thresholds and Alerts.

```APIDOC
## GET /{UNI_VERSION}/settings/alert/performance_threshold

### Description
Lists Global Thresholds and Alerts.

### Method
GET

### Endpoint
/{UNI_VERSION}/settings/alert/performance_threshold

### Parameters
#### Query Parameters
- **enabled_alerts** (bool) - Optional - Whether to include enabled alerts
- **category** (string) - Optional - Category filter

### Response
#### Success Response (200)
- **response** (object) - The response from the get request.

#### Response Example
{
  "response": {}
}
```

--------------------------------

### GET /{UNI_VERSION}/settings/registration/cloudiq

Source: https://pyu4v.readthedocs.io/en/latest/_modules/PyU4V/settings.html

Lists the CloudIQ Data Collection Configuration.

```APIDOC
## GET /{UNI_VERSION}/settings/registration/cloudiq

### Description
Lists the CloudIQ Data Collection Configuration.

### Method
GET

### Endpoint
/{UNI_VERSION}/settings/registration/cloudiq

### Parameters
#### Query Parameters
- **array_id** (string) - Optional - The storage array ID

### Response
#### Success Response (200)
- **response** (object) - The response from the get request.

#### Response Example
{
  "response": {}
}
```

--------------------------------

### get_health_check_details

Source: https://pyu4v.readthedocs.io/en/latest/_modules/PyU4V/system.html

Gets details of an individual health check for a specified array.

```APIDOC
## get_health_check_details

### Description
Gets details of an individual health check.

### Method
GET

### Endpoint
/system/symmetrix/{array_id}/health/health_check/{health_check_id}

### Parameters
#### Path Parameters
- **array_id** (string) - Optional - The array ID. If not provided, the default array ID is used.
- **health_check_id** (string) - Required - The health check ID.

### Response
#### Success Response (200)
- **health check details** (dict) - The details of the health check.

#### Response Example
{
  "health_check_details": {}
}
```

--------------------------------

### Initialise PyU4V connection with U4VConn

Source: https://pyu4v.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Initialises a connection to Unisphere using the configuration provided in PyU4V.conf. The U4VConn constructor loads the settings from the configuration file.

```python
import PyU4V
conn = PyU4V.U4VConn()
```

--------------------------------

### Get snapshot policy compliance for last week

Source: https://pyu4v.readthedocs.io/en/latest/_modules/PyU4V/snapshot_policy.html

Calls get_snapshot_policy_compliance with last_week=True to retrieve compliance for the last week.

```python
    def get_snapshot_policy_compliance_last_week(
            self, storage_group_name):
        """Get compliance attributes on a storage group for the last week.

        :param storage_group_name: storage group name
        :returns: resource -- dict
        """
        return self.get_snapshot_policy_compliance(
            storage_group_name, last_week=True)
```

--------------------------------

### Manage performance thresholds with PyU4V

Source: https://pyu4v.readthedocs.io/en/latest/programmers_guide_src/performance.html

Demonstrates retrieving all performance threshold settings, writing them to a CSV file, reading the CSV into a dictionary, updating threshold values, and uploading the updated settings to Unisphere. The example also shows directly updating a threshold metric without a CSV using update_threshold_settings. Requires an active PyU4V connection to Unisphere.

```python
1"""docs/source/programmers_guide_src/code/performance-thresholds.py."""
2
3import os
4import PyU4V
5
6# Initialise PyU4V connection to Unisphere
7conn = PyU4V.U4VConn()
8
9# Set the CSV file name and path
10current_directory = os.getcwd()
11output_csv_name = 'thresholds-test.csv'
12output_csv_path = os.path.join(current_directory, output_csv_name)
13
14# Generate a CSV file with all of the thresholds and corresponding values
15conn.performance.generate_threshold_settings_csv(
16    output_csv_path=output_csv_path)
17
18# Read the CSV values into a dictionary, cast all string booleans and
19# numbers to their proper types
20threshold_dict = PyU4V.utils.file_handler.read_csv_values(output_csv_path,
21                                                          convert=True)
22
23# Increase all of the first threshold values by 5 and second threshold
24# values by 10, alert only on the KPIs
25for i in range(0, len(threshold_dict.get('metric'))):
26    threshold_dict['firstThreshold'][i] += 5
27    threshold_dict['secondThreshold'][i] += 5
28    if threshold_dict['kpi'][i] is True:
29        threshold_dict['alertError'][i] = True
30
31# Process the CSV file and update the thresholds with their corresponding
32# values, we are only going to set the threshold value if it is a KPI
33conn.performance.set_thresholds_from_csv(csv_file_path=output_csv_path,
34                                         kpi_only=True)
35
36# It is also possible to set a threshold value without editing the values
37# in a CSV, the threshold metric and be edited directly
38threshold_settings = conn.performance.update_threshold_settings(
39    category='Array', metric='PercentCacheWP', first_threshold=60,
40    first_threshold_occurrences=2, first_threshold_samples=6,
41    first_threshold_severity='INFORMATION', second_threshold=90,
42    second_threshold_occurrences=1, second_threshold_samples=3,
43    second_threshold_severity='CRITICAL', alert=True)
44
45# Close the session
46conn.close_session()
```

--------------------------------

### get_audit_log_list

Source: https://pyu4v.readthedocs.io/en/latest/_modules/PyU4V/system.html

Retrieves a list of audit logs from Unisphere between a start and end date. Supports filtering through various input parameters.

```APIDOC
## get_audit_log_list

### Description
Get a list of audit logs from Unisphere between start and end date. It is possible to filter this list through the input parameters.

### Method
GET

### Endpoint
/system/audit_logs

### Parameters
#### Query Parameters
- **start_time** (string) - Required - Start time for audit log retrieval.
- **end_time** (string) - Required - End time for audit log retrieval.
- **array_id** (string) - Optional - Array ID.
- **user_name** (string) - Optional - User name.
- **host_name** (string) - Optional - Host name.
- **client_host** (string) - Optional - Client host.
- **message** (string) - Optional - Message.
- **record_id** (string) - Optional - Record ID.
- **activity_id** (string) - Optional - Activity ID.
- **application_id** (string) - Optional - Application ID.
- **application_version** (string) - Optional - Application version.
- **task_id** (string) - Optional - Task ID.
- **process_id** (string) - Optional - Process ID.
- **vendor_id** (string) - Optional - Vendor ID.
- **os_type** (string) - Optional - OS type.
- **os_revision** (string) - Optional - OS revision.
- **api_library** (string) - Optional - API library.
- **api_version** (string) - Optional - API version.
- **audit_class** (string) - Optional - Audit class.
- **action_code** (string) - Optional - Action code.
- **function_class** (string) - Optional - Function class.

### Request Example
GET /system/audit_logs?start_time=2023-01-01T00:00:00Z&end_time=2023-01-02T00:00:00Z

### Response
#### Success Response (200)
- **audit_logs** (array) - List of audit log entries.

#### Response Example
[
  {
    "id": "log1",
    "message": "Example log"
  }
]
```

--------------------------------

### Create a storage group snapshot with SnapVX

Source: https://pyu4v.readthedocs.io/en/latest/programmers_guide_src/replication.html

Creates a storage group with a 1GB volume, generates a snapshot name using the current time, creates a snapshot of the storage group, and verifies the snapshot exists in the snapshot list. Requires a configured PyU4V connection.

```python
"""docs/source/programmers_guide_src/code/replication-snapshot_create.py"""

import PyU4V
import time

# Initialise PyU4V connection to Unisphere
conn = PyU4V.U4VConn()

# Create storage Group with one volume using settings specified for
# service level and capacity
storage_group = conn.provisioning.create_non_empty_storage_group(
    srp_id='SRP_1', storage_group_id='PyU4V_SG', service_level='Diamond',
    workload=None, num_vols=1, vol_size=1, cap_unit='GB')

# Define a Name for the Snapshot, in this case the name auto appends
# the host
# time for when it was taken for ease of identification
snap_name = 'PyU4V_Snap_' + time.strftime('%d%m%Y%H%M%S')

# Create the snapshot of the storage group containing the volume and
# storage group created in the previous step
snapshot = conn.replication.create_storage_group_snapshot(
    storage_group_id=storage_group['storageGroupId'], snap_name=snap_name)

# Confirm the snapshot was created successfully, get a list of storage
# group snapshots
snap_list = conn.replication.get_storage_group_snapshot_list(
    storage_group_id=storage_group['storageGroupId'])

# Assert the snapshot name is in the list of storage group snapshots
assert snapshot['name'] in snap_list

# Close the session
conn.close_session()
```
Tokens:
Raw