HP Insight Management-Software User Manual
HP Virtual Connect Enterprise Manager 7.2 Command Line Interface User Guide
Abstract
This user guide is intended for HP Virtual Connect administrators who are familiar with both Virtual Connect and the Virtual
Connect management suite, including HP Virtual Connect Manager, Virtual Connect Enterprise Manager and upper level
managers such as HP Matrix OE logical server management and HP Matrix Operating Environment.
HP Part Number: 656831-005a
Published: July 2013
Edition: 2
© Copyright 2011, 2013 Hewlett-Packard Development Company, L.P.
Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial
Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under
vendor's standard commercial license.
The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express
warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall
not be liable for technical or editorial errors or omissions contained herein.
Acknowledgments
Microsoft®, Windows®, Windows XP®, and Windows NT® are U.S. registered trademarks of Microsoft Corporation.
Other trademarks are the property of their respective owners.
Warranty
HP will replace defective delivery media for a period of 90 days from the date of purchase. This warranty applies to all Insight Management
products.
Revision history
Edition NotesPublication dateEdition numberSupported versionsManufacturing part
number
July 2013SecondVersion 7.2656831-005a
Removed “Registering for
software technical
support and update
service”
Initial publicationMarch 2013FirstVersion 7.2656831-005
June 2012FirstVersion 7.1656831-004
February 2012FirstVersion 7.0656831-003
August, 2011FirstVersion 6.3.1656831-002
Contents
1 Getting started...........................................................................................6
VCEMCLI prerequisites..............................................................................................................6
Installing the VCEMCLI..............................................................................................................6
Removing the VCEMCLI.............................................................................................................6
Workflow tips...........................................................................................................................6
CLI use cases for administrators.............................................................................................6
Leveraging the VCEM web user interface................................................................................7
Gathering VC environment information...................................................................................7
Script development considerations..............................................................................................7
Choosing a location for the script files....................................................................................7
Initiating multiple commands.................................................................................................7
Security on the CMS............................................................................................................8
Authentication.....................................................................................................................8
Using delays in script commands...........................................................................................8
Profiles and powering off or powering on................................................................................8
Running scripts as Windows scheduled tasks...........................................................................8
Comparing VCMCLI scripts to VCEMCLI scripts........................................................................8
2 Using the VCEMCLI....................................................................................9
Executable...............................................................................................................................9
Environment Variable................................................................................................................9
Common options......................................................................................................................9
Using the VCEMCLI in a script .................................................................................................10
Authenticating by using VCEM.................................................................................................11
User-name and password logon................................................................................................11
Logging on without a password................................................................................................11
Session lifetime.......................................................................................................................12
Role-based access control (RBAC).............................................................................................12
RBAC Details.....................................................................................................................12
RBAC best practices...........................................................................................................14
Working with server profiles.....................................................................................................15
Creating a server profile.....................................................................................................15
Deleting a server profile......................................................................................................15
Modifying a server profile...................................................................................................15
Displaying job details.........................................................................................................18
Accessing the VCEMCLI help...................................................................................................19
Error reporting.......................................................................................................................20
3 Using VCEM commands............................................................................21
add profile............................................................................................................................21
set profile..............................................................................................................................23
assign profile.........................................................................................................................24
export profiles........................................................................................................................26
move profile...........................................................................................................................27
remove profile........................................................................................................................29
unassign profile......................................................................................................................30
add enet-connection...............................................................................................................31
set enet-connection.................................................................................................................34
remove enet-connection...........................................................................................................37
add fc-connection...................................................................................................................38
set fc-connection.....................................................................................................................40
remove fc-connection...............................................................................................................42
Contents 3
add fcoe-connection...............................................................................................................43
set fcoe-connection.................................................................................................................46
remove fcoe-connection...........................................................................................................49
add iscsi-connection................................................................................................................50
set iscsi-connection..................................................................................................................53
remove iscsi-connection...........................................................................................................56
set iscsi-boot-param................................................................................................................57
remove iscsi-boot-param..........................................................................................................61
add server-port-map................................................................................................................62
set server-port-map..................................................................................................................64
remove server-port-map...........................................................................................................66
add server-port-map-range.......................................................................................................67
remove server-port-map-range...................................................................................................69
poweroff devicebay................................................................................................................70
poweron devicebay................................................................................................................72
show power-status...................................................................................................................73
show job...............................................................................................................................74
show version..........................................................................................................................75
show vcem-status....................................................................................................................76
startvcdfwupdate....................................................................................................................77
completevcdfwupdate.............................................................................................................78
startvcdmaint.........................................................................................................................79
cancelvcdmaint......................................................................................................................80
completevcdmaint...................................................................................................................81
4 Error messages.........................................................................................82
5 Troubleshooting the VCEMCLI..................................................................103
VCEMCLI calls result in access denied errors............................................................................103
VCEMCLI calls result in errors for invalid leading character or invalid characters...........................103
VCEMCLI calls result in 404 errors..........................................................................................103
API timeouts occur................................................................................................................103
High CPU usage on the CMS server while running a VCEMCLI client...........................................103
Job reports a failed status......................................................................................................103
Completed with a warning job status......................................................................................103
Unable to assign a profile to a domain group..........................................................................104
VC Domain reports configuration mismatch status.....................................................................104
VC Domain reports expired license status.................................................................................104
Error occurs on a database operation......................................................................................104
VCEM operation failed to execute because VC firmware is not supported.....................................104
Creating a server profile fails.................................................................................................105
Server profile edit operation fails when the target server is powered on.......................................105
Server profile job completed with success but changes have not occurred....................................105
After a server profile assignment, some connections defined in the server profile are not functional...106
Error message for the -add profile or -set profile command occurs...............................................106
Error message for the -add profile command............................................................................107
Unexpected results from non-blocked (-nb) commands................................................................107
Additional troubleshooting information and tools......................................................................107
6 Support and other resources....................................................................108
Information to collect before contacting HP...............................................................................108
How to contact HP................................................................................................................108
Security bulletin and alert policy for non-HP owned software components....................................108
Subscription service..........................................................................................................108
HP services..........................................................................................................................108
How to use your software technical support and update service.............................................109
4 Contents
Warranty information.......................................................................................................109
HP authorized resellers.....................................................................................................109
Related information...............................................................................................................109
Documents......................................................................................................................109
Websites........................................................................................................................110
Typographic conventions.......................................................................................................110
7 Documentation feedback.........................................................................111
Index.......................................................................................................112
Contents 5
1 Getting started
The HP Virtual Connect Enterprise Manager (VCEM) Command Line is a family of executables that
provide the facilities necessary for the most frequently used management operations for the VCEM
infrastructure.
The VCEM Command Line Interface (VCEMCLI) can be used as an alternative method for managing
common Virtual Connect operations. The VCEM.CMD executable provides failover management.
VCEMCLI.EXE is useful when scripting bulk operations on multiple Virtual Connect (VC) server
profiles.
VCEMCLI prerequisites
The VCEMCLI supports the same Windows operating environments as the corresponding release
of VCEM. For more information, see the latest version of the HP Insight Management Support
Matrix.
Installing the VCEMCLI
The VCEMCLI is automatically installed from the Insight Management 7.2 DVD when VCEM is
installed on the central management server (CMS) host.
Removing the VCEMCLI
The VCEMCLI is removed when VCEM is removed from the CMS host.
Workflow tips
This section helps you to use the VCEMCLI efficiently.
CLI use cases for administrators
The VCEMCLI can facilitate VC management tasks in a number of scenarios. The following are
some example use cases:
• Assemble a library of scripts to create different types of common profiles. If your environment
always assigns a particular set of network and storage connections for a class of servers such
as web servers or file servers, these settings can be captured in a script. When a new web
server profile is needed, run the script to create the new profile.
• Script VCMCLI and VCEMCLI operations:
Use the VCEMCLI to put the domain into maintenance.◦
◦ Use a secure shell (SSH) client to drive the VCMCLI.
◦ Use the VCEMCLI to cancel or complete maintenance on the domain.
• Script VCSU and VCEMCLI operations:
Use the VCEMCLI to put the domain into maintenance.◦
◦ Script VCSU commands.
◦ Use the VCEMCLI to cancel or complete maintenance on the domain.
• Manipulate networks or fabrics on groups of profiles.
• Script reassignment of profiles in response to changing workloads or environment.
6 Getting started
• Run scripts in response to HP Systems Insight Manager events or from the Windows job
scheduler.
• Leverage the comma-separated values (CSV) export of profile data to answer questions such
as:
◦ Where is this MAC address or WWN used?
◦ Which profiles use this network?
◦ Which profiles use this fabric?
◦ What is different between these profiles?
Leveraging the VCEM web user interface
The VCEMCLI is designed to be used in addition to the VCEM web user interface. The web UI is
an easy way to gather information about your VC configuration and to examine the results of
scripted operations during the script development process.
Gathering VC environment information
Before you use the VCEMCLI, gather the following:
• Systems Insight Manager authentication information
• List of VC domains
• List of VC domain groups
• List of VC server profiles (can be done via the VCEMCLI -export profiles command)
• List of VC networks
• List of VC storage fabrics
• SAN-boot configuration details (if any)
• List of enclosures and a list of bays and servers contained in the enclosures
Script development considerations
The information in this section helps you with some key decisions on how your scripts are structured.
Choosing a location for the script files
Do not place the scripts you create in the VCEMCLI installation directory, because this approach
might prevent product upgrades from functioning. Instead, create your scripts in a separate directory
outside the HP installation directory tree.
Initiating multiple commands
Initiating several commands into the CMS quickly increases resource consumption on that system
for both CPU and memory. At some point, there is a risk of exceeding the system's ability to accept
and queue additional jobs.
To avoid this situation, HP recommends that you code script in such a way that it will be able to
cope with failed job submissions. Then, you must wait for a period of time and attempt to submit
the job again.
Do not use the -nb option when you are submitting multiple commands to operate on a single
profile, such as a series of commands to add multiple network connections. Doing so can cause
the commands to interfere with each other during processing.
Script development considerations 7
Security on the CMS
The VCEMCLI is installed on the CMS. By installing on the CMS, you get the benefits of the security
measures already in place for the CMS. The trade-off is that the script execution imposes additional
load on the CMS.
HP recommends that you evaluate the amount of load that the script places on the CMS, and either
program in pauses or reduce the amount of work that each invocation of the script accomplishes.
Authentication
Decide whether user name and password authentication or certificate-based authentication is
appropriate for your environment. For more information about authentication, see “Authenticating
by using VCEM” (page 11).
Using delays in script commands
Do not poll for results in a tight loop. Insert delays in your scripts to allow the CMS time to manage
other tasks. Polling for results by using tight loops without delays might overload the CMS.
Profiles and powering off or powering on
Assigning a profile to a bay that contains a server requires that the bay be powered off in order
to complete the assignment. Graceful power-off operations allow time for the operating system on
the server to go through its normal shutdown processing. If an unresponsive process prevents the
normal shutdown from proceeding, you may need to resort to an ungraceful power-off. You should
use this method only as a last resort because it may result in data loss on the affected server. The
same power-off constraint applies to unassigning or updating a profile for a bay that contains a
server.
Running scripts as Windows scheduled tasks
By configuring the Windows Task Scheduler to run your VCEMCLI script, you can schedule
operations such as server reboots so they occur during nonworking hours. Configure the scheduled
task by using the credentials that correspond to the specific VCEMCLI script that the task will run.
Comparing VCMCLI scripts to VCEMCLI scripts
The VCEMCLI uses the same keyword names that the VCMCLI uses for items common to both CLIs.
VCEMCLI keywords are always preceded by a dash. In the VCMCLI whether a dash is required
depends on the specific keyword. Name/Value pairs in the VCEMCLI are separated by a space,
whereas they are separated by an equal sign (=) in the VCMCLI.
8 Getting started
2 Using the VCEMCLI
The VCEMCLI can be executed from the Windows command-line or from scripts written in any
Windows-supported scripting language.
Executable
The vcemcli.exe executable is located in the HP VCEM Installation Root
Directory\Virtual Connect Enterprise Manager CLI directory.
During the VCEM installation process, the directory that contains vcemcli.exe is added to the
%PATH% environment variable (EV).
Environment Variable
You can control the behavior of the VCEMCLI and its common options by using the Windows EV
VCEMCLI. The format for the EV is exactly the same as the command-line. Any arguments contained
in this EV are appended to the list of arguments provided on the vcemcli.exe command-line.
Any arguments contained in the EV that are also provided on the command-line will be ignored.
Common options
VCEMCLI command-line options are not case sensitive. Options present on the command-line
override any corresponding values that the VCEMCLI environment variable (if set) contains.
Table 1 lists the common vcemcli.exe command-line options and their descriptions.
Table 1 Common options
-user username
-pw password
–port port
–loglevel level
–nb
DescriptionCLI options
Set as the user name for authentication with Systems Insight
Manager. If this command is not specified, the VCEMCLI
will use the Windows user name of the current user.
Used for authenticating with Systems Insight Manager when
the –user argument was also provided.
Used to contact the Systems Insight Manager server. If this
option is not provided, the default port is 50001. This
argument is required only if the Systems Insight Manager
environment is changed to require SOAP connections on
a different port.
File that contains VCEMCLI log messages.–logfile logfilename
Can be set to control the amount of information that
VCEMCLI logs. The available levels are: debug, info,
warn, error, and off.
The maximum size, in KB, of the VCEMCLI log file.–logsize size in kb
The default behavior is for commands to block and wait
for completion of the associated job or power operation
before they continue. The –nb (non-block) option causes
normally blocking commands to return immediately after
they are submitted. You must check the result of the
non-blocking job or power operation separately to
determine its success or failure.
Executable 9
Table 1 Common options (continued)
DescriptionCLI options
NOTE: When you are using this option, sequential edits
queued for the same profile might conflict with the changes
being applied. HP recommends that you use blocking
operations when you are performing multiple changes to
a given profile. This approach ensures that the changes
for each edit are applied to the profile before the next
group of changes are initiated. Do not submit multiple
non-blocked commands for a single profile. Later
commands may overwrite the changes made by earlier
commands. For example, do not submit a series of
non-blocked commands to add network connections to a
given profile.
Suppresses output from the VCEMCLI.–silent
–timeout seconds
-pollinginterval seconds
Using the VCEMCLI in a script
The following example illustrates how the VCEMCLI can be used to automate common profile
management tasks. This example:
• Powers on the servers in the enclosure
• Creates server profiles
• Adds and edits network connections for the server profiles
• Assigns server profiles to the bays that contain servers
@echo off
set CLI=vcemcli.exe
set VCDG=OA-78-VCDG
set NEWNET=NET2
set MAXPROFILES=5
set MAXBAYS=16
set ENCLNAME=OA-78
set VCEMCLI=-logfile c:\demo.log
echo Turn on all servers in enclosure %ENCLNAME% -------------------------------------------for /L %%I in (1,1,%MAXBAYS%) DO (
%CLI% -show power-status -enclosureName %ENCLNAME% -bayname %%I
if ERRORLEVEL 240 (
echo There is no server in bay %%I
) else (
if ERRORLEVEL 1 (
echo Server in bay %%I is already on
) else (
echo Turning on server in bay %%I
%CLI% -poweron devicebay -enclosureName %ENCLNAME% -bayname %%I
if ERRORLEVEL 1 goto ERRORHANDLER
)
)
)
echo Creating %MAXPROFILES% profiles ------------------------------------------------------for /L %%I in (1,1,%MAXPROFILES%) DO (
echo Creating profile %%I of %MAXPROFILES%
%CLI% -add profile -vcdomaingroup %VCDG% -profilename PROFILE-%%I
if ERRORLEVEL 1 goto ERRORHANDLER
)
When set, instructs the VCEMCLI how long to wait for
blocking commands.
When set, instructs the VCEMCLI how often to poll VCEM
for job or power status.
echo Profile creation complete - adding network connections -------------------------------for /L %%I in (1,1,%MAXPROFILES%) DO (
echo Adding enet connection to PROFILE-%%I
%CLI% -add enet-connection -profilename PROFILE-%%I
if ERRORLEVEL 1 goto ERRORHANDLER
)
10 Using the VCEMCLI
echo Add network connection complete - Update network connections -------------------------for /L %%I in (1,1,%MAXPROFILES%) DO (
echo Assigning enet connection %NEWNET% to port 3 of PROFILE-%%I
%CLI% -set enet-connection -profilename PROFILE-%%I -network %NEWNET% -portnumber 3
if ERRORLEVEL 1 goto ERRORHANDLER
)
echo Assign the profiles to bays that have servers present --------------------------------for /L %%I in (1,1,%MAXPROFILES%) DO (
::Turn off the server in the target bay ONLY if a server is present
%CLI% -show power-status -enclosureName %ENCLNAME% -bayname %%I
if ERRORLEVEL 240 (
echo There is no server in bay %%I - skipping profile assignment
) else (
if ERRORLEVEL 1 (
echo ----------------------------------------- echo Turning off server in bay %%I
%CLI% -poweroff devicebay -enclosureName %ENCLNAME% -bayname %%I -forceOnTimeout
if ERRORLEVEL 1 goto ERRORHANDLER
)
echo ----------------------------------------- echo The server in bay %%I is off. Assigning profile PROFILE-%%I
%CLI% -assign profile -profilename PROFILE-%%I -enclosureName %ENCLNAME% -bayname %%I
if ERRORLEVEL 1 goto ERRORHANDLER
)
)
goto END
:ERRORHANDLER
echo Error processing last command. ERRORLEVEL = %ERRORLEVEL%
:END
exit /b %ERRORLEVEL%
Authenticating by using VCEM
The VCEMCLI allows two types of authentication:
• Systems Insight Manager certificate based (administrators only): If the VCEMCLI user is logged
on as the local administrator, no credentials are required for command execution. This is the
recommended authentication method.
• User-name and password credential pair: If you are not logged on as an administrator, a
user-name and password credential pair must be provided. If only the password argument is
provided, the VCEMCLI uses the user name of the current Windows user for authentication.
User-name and password logon
Logging on requires a user-name and password credential set, which is passed to the VCEM server
for authentication. In this case, a successful logon is occurs when Systems Insight Manager validates
the supplied credentials. If the logon attempt is unsuccessful, an error message that indicates the
failure is reported.
User-name and password authentication is simple to configure, easier for testing scripts, and more
suited for use with role-based access control (RBAC). User-name and password information must
be gathered at the time that the script is run, or you must define a sufficiently secure mechanism
in your environment to store the user-name and password so the information is available to the
script when it runs.
Logging on without a password
If you log on to the CMS as an administrator, it is possible to execute the VCEMCLI without providing
credentials. This method uses a pre-installed authentication certificate available only to the CMS
administrator . HP recommends this method for executing the VCEMCLI because no password is
required as an argument on the command-line.
Authenticating by using VCEM 11
Session lifetime
VCEMCLI logon sessions remain active for a single command execution. The CLI automatically
logs out of the VCEM server after the execution finishes, whether the command succeeded or failed.
Role-based access control (RBAC)
You can use RBAC to designate which operations and resources can be manipulated.
RBAC Details
VCEM provides the following role-based user types. Individual VCEMCLI commands require different
access permissions based on the resource involved and the read or write operation being called.
Access is determined based on the credentials that the VCEMCLI uses.
• VCEM Administrator—Manages all VCEM resources. All operations are permitted to all
resources.
• VCEM Domain Group Administrator—Manages VC domains and server profiles in one or
more VC domain groups.
• VCEM Domain Group Operator—Manages server profiles in one or more VC domain groups.
• VCEM Domain Group Limited Operator—Manages the same tasks as the VCEM Domain Group
Operator except for creating, editing, and deleting a server profile.
• VCEM User (Read Only)—Has read-only access to all VCEM resources.
Table 2 lists command-line options and the role-based user access privileges that can use the
commands.
Table 2 RBAC privileges
VCEM
DomainVCEM
(page 21)
(page 23)
profile” (page 24)
profiles” (page 26)
(page 27)
profile” (page 29)
VCEM
AdministratorCommand-line option
Group
Administrator
xx-remove profile, see “remove
DomainVCEM Domain
Group
Operator
xxx-add profile, see “add profile”
xxx-set profile, see “set profile”
Group
Limited
Operator
xxxx-assign profile, see “assign
xxxx-move profile, see “move profile”
VCEM User
(Read Only)
xxxxx-export profiles, see “export
profile” (page 30)
enet-connection” (page 31)
enet-connection” (page 34)
“remove enet-connection” (page 37)
12 Using the VCEMCLI
xxxx-unassign profile, see “unassign
xxx-add enet-connection, see “add
xxx-set enet-connection, see “set
xxx-remove enet-connection, see
Table 2 RBAC privileges (continued)
VCEM
AdministratorCommand-line option
fc-connection” (page 38)
fc-connection” (page 40)
“remove fc-connection” (page 42)
fcoe-connection” (page 43)
fcoe-connection” (page 46)
“remove fcoe-connection” (page 49)
“add iscsi-connection” (page 50)
iscsi-connection” (page 53)
VCEM Domain
Group
Administrator
VCEM
Domain
Group
Operator
xxx-add fc-connection, see “add
xxx-set fc-connection, see “set
xxx-remove fc-connection, see
xxx-add fcoe-connection, see “add
xxx-set fcoe-connection, see “set
xxx-remove fcoe-connection, see
xxx-add iscsi-connection, see
xxx-set iscsi-connection, see “set
VCEM
Domain
Group
Limited
Operator
VCEM User
(Read Only)
“remove iscsi-connection” (page 56)
iscsi-boot-param” (page 57)
“remove iscsi-boot-param” (page 61)
server-port-map” (page 62)
server-port-map” (page 64)
“remove server-port-map” (page 66)
see “add server-port-map-range”
(page 67)
server-port-map-range, see
“remove server-port-map-range” (page
69)
“poweroff devicebay” (page 70)
xxx-remove iscsi-connection, see
xxx-set iscsi-boot-param, see “set
xxx-remove iscsi-boot-param, see
xxx-add server-port-map, see “add
xxx-set server-port-map, see “set
xxx-remove server-port-map, see
xxx-add server-port-map-range,
xxx-remove
xxxx-poweroff devicebay, see
“poweron devicebay” (page 72)
power-status” (page 73)
74)
xxxx-poweron devicebay, see
xxxxx-show power-status, see “show
xxxxx-show job, see “show job” (page
Role-based access control (RBAC) 13
Table 2 RBAC privileges (continued)
VCEM
Domain
Group
Limited
Operator
VCEM User
(Read Only)
xxxxx-show version, see “show version”
xxxxx-show vcem-status, see “show
(page 75)
vcem-status” (page 76)
“startvcdfwupdate” (page 77)
“completevcdfwupdate” (page 78)
“startvcdmaint” (page 79)
“cancelvcdmaint” (page 80)
“completevcdmaint” (page 81)
VCEM
AdministratorCommand-line option
VCEM Domain
Group
Administrator
xx-startvcdfwupdate, see
xx-completevcdfwupdate, see
xx-startvcdmaint, see
xx-cancelvcdmaint, see
xx-completevcdmaint, see
VCEM
Domain
Group
Operator
VCEMCLI commands for read operations require minimum VCEM privilege, whereas write operations
require full privilege to the affected resource. You can set up the VCEM privilege from the Systems
Insight Manager: Options→Security→Users and Authorizations. If the minimum RBAC is not met,
the VCEMCLI reports an error. The error message contains a description of the reason for the
failure.
RBAC best practices
In configurations where VCEM is used in conjunction with an upper-level manager such as HP
Matrix Operating Environment or HP Matrix OE logical server management, make sure that
operations invoked through the VCEMCLI do not disrupt the functioning of the upper-level manager.
The VCEM user interface warns the administrator when it detects the risk of conflict, but the VCEMCLI
does not. For more information about which commands can cause disruption of upper-level
managers, see “Using VCEM commands” (page 21).
You can configure Systems Insight Manager by using RBAC to prevent conflicts between VCEM
and upper-level managers by not allowing changes to resources that would disrupt the upper-level
managers.
To prevent conflicts:
• Define specific Systems Insight Manager users for VCEM and the VCEMCLI.
• Define additional Systems Insight Manager users for upper-level managers.
• If needed, remove roles from the VCEM users to prevent conflict with upper-level managers.
• Set permissions on VC domain groups so that only specific Systems Insight Manager users
can access them.
• Confirm that the scripts specify the correct user-name and password credentials to ensure that
they are granted only the appropriate level of permissions.
• Ensure that NTFS permissions are set on the scripts on the CMS so that they are accessible
only to the CMS users who are authorized to run them.
14 Using the VCEMCLI
Working with server profiles
The VCEMCLI provides the most commonly used server profile operations, including:
• Server profile creation or update
• Server profile assignment, unassignment, move or export to CSV
For more information on server profiles and the available server profile operations, see the HP
Virtual Connect Enterprise Manager User Guide available at: http://www.hp.com/go/vcem/.
Creating a server profile
Server profiles are defined in a multi-step process to reduce the number of arguments required in
a single VCEMCLI command. In the first step, the server profile is created as unassigned and with
default connections. Subsequent VCEMCLI operations on the same server profile define other
network and SAN connections.
Creation of a server profile requires only two attributes:
• Server profile name
• VC domain group to which the server profile will belong
The server profile name must be unique, be less than 64 characters in length, and contain only
alphanumeric characters, hyphens, and underscores. For more information, see “add profile”
(page 21).
After you create the server profile, you can add connections as required:
• For network connections, use the –add enet-connection command.
• For iSCSI connections, use the –add iscsi-connection command.
• For FC connections, use the –add fc-connection command.
• For FCoE connections, use the –add fcoe-connection command.
After you create the server profile and add the necessary connections, you can assign the server
profile. For more information see “assign profile” (page 24).
Deleting a server profile
Use the -remove profile command to remove server profiles.
Modifying a server profile
You can modify server profiles after you create them. You can choose from the following options
to modify a server profile:
• Rename the server profile by using the -set profile command.
• Select from the following network options:
Add networks by using the -add enet-connection command.◦
◦ Modify networks by using the -set enet-connection command.
◦ Remove networks by using the -remove enet-connection command.
◦ Add multiple networks by using the -add server-port-map command.
◦ Modify multiple networks by using the -set server-port-map command.
◦ Remove multiple networks by using the -remove server-port-map command.
Working with server profiles 15
NOTE: The minimum number of network connections is two. You cannot remove these two
default connections. You cannot add more than the maximum allowed network connections.
The maximum allowed network connections is based on the VC firmware mode. For more
information see the HP Virtual Connect Enterprise Manager User Guide available at: http://
www.hp.com/go/vcem/.
• Select from the following Flex-10 iSCSI network connection options:
Add Flex-10 iSCSI network connections by using the -add iscsi-connection
◦
command.
◦ Modify Flex-10 iSCSI network connections by using the -set iscsi-connection
command.
◦ Remove Flex-10 iSCSI network connections by using the -remove iscsi-connection
command.
NOTE: You can remove all of the iSCSI connections. You cannot add more connections than
the maximum allowed. The maximum connections allowed is based on the VC firmware mode.
For more information, see the HP Virtual Connect Enterprise Manager User Guide available
at: http://www.hp.com/go/vcem/.
• Select from the following FC connection options:
Add FC SAN connections by using the -add fc-connection command.◦
◦ Modify FC SAN connections by using the -set fc-connection command.
◦ Remove FC SAN connections by using the -remove fc-connection command.
NOTE: You can remove all of the FC connections. You cannot add more connections than
the maximum allowed.
• Edit the FC boot parameters by using the -set fc-connection command.
• Select from the following FCoE connection options:
Add FCoE connections by using the -add FCoE-connection command.◦
◦ Modify FCoE connections by using the -set FCoE-connection command.
◦ Remove FCoE connections by using the -remove FCoE-connection command.
• Edit the FCoE boot parameters by using the -set FCoE-connection command.
• Select from the following iSCSI boot-parameter options:
Add iSCSI boot parameters by using the –set iscsi-boot-param command.◦
◦ Modify iSCSI boot parameters by using the –set iscsi-boot-param command.
◦ Remove iSCSI boot parameters by using the -remove iscsi-boot-param command.
You can’t add more than two boot parameters on the iSCSI connection.
NOTE: You cannot add more than two boot parameters on the iSCSI connection.
• Change the server profile’s bay assignment by using the –unassign profile command,
the –assign profile command, or the -move profile command.
Server profiles can be moved within as well as between VC domain groups. The assign and
unassign commands work within a domain group. The move command can work within as
16 Using the VCEMCLI
well as between domain groups. Moving server profiles between domain groups offers new
options when upgrading hardware or firmware. As part of the move process, the source and
destination domain groups are checked for compatibility of network and storage connections.
Warnings or errors are reported, based on the severity of any mismatches that are detected.
The VCEMCLI move command can be executed from a script triggered from Systems Insight
Manager in response to designated events. The HP Virtual Connect Enterprise Manager User
Guide describes how the VCEM failover command-line utility can be invoked from Systems
Insight Manager. A similar approach can be used for Systems Insight Manager to execute the
VCEMCLI power and move commands to relocate server profiles in the event of a failure. The
VCEM failover command-line requires that compatible spare blades are designated through
the VCEM web UI, but the VCEMCLI power, move, assign and unassign commands can be
used to:
◦ Shut down a lower priority workload.
◦ Reassign a higher priority workload server profile to a vacated blade.
◦ Power up a high priority server profile in its new location.
Once the original blade has been repaired, the process can be reversed to restore the server
profiles to their normal assignments.
Working with server profiles 17
Displaying job details
The –show job -jobid command displays details for the specified VCEM job. The command
returns a value that corresponds to the current state of the job.
The job state return codes are:
• COMPLETED (0)—The job is complete.
• PENDING (10)—The job is waiting to run.
• RUNNING (11)—The job is still running.
• WARNING (12)—The job succeeded with minor errors.
• FAILED (13)—The job failed.
Sample job details:
Y:\>vcemcli -show job -jobid 10
Listing details for specified VCEM job...
Job ID: 10
Job Name: Delete Server Profile [SmokeTestProf]
Job Description: Delete Server Profile
Job State: COMPLETED
Job Progress: 100%, [Mon Dec 20 11:13:47], Delete Server Profile finished.
Job User Name: VCEM-2K3-QA3\Administrator
Job Create Time: [Mon Dec 20 11:13:46]
Job Start Time: [Mon Dec 20 11:13:46]
Job End Time: [Mon Dec 20 11:13:47]
18 Using the VCEMCLI
Accessing the VCEMCLI help
Obtain help by running the VCEMCLI without any arguments.
GETTING STARTED:
-help : displays a list of available commands and managed elements
-help <command | managed element>: displays help on the specified item
-----------------------------------------------------------------Control commands
------------------------------------------------------------------
-logfile : The path to a logfile for VCEMCLI diagnostic logging
-loglevel : Controls the level of diagnostic logging
-logsize : The maximum size in KB of the VCEMCLI logfile
-nb : Return immediately without waiting for command results
-pollinginterval : How frequently VCEMCLI checks for results
-pw : The password to authenticate with the CMS
-serverport : The port number to use when contacting the CMS
-silent : Suppress output from VCEMCLI
-timeout : Number of seconds VCEMCLI waits for results of blocking commands
-user : The username to authenticate with the CMS
-----------------------------------------------------------------Subcommands
------------------------------------------------------------------
-add : Add a new object to the domain or to another object
-assign : Assign a server profile to a device bay
-cancelvcdmaint : Cancel maintenance mode for the VC domain.
-completevcdmaint : Complete maintenance for the VC domain.
-completevcdfwupdate : Complete firmware update for the VC domain.
-export : Export VCEM information to a CSV file.
-fcoenetwork : Name of FCoE network associated with the connection
-help : Displays a list of available subcommands
-move : Move a server profile within the VC Domain Group or across VC Domain Groups
-poweroff : Power off a bay in an enclosure
-poweron : Power on a bay in an enclosure
-remove : Remove or delete an existing object (networks, etc.)
-set : Modify one or more configuration properties of an object
-show : Display information about a job, bay power, VCEM domain status or VCEMCLI version
-startvcdmaint : Enter maintenance mode for the VC domain.
-startvcdfwupdate : Enter firmware update mode for the VC domain.
-unassign : Unassign a server profile from a device bay
-----------------------------------------------------------------Subcommand options
------------------------------------------------------------------
-authentication : Authentication method used by the initiator to login to the target.
-bayname : The name or number of the bay containing the server
-bootlun : The logical unit number (LUN) to use for SAN boot
-bootorder : Enables or disables iSCSI boot.
-bootport : The target WWPN for the SAN target
-bootpriority : Controls whether the HBA port is enabled for SAN boot
-connectionbay : The bay containing the Ethernet or SAN interface
-customspeed : The custom speed for the FCoE connection
-dhcpvendorid : String used to match the Vendor Class Id field in the DHCP offer packet.
-domainname : Virtual Connect domain name
-efistate : Specifies the presence of EFI state information
-enclosurename : The name the administrator has assigned to the VC enclosure
-exportfile : The name of a file to receive the exported VCEM information.
-fabric : The name of an existing SAN fabric to associate with the profile
-force : Forces an abrupt power off operation
-forceontimeout : Force a shutdown if normal shutdown doesn't complete in the specified timeout period
-gateway : Default IP route used by the iSCSI initiator.
-initiatorip : IP address used by the iSCSI initiator.
-initiatorname : Name used for the iSCSI initiator on the booting system.
-iscsibootparamdhcp : Allows iSCSI option ROM to retrieve iSCSI boot parameters from DHCP or static configuration.
-jobid : The VCEM jobid to report status on
-lun : The Logical Unit Number (LUN) of the Target identifies the volume to be accessed.
-mactypeoverride : Override VCEM MAC address and instead use the factory default.
-mask : IP network mask used by the iSCSI initiator.
-matchuplinkset : Requires matching Vlans on uplinkset.
-mcastfilter : Name of an existing multicast filter associated with the connection.
-mcastfilterset : Name of an existing multicast filter set associated with the connection.
-mutualsecret : Mutual Secret password for CHAPM authentication.
-mutualusername : Mutual username for CHAPM authentication.
-nag : Network Access Group
-name : The new name to be set on the profile
-network : An existing network name to be associated with the profile
-networkparamdhcp : Allows iSCSI option ROM to retrieve TCP/IP parameters from DHCP or static configuration.
-portnumber : An integer uniquely identifying network connections in the server profile
-poweronbay : Power the bay on after assigning the profile.
-profilename : The name of the profile to be managed
-pxe : Specifies preboot execution environment setting for the connection
-restoreconfig : Restore previous domain configuration if needed
-secret : Secret password for CHAP and CHAPM authentication.
-sntypeoverride : Override the VCEM serial number and instead use the factory default
-speed : The speed for the connection
-speedtype : The speed setting for iSCSI, FCoE or Ethernet connections
-targetip : Primary IP address of the iSCSI target.
-targetip2 : Alternate target IP address for use if the primary port is unavailable.
-targetname : Name of the target from which to boot.
-targetport : The TCP port associated with the primary target IP address.
Accessing the VCEMCLI help 19
-targetport2 : The TCP port associated with the alternate target IP address.
-tobayname : The name or number of the bay in the target enclosure
-tovcdg : The target Virtual Connect domain group name
-toenclosurename : The target Virtual Connect enclosure name
-untagged : Controls whether the network handles untagged packets
-uplinkset : The name of the shared uplinkset
-username : Username for CHAP and CHAPM authentication.
-validate : Validates certain preconditions
-vcdomaingroup : The name of the VCEM domain group for the profile
-vlanid : The vlanid to be used for the port mapping.
-vlanids : The vlanids to be used for the port mapping.
-wwntypeoverride : Override VCEM WWN and instead use the factory default
-----------------------------------------------------------------Managed Elements
-----------------------------------------------------------------devicebay : Bay which can contain a Virtual Connect server.
enet-connection : Ethernet Network Connection
fc-connection : Fibre Channel SAN Fabric Connections
fcoe-connection : Network and FCoE Fabric Connections
iscsi-boot-param : iSCSI Boot Parameter information
iscsi-connection : iSCSI Network Connections
job : VCEM jobs
power-status : Bay power status
profile : Virtual Connect Server Profile
profiles : VCEMCLI profile export information
server-port-map : Shared Server Downlink Port Mapping Configuration
server-port-map-range : Shared Server Downlink Port Mapping Range Configuration
vcem-status : The VCEM management status of the VC domain
version : VCEMCLI Version Information
Error reporting
All VCEMCLI commands can report errors. These error messages contain both a text description
of the exception and a numeric value in string form that represents the error code for the
corresponding exception.
The VCEMCLI sets the DOS ERRORLEVEL environment variable based on the success or failure of
the command. Success is indicated by a level of zero (0). Failure is indicated by levels of one (1)
or greater, where the specific value corresponds to an error described in the error message tables.
For the -show command, the ERRORLEVEL environment variable is set to indicate state, not an
error condition. This configuration allows for a script to execute -show for jobs or power states
and then, based on the value of ERRORLEVEL, change the control flow of a script. For example:
for /L %%I in (1,1,%MAXBAYS%) DO (
%CLI% -show power-status -enclosureName %ENCLNAME% -bayname %%I
if ERRORLEVEL 240 (
echo There is no server in bay %%I
) else (
if ERRORLEVEL 1 (
echo Server in bay %%I is already on
) else (
echo Turning on server in bay %%I
%CLI% -poweron devicebay -enclosureName %ENCLNAME% -bayname %%I
if ERRORLEVEL 1 goto ERRORHANDLER
)
)
)
For more information, see “Error Messages” (page 82) or the Systems Insight Manager
documentation.
20 Using the VCEMCLI
3 Using VCEM commands
This chapter describes VCEMCLI commands.
add profile
The -add profile command creates a profile from the supplied description of a server profile.
Syntax
-add profile -profilename <profileName>
-vcdomaingroup <vcDomainGroupName>
[-mactypeoverride <true|false>]
[-wwntypeoverride <true|false>]
[-sntypeoverride <true|false>]
Parameters
Table 3 Parameter descriptions for -add profile
OptionalRequiredDescriptionParameter
-profilename
-vcdomaingroup
-mactypeoverride
-wwntypeoverride
-sntypeoverride
xSpecifies the unique name
of a newly created server
profile.
xSpecifies the name of the VC
domain group to which the
profile is added.
xUses factory-default MAC
addresses instead of
VCEM-provided settings for
Ethernet network connections
when creating the server
profile. Defaults to false.
xUses factory-default WWNs
instead of VCEM-provided
settings for FC SAN
connections when creating
the server profile. Defaults to
false.
xUses factory-default serial
numbers instead of
VCEM-provided settings
when creating the server
profile. Defaults to false.
Examples
• Create a new profile and add it to the domain, by using default connections and Virtual
Connect default serial numbers:
vcemcli -add profile -profilename MyNewProfile –vcdomaingroup Group1
• Create a new profile and use factory-default MACs for Ethernet connections:
vcemcli -add profile -profilename MyNewProfile2 –mactypeoverride true –vcdomaingroup Group1
Output
The function returns the result of the add operation or a jobid, if –nb is specified.
add profile 21
Minimum required role-based security
VCEM Group Administrator
Remarks
This command creates a new unassigned server profile.
VCEM fills empty attributes with a default value. VCEM generates a profile based on the value
settings associated with the -vcDomainGroup argument (it fills all the minimum required attributes
to create a profile with default values), and it overwrites some of the default values with the values
specified on the VCEMCLI command-line.
You can obtain the job status of non-blocking operations by executing the VCEMCLI with the –show
job command and providing the associated job ID. For more information, see “show job”
(page 74).
Server profile prerequisites
The server profile must have:
• Unique name within all VCEM managed profiles
• Target VC domain group where the server profile will reside
22 Using VCEM commands
set profile
The -set profile command modifies the properties on an existing server profile.
Syntax
-set profile -profilename <profileName>
[-name <NewName>] [-efistate absent]
Parameters
Table 4 Parameter descriptions for -set profile
OptionalRequiredDescriptionParameter
-profilename
profile you want to modify.
-name
the server profile.
-efistate
state information.
xSpecifies the name of the
xSpecifies the new name of
xSpecifies the presence of EFI
Output
The function returns the result of the set operation or a jobid if –nb is specified.
Examples
Rename a profile from MyProfile to YourProfile:
vcemcli -set profile -profilename MyProfile –name YourProfile
Minimum required role-based security
VCEM Group Operator
CAUTION: If the VCEMCLI is used in environments where logical server managers or upper-level
managers are present, updating a server profile can make it inconsistent with the upper-level
managers. HP recommends using the upper-level managers to update server profiles.
Remarks
You can obtain the job status for the jobid by executing the VCEMCLI with the –show job
command and providing the associated jobid. For more information, see “show job” (page 74).
set profile 23
assign profile
The -assign profile command assigns the profile identified by the ProfileName to the bay
specified by the BayName.
Syntax
-assign profile –ProfileName <profileName>
-enclosurename <enclosureName> -bayname <bayName> [-poweronbay]
Parameters
Table 5 Parameter descriptions for -assign profile
OptionalRequiredDescriptionParameter
-profilename
of the server profile to be
assigned.
-enclosurename
contains the bay to assign
the profile to.
-bayname
the server profile is assigned
to.
NOTE: To assign a profile
to a multi-blade server, the
enclosure name and bay
name must match those for
the primary bay.
-poweronbay
the profile has been
assigned.
xSpecifies the unique name
xSpecifies the enclosure that
xSpecifies the device bay that
xPowers on the server after
Output
The function returns the result of the assign operation or a jobid if –nb is specified.
Examples
• Assign a profile to device bay 1 of the enclosure:
vcemcli -assign profile -profilename MyProfile1 –enclosurename BigEnclosure –bayname 1
• Assign a profile to a multi-blade server in bays 5 to 8 of the enclosure:
NOTE: Note the use of bay 5 for a multi-blade server. A multi-blade server occupies more
than one slot in the enclosure. The operation fails if you specify any slot other than the slot
that the upper-left quadrant of the multi-blade server occupies.
vcemcli -assign profile –profilename MyProfile1 –enclosurename enc0 –bayname 5
Minimum required role-based security
VCEM Group Limited Operator
CAUTION: If the VCEMCLI is used in environments where logical server managers or upper-level
managers are present, assigning a server profile can make it inconsistent with the upper-level
managers. HP recommends using the upper level managers to assign server profiles.
24 Using VCEM commands
Remarks
You can obtain the job status of non-blocking operations by executing the VCEMCLI with the –show
job command and providing the associated jobid. For more information, see “show job”
(page 74).
The system page in HP Systems Insight Manager provides the enclosure name, as shown circled
in red in Figure 1 (page 25).
Figure 1 Enclosure name
The bay name is a string representation of the bay number. The first bay is “1”; the second bay
is “2”. For a double-dense blade, the bay for the 1a blade has the name of “1a”, whereas the
bay for the 1b blade has the name of “1b”. If an invalid enclosure name and bay name are
supplied to the VCEMCLI, an error is reported.
Prerequisites
The bay that the server profile is assigned to must meet the following criteria:
• A profile can be preassigned to an empty bay. If the bay contains a server and the power
state is on, it must be powered off before you initiate the profile operation. This can be
accomplished with a vcemcli -poweroff command executed prior to this operation.
• The requested bay must be associated with an enclosure.
• The requested bay must not have a server profile.
• The bay must belong to the same VC domain group where the server profile belongs.
• The bay is not an auxiliary bay. VCEM currently does not provide a method to detect auxiliary
or covered bays. A server profile cannot be assigned to an auxiliary or covered bay. The
VCEMCLI reports an error if an attempt is made to assign a server profile to an auxiliary or
covered bay.
For more information about hardware and firmware, see the HP Virtual Connect for c-Class
BladeSystem User Guide.
assign profile 25
export profiles
The -export profiles command exports server profiles to a CSV file for use with external
tools.
Syntax
-export profiles –exportfile <export filename>
Parameters
Table 6 Parameter descriptions for -export profiles
OptionalRequiredDescriptionParameter
-exportfile
to receive the exported
profile data in CSV format
xSpecifies the name of the file
Examples
vcemcli -export profiles -exportfile MyProfiles.csv
Minimum required role-based security
VCEM User
Remarks
None
26 Using VCEM commands
move profile
The -move profile command moves a server profile across VC domain groups.
Syntax
-move profile —profilename <profile name> [-tovcdg <VCDGName>] [-toenclosurename <EnclosureName> —tobayname
<BayName> [-validate]
Parameters
Table 7 Parameter descriptions for -move profile
OptionalRequiredDescriptionParameter
-profilename
-tovcdg
-toenclosurename
-tobayname
-validate
profile to be moved
Specifies the name of the
target VC domain group
Specifies the name of the
target enclosure
Specifies the name of the
target bay
moving the profile
xSpecifies the name of the
Required for moving across
domain groups
Required for moving within
a domain group
Required for moving within
a domain group
Optional for moving within
a domain group
Optional for moving across
domain groups
Optional for moving across
domain groups
xVerify preconditions before
Output
The function returns the results of the move operation or a jobid if –nb is specified.
Examples
• Move assigned profile profile_blue within VCD group:
vcemcli -move profile -profilename profile_blue -toenclosurename
hisenclosure -tobayname 3 -validate
• Move unassigned profile profile_blue to VCDG_blue (move across VCD groups):
vcemcli -move profile -profilename profile_blue -tovcdg VCGD_blue
• Move assigned profile profile_blue to VCDG_blue without specifying toenclosurename
and tobayname. The profile will be automatically unassigned (move across VCD groups):
vcemcli -move profile -profilename profile_blue -tovcdg VCGD_blue
• Move profile_blue to VCDG_red with -validate flag (move across VCD groups):
vcemcli -move profile -profilename profile_blue -tovcdg VCDG_red
-toenclosurename hisenclosure -tobayname 3 -validate
• Move profile_blue to VCDG_red (move across VCD groups):
vcemcli -move profile -profilename profile_blue -tovcdg VCDG_red
-toenclosurename hisenclosure -tobayname 3
Minimum required role-based security
VCEM Limited Group Operator
Remarks
You can obtain the job status for the jobid by executing the VCEMCLI with the –show job
command and providing the associated job ID. For more information, see “show job” (page 74).
move profile 27
When –validate is specified, the job is not triggered; only precondition validation is performed.
The CLI will return the results of the validation.
28 Using VCEM commands
remove profile
The -remove profile command removes a server profile from VCEM.
Syntax
-remove profile —profilename <profile name>
Parameters
Table 8 Parameter descriptions for -remove profile
OptionalRequiredDescriptionParameter
-profilename
profile to be removed
xSpecifies the name of the
Output
The function returns the results of the remove operation or a jobid if –nb is specified.
Examples
vcemcli -remove profile -profilename Server1Profile
Minimum required role-based security
VCEM Domain Group Administrator
Remarks
None
remove profile 29
unassign profile
The -unassign profile command unassigns the selected server profile.
Syntax
-unassign profile -profilename <profileName>
Parameters
Table 9 Parameter descriptions for -unassign profile
OptionalRequiredDescriptionParameter
-profilename
server profile that is currently
assigned to a device bay.
xSpecifies the name of a
Output
The function returns the result of the unassign operation or a jobid if –nb is specified.
Examples
Unassign a server profile from a device bay:
vcemcli -unassign profile -profilename MyProfile1
Minimum required role-based security
VCEM Group Limited Operator
CAUTION: If the VCEMCLI is used in environments where logical server managers or upper-level
managers are present, unassigning a server profile can make it inconsistent with the upper-level
managers. HP recommends using the upper-level managers to unassign server profiles.
Remarks
You can obtain the job status for the jobid by executing the VCEMCLI with the –show job
command and providing the associated job ID. For more information, see “show job” (page 74).
You can unassign server profiles whether or not a server is in the specified bay. If a server is in
the bay, the bay must be powered off before the -unassign profile command is issued.
Unassigned profiles belong to the VC domain group.
Prerequisites
• The profile must exist and be associated with a bay.
• If the bay contains a server, the bay must be powered off before the server profile is unassigned.
30 Using VCEM commands
Loading...