CLI commands

Edit online

IBM® Power® Virtualization Center offers a command line interface that rounds out the functions of the user interface, particularly in helping to troubleshoot problems.

To access the PowerVC commands, open a command line to the operating system on top of which PowerVC is installed.

Following are the commands and their descriptions. For instructions to use the command, open a command line and enter the command name followed by --help. For example, powervc-audit-export --help. Some commands output to a log file in the following location: /opt/ibm/powervc/log directory.

Table 1. PowerVC commands and descriptions
Command Description
powervc-audit-export Allows you to export previously collected audit data.
powervc-opsmgr backup Backs up essential PowerVC data so that you can restore to a working state in the event of data corruption or a disaster.

For details, see Backing up.
powervc-cloud-config Allows an administrator to work with projects, policies, and virtual machines. For example, you can use this command to create and change policies, or to change the owner of a virtual machine.
powervc-config Configures the PowerVC management server. Using this command is the only supported method for changing the PowerVC config files. For the list of available powervc-config subcommands, see Table 2.
powervc-diag Collects diagnostic data from your PowerVC installation.
powervc-encrypt Prompts the user for a string, then encrypts the string and returns it. Use the command to encrypt passwords, tokens, and strings that are stored by PowerVC.
powervc-opsmgr install Run -c <clustername> -s subcommand to install PowerVC operations manager utility.
openstack Facilitates communication with OpenStack services. This command was developed by the OpenStack community. PowerVC supports a subset of the full function of this command. For more information, see Table 3.
Notes:
  • The help for this command has not been translated.
  • These commands have been deprecated. Access the user interface to perform these functions.
powervc-log Enables or disables debug log level for PowerVC. Run this command without any option to view the current settings.

Use this command to enable debug level without having to restart services. This command helps in capturing detailed diagnostic information in logs without the risk of interruption to any ongoing operation.
powervc-log-management Enables you to view and modify the settings for log management for PowerVC. The default action is to view the current settings.
powervc-register Registers an OpenStack supported storage provider or fabric.
powervc-opsmgr restore Recovers PowerVC data that was previously backed up. This command is blocked when the powervc-services command is used to disable services.
powervc-opsmgr resync In a multinode environment, use this command to synchronize conf file between compute planes or between controller nodes.
Example format: powervc-opsmgr resync_node -s <source_host> -d <dest_host>
Example: powervc-opsmgr resync_node -s 9.x.x.x -d 9.x.x.x
powervc-resmgr Allows you to manage PowerVC resources such as instance snapshots, groups, group snapshots and resources associated with volume. Use this command to:
Cleanup resources that are failed or stuck in an intermittent state.
Display all the corresponding entities/resources associated with a resource.
Reset the status of given resource.
powervc-services Enables you to stop, start, restart, enable, or disable PowerVC services. Services must be enabled to run any CLI command that starts and restarts PowerVC services.
Note: By default, the effects of this command apply to the management server, network nodes, and any remote hosts. Use the --local option to impact the management server only.

Use powervc-services status to view results in a tabular format. To view results in older format, run powervc-services status --raw.

Use powervc-services restart --advanced to restart a component, a node, or a specific host (inventory_hostname). For example, powervc-services restart --advanced node command restarts all services on a node first. Next, the services are restarted on the other node.

Note: Starting PowerVC 2.1.1.1, powervc-services command displays additional statuses.
  • NoHeartbeat - This status indicates that the service is unable to communicate with the RabbitMQ service. If a service persists in this state for more than 15 minutes, check for any RabbitMQ communication issues.
  • NoResponse - This status is displayed for API services when the API does not respond within 15 seconds.
  • NotAvailable - This status is displayed for API services, when the API returns an error code.
powervc-opsmgr uninstall Uninstalls PowerVC OpsMgr from your management server or host.
powervc-validate Validates that your environment meets certain hardware and software requirements.
powervc-volume-image-import Creates a deployable image by using one or more volumes already hosted by the storage providers.
powervc-image This command has the following sub-commands:
powervc-image config - Displays or changes the command configuration properties.
powervc-image import - Imports an uncompressesed deployable image from OVA to PowerVC.
powervc-image export - Exports a deployable image from PowerVC to a local OVA.
powervc-image list - Lists the deployable images managed by PowerVC.
powervc-tape-reg

Use this command to register a Fibre Channel tape driver in PowerVC. This driver enables zoning of a tape library to a virtual machine that uses NPIV during deployment. Specify name and target WWPNS to configure a new cinder-volume service.

powervc-edit-scg Use this command to update the storage connectivity group that is assigned to a managed virtual machine (VM). If initiator port groups (IPG) are associated with the VM before unmanage of the VM, then use the --include-ipg flag to repopulate IPGs when setting the storage connectivity group for managed virtual machines.
powervc-ipg-info Use this command for additional IPG information for boot and data volumes that are attached to a virtual machine.
powervc-scale-config Applies scale tuning parameters to the management and NovaLink nodes. These settings are intended for high scale environment.
Note:
  • Supported for NovaLink and HMC on single node and multinode environments.
  • To apply the scale settings on a multinode environment, update the /etc/oslo/scale_multi_node.conf configuration file, then run the powervc-scale-config --apply command.
  • To apply the scale settings on a single node environment, update the /etc/oslo/scale_single_node.conf configuration file, then run the powervc-scale-config --apply command.
Some powervc-config subcommands might involve changes to configuration files and perform automatic service restart. For details about any of the following commands, run powervc-config subcommand child_subcommand -h.
Note:
  • Running powervc-config subcommands while any of the PowerVC operations are in progress might lead to temporary disruption of service availability.
  • Starting PowerVC 2.1.1, the powervc-scale-config --list subcommand displays values in a tabular format along with the Oslo_Conf Value and System_Conf Value columns. The Oslo_Conf Value is the scale configuration value and the System_Conf Value is the attribute value that is configured in the system.
Table 2. Supported powervc-config subcommands
Subcommand Child subcommand Description
event add-type Store the specified types of events. Separate multiple types with a space. For example: event_type1 event_type2.
audit Configure the audit settings for the event service. You can enable or disable auditing for each service, and can specify operations to ignore.
list-types List the event types that are being stored.
remove-type Remove the specified event types from the list of events that are being stored. Separate multiple types with a space. For example: event_type1 event_type2.
purge Use this command to remove all events and traits that are stored in the Panko database.
general audit Configure the audit settings for the general service.
identity token-expiration Configure the expiration interval for the identity token.
token-rotation Configure the fernet token key rotation interval.
repository Configure the repository for authentication credentials, for example an LDAP server.
image audit Configure the audit settings for the image service.
image-size-cap Configure the maximum image size that can be uploaded through the PowerVC management node.
user-storage-quota Configure the maximum amount of image storage that is allowed for a user.
storage audit Configure the audit settings for the storage service.
clone-name-prefix Sets the preferred clone name prefix for the clone volumes.
Usage:
powervc-config storage clone-name-prefix [-h] [--prefix Prefix]
[--restart]
ds8000 Sets certain IBM System Storage DS8000® Cinder and storage template configuration options.

--cg-lss - Range of logical subsytem IDs to be used with consistency groups and consistency snapshots. Example: LSS ID range 00-0F. A volume that is added to a consistency group is migrated to one of the LSSes in this range. Setting an LSS range for volume creation in a storage template is not recommended.
--storage-template <ID> --lss - List of logical subsystem IDs to be used by the storage template when creating volumes. Example: 00, 01.
--storage-template <ID> --pools - List of pool IDs to be used by the storage template when creating volumes. Example: P1, P2.
delete-check Configure the function to detect volumes that were possibly deleted outside of PowerVC.
fc-zone zone_by_stg_provider When enabled, creates a zone per storage provider for initiator and initiator-vfc modes.

For details, see Zoning per storage provider in PowerVC.
fc-zone zone-masking --blacklist Create a list of target (storage provider) WWPNs that will not be zoned with the source NPIV WWNs of a virtual machine. To populate the blacklist, add the WWPNs after the command. For example: powervc-config storage fc-zone zone-masking --blacklist twwpn1 twwpn3 twwpn4
fc-zone zone-masking --whitelist Create a list of target (storage provider) WWPNs that will be zoned. To populate the whitelist, add the WWPNs after the command. For example: powervc-config storage fc-zone zone-masking --whitelist twwpn1 twwpn3 twwpn4
fc-zone zone-name-prefix Set the prefix to be used when zone names are created.
fc-zone zone-name-template

Use this command to display or configure the zone-name-template setting for PowerVC. The zone-name-template is a string that specifies how to name new zones. It contains static text and dynamic replacement variables that represent pieces of information that will be inserted into zone names created for NPIV volume attachments. Some example replacement variables are virtual machine name, initiator WWPN, and storage host name.

Example: powervc-config storage fc-zone zone-name-template -t "powervc_%(vm_name)s_%(initiator_wwpn)s_%(storage_hostname)s" --restart

Run powervc-config storage fc-zone zone-name-template -h to determine the valid values.
fc-zone zone-one-target When this is enabled, only one target is used per initiator for zone creation. When zone-one-target is disabled, all targets are used when creating a zone. The default value is true.
Note: This property is not used with IBM Storwize® controllers. For Storwize controllers, the extra spec property drivers:multipath determines whether all of the targets should be zoned or if one target from each node in an IO group should be zoned.
hitachi group-name-format Sets the naming format to be used while creating the Hitachi HostGroup name in the backend. Default value: HBSD-{wwn}.
Note: This command is only applicable for volumes which are attached using NPIV.
hitachi array-ports Configure the specified Hitachi provider with the listed Hitachi array ports.
hitachi thin-pool Set the Hitachi controller pool to be used with cascade thin image clones and snapshots. This command is deprecated. Access the user interface to perform this function.
hitachi-thinpool Set the Hitachi controller pool to be used with cascade thin image clones and snapshots. This command is deprecated. Use hitachi thin-pool instead.
host-name-format

Set the template for short host name customization for PowerMax storage provider.
onboard-voltype Configure the Volume Type for a storage provider that was added to PowerVC. This command is deprecated. Use powervc-config storage set-template instead.
portgroup Configure the EMC VMAX candidate port group list, including auto-configuration options. This command is deprecated.
portgroup-format Set the template for port group customization for PowerMax storage providers.
replication Enables a VMAX storage provider to make use of an SRDF replication group. This command is deprecated.
set-template Sets the storage template for a volume. When existing volumes are managed, they do not have storage templates associated with them. This creates problems with any functions, such as consistency groups, that require a storage template.
storwize Sets the PowerVC Cinder configuration for IBM Storwize devices. For a given Storwize provider, use these arguments.
  • use-one-iogrp - Consolidate a virtual machine's volumes to a single IO group.
  • flashcopy-rate - Configure the flashcopy rate.
  • clean-rate - Configure the clean-rate.
  • ratelimit - Configure the rate-limit.
  • volume_pool - Configure the volume pool.
  • snapshot_child_pools - Configure the snapshot child pools.
snapshot-usage View or configure the intervals for snapshot usage.
timeouts Configure storage timeout and interval settings.
vol-name-format

Use this command to display or configure the volume name template for PowerVC. This template specifies how to name new volumes. It contains static text and dynamic replacement variables that represent pieces of information that will be inserted into volume names.

Run vol-name-format -h to determine the valid values.
zone-name-prefix Specifies the prefix to use when PowerVC creates zones. This command is deprecated. Use fc-zone zone-name-prefix instead.
backup-service swift Enables cinder swift backup driver with the specified authentication properties in single user mode for remote and local backup node. Use --backup-node to specify the backup node which needs to be configured. Use --help option to see the details of the properties which can be configured. Only Keystone v3 auth system is supported. .
backup-service posix Enables default POSIX as a backup service for remote and local backup node. Use --backup-node to specify the backup node that needs to be configured. Use --help option to see the details of the properties which can be configured.
svc-retain-aux-vol Modifies the default behavior of deletion of volumes on secondary storage when retype or delete of global mirror volume is performed.
cisco_wait_retry Sets the Cisco fabric retry time out. The calls to the Cisco switches are retried with exponential increasing intervals for the time specified in this configuration.
purestorage snapshot-interval Sets the PowerVC cinder configuration for replication enabled Pure Storage devices. This argument configures the snapshot replication interval in seconds for Pure Storage provider.
purestorage snapshot-retention-short Sets the PowerVC cinder configuration for replication enabled Pure Storage devices. This argument configures the snapshot retention time on target in seconds for Pure Storage provider.
purestorage snapshot-retention-perday Sets the PowerVC cinder configuration for replication enabled Pure Storage devices. This argument configures the number of snapshots to be retained in a day for Pure Storage provider.
purestorage snapshot-retention-long Sets the PowerVC cinder configuration for replication enabled Pure Storage devices. This argument configures the number of days the snapshots can be retained on the target per day for Pure Storage provider.
network audit Configure the audit settings for the network service.
tunneling-ip Display or set the tunneling IP address. This address can communicate directly with the nova-compute processes.
compute allow-dup-net Configure ability to create duplicate VLAN networks.
arr-host-maint Configure whether a host is put into maintenance mode after automated remote restart.
audit Configure the audit settings for the compute service.
auto-pvmvlan-clnup If this is enabled, PowerVC removes the VLAN after migrating a virtual machine. If you use the -host parameter to specify a host name, the action applies to only that host. If you do not specify a host, the action applies to all registered hosts.
fabric-sync Use this command to change the fabric sync interval (in minutes). After this interval has elapsed, the next time that the PowerVM® host reconciles its topology information in the environment with topology information in the database, it connects to all the registered fabrics and determines which host ports are logged into which fabrics. This happens for each registered host.

This synchronization activity happens automatically whenever a new fabric is managed or unmanaged. But in case Fibre Channel physical cabling changes and PowerVC is unaware of that, this synchronization interval ensures that PowerVC updates its information so that virtual machine deployments are accurately scheduled to hosts that meet the storage connectivity group requirements.

The default fabric synchronization interval is 120 minutes plus a random number of minutes between 0 and 30. The random additional minutes prevents all of the compute hosts from contacting the Fibre Channel fabrics at the same time and overloading them with queries.

reset-instance-task-state Forcefully reset the task state of a virtual machine, if it is stuck in an intermittent state for a longer period of time.
Example format:
powervc-config compute reset-instance-task-state --instance_id <vm_uuid1, vm_uuid2, etc.>
live-capture Set the ability to capture a running virtual machine.
maint-migr-timeout Configure the timeout value for virtual machine migrations when the host enters maintenance mode. If any virtual machine's migration takes longer than this value, the host goes into maintenance error state.
mover-service-par Use this command to configure the comma separated list of VIOS IP addresses to use as the mover service partitions for live partition migration.

If you have more than one network adapter on your VIOS and want migrations to run on the faster network, set the value to the IP address of the faster network. For multiple VIOS environments, you can list MSP IP's of all VIOSes and two will randomly be chosen for redundant MSP during the live partition migration operation.
avoid-msp-validation Use this command to avoid validation of MSP IP's configured by using mover-service-par command.
server-domain Display or set the default virtual machine domain name.
vfc-over-commit Configure whether to over-commit allocation of NPIV ports.
storage_hostname_template Use this command to customize hostname on the backend storage during NPIV virtual machine deployment. This command is applicable for SVC storage type.

The storage_hostname_template can have prefix, suffix, host where the virtual machine is deployed and the vm_display_name which is used for the virtual machine name. The prefix and suffix are optional but you must provide either host or vm_display_name.

Given below is an example to set storage_hostname_template:

powervc-config compute storage_hostname_template --host V7R2_20 --set "powervc_%(host)s_%(vm_display_name)s_<storagetype>" --restart
By default, the truncation length for hostname and vm_display_name is 20 characters each.
  • If the hostname is thisIsAPowerVCHostAndItHasALongLength, PowerVC truncates the hostname to thisIsAPowerVCHostAn.
  • If vm_display_name is thisIsAPowerVCVMDisplayNameAndItHasALongLength, PowerVC truncates the name to thisIsAPowerVCVMDisp.

However, you can also specify the custom truncation length in PowerVC CLI. For details, run powervc-config compute storage_hostname_template --help.
use_vios_from_scg_for_sriov_vnic Configures a new property in the default section of the nova conf file enabling VIOS selection based on instance SCG to create vNIC server during SR-IOV deployments.

Example:

# powervc-config compute use_vios_from_scg_for_sriov_vnic --enable/--disable --host HOSTNAME --restart
metering list-meters Display PowerVC supported meters. Use --enabled to get enabled meters.
enable-meters Add new meters and collect their data (metrics).
disable-meters Stop specific metric collection by disabling the corresponding meters.
web inactivity-timeout How long the user interface can sit idle before the user is prompted and logged out. Specify 0 or less to disable the timer.
reauth-warn-time How long before token expiration to prompt the user for the password. Inputting the password obtains a new token. Specify 0 or less to disable the timer.
self-service audit Configure the audit settings for the self-service service.
validation audit Configure the audit settings for the validation service.
Table 3. Supported openstack subcommands
Command Description
openstack token issue Issues a new token.
openstack token revoke Revokes an existing token.
openstack port list Lists ports.
openstack port delete Deletes ports.