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 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 of the commands write the output to a log file that is at /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 it to a working state if there is a 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 for a string. Once the string is provided, this command encrypts the string and returns it. Use the command to encrypt passwords, tokens, and strings that are stored by PowerVC.
powervc-fabric-mgr Display and perform operations on fabrics from PowerVC for a particular virtual machine . The powervc-fabric-mgr command has the following sub commands:
Note: The powervc-fabric-mgr command is applicable only for IBM Flashsystem Storage controllers.
zone-show
Syntax
zone-show --instance_id InstanceID [ --fabric_key FabricKey ]
Description
Display switch zones and zone member information of a VM. The InstanceID provides the ID of the VM. The FabricKey provides the fabric key for which you want to get the zone information. If the FabricKey is not provided, zone information for all the fabrics is displayed for the specified VM.
zone-add
Syntax
zone-add --instance_id <InstanceID> --storage_host <StorageHostID> [ --fabric_key FabricKey ]
Description
Adds corresponding virtual ports to a VM. The InstanceID provides the ID of the VM. The StorageHostID provides the storage hostname of the volume that is attached to the VM. You can restrict the add operation to a specific fabric by using the --fabric_key FabricKey option.
zone-remove
Syntax
zone-remove --instance_id <InstanceID> --storage_host <StorageHostID> [ --fabric_key FabricKey ] --physical
Description
Removes physical ports of a VM. The InstanceID provides the ID of the VM. The StorageHostID provides the storage host name of the volume that is attached to the VM. You can restrict the remove operation to a specific fabric by using the --fabric_key FabricKey option. The --physical option indicates that all the physical ports attached to the specified VM must be removed. The --physical option is mandatory for the zone-remove command.
powervc-opsmgr install Run -c <clustername> -s subcommand to install PowerVC operations manager utility.
openstack Facilitates communication with OpenStack services. The OpenStack community has developed this command. PowerVC supports a subset of the full function of this command. For more information, see Table 3.
Notes:
  • The help for this command is not translated.
  • These commands are 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.
Use the following format for this command:
powervc-opsmgr resync_node -s <source_host> -d <dest_host>
For 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 perform the following operations:
  • Cleanup resources that are failed or stuck in an intermittent state.
  • Display all the corresponding entities or resources that are associated with a resource.
  • Reset the status of a specified resource.
powervc-services Allows 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.

Notes:
  • Starting with PowerVC 2.1.1.1, powervc-services command displays the following additional statuses:
    • NoHeartbeat - 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 - Displayed for API services when the API does not respond within 15 seconds.
    • NotAvailable - Displayed for API services, when the API returns an error code.
  • Starting with PowerVC 2.3.1, powervc-services command displays the following additional statuses:
    • PublishFailed - Indicates that the service is unable to publish the data to its designated publisher.
    • NoEvents - Indicates that the service is unable to receive any events from bumblebee. The data that is shown in the UI might not be the latest.
  • Starting with PowerVC 2.3.1, the output of the clustercheck command of the galera cluster is integrated with the powervc-services status. In the powervc-services status, the galera cluster check details are listed under the galera-cluster-check field. The following values are the valid values for the galera-cluster-check field:
    • Synced- Indicates that the galera cluster is in sync across all nodes.
    • OutOfSync- Indicates that the galera cluster is not in sync across all nodes.
    • ReadOnly- Specifies that the galera cluster node is in read-only mode. The read-only mode means that the galera cluster does not allow writes but responds to read queries.
  • Starting with PowerVC 2.3.1, the output of the cluster_status command of the rabbitmqctl cluster is integrated with the powervc-services status. In the powervc-services status, the rabbitmqctl cluster check details are listed under the rabbitmq-cluster-status field. The following values are the valid values for the grabbitmq-cluster-status field:
    • Healthy- Indicates that the rabbitmqctl cluster across all nodes is in a healthy state.
    • Degraded- Indicates that the rabbitmqctl cluster is not healthy.
  • Starting with PowerVC 2.3.2, powervc-services command displays the following additional status:
    • NotEnabled- Indicates that the service is not enabled.
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 that are already hosted by the storage providers.
powervc-image This command has the following subcommands:
powervc-image config - Displays or changes the command configuration properties.
powervc-image import - Imports a decompressed 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 that are 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 the 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 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 you set 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.

Starting with PowerVC 2.3.1, the set parameter is introduced to update the maximum memory value in the specified service or configuration file. The following syntax is used to update the maximum memory value in a service file:
powervc-scale-config --set nova-compute-svc MemoryMax=memory_value [ host=host_mtms ] [ restart=true ]

The nova-compute-svc parameter is a command that updates the maximum memory value for the host that can be allocated for the nova compute process in a service or configuration file. The MemoryMax parameter is used to specify the maximum memory value for the host. The maximum memory field in the service file is updated with the value specified by the MemoryMax parameter. The MemoryMax value must be specified in Gigabyte (G), Megabyte (M), or Kilobyte (K). You can also update the MemoryMax value for a specific host by using the host parameter. The host parameter takes the host key value to identify a specific host. The MemoryMax value of only one host must be updated at a time. If you want to restart the service file that is updated, specify the restart=true parameter. The host and restart parameters are optional.

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.
  • To ensure that the scale settings are correctly applied to all the managed hosts, register all the NovaLink hosts before you run the scale configuration command.
  • If you add a NovaLink host after the powervc-scale-config --apply command completes successfully, run the powervc-scale-config --apply command again to apply the updated configuration to the newly added NovaLink host.
powervc-update-scg-ipg Use this command to add or remove host in the storage connectivity group (SCG), which is associated with the IPG. Use the subcommand update-fc-ports-on-ipg to update the FC-Ports for new hosts to respective IPGs. For example: 
powervc-update-scg-ipg -n <SCG-name> update-fc-ports-on-ipg --ipg-name <IPG-name> --fc-ports '1000000X1,100000X2,10000X3'
powervc-health-check Use this command to perform pre health check of the system before you run any of the opsmgr operations.
The powervc-health-check command has the following subcommands:
  • powervc-health-check install -c <cluster-name>: Health check command of the install operation.
  • powervc-health-check update -c <cluster-name>: Health check command of the update operation.
  • powervc-health-check restore -c <cluster-name> -b <backup-archieve-path>: Health check command of the restore operation.
  • powervc-health-check backup -c <cluster-name>: Health check command of the backup operation.
  • powervc-health-check addnode -c <cluster-name> -u <username-of-new-vm> -i <ip-address-of-new-vm> -p: Health check command of the addnode operation.
Note: You can use the -fc flag with all the commands to run health check only for the failed checks. For example, powervc-health-check install -c <cluster-name> -fc
Run the following pre-setup opsmgr health check command before you perform the setup opsmgr operation:
For RHEL
/usr/libexec/platform-python powervc_opsmgr_health_check.py
For SLES
python3 powervc_opsmgr_health_check.py
Run the following pre-update opsmgr health check command before you perform the update opsmgr operation:
python3 powervc_opsmgr_health_check.py
Run the respective health check command before you perform any opsmgr operation. For example, run the health check command of the install operation before you perform the install operation:
powervc-health-check install -c <cluster-name>

The health check results are classified into three types Pass, Warning, and Error. The health check result is Pass when the health check succeeds. If the health check result is Warning, cross verify whether there is a serious issue or not. If the health check result is Error, the respective operation cannot be performed until the issue is fixed and health check is run again.

Notes:
  • All the health checks are mandatory except the health check for addnode operation.
  • In some rare scenarios where sudo binary is not present and the inventory user is a non-root user who can act as a privileged user, edit the /opt/ibm/powervc-opsmgr/health_checks/checks_config.yaml file and change the check_sudo field value to false.
  • If some commands like the powervc-services status command take more time to run, set the PVC_CHECK_TIMEOUT environment variable that sets the maximum wait time for the command to complete. For example, the export PVC_CHECK_TIMEOUT="300" sets the maximum wait time to 300 seconds.
  • Run the corresponding health check command for every instance of any opsmgr operation. For example, to take a backup you must run the powervc-health-check backup -c <cluster-name> command followed by the powervc-opsmgr backup -c <cluster-name> command. You must run the backup health check command again before initiating a subsequent backup operation, regardless of the success of the previous backup operation.
powervc-dbcheck Allows you to perform the following tasks:
  • Recover volumes or virtual machines if they are in transient states.
  • Discover inconsistencies related to database, network ports, and placement allocations.
For more information on the powervc-dbcheck command, see the powervc-dbcheck Utility page.
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 subsystem IDs to be used with consistency groups and consistency snapshots. For example, logical subsystem (LSS) ID range 00-0F. A volume that is added to a consistency group is migrated to one of the LSSs 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 volumes are created. For example, 00, 01.
--storage-template <ID> --pools - List of pool IDs to be used by the storage template when volumes are created. For 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 are not zoned with the source NPIV WWNs of a virtual machine. To populate the list, 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 are zoned. To populate the list, 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 is inserted into zone names that are created for NPIV volume attachments. Some example replacement variables are virtual machine name, initiator WWPN, and storage hostname.

For example, powervc-config storage fc-zone zone-name-template -t "powervc_%(vm_name)20s_%(initiator_wwpn)s_%(storage_hostname)10s" --restart

Run powervc-config storage fc-zone zone-name-template -h to determine the valid values.

Note: If the zone-name -template has storage_display_name parameters, it is not truncated. Also, if the overall zone name length exceeds 64 characters, the zone creation fails.
fc-zone zone-one-target When this subcommand is enabled, only one target is used per initiator for zone creation. When zone-one-target is disabled, all targets are used when a zone is created. 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 the targets must be zoned or if one target from each node in an IO group must be zoned.
hitachi group-name-format Sets the naming format to be used you create the Hitachi HostGroup name in the backend. The default value is HBSD-{wwn}.
Note: This command is only applicable for volumes that are attached by 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 hostname 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 the following command instead:
powervc-config storage set-template
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 use 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 the storage templates that are associated with them. This issue 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 is 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 a 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 that needs to be configured. Use --help option to see the details of the properties that can be configured. Only the 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 that can be configured.
svc-retain-aux-vol Modifies the default behavior of deletion of volumes on auxiliary 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 that is 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 the ability to create duplicate VLAN networks.
arr-host-maint Configure whether a host is put into maintenance mode after an automated remote restart.
audit Configure the audit settings for the compute service.
auto-pvmvlan-clnup If this subcommand is enabled, PowerVC removes the VLAN after a virtual machine is migrated. If you use the -host parameter to specify a hostname, 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 the interval elapses, 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 in to which fabrics. This activity 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 this change, 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 prevent all 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.
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 a 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 IPs of all VIOSs and two are randomly chosen for redundant MSP during the live partition migration operation.
avoid-msp-validation Use this command to avoid validation of MSP IPs 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 the 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.

For example, to set storage_hostname_template, enter the following command:

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 the 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.

For 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.
sync resource Synchronizes the user interface (UI) data with the PowerVC back-end. The optional resource variable specifies the name of the resource that must be synchronized. The following resources are the valid resources:
  • vm
  • host
  • hmc
  • volume
  • image
  • network
  • log
  • snapshots
  • storageProvider

You can specify multiple resources that are separated by comma without any space. For example, powervc-config web sync vm,volume,network. If the resources are not specified, all the resources are synchronized.
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 To issue a new token.
openstack token revoke To revoke an existing token.
openstack port list To list ports.
openstack port delete To delete ports.