PowerVM NovaLink command-line interface

When PowerVM NovaLink is at version 1.0.0.16 or later, you can specify the license key of IBM® i logical partitions by entering the following command:

/usr/bin/chlickey -p <system name> -o a --lickey "<license key>"

Comma-separated list of license keys and input file (--lickey file) options are available for PowerVM NovaLink version 1.0.0.16, or later.

chlickey -p lpar | --id id -o a (--lickey <comma separated list of licensekey.> | --lickeyfile <input file> )

Where

• -p <system name> indicates the logical partition or the server.
• -o indicates the type of the operation to be performed.
• a indicates that the license information must be added to the license repository.
• --lickey <license key> specifies a single key or comma-separated list of license keys that are 101 bytes long, which is applicable for an IBM i virtual machine.
• --lickey <inputfile> specifies the file that contains the license keys for an IBM i virtual machine. The license keys are listed as comma-separated list of keys, which are 101 bytes long.

The following example shows the format of a 101-byte long license key and an example license key:

Format for 101 byte key:
keyFileTimeStamp(13) + systemName(8) + productId + licenseTerm + feature + serial + processorGroup + usageLimit + expirationDate + vendorData + licenseKey + keyGenTimeStamp(13)
If any value unknown, default must be used as :
keyFileTimeStamp = "0000000000000";
systemName = "        ";
serial = "  *LOCAL";
processorGroup = "999";
expirationDate = "9999999";
vendorData = "        ";
keyGenTimeStamp = "0000000000000";
More details on default and fillers as below:
Valid attribute names:( From HMC usage)
prdid
lictrm
Specify in Vx, VxRy, or VxRyMz format, where x and y can be a number from 0 through 9, and z can be a
number from 0 through 9 or a letter from A through Z
feature
[serial]
Defaults to *LOCAL
[prcgrp]
Specify in Pxx format where xx is a number from 00 to
99
Defaults to 999
usglmt
Specify *NOMAX for no limit
[expdate]
Specify in 1YYMMDD format
Defaults to 9999999 which correlates to *NONE
[vnddta]
Defaults to blank which correlates to *NONE
lickey

An example license key is as follows:

1210222210611RCHASC025770SS1V7R4M05117 7800050999  -11220223   DD0829B7E5E2A6B5011210222210611

Run the pvmctl command only if you are in the pvm_admin group. To add a user to the pvm_admin group, enter the following command:

sudo useradd -G pvm_admin -m -p `openssl passwd -1 neo123`  neo

If you are using PowerVM NovaLink version 2.2.0, or later, use the health monitor system (hms) option in the pvmctl command to check the health of the PowerVM NovaLink system. The hms option displays the following information:

• MEMORY CONSUMPTION: The PowerVM NovaLink system uses memory to ensure that sufficient memory is available for PowerVM NovaLink operations.
• To view whether sufficient file handles are available for PowerVM NovaLink operations, provide the following details:
  • FILES OPENED: The file handles that are open.
  • SSH FILES OPENED: The file handles that are open due to the Secure Shell Protocol (SSH) process.
  • PIPE FILES OPENED: The file handles that are open due to the pipe operation created in PowerVM NovaLink system.
• Status of the connection between pvm-rest and pypowervm subsystems, which provides the REST APIs that are compatible with OpenStack APIs.

To check the health of PowerVM NovaLink system, enter the pvmctl hms list command or pvmctl healthmonitor list command.

$ pvmctl hms list
Health Monitor
+--------------------+--------------+------------------+-------------------+-------------+
| MEMORY CONSUMPTION | FILES OPENED | SSH FILES OPENED | PIPE FILES OPENED | REST STATUS |
+--------------------+--------------+------------------+-------------------+-------------+
| 135.0270980983228  |   85.9375    |       0.0        |        0.0        |    Passed   |
+--------------------+--------------+------------------+-------------------+-------------+
$

To display the help menu of the health monitor system (hms), enter the help command as follows:

$ pvmctl hms --help
usage: pvmctl hms [help | --help] 
positional arguments:
  {list}
optional arguments:
 {--verbose}
help arguments:
  help    show this help message and exit
$

When you run the --verbose command, you can view detailed information of the following resources:

Use the PowerVM NovaLink version 2.2.0, or later, to activate an IBM i network installation. The supported adapters are as follows:

• POWER8 processor-based servers, or later, that support Network File System (NFS)-based installation.
• POWER9 processor-based servers, or later, that support Internet Small Computer Serial Interface (iSCSI)-based installation.

To initiate the IBM i network installation, enter the following command:

pvmctl vm network-install --help
usage: pvmctl [help | --help] LogicalPartition network-install {--object-id | -i} <LogicalPartition field>=value {args}

The following table lists the required arguments for the IBM i network installation:

Required argument	Description
--type {nfs,iscsi}	Specifies the network installation type.
--ip IP	Specifies the IP address of the client partition.
--gateway GATEWAY	Specifies the gateway address of the client partition.
--netmask NETMASK	Specifies the netmask address of the client partition. If the IP address format is mentioned as IPV6, this argument is not allowed.
--serverip SERVERIP	Specifies the IP address of the NFS server when nfs is the network installation type.
--serverdir SERVERDIR	Specifies the image path on the NFS server when nfs is the network installation type.
--targetip TARGETIP	Specifies the IP address of the iSCSI target when iscsi is the network installation type.
--targetname TARGETNAME	Specifies the iSCSI target name when iscsi is the network installation type.

The following table lists the optional arguments for the IBM i network installation:

Optional argument	Description
--duplex {auto,half,full}	Specifies the duplex for the network interface.
--mtu {1500,9000}	Specifies the maximum transmission unit for the network interface.
--speed {auto,1,10,100,1000}	Specifies the speed settings for the network interface.
--vlan VLAN	Specifies the VLAN ID.
--initiatorname INITIATORNAME	Specifies the iSCSI initiator name when iscsi is the network installation type.
--chapname CHAPNAME	Specifies the Challenge-Handshake Authentication Protocol (CHAP) name when iscsi is the network installation type.
--chapsecret CHAPSECRET	Specifies the CHAP secret when iscsi is the network installation type.
--targetport TARGETPORT	Specifies the iSCSI target port.

To query for an object type, use the --object-id id=value, -i id=value identifier argument and specify the object type as a name=value pair. For example,

--object-id name=value

The PowerVM NovaLink CLI supports the following object types. You can use either the full object type or the indicated short names for each object type.

• Cluster
• IOSlot (io)
• LogicalPartition (lpar or vm)
• LogicalUnit (lu)
• LogicalVolume (lv)
• ManagedSystem (sys)
• LogicalPartition (lpar or vm)
• NetworkBridge (nbr, bridge, sea, sharedethernetadapter)
• PhysicalVolume (pv)
• SharedProcessorPoool(sharedprocpool, spp)
• VirtualIOServer (vios)
• SharedStoragePool (ssp)
• SRIOVadapter (sriov)
• sriovethernetlogicalport (ethlogicalport, ethlp)
• SharedEthernetAdapter (sea)
• VirtualEthernetAdapter (vea or eth)
• VirtualFibreChannelMapping (vfc or vfcmapping)
• VirtualMediaRepository (vmr or repo)
• VirtualNICdedicated (vnic)
• VirtualNetwork (vnet or net)
• VirtualOpticalMedia (vom or media)
• VirtualSCSIMapping (scsi or scsimapping)
• VirtualSwitch (vswitch or vsw)
• Volumegroup (vg)
• virtualserialnumber (vsn)
• persistentmemorydevice (pmemd)
• persistentmemoryvolume (pmemv)

pvmctl [--version] [object] [operation] [arguments...] [help | --help]

For example, to list the logical partitions on the managed system, enter the following command:

pvmctl LogicalPartition list

To list all Virtual I/O Server names, IDs, states, and their associated I/O Adapter device names, use the --display-fields (or -d) argument:

pvmctl vios list -d name id state IOAdapter.dev_name

To list the names, IDs, states, and associated I/O Adapter device names of all Virtual I/O Servers that are not running, use the --where argument to add the condition to the command:

pvmctl vios list -d name id state IOAdapter.dev_name --where VirtualIOServer.state!=running

To list a network bridge with a port VLAN ID of 10, use the --object-id (or -i) argument:

pvmctl bridge list --object-id pvid=10

To update the required memory of a logical partition with name mylpar to 512 MB, use the --set-fields argument:

pvmctl lpar update -i name=mylpar --set-fields PartitionMemoryConfiguration.desired=512 

To delete a virtual Ethernet adapter, specify its parent identifier with the --parent-id (or -p) argument:

pvmctl vea delete -i pvid=1 --parent-id name=lpar_name

The following command creates an AIX®/Linux logical partition that is named new_lpar with one dedicated processor and 512 MB of memory:

pvmctl lpar create --name new_lpar --proc 1 --proc-type dedicated 
--sharing-mode normal --type AIX/Linux --mem 512

To display the help menu of the VSN, enter the following command:

[neo@MyCec ~]$ pvmctl vsn
usage: pvmctl virtualserialnumber [help] <operation> [help] [<args>]
Supported operations:
list     List information about Virtual Serial Numbers.
delete   Delete VSN from the system.
transfer Transfer VSN to other managed system.
Object type aliases:
virtualserialnumber
vsn

To list the virtual serial number on the managed system, enter the following command:

[neo@MyCec ~]$ pvmctl vsn list
Virtual Serial Numbers
+---------+---------+-------------+
|   VSN   | LPAR ID | AUTO ASSIGN |
+---------+---------+-------------+
| VSHJKSZ |    -    |     True    |
| VSHJKZY |    22   |    False    |
+---------+---------+-------------+

To delete the VSN from managed systems, enter the following command:

pvmctl vsn delete -i name=<virtual serial number>

To transfer the VSN to other managed systems, enter the following command:

pvmctl vsn  transfer --mgmt-svr <server ip>  -i id=<virtual serial number> --mgmt-usr <userid> --sys <target sys name>

To list the trusted system key information for a managed system, enter the following command:

# lstskey
key_length=32,key_status=default_key
#

To view the help information for changing the trusted system key information for a managed system, enter the following command:

# chtskey
Usage: chtskey -m <managed system>
               -o change | restore
               --newkey <key file>
               [--oldkey <key file>]
               [--force]
               [--help]
Changes the trusted system key for a managed system.
    -m <managed system> - the managed system's name
    -o                  - the operation to perform:
                            change  - set the key and re-encrpyt virtual
                                      Trusted Platform Module (vTPM) data
                            restore - set the key without re-encrpyting vTPM
                                      data
    --newkey <key file> - binary file that contains the new key
    --oldkey <key file> - binary file that contains the current key
    --force             - force a change when previous change operation is
                          still re-encrypting vTPM data
    --help              - prints this help.
#

To list the persistent memory devices that are associated with a logical partition, enter the following command:

 pvmctl pmemd list

To list the persistent memory volumes that are assigned to a logical partition, enter the following command:

pvmctl pmemv list

To create a persistent memory volume, enter the following command:

 pvmctl pmemv create --name volume_name --size volume_size --lpar_id associated_lpar_id

To delete a persistent memory volume, enter the following command:

pvmctl pmemv delete -i name=volume_name

For example, to open a virtual terminal connection to a partition with partition ID 3, enter the following command:

mkvterm --id 3

For example, to backup the partition configuration to the /tmp/mybackup.bak file, enter the following command:

bkprofdata -o backup -f /tmp/mybackup.bak

To restore the partition configuration data from the /tmp/mybackup.bak file by using phase 2 restoration, enter the following command:

rstprofdata -l 2 -f /tmp/mybackup.bak

For example, to run the lsmap -all command on the Virtual I/O Server with partition ID 2, enter the following command:

viosvrcmd --id 2 -c "lsmap -all"