Introduction
This guide is intended to cover the initial configuration of both iSCSI and MPIO, and guide the user through ensuring adequate additional sessions have been prepared. This should aid any environment to be more resilient to network interruptions or planned/unplanned maintenance activities. Completing the entire guide will require a few reboots of the client to ensure the configuration has been properly applied.
Multipath I/O(MPIO) is a technology used to bridge parallel communication paths to the same underlying disk. In this case it will be leveraged to re-combine multiple iSCSI paths(which would in turn appear as separate iSCSI disks to the OS) into a single system disk, and offer both performance and redundancy benefits.
This guide is tested and applicable for Windows Server 2016, Windows Server 2019 and Windows Server 2022.
Shortcut: Using the VPSA Automatic Enrollment Script
The VPSA offers an automatic enrollment script for Windows and Linux. This can be used to skip a few sections below, but it does not currently configure additional sessions nor the MPIO service.
1. Open a Web Browser capable of access the VPSA Web GUI, and login to it.
2. Navigate to Resources > Servers
3. Click the "Add" Button, and select "Automatic" in the dropdown.
4. Ensure the "Windows" platform is selected, and click the "Click here to download the Windows connection script." link to save the file "vpsa_win.vbs" to your downloads folder.
5. From the Windows Start Menu, search for "iscsicpl", and open the "iSCSI Initiator" desktop application.
6. You will be prompted to configure the iSCSI Initiator Service to activate by default on every reboot, select Yes.
7. You will be presented with the iSCSI Initiator Properties window, go ahead and close it.
8. Locate the "vpsa_win.vbs" script in your Downloads folder, and execute it.
8a. This script will create the Server Record in the VPSA, and establish the initial iSCSI session. You will still need to prepare MPIO, add the additional sessions, and "Attach" one or more block volumes to the Server record in the VPSA GUI.
9. Jump ahead to the "Preparing the MPIO Windows Feature" section below, and continue with the rest of the guide from there.
** The "vpsa_win.vbs" script will contain an expiring API token for the VPSA in order to register the host correctly. The token should be good for about 24 hours. If this script is being incorporated to any automation environments, a persistent key should be configured in the VPSA interface and inserted into this script.
Preparing the iSCSI Initiator Service
1. From the Windows Start Menu, search for "iscsicpl", and open the "iSCSI Initiator" desktop application.
2. You will be prompted to configure the iSCSI Initiator Service to activate by default on every reboot, select Yes.
3. You will be presented with the iSCSI Initiator Properties window.
4. Click the "Configuration" tab and take note of this hosts "Initiator Name" for the next section:
Create the VPSA Server Record for this host
1. Open a Web Browser capable of access the VPSA Web GUI, and login to it.
2. Navigate to Resources > Servers
3. Click the "Add" Button, and select "Manual" in the dropdown.
4. Disable File Access if unnecessary, and enable "iSCSI". Then provide the "Initiator Name" from the previous step to the IQN field.
Discover the iSCSI Target provided by the VPSA
1. From the Windows Start Menu, search for "iscsicpl", and open the "iSCSI Initiator" desktop application.
2. Enter the VPSA's "iSCSI IPv4" address into the "Target" field of the "iSCSI Initiator Properties" window, then click the "Quick Connect..." button
3. The VPSA IQN should show up as "Inactive", which is expected as the iSCSI credentials have not yet been supplied. Click "Done" to return to the iSCSI Initiator Properties screen.
4. Select the VPSA IQN from the "Discovered Targets" section, and click the "Connect" button.
5. Check the "Enable multi-path" checkbox, and click the "Advanced..." button.
6. In the Advanced Settings window set the following:
- Local adapter - Microsoft iSCSI Initiator
- Initiator IP - IPv4 address of the Network Interface that has a route to the VPSA
- Target Portal IP - IP address of the VPSA
- Enable CHAP log on - Check the box
- Name - The value of "VPSA CHAP User" in the VPSA GUI under Servers > [Server Record] > Properties
- Target secret - The value of "VPSA CHAP Secret" in the VPSA GUI under Servers > [Server Record] > Properties
7. The status will change from "Inactive" to "Connected".
Adjust timeouts for the iSCSI Initiator in the Windows System Registry
1. From the Windows Start Menu, search for "regedit", and run the "regedit" command.
2. Navigate to the registry path [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{4D36E97B-E325-11CE-BFC1-08002BE10318}]. You can confirm you are in the right path when the "Class" property contains "SCSIAdapter".
3. Search through the sub-paths in the navigation tree to the left until you find one where the "DriverDesc" is "Microsoft iSCSI Initiator". In the example case below this was 0002.
4. Open the "Parameters" subpath, and update the following keys to these values:
- MaxRequestHoldTime - Decimal 120
- LinkDownTime - Decimal 120
- SRBTimeoutDelta - Decimal 120
- WMIRequestTimeout - Decimal 15
5. Ideally reboot the client after these changes, however if you are continuing with MPIO and additional iSCSI sessions, this reboot can be skipped as the MPIO step will require a reboot anyway. It is best practice to continue with the rest of this guide.
Preparing the MPIO Windows Feature
Enabling and configuring this feature will require two reboots, once to activate it and again to complete it's configuration.
1. From the Windows Start Menu, search for "Server Manager" and open the application.
Click Manage and select "Add Roles and Features".
2. Progress through the Wizard to the "Features" step, and enable the "Multipath I/O" feature.
3. Complete the wizard and reboot the server when the installation has completed. This is required to perform the next step.
4. From the Windows Start Menu, search for "mpiocpl" and run this command or App.
5. Select the "Discover Multi-Paths" from the "MPIO Properties" window, and check the "Add support for iSCSI devices" checkbox and click the "Add" button.
6. You will be prompted to reboot the system for this to take effect. Select yes, or reboot shortly after completion.
Add additional iSCSI sessions
1. From the Windows Start Menu, search for "iscsicpl", and open the "iSCSI Initiator" desktop application.
2. In the "iSCSI Initiator Properties" window, select the "Connected" VPSA IQN, and click "Properties..."
3. From the "Properties" window, click the "Add Session" button.
4. Check the "Enable multi-path" checkbox, and click the "Advanced..." button.
5. In the Advanced Settings window set the following:
- Local adapter - Microsoft iSCSI Initiator
- Initiator IP - IPv4 address of the Network Interface that has a route to the VPSA
- Target Portal IP - IP address of the VPSA
- Enable CHAP log on - Check the box
- Name - The value of "VPSA CHAP User" in the VPSA GUI under Servers > [Server Record] > Properties
- Target secret - The value of "VPSA CHAP Secret" in the VPSA GUI under Servers > [Server Record] > Properties
6. The status will change from "Inactive" to "Connected".
7. Zadara recommends a minimum of 4 sessions, so it is advised to repeat this process until 4 or more total sessions have been created.
8. Optional - This process can be repeated multiple times across multiple Windows Network Interfaces to assist in distributing IO traffic through multiple physical or virtual interfaces. This may be used to overcome QoS limitations imposed by some compute environments.
9. Confirm the number of sessions detected by the VPSA in the web GUI by navigating to Resources > Servers, selecting the Server Record and clicking the "Paths" tab in the lower panel.
Attach the VPSA Server Record to the desired Block Volume
1. Open a Web Browser capable of access the VPSA Web GUI, and login to it.
2. Navigate to Resources > Volumes
3. Select the desired "Available" block volume, and click the "Servers" button. Then select "Attach to Server(s)".
4. Click the checkbox next to the Server Record we've prepared.
4a. A block volume should NOT be associated with multiple Server Records unless you are utilizing a cluster-aware filesystem or hypervisor. Doing so may cause data consistency issues to your filesystem.
4b. Optionally you may define a specific iSCSI LUN number for each block volume, which is necessary for cluster environments and may be useful for debugging purposes elsewhere. Otherwise the VPSA will automatically assign this per-host in an incrementing fashion.
5. Repeat for each block volume as necessary.
6. From the Windows Start Menu, search for "diskmgr", and open the "Create and format hard disk partitions" control panel application.
6. Online, initialize and format the newly detected disks as required.
6a. If the new volumes do not appear in this screen, performing a "Refresh" from the "iSCSI Initiator Properties" window should cause the system to rescan for the volume.
Adjust the DSM/Disk Specific Module
In order to further accommodate for VPSA maintenance (e.g. VPSA failover), it is necessary to reconfigure the DSM timer counters as follows:
1. In Windows Explorer, right-click the newly added Volume / Drive (e.g. F:\ drive) and select Properties.
2. Click on the Hardware tab.
3. Click on the Zadara VPSA Multi-Path Disk Device and then Properties.
4. Next to DSM Name click on Details.
5. Set the following:
- Path Verify period = 20
- Path Verify Enabled = ticked
- Retry count = 6
- Retry interval = 1
- PDO Remove Period = 30
6. Click OK three times to come out. A reboot will be required for these settings to take effect.
Conclusion
This document has walked through the process of preparing an initial iSCSI session, enabling MPIO, adding additional iSCSI sessions and optimizing system timeout values to improve the host's behavior in the event of planned or unplanned activity within the VPSA. Zadara Support is always available to answer any questions related to this process and to offer further details if necessary.