Parameters

The following table shows parameter names and functionality.

-s

Specify this parameter when you do not want to display the confirmation messages during execution of the dlmcfgmgr utility. When you execute this utility with this parameter specified, the confirmation message for each HDLM device is not displayed.

Use this parameter when you want to skip a response to the confirmation message (to eliminate the manual intervention). For example, use this parameter when executing a command using a shell script or batch file.

When you specify the -v parameter, the message confirming that the utility is executed is not displayed even if you omit the -s parameter.

-r

Specify this parameter when you register, in HDLM, a path that HDLM has not recognized. When the dlmcfgmgr utility is executed, the logical device file of the HDLM device is created in the /dev directory. This enables a user to use an LDEV of the storage system as an HDLM device.

This parameter is used to create a new HDLM device definition: for example, when changing the configuration of the storage system (for example, add or delete an LU), or the host-side hardware configuration.

The path definition information registered in HDLM is inherited even though the path is disconnected when the host starts.

If the SCSI device of the new path that HDLM detected is already registered (that is, when the path between the host and an LU of the storage system already exists and a new path is added), the same HDLM device mapped with the path already registered is allocated. If the SCSI device of the new path that HDLM detected is not yet registered (that is, when you define a new path from the host to an LU of the storage system), the HDLM device with the lowest available letter is allocated to the path. The following table shows examples of allocating a new HDLM device.

Table. Example: allocation of new HDLM devices

Status before executing the dlmcfgmgr utility (dlmcfgmgr -r)	Status after executing the dlmcfgmgr utility (dlmcfgmgr -r)
none	/dev/sddlmaa #
/dev/sddlmaa	/dev/sddlmaa /dev/sddlmab #
/dev/sddlmaa /dev/sddlmab	/dev/sddlmaa /dev/sddlmab /dev/sddlmac #
/dev/sddlmaa /dev/sddlmac	/dev/sddlmaa /dev/sddlmab # /dev/sddlmac
/dev/sddlmab /dev/sddlmac	/dev/sddlmaa # /dev/sddlmab /dev/sddlmac
/dev/sddlmaa : /dev/sddlmpp	/dev/sddlmaa : /dev/sddlmpp /dev/sddlmaaa#
/dev/sddlmaa : /dev/sddlmaap	/dev/sddlmaa : /dev/sddlmaap /dev/sddlmbaa#

#

A newly assigned logical device file name of the HDLM device

Every time the host starts, the dlmcfgmgr utility (dlmcfgmgr -r) is automatically executed. This utility can be executed a number of times if necessary after starting the host. When this utility is executed, this utility checks the current HDLM settings. If a new path is detected, this utility registers the path dynamically so that the path can be used. The path status for the newly detected path or the existing path other than the Offline(C) path is changed to the current status. In this case, the path health checking and the automatic failback are executed at the same time.

If the error message KAPL10357-E is displayed, HDLM does not add an HDLM device even though a new LU was recognized. In this case, execute the dlmcfgmgr utility with the -u parameter to delete the unused HDLM device. This releases a usable name and you can create a logical device file for the HDLM device for a new LU.

Even if you execute the dlmcfgmgr utility (dlmcfgmgr -r) to add a path to an HDLM device that is not managed by HDLM, that HDLM device will not be managed by HDLM.

-o {logical-device-file-name-of-the-HDLM-device ...|all}

Use this parameter to exclude the management-target HDLM device from being managed.

You can specify one or more logical device file names of an HDLM device (/dev/sddlm[aa-pap]) as a parameter value. For details on logical device files for HDLM devices, see Logical device files for HDLM devices.

If you want to exclude all the HDLM devices from being managed, specify all. Specifying all together with a logical device file name of the HDLM device causes an error.

Specifying the -o parameter without a parameter value also causes an error. If you specify a logical device file name of an HDLM device that does not exist, non-HDLM device, or HDLM device that is already defined as a non-HDLM-managed device, the specification is ignored.

The dlmcfgmgr utility with this parameter can be executed a number of times while Linux is running. The specified HDLM device can be excluded from being managed immediately after execution of the utility, except when the specified HDLM device is in use. If the specified HDLM device is in use, an error occurs.

You can use this parameter to exclude the HDLM devices that are no longer required to be managed by HDLM. The excluded HDLM devices are not displayed with the HDLM command's view operation and the HDLM device files for these devices are not created. Therefore, these devices become unavailable to the user.

-i {logical-device-file-name-of-the-HDLM-device ...|all}

Use this parameter to reset the HDLM device that has been excluded from being managed to an HDLM management target.

You can specify one or more logical device file names of an HDLM device (/dev/sddlm[aa-pap]) as a parameter value. For details on logical device files for HDLM devices, see Logical device files for HDLM devices.

If all the HDLM devices are the target, specify all. Specifying all together with a logical device file name of an HDLM device causes an error.

Specifying the -i parameter without a parameter value causes an error. If you specify a logical device file name of an HDLM device that does not exist, non-HDLM device, or HDLM device that is already defined as a management target, the specification is ignored.

The dlmcfgmgr utility with this parameter can be executed a number of times while Linux is running. The specified HDLM device becomes available immediately after execution of the utility.

You can use this parameter to reset an HDLM device that must be managed again to a management target. The HDLM devices reset to a management target are displayed with the HDLM command's view operation, and the HDLM device files for the devices are created. Therefore, these devices become available to the user again.

-v [-udev]

Use this parameter to display the management status and configuration information of all the HDLM devices recognized by HDLM.

Specify this parameter when you want to get the current status of management, configuration, or other information for the HDLM device.

With this parameter, the message confirming that the utility is executed is not displayed at execution of the utility even if you omit the -s parameter. Unlike the -o, -i, or -u parameter, the utility with this parameter specified can operate during the I/O processing to and from the HDLM device.

If you also want to check the udev name assigned to the SCSI device that corresponds to the HDLM device, specify the -udev parameter.

-u {logical-device-file-name-of-the-HDLM-device ...|all}

Use this parameter to delete the paths displayed as hyphens (-) in the Device column of HDLM device configuration information that is displayed by specifying the -v parameter.

You can specify one or more logical device file names of an HDLM device (/dev/sddlm[aa-pap]) as a value of the -u parameter. For details on logical device files for HDLM devices, see Logical device files for HDLM devices. Specifying the -u parameter without the parameter value causes an error.

If all the HDLM devices are the target, specify all. Specifying all together with a logical device file name of an HDLM device causes an error. If you specify the logical device file name for an HDLM device that does not exist or a non-HDLM device, the specification is ignored.

The dlmcfgmgr utility with this parameter can be executed a number of times while Linux is running. The re-configured HDLM device becomes available immediately after execution of the utility.

You can use this parameter to delete information about HDLM device paths for which a compatible SCSI device does not exist (paths displayed as hyphens (-) in the Device column of the HDLM device configuration information that is displayed by specifying the -v parameter), and to release the registration of the path from HDLM.

In general, the path information for the HDLM device is added at HDLM startup time once it is recognized. Even if the recognized HDLM device is not available because this path is disconnected or the LU is deallocated, the path information for the unavailable HDLM device will not be deleted automatically. Because the unused HDLM device path information is preserved, newly defined LUs and added paths cannot be used in some cases. This parameter is useful to eliminate such a problem.

If you specify this parameter with all, an HDLM device, which was simply disconnected at host boot time but is currently being used, might be assumed to be deleted. Before executing the dlmcfgmgr utility with this parameter set to a value of all, check the status of the HDLM device to be deleted by executing this utility with the -v parameter.

-extenddev {logical-device-file-name-of-the-HDLM-device ...|all}

If this parameter is specified, when the system is running, the capacity of the HDLM device specified for the -extenddev parameter and that of the SCSI device under the HDLM device will be compared. If the capacity of the HDLM device is smaller than that of the SCSI device, the capacity of the HDLM device will be expanded to match that of the SCSI device.

You can execute the dlmcfgmgr utility with this parameter specified, if the path status is Online and no error has occurred. Note that the utility will be executed regardless of whether the HDLM device is in use.

Note that you cannot reduce the capacity of an HDLM device. To reduce the capacity of an HDLM device, first execute dlmcfgmgr -o to remove the HDLM device from the HDLM management target, and then reduce the capacity. Then, execute dlmcfgmgr -i to add the HDLM device back to the HDLM management target. Alternatively, restart the server after changing the capacity, and then reconfigure the HDLM device.

You can specify one or more logical device file names of an HDLM device (/dev/sddlm[aa-pop]) as a parameter value. For details on logical device files for HDLM devices, see Logical device files for HDLM devices.

If all the HDLM devices are the target, specify all. Specifying all together with a logical device file name of an HDLM device causes an error.

Specifying the -extenddev parameter without a parameter value causes an error. Similarly, an error occurs if you specify the file name of a logical device file of an HDLM device that does not exist, of a non-HDLM device, or of a device for which dlmcfgmgr -o was executed to remove the device from the HDLM management target.

-logfs [dlmcfgmgr-utility-log-file-size]

Use this parameter to change the size of the dlmcfgmgr utility log file (dlmcfgmgr[1-2].log).

For dlmcfgmgr-utility-log-file-size, specify a value in the range from 1024 to 999999 (in KB).

If the number of LUs to be managed by HDLM is 65 or more or the number of paths to be managed by HDLM is 129 or more, we recommend that you specify a value of 10240 KB or more.

When you change the log file size, the size of the current dlmcfgmgr[1-2].log file is not changed. The next dlmcfgmgr[1-2].log file will be created with the specified file size.

If you do not specify the log file size for the dlmcfgmgr utility, the current setting is displayed.

Examples

Example 1:

To register the path that HDLM has not identified, by confirming the execution of the utility:

In response to the confirmation message, enter y to execute the utility and n not to execute the utility.

Example 2:

To exclude the HDLM device sddlmaa from being managed without confirming the execution of the utility:

Example 3:

To delete the information for all the unavailable paths and unregister the path information from HDLM after confirming the execution of the utility:

In response to the confirmation message, enter y to execute the utility and n not to execute the utility.

Example 4:

The following table shows the items displayed.

Table. Information for the management status and configuration information of an HDLM device

Item	Description
HDevName	Indicates the logical device file name of the HDLM device, using an absolute path. This is indicated only for the first path for the relevant LU.
Management	Indicates the current management status of the HDLM device. configured: indicates that the HDLM device is to be managed. unconfigured: indicates that the HDLM device is excluded from being managed.
Device	Indicates the paths associated with the HDLM device. The logical device file of the SCSI device is indicated. The path whose allocation to an LU is canceled or path that was disconnected at boot time is temporarily registered into HDLM and indicated by a hyphen (-).
Host	Indicates the host ID (host port number).
Channel	Indicates the channel number (bus number).
Target	Indicates the target ID (target ID).
Lun	Indicates the Lun (host LU number).
Udev	Indicates the udev name. The name of a device whose name has not been customized by using the udev function is indicated by a hyphen (-).

Example 5:

The following shows an example of setting the size of the dlmcfgmgr utility log file:

#dlmcfgmgr -logfs 10240

In the above example, the setting value of the size of the dlmcfgmgr utility log file is 10240 KB.

Example 6:

The following shows an example of specifying the size of the dlmcfgmgr utility log file:

#dlmcfgmgr -logfs
KAPL10938-I dlmcfgmgr Log File Size(KB) : 10240
#

Reference information

If you do not specify a parameter, the syntax of the dlmcfgmgr utility is displayed.

# /sbin/dlmcfgmgr
KAPL10319-W usage: /sbin/dlmcfgmgr [-s] 
                     { -r 
                     | -o {special-file-name ... | all}
                     | -i {special-file-name ... | all} 
                     | -v [-udev]
                     | -u {special-file-name ... | all}
                     | -extenddev {special-file-name ... | all}
                     | -logfs [log-file-size]}
#

Notes

• When an LDEV is allocated to a path and then another LDEV is allocated to the same path (host port number, bus number, target ID, and host LU number), the HDLM device name for the new LDEV might sometimes be the same as that for the old LDEV. For example, when an LDEV is deallocated while a host is running, another LDEV can be allocated to the same path. In this case, if an application preserves the settings to use that HDLM device name, a program such as a higher-level program product of HDLM accesses that HDLM device without recognizing that the LDEV was changed. This might result in data corruption. Check that the HDLM device name you previously used is nowhere to be found before deallocating the LDEV.

• You cannot execute multiple instances of the dlmcfgmgr utility at the same time.

• You cannot execute the dlmcfgmgr utility while the dlmstart utility is executing.

• A logical device file name of the HDLM device file that can be specified with the -i, -o, or -u parameter of the dlmcfgmgr utility can consist of up to 4,095 characters. If a name is more than 4,096 characters long, the error message KAPL10358-E is displayed.

• If an LU is allocated and another LU is reallocated using the same host LU number, HDLM does not handle them as different LUs. Therefore, restart the host whenever a configuration change is made.

• When two or more HDLM devices are specified with the -s parameter, the confirmation message is not displayed each time the processing for each HDLM device is executed. For example, when this utility executes an operation specified with the -o parameter for /dev/sddlmaa, /dev/sddlmab, and /dev/sddlmac, the confirmation message KAPL10339-I is not displayed for the processing of each device. This message is displayed once at the beginning of the operation. If you enter y, the processing for all the specified HDLM devices (/dev/sddlmaa, /dev/sddlmab, and /dev/sddlmac) is executed continuously.

• After changing partition configuration directly from a SCSI device for LUs corresponding to the HDLM devices not to be managed, if the HDLM device is returned to management target, execute the following operations:

  1. Execute the dlmcfgmgr utility with the -i parameter specified.

  2. Execute the dlmcfgmgr utility with the -r parameter specified.

• If you execute the dlmcfgmgr utility with the -i parameter specified, the HDLM device that is not a management target can be changed to a managed status. At this time, if an error occurs anywhere on the paths to an HDLM device and you change that HDLM device to a managed status, the message KAPL08026-E might be output to the syslog. However, HDLM operations are not affected.

• If you execute the dlmcfgmgr utility with the -r parameter specified, the I/O and I/O error counts for existing paths displayed when the HDLM command (dlnkmgr view -path) is executed are initialized to 0.

• If an HDLM device that is managed on the active host is changed to be managed on the standby node, and then the same HDLM device is excluded from management on the standby node then, during the cluster creation, an error will occur when the active node is failed over. When the dlmcfgmgr utility is executed with the -o parameter specified to exclude an HDLM device from management on the standby node, make sure that you exclude the same HDLM device from management on the active node.

• When an HDLM device is bound to a raw device, do not attempt to exclude that HDLM device from management by executing the dlmcfgmgr utility with the -o parameter specified. If the HDLM device is not being managed, an error will occur when the raw device is accessed.

• After configuring an HDLM device by executing the dlmcfgmgr utility, do not change the settings of the sysfs interface that handles SCSI devices.

• After configuring an HDLM device by executing the dlmcfgmgr utility, if you unload the HBA driver, perform the operations below. If you load the HBA driver without first performing the operations, the number of HDLM paths that cannot be used might increase.

  1. Update the HDLM device with information about unavailable SCSI devices by executing the dlmcfgmgr utility with the -r parameter specified.

  2. Delete the HDLM device by executing the dlmcfgmgr utility with all specified in the -u parameter.

• If you execute the dlmcfgmgr utility with the -r parameter after dynamically deleting a SCSI device, the HDLM device will become unavailable. If you then add the SCSI device dynamically and execute the dlmcfgmgr utility with the -r parameter specified, the HDLM partition information will be lost from /proc/partitions. To restore the information, follow these steps:

  1. Delete the SCSI device you just added.

  2. Dynamically add the SCSI device once again.

  3. Execute the online operation to place the device path online.

  4. Execute the dlmcfgmgr utility with the -r parameter specified.

• If you execute the dlmcfgmgr utility with the -r parameter specified while all paths connecting to the HDLM device are disconnected, the HDLM partition information will be lost from /proc/partitions. To restore the HDLM partition information, follow these steps:

  1. Connect the path and place the device online.

  2. Execute blockdev --rereadpt HDLM-device to update the partition information.