The EMC CLARiiON Navisphere Command Line Interface (CLI): History and Best Practices

The EMC CLARiiON Navisphere Command Line Interface (CLI): History and Best Practices A Detailed Review Abstract This white paper describes the EMC Navisphere Command Line Interface (CLI). It describes how it was developed, the best way to use it on a new CLARiiON array, and how to easily update your scripts and commands to use this powerful tool on CLARiiON storage systems. July 2009

Copyright 2009 EMC Corporation. All rights reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com All other trademarks used herein are the property of their respective owners. Part Number h6431 A Detailed Review 2

Table of Contents Executive summary...4 Introduction...4 Audience... 4 Navisphere CLI milestones...4 Iterations of Navisphere CLI... 5 Script compatibility considerations...6 Application support for Secure CLI...6 Deploying CLI clients and Host Agents...6 Migrating scripts written with Classic CLI to Secure CLI...7 Using naviseccli instead of navicli... 7 Renaming naviseccli.exe... 7 Host Agent commands... 8 Conclusion...10 References...10 Appendix: FAQ for migrating to Secure CLI...11 A Detailed Review 3

Executive summary The EMC Navisphere Command Line Interface (CLI) has been a popular way of monitoring and managing CLARiiON storage systems since its inception in 1995. Through the years, it has evolved from a powerful scripting language to a completely secure and auditable interface that provides the same functionality as the Navisphere Manager graphical user interface. Introduction This white paper describes the development of Navisphere CLI and its impact on the user community. It describes Secure CLI, which is the latest version of CLI. It also discusses the best way to use Secure CLI s powerful capabilities in new and legacy CLARiiON storage systems. Audience This white paper is recommended for anyone who is interested in learning about how Navisphere CLI was developed and how to best use Navisphere CLI in new and legacy CLARiiON storage systems. Navisphere CLI milestones The following list outlines the milestones in the development of Navisphere CLI: 1997: Navisphere CLI (Classic CLI) Supports basic array and host commands. December 2000: Java CLI client (FLARE release 8.3) Supports MirrorView and other layered applications. August 2005: Secure CLI (FLARE release 19) Supports most Classic and Java CLI commands (with the exception of snapshot clone, MirrorView, Analyzer archive, NDU, and host commands). March 2006: Secure CLI (FLARE release 24) Supports snapshot clone, MirrorView, and NDU commands. This was the last release of the Java CLI client, and is still available on Powerlink. August 2007: Secure CLI (FLARE release 26) Supports Analyzer archive commands. Java CLI is no longer supported on the array; only the host commands remain. July 2008: Classic CLI (FLARE release 28) This is the final version of Classic CLI. This client will continue to be supported on CX4 platforms with future FLARE releases, but no new versions of Classic CLI will be released. 2009: Secure CLI (FLARE release 29) Supports Host Agent commands, LDAP, and event monitoring. A Detailed Review 4

Iterations of Navisphere CLI The Navisphere CLI has gone through three major iterations over the years: Classic CLI Java CLI Secure CLI Classic CLI (navicli) The original CLARiiON Command Line Interface navicli (also known as Classic CLI) is over 10 years old. Classic CLI does not support user authentication or Navisphere roles. Some degree of security is provided by the privileged user list, which can be configured to limit the users and IP addresses that can manage the array. The Classic CLI client maintains a list of valid system types that is updated with each release. The Classic CLI client version must be equal to or higher than the target array. This requires Classic CLI clients to be upgraded prior to any array upgrade. Classic CLI is being phased out in favor of its more secure successor Secure CLI. New features and functions have not been made available in Classic CLI since release 24. Classic CLI will not be offered on CLARiiON systems after the CX4 series. Commands, flags, and outputs are for the most part completely compatible between Classic and Secure CLI. Scripts and tools relying on Classic CLI should be converted to Secure CLI at the earliest opportunity. For security-conscious users (or those who wish to perform testing), Classic CLI can be enabled and disabled at the array starting with release 26. Enabling and disabling Classic CLI on the array has no impact on the SP or host I/O. Java CLI (navicli.jar) Introduced in 2002, Java CLI (navicli.jar) provided a secure connection and required valid CLARiiON user credentials; however, it did not enforce user roles or support audit logging of command activity. The Java client required that an appropriate JRE be present on the host. Java CLI was used for the initial releases of several layered applications including MirrorView, Analyzer, and SnapView clones. Java CLI commands were moved to Secure CLI in release 19. A built-in compatibility mode in the CLI client made this transition relatively uneventful. The Analyzer archive commands were the last remaining usages of Java CLI. Java CLI was completely discontinued in release 26. Any scripts still utilizing Java CLI commands should be converted to Secure CLI as soon as possible. Secure CLI (naviseccli): The current version Secure CLI was designed to meet the needs of a more security-conscious user base, while making it easy for existing users to migrate to Secure CLI. Secure CLI incorporated some significant improvements. Secure CLI is a thin client that is installed on the host. It consists of the functionality required for a secure connection to a CLARiiON. It is fully backward- and forward-compatible with releases of Navisphere that support Secure CLI. Any valid Secure CLI command can be used with any version of the Secure CLI client and any CLARiiON running release 19 or later. The Secure CLI client on the host does not need to be upgraded even when the CLARiiON arrays it communicates with are running later releases of firmware. An older version of the Secure CLI client can support scripts with commands made available in later versions of Navisphere. Secure CLI enforces standard Navisphere user roles and audit logging. Each Secure CLI command must be accompanied by valid Navisphere user credentials. Users can either submit the credentials with each command or configure a Secure CLI security file on the local host, which will provide these credentials automatically. This is a convenient and secure way to avoid having to type credentials with each command. The security file is stored in an encrypted form on the local host. It cannot be copied or moved. Secure CLI A Detailed Review 5

makes a secure connection to the array using SSL in the same manner as the Navisphere Manager UI. Credentials are never passed in the clear. Every user on the host can have one or more Secure CLI security files. The security file can be configured as a global file that will pass one set of credentials where the command is sent, or on a per-sp IP address that will pass a specific set of credentials to a specific IP address. The security file can also be sent to an alternate username. Secure CLI commands, flags, and outputs are consistent with pre-existing Classic or Java commands with a few exceptions, which are discussed in the section Script compatibility considerations. Secure CLI also offers optional full XML tagging (-xml) for all commands, which makes it easier to parse output. Starting with release 22 and the CX3 series systems, all new features are only supported by Secure CLI. Secure CLI is the only command line interface supported on the AX4-5 system. Script compatibility considerations We make every effort to maintain complete script compatibility from release to release. However, from time to time technical considerations require us to make changes. Any known incompatibilities are listed in the release notes. Commands and flags that we are unable to support include: getall getall is a comprehensive listing of all current array features and settings. Running getall is an inefficient way to gather specific information. It is updated with every release and will not offer a consistent output. For these reasons, you should not use getall in production scripts. Use the specific get commands instead. -all The -all flag forces the output of all current command content based on the release of Navisphere on the target SP. With -all, the structure of the output changes from release to release, which may impact scripts that parse content. For this reason, you should not use -all in scripts. Application support for Secure CLI EMC has worked extensively to ensure that EMC applications are fully operational with just Secure CLI operating on the array. Following is a list of the minimum versions for each application that support disabling Classic CLI on the array: For EMC products: EMC ControlCenter 6.0 Replication Manager 5.1 NetWorker PowerSnap 2.4 Solutions Enabler 6.3 SMI-S Provider VDS/VSS 3.1 For third-party products: Veritas Cluster Server MirrorView Agent (UNIX variants as of July 2008;Windows VMware in process as of July 2008 Deploying CLI clients and Host Agents We are changing the way in which CLI clients and Host Agents are made available and installed. Traditionally, the Host Agent and Navisphere CLI clients were packaged in a single installer and installed at the same time. The user had to install all of the components, and after the installation process, manually remove unwanted clients. Starting with release 24, the agents and CLI clients were put in separate install packages, and users can install or retain Classic and Java CLI. The Java CLI installer was dropped from install packages starting with release 26. A Detailed Review 6

After release 28, the Host Agent and each client will be available as individual install packages that are downloadable from Powerlink. In addition, the practice of packaging these installers on CDs will be discontinued. The most recent supported versions of all host software will continue to be available from Powerlink. Migrating scripts written with Classic CLI to Secure CLI The CX4 series is probably the last of the CX systems that will support Classic CLI. Therefore, while it is important that all new development of scripts be done in Secure CLI only, existing scripts that utilize Classic CLI commands should be modified to take advantage of Secure CLI. With the exception of a few Host Agent commands, Secure CLI commands are completely compatible with Classic CLI commands, sub-commands, flags, and outputs. Therefore, this process is relatively straightforward. Using naviseccli instead of navicli Although you could embed credentials with each command, we do not recommend this because it is difficult to maintain. Instead, use navicli instead of naviseccli in your production scripts: In an editor, change all instances of navicli to naviseccli. Load the Secure CLI client on the host. Create a Secure CLI security file on the host 1. Renaming naviseccli.exe Use this method only when there is a relatively small number of static scripts or there is a need to quickly test command compatibility. The drawback to this approach is that it disables the standard method of invoking Secure CLI commands. This might cause confusion at a later date. But it can be used to verify the ability of an older script to be run on a Secure CLI client. To do this: Load the Secure CLI client on the host and uninstall the Classic CLI client. Create a Secure CLI security file 2. Change the directory name of the Secure CLI client from program files/emc/navisphere CLI/naviseccli to program files/emc/navisphere CLI/navicli. 1 The credentials stored in the CLI Security File must reflect an account that exists and has the appropriate privileges on all CLARiiON systems that you wish the script to manage while logged in as this user. 2 Same as above. A Detailed Review 7

Host Agent commands Because the Host Agent does not support credentials or user roles, the Host Agent commands were difficult to migrate to Secure CLI. (These commands require authentication and authorization.) The replacement Secure CLI commands must be directed to a storage processor, so there are changes in formatting and command names. These host commands include getagent, lunmapinfo, remoteconfig, register, clearlog, emconfiguration, insertestevent, and responsetest. We are currently developing replacement commands. You need to modify existing scripts to use these new commands. Secure CLI Host Agent commands will not go directly to the Host Agent. The storage processor will authenticate the request and serve as a proxy. The storage process will then gather information from the agent and respond to the client. You do not need to modify Host Agents configurations to use the new Secure CLI commands. Following is a brief summary comparing some of the old and new host commands. Note that the new commands have changes in syntax and require a storage processor (SP) address. There will be no change in output with the new commands. If you do not change to the new Secure CLI Host Agent commands right now, you can continue to use scripts that use Classic CLI commands until further notice. getagent With Classic CLI, you use this following command to get the revision of the agent on a host: With Secure CLI, use: navicli h <host> getagent naviseccli h <sp> server getagent host <host> Secure CLI talks to the SP, which locates the requested host and determines the revision of the host s agent. If the host is not attached to the array, it returns an error message. Note that, like older versions, the host needs to be running. One additional requirement is that the agent has to have been registered to the SP. A network connection between the host and array is necessary. getlog With Classic CLI, you use this command to get the event log file from the agent on a host: With Secure CLI, use: navicli h <host> getlog naviseccli h <sp> server getlog host <host> remoteconfig With Classic CLI, you use this command to get or set configuration file information for a host s agent: With Secure CLI, use: navicli h <host> remoteconfig naviseccli h <sp> server remoteconfig host <host> A Detailed Review 8

Secure CLI talks to the SP, which finds the requested host and uses the functions that Navisphere Manager uses to set/get agent configuration data. If the host is not attached to the array, it returns an error message. Please note that, like older versions, the host needs to be running. One additional requirement is that the agent has to have been registered to the SP. A network connection between the host and array is necessary. The sub-switches still work in the same manner. register With Classic CLI, you use this command to register a host or get register information from a host: With Secure CLI, use: navicli h <host> register naviseccli h <sp> server register host <host> If the host is not attached to an array, CLI returns an error message. Please note that, like older versions, the host needs to be running. A network connection between the host and the array is necessary. If the host is not registered, you must use the IP address instead of the hostname. The sub-switches work in the same manner. lunmapinfo This command is used to get information such as mount-point information. You can also specify one or more SPs to correlate the LUN WWN. The Classic CLI command is: The Secure CLI is: navicli h <host> lunmapinfo <sp> <sp> naviseccli h <SP> server volmap -host <host> [-local] [-vm] If the host is a physical host, the existing output of the lunmapinfo command and additional information like array IP address is displayed. volmap does not support multiple SPs. Individual commands need to be sent to each storage system attached to the host. A Detailed Review 9

Conclusion Navisphere CLI is a reliable and powerful tool. As described in this white paper, EMC is always working to improve this leading-edge interface to make it more robust, secure, and reliable, while making it easy for the legacy customer to migrate to this state-of-the-art tool. References Navisphere CLI references available on Powerlink: EMC Navisphere Command Line Interface (CLI) Reference EMC Navisphere Analyzer Command Line Interface (CLI) Reference EMC Navisphere Quality of Service Manager Command Line Interface (CLI) Reference EMC MirrorView/Asynchronous Command Line Interface (CLI) Reference EMC MirrorView/Synchronous Command Line Interface (CLI) Reference EMC SAN Copy Command Line Interfaces Reference EMC SnapView Command Line Interfaces Reference References on other CLIs related to CLARiiON are also available on Powerlink: admsnap is covered in the EMC SnapView Command Line Interfaces Reference Initialization Utility CLI naviinittoolcli is covered in the CLARiiON Server Support Products Software Installation Guides Server Utility CLI naviserverutilcli is covered in the CLARiiON Server Support Products Software Installation Guides Powerlink Knowledgebase article of interest: Emc198572 NaviCLI Java CLI Client, navcli.jar A Detailed Review 10

Appendix: FAQ for migrating to Secure CLI Q. Which is the oldest release of FLARE to support Secure CLI? A. Release 19, which shipped on CX200, CX300, CX400, CX500, CX600, and CX700 systems Q. Which is the last release of FLARE to support Java CLI? A. Release 24, which shipped on CX300, CX500, and CX700 Q. Do I have to migrate to a new Host Agent to use Secure CLI commands? A. No, there is no link or compatibility issue with the Host Agent and any version of Navisphere CLI. These products are now available as separate downloadable files. Q. Can I still use the old (Classic) navicli host agent commands with newer versions of the host agent? A. Yes, you can use the existing commands for as long as those versions of software remained supported. Q. Can I still install Java CLI on a new host that is attached to an older array? A. Yes, but first you must install the R24 Agent/CLI package as that is the last package with Java CLI. When upgraded to later versions of CLI, the installer will provide you with a choice of uninstalling or keeping the Java CLI client. Just choose to keep it for as long as you need it. The Java CLI client is only required for scripts including commands invoked with navicli.jar. Q. What should I do to convert a script using Java CLI to Secure CLI? A. Java and Secure CLI commands, flags, and outputs are identical so the transition is straightforward. First, decide how to handle the credentials required by Secure CLI. Credentials may be added with each command line or by creating Secure CLI security file. This file is different from the Java CLI security file. Then, modify each command line accordingly to conform to the navseccli invocation and credential handling. Q. What should I do to convert a script using Java CLI to Secure CLI? A. Java and Secure CLI commands, flags, and outputs are identical so the transition is relatively easy. However, the security files are not compatible. Remember to set up a Secure CLI security file. Q. How long will the Java CLI client be supported? A. The Java CLI client itself was frozen as of release 24. It will follow EOL planning for release 24. Q. When do I absolutely have to convert a script from Classic CLI to Secure CLI? A. When you need to access a new feature or when you point at a platform that does not support Classic CLI. The CX4 series will be the last CX platform to support Classic CLI. A Detailed Review 11