Creating a default CLI profile

You can specify default settings for the CLI by defining one or more profiles on the system. For example, you can specify the default output format for list commands, the primary and secondary storage manager IP addresses for the DS8000®, or the storage image ID that is required by many commands.

If a user enters a value with a command that is different from a value in the profile, the command overrides the profile.

The following options are available for profile files:
  • You can modify the default profile. The default profile, dscli.profile, is installed in the profile directory with the software. For example, c:\Program Files (x86)\IBM\dscli is the directory path for operating systems Windows 7 and later. The directory path for operating systems UNIX and Linux is /opt/ibm/dscli/profile/dscli.profile.
    Note: Changing the default profile changes the DS CLI default settings for all users. If you do not want to change the DS CLI default settings for all users, consider creating a personal default profile instead.
  • You can create a personal default profile by making a copy of the system default profile as <user_home>/dscli/profile/dscli.profile.
  • You can create a profile for a specific DS8000 system by making a copy of the system default profile and specifying the primary and secondary management console IP addresses and the storage image ID. For example:
    • <user_home>\dscli\profile\DS8000_name1
    • <user_home>\dscli\profile\DS8000_name2
  • You can create a profile for the storage unit operations, typically for Copy Services commands, by starting with a specific DS8000 profile and then adding the remote storage image ID. For example:
    • <user_home>\dscli\profile\operation_name1
    • <user_home>\dscli\profile\operation_name2

These profile files can be specified using the DS CLI command parameter -cfg <profile_name>. Profile names are not required to use the .profile file name extension or any extension. However, the -cfg profile_name parameter must be a complete file name, including the extension if one is specified. Also, if the profile is stored in the user's personal profile directory at <user_home>\dscli\profile, you need to specify only the file name. If the profile is stored in any other directory, the <profile_name> must also include the full path name. If the -cfg profile file is not specified, the user's default profile file is used. If a user's profile file does not exist, the system default profile file is used.

The home directory <user_home> is defined by the Java™ system property named "user.home". The location of your home directory is determined by your operating system. The following examples are home directories in different operating systems:
Windows 7 and later operating systems
For Windows 7 and later operating systems, the property value defaults to the environment variable %USERPROFILE% in a directory called c:\Users\Administrator.
UNIX or Linux operating systems
For a UNIX or Linux operating system, the property value defaults to the environment variable $HOME. As a result, your personal profile is ~/dscli/profile/dscli.profile.

When you install the DS CLI, the default profile is installed in the profile directory with the software. The file name is dscli.profile; for example, c:\Program Files (x86) \IBM\dscli\profile\dscli.profile.

The following steps provide a Windows example of the process you can use to modify key items in the profile file:
  1. Click the DSCLI icon on your desktop. A command prompt window is displayed.
  2. Enter cd profile at the command prompt to move to the system default profile directory.
  3. Edit the profile file with a text editor such as NotePad or WordPad.
  4. Scroll down to the number (#) sign in front of hmc1: and remove the # sign.
  5. Enter the correct IP address of your management console.
  6. If this is a dual HMC DS8000, perform steps 4 and 5 for hmc2.
  7. Scroll down to the # sign in front of devid and remove the # sign.
  8. Enter the serial number of your machine type (include the values for manufacture, machine type, and serial number). For example, IBM®.2107-75YZ881.
  9. Save the file.
  10. Enter cd.. at your command prompt.
  11. Enter DSCLI at your command prompt and the DS CLI starts. You are asked to provide only your user ID and password and not the address of your management consoles.

Table 1 provides the list of profile variables that you can use to create the profile.

Table 1. Profile variables
Variable Description
username: string Specifies your user name for entering DS CLI commands. This variable is equivalent to option -user.
password: string Specifies the password to authenticate when you start a CLI session. This parameter is not required nor recommended. If you use this method to designate your password, the password is displayed on the screen. Another option is to specify a password file (pwfile) that is used when you start the DS CLI. This variable is equivalent to option -passwd.
pwfile: passwordfile Specifies a password file containing your password as an alternative to the variable password. This variable is equivalent to option -pwfile.
banner: on | off Enables or disables the banner that appears before the command output. This variable is equivalent to the command option -bnr. The command option -bnr overrides this default value.
delim: character Specifies a delimiter character for the format: delim variable. The default character is a comma. This variable is equivalent to the command option -delim. The command option -delim overrides this default value.
devid: string Specifies the storage image ID that is the target for the command. This value is equivalent to the command option -dev. The command option -dev overrides this default value.
echo: on | off Specifies whether the command is printed before it is executed.
Specify one of the following formats:
  • on: Specifies that the command is printed before it is executed.
  • off: Specifies that the command is not printed before it is executed.
echoprefix:

prefix | none

 Specifies the command prefix to print before a command is executed.
  • echoprefix: Specifies the prefix to print before a command is executed. If echo is on and echoprefix is specified, then its value is to be printed on the line before the echoed command.
  • none: Specifies that no prefix is to be printed before an echoed command.
format: option Specifies the output format for list commands.
Specify one of the following formats:
  • default: Specifies default output.
  • xml: Specifies XML format.
  • delim: Specifies columnar format. Columns are delimited with the character that you must specify with the delim variable.
  • stanza: Specifies a vertical table.
This variable is equivalent to the command option -fmt. The command option -fmt overrides this default value.
fullid: on | off Specifies that IDs display in fully qualified format, which includes the storage image ID.
header: on | off Enables or disables the headers that display with the columns of data in the list commands. This variable is equivalent to the command option -hdr. The command option -hdr overrides this default value.
hmc1: string Specifies the primary Storage Manager IP address. This variable is equivalent to the command option -hmc1. The command option -hmc1 overrides this default value.
hmc2: string Specifies the secondary Storage Manager IP address. This variable is equivalent to the command option -hmc2. The command option -hmc2 overrides this default value.
locale: code Specifies the language for the output on the local computer.
  • ar: Arabic
  • be: Byelorussian
  • bg: Bulgarian
  • ca: Catalan
  • cs: Czech
  • da: Danish
  • de: German
  • el: Greek
  • en: English
  • es: Spanish
  • et: Estonian
  • fi: Finnish
  • fr: French
  • gu: Gujarati
  • hi: Hindi
  • hr: Croatian
  • hu: Hungarian
  • in: Indonesian
  • is: Icelandic
  • it: Italian
  • iw: Hebrew
  • ja: Japanese
  • kk: Kazakh
  • kn: Kannada
  • ko: Korean
  • lt: Lithuanian
  • lv: Latvian (Lettish)
  • mk: Macedonian
  • mr: Marathi
  • ms: Malay
locale: code
  • nl: Dutch
  • no: Norwegian
  • pa: Punjabi
  • pl: Polish
  • pt: Portuguese
  • ro: Romanian
  • ru: Russian
  • sa: Sanskrit
  • sh: Serbo-Croatian
  • sk: Slovak
  • sl: Slovenian
  • sq: Albanian
  • sr: Serbian
  • sv: Swedish
  • ta: Tamil
  • te: Telugu
  • th: Thai
  • tr: Turkish
  • uk: Ukrainian
  • vi: Vietnamese
  • zh: Chinese
maxNumReports: number Sets the maximum number of records (lines) for an I/O Performance Manager performance report.
Note: The default maximum number of records for a performance report is 256. The value for maxNumReports is recommended to be no larger than 3000. If the target is a DA pair, the recommended value is to be no larger than 1500.
port: 1718 | 1750 | 1751 Specifies the port that the DS CLI should use when connecting to the DS8000 system. If the port is not specified, the DS CLI first attempts to connect using port 1751 with a NIST-compliant certificate. If that connection attempt fails, it attempts to connect to the existing DS8000 port 1750 with the legacy certificate. If the second attempt fails, the DS CLI attempts to connect to port 1718 with the legacy certificate used by ESS 2105 machines. This default behavior means that the DS CLI will connect to any ESS 2105 or DS8000 system. However, checking multiple ports can cause a connection delay when a Release 7.2 or later DS CLI attempts to connect to a DS8000 system or ESS 2105 machine that does not listen on the 1751 port. To prevent the additional delay, you can use this variable to specify a single attempt on the specified port.
1718
Attempt to connect using only port 1718 (ESS 2105 with legacy certificate).
1750
Attempt to connect using only port 1750 (DS8000 prior to Release 7.2 with legacy certificate).
1751
Attempt to connect using only port 1751 (DS8000 Release 7.2 and later with NIST SP 800-131a-compliant certificate).
paging: on | off Controls the display of output. If paging is enabled, a limited number of lines of output displays when a command is issued. The lines do not scroll. You must set the number of lines per page with the rows variable. This variable is equivalent to command option -p. The command option -p overrides this default value.
timeout: number Sets the timeout value of client/server synchronous communication. The unit of the value is seconds. The default value is 900 seconds. You can set this timeout if the processing of a command ends by timeout due to network or client or server performance issue.
Note: The command timeout value can be longer than this value because one command can consist of multiple client/server requests.
timeout.connection: number
Sets the timeout value to establish client or server connection. The unit of this value is seconds. The timeout value must be greater than zero. System-default socket timeout value is used if the value is set to zero. The default value is 20 seconds.
Notes:
  1. If the DS CLI returns a connection error, check for the following conditions:
    • Is there a secure physical connection between the client and server?
    • Is the default timeout value too short to establish a connection?
  2. Setting a connection timeout value that is too short can cause unexpected connection problems.
remotedevid: string Specifies the remote storage image ID. This variable is equivalent to the command option -remotedev. The command option -remotedev overrides this default value.
rows: number Specifies the number of rows per page of output if the paging variable is enabled. This variable is equivalent to command option -r. The command option -r overrides this default value.
verbose: on | off Enables or disables verbose output. This variable is equivalent to the command option -v. The command option -v overrides this default value.

Example

#
# DS CLI Profile
#

#
# Management Console/Node IP Address(es)
#   hmc1 and hmc2 are equivalent to -hmc1 and -hmc2 command options.
#hmc1:	127.0.0.1
#hmc2:	127.0.0.1

#
# Default target Storage Image ID
#    "devid" and "remotedevid" are equivalent to 
#    "-dev storage_image_ID" and "-remotedev storage_image_ID" command options,
#     respectively. 
#devid:		IBM.2107-AZ12341
#remotedevid:	IBM.2107-AZ12341

#  pwfile
#  Specifies a password file containing your password as an alternative 
#  to the variable of password. 
#  pwfile is equivalent to command option -pwfile 
#  Example: pwfile:c:/mydir/75CNF11/pwfile.txt 
#
# locale
#    Default locale is based on user environment.
#locale:		en

# Timeout value of client/server synchronous communication in second.
#    DSCLI command timeout value may be longer than client/server communication
#    timeout value since multiple requests may be made by one DSCLI command
#    The number of the requests made to server depends on DSCLI commands.
#    The default timeout value is 900 seconds.
#timeout:		900

# Socket connection timeout value in seconds.
#    The timeout value must be greater than zero.
#    System default socket timeout value is used if timeout value is set to zero.
#    The default connection timeout value is 20 seconds.
#timeout.connection: 20

# Output settings
#
# ID format of objects:
#   on:		fully qualified format
#   off:	short format
fullid:		off

# Paging and Rows per page. 
# paging enables/disables paging the output per line numbers specified by "rows".
# "paging" is equivalent to "-p on|off" option.
#   on  : Stop scrolling per output lines defined by "rows".
#   off : No paging. (default)
# "rows" is equivalent to "-r #" option.
paging:		off
#rows:		24

# Output format type for ls commands, which can take one of the following values:
#   default: Default output
#   xml    : XML format
#   delim  : delimit columns using a character specified by "delim"
#   stanza  : Horizontal table format
# "format" is equivalent to option "-fmt default|xml|delim|stanza".
#format:		default

# delimiter character for ls commands.
#delim:		|
# Display banner message. "banner" is equivalent to option "-bnr on|off".
#   on  : Banner messages are displayed. (default)
#   off : No Banner messages are displayed.
banner:		on

#
# Display table header for ls commands. "header" is equivalent 
# to option "-hdr on|off".
#   on  : Table headers are displayed. (default)
#   off : No table headers are displayed.
header:		on

#
# Display verbose information. "verbose" is equivalent to option "-v on|off".
#   on  : Display verbose information.
#   off : No verbose information.
verbose:	off

# Echo each dscli command.
# on : Echo commands to standard out prior to execution. Passwords within 
command line arguments will be hidden.
# off : No command echo. (default)
#echo:on

# If echo is on and echoprefix is specified, its value will be printed on the 
line before the echoed command.
#echoprefix:dscli>

# The max number of records for performance report.
# The default max number of records for performance report is 256. 
# The value for it is suggested to be
# not larger than 3000. If the target is dapair, the value is 
# suggested to be not larger than 1500.
#maxNumReports: 256

# Connection port number used when connecting to the DS8000.
# This is equivalent to –port 1718 | 1750 | 1751 on the command line. If not specified, the
#   DSCLI first attempts to connect using the new port 1751 with a NIST-compliant certificate, and
#   if that fails, it attempts to connect to existing DS8000 port 1750 with the legacy certificate.
#   If the second attempt also fails, the DSCLI attempts to connect to port 1718 with the legacy
#   certificate used by ESS 2105 machines. While this default behavior means that the R7.2+ DSCLI
#   will connect to any ESS 2105 or DS8000, checking multiple ports can cause a connection delay
#   when a R7.2+ DSCLI attempts to connect to a DS8000 or ESS 2105 that does not listen on the
#   1751 port. To prevent this additional delay, this variable may be used to specify a single 
		attempt on the specified port.
# 1718 : Only attempt to connect using port 1718 (ESS 2105 with legacy certificate).
# 1750 : Only attempt to connect using port 1750 (DS8000 prior to R7.2 with legacy certificate).
# 1751 : Only attempt to connect using port 1751 (DS8000 R7.2+ with NIST compliant certificate).
#port:	1750

# End of Profile