Adding logical paths by using a CSV file

Edit online

You can create a comma-separated value (CSV) file to define logical paths. The CSV file specifies storage systems pairings and associated port pairings that are used for replication. Copy Services Manager uses the port pairings that are defined in the CSV file to establish logical paths. You can edit the port pairings file by using the Copy Services Manager GUI. You can also edit the file manually if necessary.

Before you begin

You can define the following types of port pairings for the source and target storage systems:
  • Port pairings for all logical subsystems that are in a session.
  • Port pairings for a logical subsystem to logical subsystem mapping.
  • Port pairings for all logical subsystems. You can define a single set of port pairings for the logical subsystems or you can define different pairings for all even logical subsystems and all odd logical subsystems.
  • Port pairings based on the direction of the copy.

Adding logical paths with a CSV file by using the GUI

Edit online

You can use the DS8000 Port Pairings CSV panel in the Copy Services Manager GUI to add logical paths by editing a sample CSV file.

About this task

You can define the port pairings within a CSV file by using the GUI. However, if the GUI is not accessible, you can also define them by manually editing the portpairings.csv file. For more information, see Adding logical paths with a CSV file by editing it manually.

Complete these steps to add IBM® DS8000® logical paths with a CSV file in the Copy Services Manager GUI:

Procedure

  1. Log in to the Copy Services Manager GUI as a user with administrator privileges.
  2. Click Paths > DS8000 Port Pairings CSV.
  3. Click Edit to put the CSV file into edit mode.
  4. Enter the necessary changes to the sample portpairings.csv file for your environment. For more information, see the online help at ? > Help for guidance and tips on editing the file.
  5. When you are finished updating the file, click Save to keep your changes, or click Cancel to exit without saving changes.

Results

New logical paths are added according to the updates that you made in the CSV file.

Adding logical paths with a CSV file by editing it manually

Edit online

You can manually edit a portpairings.csv sample file to add logical paths.

About this task

You can define the port pairings within a CSV file through a manual edit, if necessary. However, the preferred method is to define this file by using the Copy Services Manager GUI. For more information, see Adding logical paths with a CSV file by using the GUI.

Complete these steps to add IBM DS8000 logical paths with a CSV file by editing it manually:

Procedure

  1. Create a CSV file that is named portpairings.csv in the install dir\liberty\wlp\usr\servers\csmServer\properties directory for distributed systems, or in the path_prefix/opt/IBM/CSM/wlp/usr/servers/csmServer/properties directory for z/OS. You can create the CSV file in a spreadsheet such as Microsoft Excel or in a text editor.
    In the properties directory, find the sample CSV file that is named portpairings.csv. This file contains the following example port pairs:
    
# 1. Each line in the file represents a storage system pairing and its
#    associated port pairings. 
#    There are multiple formats that define different port pairing types:
#
# Specific Session:  This format can be used if you want to use a 
# different set of port pairings for each session.  
# This might be necessary in some environments to prevent
# the paths of a session from affecting the paths of another session.
#
# Format:
# storageSystemA:storageSystemB:sessionName,port1:port2,...,portN:portM
#            
# storageSystemA:storageSystemB,port1:port2,...,portN:portM
# where storageSystemA and storageSystemB are the storage system IDs 
# that are used to identify the storage systems, and sessionName is 
# the name of the session that you wish this port pairing to be used for.  
# port1, port2, portN, portM are hexadecimal numbers which indicate the 
# storage system communication ports. 
#
# A valid example is:
# 2107.04131:2107.01532:myPayRollSession,0x0331:0x0024,
# 0x0330:0x0100,0x0331:0x000C
#
#
#
# Specific LSS to LSS pairing:  This format can be used if you want 
# to specify for a specific LSS pairing to use a specific set of 
# port pairings.    
#
# Format:
# storageSystemA:systemALSS:storageSystemB:systemBLSS,
# port1:port2,...,portN:portM
#            
# where storageSystemA and storageSystemB are the storage system IDs 
# that are used to identify the storage systems, and systemALSS/systemBLSS 
# are LSSs on storage Systems in hexadecimal format.  port1, port2, 
# portN, portM are hexadecimal numbers which indicate the storage system 
# communication ports. 
#
# A valid example is:
# 2107.04131:0x52:2107.01532:0x5f,0x0331:0x0024,0x0330:0x0100,
# 0x0331:0x000C
#
#
#
#
# Box to Box pairing:  This format can be used if you want to 
# specify a set of port pairings to use for all LSS pairings 
# across the same source and target Box. This pairing has multiple options. 
# A single set of port pairings can be defined for all LSS pairings between 
# the boxes, OR the port pairings can define that the even source LSSs should 
# use one set, and the odd LSSs should use a different set. There are some 
# scenarios particularly with Global Mirror support where performance can be 
# improved by mapping even and odd LSSs.
#               
#
# Format:
# Option 1: 
# storageSystemA:storageSystemB,port1:port2,...,portN:portM
#            
# where storageSystemA and storageSystemB are the storage system IDs 
# that are used to identify the storage systems.
# port1:port2,... portN:portM are hexadecimal numbers which indicate 
# the storage system communication ports.
#                   
#
# A valid example is:
# 2107.04131:2107.01532,0x0331:0x0024,0x0330:0x0100,0x0331:0x000C
#
# Option 2: 
# storageSystemA:storageSystemB,even, port1:port2,...,portN:portM, 
# odd, port1:port2,...portX:portY
#            
# where storageSystemA and storageSystemB are the storage system IDs 
# that are used to identify the storage systems.   
# port1:port2,...portN:portM is the set of port pairings to use when 
# the source is on an even LSS
# port1:port2,...portX:portY is the set of port pairings to use when 
# the source is on an odd LSS
# All ports are hexadecimal numbers which indicate the storage system 
# communication ports. 
#
# A valid example would be:
# 2107.04131:2107.01532,even,0x0331:0x0024,0x0330:0x0100,
# odd,0x0331:0x000C,0x0334:0x0330
  2. To enable the changes in the file, complete a task that requires new paths to be established.
    For example, suspend a session to remove the logical paths, and then issue the Start H1->H2 command to enable the paths to use the port pairings in the CSV file.

What to do next

Considerations when you are creating and using the CSV file:
  • The CSV file now supports Global Mirror control paths. Please refer Adding Global Mirror Control paths with a CSV file by editing it manually for more information.
  • The entries for the port pairs are bidirectional unless the last comma-separated entry on the line is the string onedir. The portpairings.csv file contains the following information about using the onedir string:
    
# 2. The entry for the port pairs are bi-directional unless the last 
# comma-separated entry on the line is the string "onedir".
# This means that a line that has systemA:systemB is equivalent to a line
# that has systemB:systemA, and the last entry in the file takes precedence.
#
# If the string "onedir" is the last entry in the line, as in the 
# following example:
# 2107.04131:2107.01532,0x0331:0x0024,0x0330:0x0100,
# 0x0331:0x000C,onedir
# then the entry is not considered to be bi-directional, and the 
# port pairings are only used if the first box listed (2107:04131)
# is the source of the pair, and the second box listed (2107.01532) 
# is the target of the pair.  
# NOTE: You can specify the "onedir" tag on any of the supported 
# formats for port pairs. However, if there is also an entry for 
# the same set of boxes without the "onedir" tag, the entry without 
# the "onedir" tag might take precedence.
#   
#  Example Session format:
#  2107.ZA811:2107.BAY81:myMM,0x0133:0x0332,onedir
#  2107.BAY81:2107.ZA811:myMM,0x0033:0x0030,onedir
#  The above example indicates that session "myMM" will use 
#  0x0133:0x0332 for any establishes from ZA811 to BAY81, 
#  but will use 0x0033:0x0030 for any establishes
#  from BAY81 to ZA811.
#
#  Example LSS to LSS format:
#  2107.ZA811:0xD0:2107.BAY81:0xD0,0x0133:0x0332,onedir   
#  2107.BAY81:0xD0:2107.ZA811:0xD0,0x0033:0x0030,onedir
#  The above example indicates that ports 0x0133:0x0332 
#  will be used for any establishes from ZA811 LSS 0xD0 
#  to BAY81 LSS 0xD0, but that ports 0x0033:0x0030 
#  will be used from BAY81 LSS 0xD0 to ZA811 LSS 0XD0.
#
#  Example Box to Box format:
#  2107.ZA811:2107.BAY81,0x0133:0x0332,onedir
#  2107.BAY81:2107.ZA811,0x0033:0x0030,onedir
#  The above example indicates that ports 0x0133:0x0332 
#  will be used for any establishes from ZA811 to BAY81, 
#  but that ports 0x0033:0x0030 will be used for any
#  establishes from BAY81 to ZA811.  
#
# 3. Lines that are incorrectly formatted are discarded. For example, 
# if a line contains ports without the 0x, or does not contain port 
# pairs delimited by the : character, then the whole line is discarded.
#
# 4. A line can be properly formatted but contain invalid ports for your 
# given storage system configuration. In this case, the ports will be 
# passed down to the storage system to be established, and no validation 
# is done. The valid ports might be established by the storage system, 
# while the invalid ones might be rejected.
#
# 5. If a file contains duplicate lines for the same storage systems, the
# last line is used. And the ports on the last line are the ones that are used.
# Also note that the entries are bi-directional (see rule 2). Therefore, if you
# have systemA:systemB, and then a line with systemB:systemA, this second
# line is the one that is used.
#
# 6. This file is read at most once every 60 seconds. Therefore, if you change 
# the file you might need to wait two minutes until you issue the next start
# command. 
#
# 7. Any line that starts with a # character is counted as a comment and is
# discarded. The # must be at the start of the line. Placing it in other
# positions might cause the line to be invalid.
#
# 8. The portpairings.csv file is not automatically shared between 
# two copy services management servers in a high availability environment. 
# Therefore, it is possible that different port pairings can be established 
# from the standby server after a takeover. In most cases you will want to 
# copy the portpairings.csv file to the standby server to ensure that the 
# two files are equal.
#
# 9. The following is the order in which each port pairing is checked.  
# The first match when going down this order is used as the port pairings:
# a) If a Specific LSS pairing is found for the given LSS pairing being 
# established
# b) If a Specific Session port pairing is found for the given session
# c) If a box to box mapping is found for the given pair being established
# 
# For more information on how the port pairings works, see the
# user’s guide and other documentation.
#
# Examples:
# Normal Box to Box Mappings
#2107.04131:2107.01532,0x0331:0x0024,0x0330:0x0100,0x0331:0x000C
#2107.05131:2107.01532,0x0330:0x0029,0x0331:0x0001
# Specific Session Option
#2107.04131:2107.01532:GMP,0x0030:0x0303,0x0031:0x0303        
# Specific LSS to LSS Mapping Option
#2107.04131:0x50:2107.01532:0x51,0x0301:0x0303,0x0302:0x0303        
# Box to Box Mapping with Even and Odd LSS pairings defined            
#2107.04131:2107.01532,even,0x0030:0x0031,0x0032:0x0033,0x0030:
0x0033,odd,0x0300:0x0301,0x0302:0x0303
  • If the CSV file contains multiple lines that specify the same storage system to storage system pairing, Copy Services Manager uses the last line. This rule applies regardless of the order of the storage system pairing. For example, if you have storage systems 2107.04131:2107.01532 defined on the first line of the CSV file and then have 2107.01532:2107.04131 defined on the second line, Copy Services Manager uses second line.
  • If a line in the CSV contains information that is not formatted correctly, the line is ignored. This rule includes lines that specify storage systems but do not include ports or include ports that are not formatted correctly.
  • If the CSV file contains valid and invalid port pairs, the valid port pairs might or might not be established. Invalid port pairs can cause the following errors to be displayed in the Copy Services Manager console and on the ESS/DS Paths page:
    • Return Code F52: This error is displayed if a port is invalid.
    • Return Code 0400: This error is displayed if a port is invalid and out of the range for the device.
    Other storage system error codes might be displayed also, depending on the path topology, types of paths, and the incorrect port pairings that are specified in the CSV file.
  • If the CSV file contains no valid port pairs, no logical paths are established and subsequent commands to the storage systems that require logical paths might fail. Any existing logical paths for a storage system are used until they are removed.

Adding Global Mirror Control paths with a CSV file by editing it manually

Edit online

You can manually edit a sample.csv file to add logical paths.

About this task

You can define the port pairings within a CSV file through a manual edit, if necessary. However, the preferred method is to define this file by using the Copy Services Manager GUI. For more information, see Adding logical paths with a CSV file by using the GUI.

Complete these steps to add IBM DS8000 logical paths with a CSV file by editing it manually:

Procedure

  1. Create a CSV file that is named sample.csv in the install dir\liberty\wlp\usr\servers\csmServer\properties directory for distributed systems, or in the path_prefix/opt/IBM/CSM/wlp/usr/servers/csmServer/properties directory for z/OS. You can create the CSV file in a spreadsheet such as Microsoft Excel or in a text editor.
  2. In the properties directory, find the sample CSV file that is named sample.csv. This file contains the following example port pairs: 
    ##############################################################################################################################################
# Starting in CSM 6.2.12, this file can now define Control Paths to use for sessions with DS8000 Global Mirror
#
# Lines starting with "GM" define port pairings that should be used for Global Mirror control paths between Master and Subordinate control systems
# This file supports two ways to define the control paths
#
# LSS to LSS - This format specifies the LSS on the Master and the LSS on the subordinate to use when establishing the path
# The format for an LSS to LSS mapping is
#     GM,master:subordinate,LSS,master_lss:subordinate_lss,master_port1:subordinate_port1,master_port2:subordinate_port2....
#
# LSS to LSS For Specific Session - This format also specifies specific LSSs but will only be applied to a specific session
#     NOTE: When specifying the session name in the properties file, all spaces should be replaced with "_".  Example "My session" should be specified as "My_session"
#     NOTE: When using this format, if you have multiple sessions with GM that share the same consistency group name, all shared sessions should have a line in the file with the same port pairings
# The format for a Specific Session mapping is
#     GM,master:subordinate:session_name,master_lss:subordinate_lss,master_port1:subordinate_port1,master_port2:subordinate_port2....
#
#
# NOTE 1:  In order for the control paths to be created, there must be a line in this file specifying the paths for every Master to Subordinate relationship in the session.
#          This line is NOT bi-directional as it is for MM or GC paths and as such will be used to determine which of the source boxes will be the Master box.
# NOTE 2:  This file will only take affect when the Master is started new.  This might be a new start or after a Suspend/Recover and restart.
#          Control paths in this file will not be used when simply restarting a session
#
# The following examples consider a session that has H1 volumes in a GM session across the following boxes
# GXE34, KX432, LR345
#
# Example of defining LSS to LSS Mappings for the session where GXE34 is the desired Master box
# GM,2107.GXE34:2107.KX432,LSS,0x05:0x10,0x0133:0x0130,0x0300:0x0301
# GM,2107.GXE34:2107.LR345,LSS,0x4D:0x5E,0x0233:0x0230,0x0320:0x0321
#
# Example of defining Specific Session Mappings for the session where GXE34 is the desired Master box and the session is "My session"
# GM,2107.GXE34:2107.KX432:My_session,LSS,0x05:0x10,0x0133:0x0130,0x0300:0x0301
# GM,2107.GXE34:2107.LR345:My_session,LSS,0x4D:0x5E,0x0233:0x0230,0x0320:0x0321

Results

New logical paths are added according to the updates that you made in the CSV file.