Scripts

Explore this Page

Overview

The Scripts section provides PowerShell-based automation capabilities in DataCore SANsymphony to help manage, maintain, and recover storage environments. It includes scripts for repairing virtual disks, handling storage performance degradation, and automatically evacuating storage from offline servers, enabling efficient response to failures and performance issues.

Repairing Virtual Disks

The Repairing Virtual Disks feature enables recovery of failed mirrored virtual disks by replacing failed storage sources with healthy ones from available disk pools, ensuring data availability and system resiliency. For detailed steps and automation using PowerShell, refer to Repairing Virtual Disks.

Managing Storage Performance Degradation

In DataCore SANsymphony, performance degradation on storage sources can impact virtual disk responsiveness and host applications. When latency issues are detected, SANsymphony can trigger automated actions such as disabling access to affected storage to restore performance. This feature uses storage latency thresholds and PowerShell scripts to manage mirrored virtual disks temporarily until the issue is resolved.

Understanding Storage Latency Thresholds

Performance degradation on storage sources can occur for many reasons and when it happens can affect host application performance. In some cases, performance degradation can change without warning, such as when a RAID array is rebuilding or there is I/O contention with other resources. Performance degradation may also occur due to a planned maintenance activity.

DataCore SANsymphony software provides storage latency thresholds which are monitored and will report to the System Health tool when a threshold has been reached. The threshold values can be customized to inform administrators when unacceptable latency is occurring on storage used by virtual disks.

When storage performance degradation is detected by a storage latency threshold, administrators can select to automatically disable front-end and mirror access to mirrored virtual disks, causing a failover to another front-end path on a different server. When the storage on one server is drastically compromised, temporarily failing over to faster storage on another server will result in improved performance for the virtual disks and host applications until the latency issue can be corrected.

Once access to logical disks have been disabled, latency reported on the logical disk might remain high until all cache I/Os have been destaged, but the virtual disk performance will not be affected anymore.

Disabling access to slow storage sources when a threshold is reached can be performed automatically through a task running a provided PowerShell script. When the performance degradation has been corrected, access can be automatically enabled again using another provided PowerShell script.  

This implementation is intended as a temporary measure to restore performance to mirrored virtual disks until the latency is corrected.

Ensure that storage latency thresholds are set to the desired settings and use caution when electing to disable access to storage sources. When storage latency occurs, disabling access may not be the most suitable solution in all cases. We recommend that the administrator assess the situation before taking action. DataCore Software does not guarantee performance improvements when using this solution.

A logical disk is the internal software representation of a virtual disk on a server. Logical disks are created by the software when virtual disks are created from disk pools or pass-through disks. A single virtual disk is comprised of one logical disk on one server. A mirrored or dual virtual disk is comprised of two logical disks—one logical disk on each server used as a storage source for the virtual disk.

Since logical disks are used internally by the software, they are not revealed in the DataCore Management Console, but are most closely related and referred to as "storage sources" in the console.

Using PowerShell Scripts to Manage Storage Access

Sample PowerShell Scrips

DisableLogicalDisksAccess.ps1

 The script file takes an array of logical disk monitor triggers as a parameter. The monitor triggers will be provided from a task trigger configured in DataCore SANsymphony.

When the trigger is fired, the script will run as the task action. The script validates the logical disks, triggered by the monitors, to ensure that there is a path available on the partner server in order to maintain high availability, and the virtual disk can remain accessible from all hosts it is served to. The script will disable access to all validated logical disks and skip the logical disks that do not pass validation.

The script uses the DataCore CmdletSet-DcsLogicalDiskAccess to disable access to the logical disks. (This cmdlet can also be used to manually disable access without using the script in a task, such as before a planned maintenance activity.)

All messages regarding this operation are saved to DisableLogicalDisksAccess.log in the DataCore SANsymphony installation folder.

EnableLogicalDisksAccess.ps1

The script file takes a server name as a parameter and will enable all disabled logical disks on the specified server. The script can be run from the command line when the storage latency issue has been corrected.

For example, entering EnableLogicalDisksAccess.ps1 -Server [Server1] at the command line would enable access to the disabled storage sources on the server named "Server1".

The script uses the DataCore CmdletSet-DcsLogicalDiskAccess to enable access to the logical disks. (This cmdlet can also be used to manually enable access without using the script.)

All messages regarding this operation are saved to EnableLogicalDisksAccess.log in the DataCore SANsymphony installation folder. The script files are included in the DataCore SANsymphony installation folder (default path C:\Program Files\DataCore\SANsymphony).

Configuring Automated Tasks

To use the DisableLogicalDisksAccess.ps1 script without modification:

  • Create a task to trigger on a monitor state change for the monitor type Virtual disk sources and Storage latency. Select All or specify the virtual disks to monitor. Set the trigger state to the threshold value, when reached, that the action should take place, for example "= Critical". In this case, the trigger will fire when any of the selected storage sources reach the threshold for critical storage latency. In order to fire a trigger, the trigger state must be at least "> Healthy", which means "Attention or greater". (See Automated Tasks for more information.)
  • In the task, configure an action to run the PowerShell script file (C:\Program Files\DataCore\SANsymphony\DisableLogicalDisksAccess.ps1). Select the check box to append the associated Task Trigger Data objects. When a trigger fires, the associated trigger state data objects for the logical disk Ids will be appended to the script file action as parameter values. The trigger state data objects are a list of trigger states that caused the action to occur. See Trigger State Data for more information.
  • Optionally, another trigger could be set to run during scheduled times such as when I/O processing is slow or during off-hours. In this case, also set the "Only run when all trigger conditions are met task" setting.
  • Optionally, an additional task action could be created to send an email to the administrator and an Action delay could be set in the task settings so that the script will be executed after a desired amount of time in order for the administrator to assess the situation.

When the storage latency threshold reaches the threshold set, the trigger will fire and the script file will run. After the storage latency issue is corrected, run the EnableLogicalDisksAccess.ps1 script file with the server name to enable access to the storage sources again.

Auto-evacuating Pools on Offline Servers

An offline server causes mirrored virtual disks to lose fault tolerance and single virtual disks to fail. Evacuating virtual disk storage sources from offline servers to healthy servers can be automated by creating a task that monitors the state of DataCore Servers and runs a script, and after determining that they are offline, automatically evacuates the storage sources of that server to another server that shares the pool.

The Windows PowerShell script file named EvacuateOnFail.ps1 is included in the DataCore SANsymphony installation folder (default path C:\Program Files\DataCore\SANsymphony). The script uses the DataCore CmdletStart-DcsDistributionPlan to perform the evacuation.

As outlined in this topic, the task will monitor the health of DataCore Servers in the server group. When the state of any server transitions from Healthy to any other state, a PowerShell script is executed on each server. The script will determine which server is offline, validate that it is, and evacuate those storage sources in compliant shared pools to a designated alternate server in the group.

Shared Multi-port Array (SMPA) licenses are not required to automatically evacuate the pools, although certain limitations apply. Without an SMPA license, all storage sources (virtual disks) from a pool must be evacuated and they must be evacuated to the sameDataCore Server. See Important Notes on Using Shared Disk Pools in the Maintenance Mode topic for more information.

Also see Shared Multi-port Array Support for the characteristics of SMPA pools and non-SMPA pools.

Configuration Requirements

The following configuration is required in order to automate the evacuation process.

  • Storage sources must be in pools that are shared between a minimum of two servers in the group in order to be eligible for automatic evacuation. Storage sources that are not in pools that are shared will not be evacuated.
    • To create shared pools, back-end paths must be created between each disk in the pool and the other servers in the group. See Important Notes on Using Shared Disk Pools in the Maintenance Mode topic for instructions on preparing to move storage sources without an SMPA license (if applicable).
  • The script requires the addition of the following configuration token string to the Description field in the Server Group Details page:

    [Offline-Takeover:On|Off|Kill]

    Specify On to enable the process.

    In the string above, the brackets are significant and should be included: [Offline-Takeover:On|Off|Kill].

    All possible actions include:

    • On - the process is active
    • Off - the process is not active
    • Kill - stop the process

      The configuration token is identified by the brackets and may be located anywhere in the Description field. The configuration token is not case sensitive and may contain spaces within the brackets. Other description information may also be included in the Description field, provided that it is not included within the brackets.

  • Configure the pool owners for each shared disk pool by adding the following required configuration token string to the Description field in each Shared Disk Pool Details page:

    [Possible-Owners: Server1, Server2]

    In the string above, the brackets are significant and should be included: [Possible-Owners: Server1, Server2].

    Where Server1 and Server2 are the machine names of the pool owners for that particular shared disk pool and act as alternate servers for the pool.

    • Two servers can be listed as possible pool owners. In the case of Server1 and Server2 listed as owners, if Server1 goes offline, storage sources will be evacuated to Server2. Alternately, if Server2 goes offline, storage sources will be evacuated to Server1.
    • Pool owners may be changed in the Description field in a Shared Disk Pool Details page as needed. When pool disks are shared between all servers in the group, the designated pool owners can be changed to any server in the group simply by changing the description string without changing the disk or pool configuration, or task.

      Pool owners may be changed while the script is running, although the changes will not take effect until the task is triggered the next time.

    • Virtual disks with storage sources on both configured pool owners will not be evacuated.
    • All virtual disks from all configured shared pools must be evacuated from the offline server when the server is not licensed for SMPA. See Important Notes on Using Shared Disk Pools in the Maintenance Mode topic for more information about evacuating storage sources in non-SMPA pools.
  • Enable write-through mode for all mirrored virtual disks created from the shared pools. This is not necessary for single or dual virtual disks.
    • Write-through can be enabled on the Virtual Disk Details page>Settings tab. Write-through can also be set for virtual disks using the cmdlet Set-DcsVirtualDiskProperties or set for the server using the cmdlet Disable-DcsServerWriteCache.
  • Configure tasks
    • Create one task per server. The script must run locally on each server in the group.
    • Set Trigger:
      • Trigger on Monitor state changed
      • Monitor type: State of DataCore Servers
      • Monitored object: All
      • Trigger state > Healthy (transition from Healthy to any other state will execute the script)
    • Set Action:
      • Perform action: Run a powershell script
      • DataCore Server: Specify one of the servers in the group. (Each task should run on a different server in the group.)
      • File: C:\Program Files\DataCore\SANsymphony\EvacuateOnFail.ps1
      • There are no script parameters
  • See General Maintenance Mode Notes in the Maintenance Mode topic for features that are not supported with the evacuate operation.
  • The script can be manually run in an evaluation mode in a PowerShell window; this is recommended to ensure that the configuration is correct. Evaluation mode displays messages in the PowerShell window as if running the script without actually evacuating the storage sources. To evaluate, configure as outlined above and run the script at the PowerShell prompt with the switch -eval. For example: PS C:\Program Files\DataCore\SANsymphony> EvacuateOnFail -eval
  • The script checks to ensure that the server that transitions from Healthy to any other state is offline before evacuating storage sources to prevent unnecessary evacuations.
  • When a server state changes from "Running" to "Stopped", the script will run but storage sources will not be evacuated from the "Stopped" server. When the server changes from "Running" to "Unavailable", the script will run, and storage sources from the "Unavailable" server will be evacuated where possible.
  • All physical disks in the pool being evacuated must be present. Storage sources in an offline pool will not be evacuated if any physical disks are missing.
  • The “Preferred Server” setting of “All” is unsupported with Evacuation.
  • The static (non-moving) side must be set as the preferred server before evacuation..
  • Before evacuation, the path to the static DataCore Server must be healthy to avoid loss of access by the host. Further, ensure that a path can be created from the destination DataCore Server to the host.
  • Storage source evacuations run in parallel for all shared pools per server.
  • All messages from running the script are recorded in the Event Log and logged to the file named EvacuateOnFail.txt located in C:\Program Files\DataCore\SANsymphony. Warning and errors are also posted as Alerts.
  • After evacuation of an offline server, storage sources do not return to the original server automatically. They must be evacuated or redistributed by the administrator.

Example Scenarios

Scenario 1 for a non-SMPA pool.

Configuration:

  • Pool owners configured for Shared pool 1 are Server 1 and Server 2.
  • Pool owners configured for Shared pool 2 are Server 2 and Server 3.
  • Pool owners configured for Shared pool 3 are Server 3 and Server 4.
  • Pool owners configured for Shared pool 4 are Server 4 and Server 1.
  • Mirrored Virtual disk 1 has storage sources from Server 1 (Shared pool 1) and Server 3 (Shared pool 3).
  • Mirrored Virtual disk 2 has storage sources from Server 2 (Shared pool 2) and Server 4 (Shared pool 4).
  • Mirrored Virtual disk 3 has storage sources from Server 3 (Shared pool 3) and Server 1 (Shared pool 1).
  • Mirrored Virtual disk 4 has storage sources from Server 4 (Shared pool 4) and Server 2 (Shared pool 2).
  • Single Virtual disk 5 has a storage source from Server 1 (Shared pool 1).

Task trigger:

Server 1 goes offline.

Task actions:

  • Virtual disk storage sources from shared pools on Server 1 are evacuated to Server 2.
  • The storage sources in Virtual disk 1, Virtual disk 3, and Virtual disk 5 are evacuated from Server 1 to Server 2.
  • Virtual disk 2 and Virtual disk 4 are unaffected because there is no storage source from Server 1 in either virtual disk.

Scenario 2 for an SMPA pool.

Configuration:

  • Pool owners configured for Shared pool 1 are Server 1 and Server 2.
  • Pool owners configured for Shared pool 2 are Server 3 and Server 4.
  • Mirrored Virtual disk 1 has storage sources from Server 1 (Shared pool 1) and Server 3 (Shared pool 2).
  • Mirrored Virtual disk 2 has storage sources from Server 2 (Shared pool 1) and Server 4 (Shared pool 2).
  • Mirrored Virtual disk 3 has storage sources from Server 3 (Shared pool 2) and Server 1 (Shared pool 1).
  • Mirrored Virtual disk 4 has storage sources from Server 4 (Shared pool 2) and Server 2 (Shared pool 1).
  • Single Virtual disk 5 has a storage source from Server 1 (Shared pool 1).

Task trigger:

Server 1 goes offline.

Task actions:

  • Virtual disk storage sources from shared pools on Server 1 are evacuated to Server 2.
  • The storage sources in Virtual disk 1, Virtual disk 3, and Virtual disk 5 are evacuated from Server 1 to Server 2.
  • Virtual disk 2 and Virtual disk 4 are unaffected because there is no storage source from Server 1 in either virtual disk.

Learn More