hpvmmodify(1M)

NAME

hpvmmodify — Rename a virtual machine or modify the attributes of a virtual machine.

SYNOPSIS

hpvmmodify { -P vm-name -p vm-number } [ -F -s ] [-N new-vm-name]
[-l vm-label] [-B start-attr] [-O os-type [:version]]
[-c number-vcpus | -c number-vcpus:minimum:maximum]
[ -e percent[:maximum_percent] | -E cycles[:maximum_cycles] ] [-r amount]
[-g -group]... [-g -group [+]group[: {adminoper}]]...
[-u -user] [-u [+]user[: {adminoper}]]
[-a rsrc] [-m rsrc] [-d rsrc] [-i { SG SG-pkgname GWLM SG-pkgname , GWLM NONE }] [-j {0|1} ]...
[-r amount [-x name=value [:name=value]]]

hpvmmodify -A { -P vm-name -p vm-number } [-F] [-l vm-label] [-B start-attr] [ -e percent -E cycles [-a rsrc]... [-m rsrc]... [-d rsrc] ]
[[-x name=value [:name=value]]]

hpvmmodify -P guest -m rsrc

DESCRIPTION

The hpvmmodify command modifies the attributes and resources of the specified virtual machine.

All attributes and resources can be changed statically, so that changes take effect when the virtual machine is next restarted.

Some attributes and resources can also be changed dynamically. Dynamic changes take effect immediately and remain in effect when the virtual machine is next started, unless you explicitly specify otherwise with the -A option.

Only specified attributes or resources are changed. All others retain their original values.

Virtual machine modification is designed for flexibility and assumes that all existing virtual machines are not necessarily running at the same time or on the current VM Host. Therefore, the hpvmmodify command allows virtual machines to be modified in such a way that they cannot boot on the current system. A guest configuration receives a warning at modification and an error at start time, for any issues that might prevent it from starting on the current VM Host. To verify a particular configuration for the current VM Host without actually modifying the guest, use the -s option.

When a new device is added to a guest without specifying the bus/target/lun in the resource parameter, a default order of bus/target/lun allocation is followed. This ordering fills 0-14 targets on the lowest numbered bus before proceeding to the next higher-numbered bus. This default ordering is the same for both AVIO and VIO guest adapters.




	NOTE: Targets higher than 14 are supported only on AVIO adapters.

Only a superuser can execute the hpvmmodify command.

Options

The hpvmmodify command recognizes the following command-line options and arguments.

-P vm-name

Specifies the name of the virtual machine to be modified.

You must specify either the -P or the -p option.

-p vm-number

Specifies the number of the virtual machine to be modified. The vm-number is displayed by the hpvmstatus command.

You must specify either the -P or the -p option.

-A

Specifies that the addition, modification, or deletion of resources is done to an active virtual machine's configuration file. These modifications will be effective until the virtual machine is rebooted. Not all modifications can be done to an active virtual machine; in this case, an error message indicates the changes that require the virtual machine to be rebooted.

-e percent[:maximum_percent]

Specifies the percentage of CPU resources to which each of the guest's virtual CPUs is entitled and optionally specific the maximum percent or entitlement cap. The default cap is 100%.

During peak system CPU load, the entitlement is the guaranteed minimum allocation of CPU resources for this virtual machine.

The percent can be set to an integral value between 0 and 100. If the value specified is less than 5, the virtual machine will be allocated the minimum percentage of 5%. The default is 10%.

The maximum entitlement may not exceed 100 percent, and may not be less than the minimum. Each group has a default maximum setting of 100 percent.

In addition to the guest calculation, Integrity VM reserves processing power for essential system functions such as logging, networking, and file system daemons.

The -e and the -E options are mutually exclusive.

-E cycles[:maximum_cycles]

Specifies the virtual machine's CPU entitlement in CPU cycles and optionally specifies the maximum cycles or entitlement cap. The default entitlement cap is the total maximum cycles supported by the physical CPU.

The cycles are expressed as an integer, followed by one of the following letters to specify units:

M (megahertz)
G (gigahertz)
If no letter is specified, the default unit is megahertz.

The -e and the -E options are mutually exclusive.

-F

Suppresses all resource conflict checks and associated warning messages (force mode). Force mode is provided for scripts and other noninteractive applications. Note that you will receive no notification of potential resource problems for a virtual machine modified with the -F option.

The -F and -s options are mutually exclusive.

-i package-name

Specifies whether the virtual machine is managed by Serviceguard or gWLM (or both). For the argument, specify the Serviceguard package name or gWLM, both, or NONE. This option is used by Integrity VM software; do not use this option without explicit instruction from HP.

-j {0 | 1}

Specifies whether the virtual machine is a distributed guest (that is, managed by Serviceguard and can be failed over to another cluster member). This option is used by Integrity VM software; do not use this option without explicit instruction from HP.

-l vm-label

Specifies a descriptive label for the virtual machine, which can be useful in identifying a specific virtual machine in the hpvmstatus verbose display. The label can contain up to 256 alphanumeric characters, including A-Z, a-z, 0-9, the dash (—), the underscore (_), and the period (.). To specifiy white space, the label must be quoted (" ").

-B start-attr

Specifies the startup behavior of the virtual machine. The start_attr argument can have the following (case-insensitive) values:

auto: Automatically start the virtual machine when Integrity VM is initialized on the host.
manual: Manually start the virtual machine.

If the start_attr attribute is set to auto, the virtual machine is started when Integrity VM is initialized. This is the default. This occurs when the VM Host system is booted, and when the Integrity VM software is stopped and restarted on a running VM Host. For example, when you upgrade Integrity VM to a new version on a running system, the software is started automatically. The VM Host attempts to start all virtual machines for which the attribute is set to auto. If insufficient resources exist, some virtual machines might fail to start.

If the attribute is set to manual, the virtual machine does not start automatically when Integrity VM is initialized on the VM Host. The virtual machine can then be started manually with the hpvmstart command or through its virtual console.

This option does not set the virtual machine's console to enable booting when the virtual machine is started. This function must be set with the virtual machine's console.

[-O os-type:[version]]

Specifies the type and version of the operating system running on the virtual machine. The response affects the default selection of certain virtual machine attributes, such as amount of memory and CPU power. The os_type is one of the following: HPUX, WINDOWS, or LINUX. This parameter is not case sensitive. The version is specific to the operating system type.

The version specifies a descriptive text string of the version of the operating system. The version string can consist of up to 256 alphanumeric characters, including A-Z, a-z, 0-9, the dash (—), the underscore (_), and the period (.). To specify white space, version must be quoted (" ").

-a rsrc

Adds an I/O resource to a virtual machine.

NOTE: When assigning a null device to a resource on a virtual machine, the file name serves as a placeholder. Therefore, if the file does not exist, you do not receive an error. For example, in the following command, if the file XXX.iso does not exist, no error is given.

# hpvmmodify -P vm1 -a disk:scsi::null"/opt/XXX.iso

The resource is specified as described in hpvmresources(5).

This option can be specified more than once.

-d rsrc

Deletes an I/O resource from a virtual machine. The resource is specified as described in hpvmresources(5). The physical device portion of the rsrc is optional.

This option can be specified more than once.

-m rsrc

Modifies an existing I/O resource for a virtual machine. The resource is specified as described in hpvmresources(5). You must specify the hardware address of the device to modify. The physical device portion of the rsrc specifies a new physical device to replace the one in use.

This option can be specified more than once.

The rsrc specifies the mapping of a guest virtual device to a VM Host backing store. Integrity VM guests access virtual devices that are instantiated on physical entities managed by the VM Host. These physical entities (for example, network cards, files, logical volumes, and so forth) are collectively referred to as backing stores.

Integrity VM recognizes the following types of guest virtual devices:

Virtual disks, which can be backed by files in a VM Host file system, by logical volumes or by whole disks.
Virtual DVDs, which can be backed by files in a VM Host file system or by the physical DVD drive.
Virtual network devices, which are created through the hpvmnet command and backed by physical LAN cards. For more information about virtual network devices, see hpvmnet(1M).

For information about specifying storage and network resources for guests, see the hpvmresources manpage.

Integrity VM Version 4.0 supports the usage of both legacy and agile devices in guest configurations. Over time, you should migrate from using legacy device names to agile device names to simplify the management of devices. You can use the hpvmmodify -P guest -m rsrc command to change the existing legacy device to its agile device equivalent. The ioscan -m dsk command displays the mapping of the agile devices to legacy devices for the specific device special file, dsf.




	NOTE: The rmsf `-L` command should not be executed on an Integrity VM server until all guest devices names have been changed to agile device names.

The following commands are helpful for reconfiguring guests to use agile device names:

insf
By default, creates both persistent and legacy DSFs for new devices.
insf -L
Restores legacy DSFs and legacy configuration information.
rmsf -L
Aids in migration by removing all legacy DSFs and legacy configuration information.
ioscan —m dsf
Maps persistent DSFs to their equivalent legacy DSFs and vice versa.
ioscan -N
Prints persistent DSFs when used with the -n option to list DSFs.
io_redirect_dsf
Associates a new disk with an existing set of DSFs. Used when replacing an internal disk or a disk in a JBOD.
hpvmmodify -P guest —m rsrc
Used to modify backing devices for guest devices.

-N new-vm-name

Specifies the new name for the virtual machine being modified, assuming no virtual machine with that name already exists. The name can consist of up to 256 alphanumeric characters, including A-Z, a-z, 0-9, the dash (—), the underscore (_), and period (.). The virtual machine name cannot start with a dash (-).

The virtual machine name can only be changed by using the -N option.

The name change takes effect immediately.

-c number-vcpus | -c number-vcpus:minimum:maximum

Specifies the number of virtual CPUs and vCPUs his virtual machine sees at boot time along with the range that the vCPUs must be within. The specification of the range is optional. When the range is not specified, a default range is used consisting of a minimum of one vCPU and a maximum equal to the maximum vCPUs supported for the specific guest operating system type.

Integrity VM Version 4.0 supports up to 8 vCPUS for all guest types. For example, to set a guest with four vCPUs with no range, use the following command:

# hpvmmodify -P guestname -c 4

To set a quest with four vCPUs with a range of two to six vCPUs, use the following command:

#hpvmmodify -P guestname -c 4:2:6

-r amount

Specifies the amount of memory available to this virtual machine.

The size is expressed as an integer, optionally followed by one of these units:

M (megabytes)
G (gigabytes)
If the letter is omitted, the default unit is megabytes.

-g [+]group[:{admin | oper}]]

Adds (+ or unspecified) or removes (-) a group authorization. A VM Host user account that is a member of an authorized group can use the hpvmconsole command to manage this guest. The {admin|oper} argument specifies the privilege level available at the hpvmconsole — either admin or oper (the default). Do not specify the privilege level when you are removing a group.

This option can be specified more than once.

-u [+]user[:{admin | oper}]]

Adds (+ or unspecified) or removes (-) a user authorization. An authorized VM Host user account can use the hpvmconsole command to manage this guest. The {admin|oper} argument specifies the privilege level available at the hpvmconsole, either admin or oper (the default). Do not specify the privilege level when you are removing a user.

This option can be specified more than once.

-s

Verifies the virtual machine configuration and returns warnings or errors, but suppresses the action that the command would normally perform. This option starts resource checking for the specified virtual machine configuration without actually modifying the virtual machine. In typical cases, where -s is not specified, the virtual machine is modified even if resource warnings occur.

The -F and -s options are mutually exclusive.

-x name=value

Specifies whether the virtual machine uses dynamic memory and the values associated with it by including the following keywords:

-x dynamic_memory_control={0|1}
-x ram_dyn_type={none|any|driver}
-x ram_dyn_min=amount
-x ram_dyn_max=amount
-x ram_dyn_target_start=amount
-x ram_target={0 | start | amount}
Specifies the guest RAM target, where the values are:
- 0 indicates the dynamic memory driver reduces the memory on the guest to what it determines is a comfortable minimum that does not result in guest memory being paged out.
- start indicates the guest dynamic memory size set back to the boot time value.
- amount is a specific target memory size for the guest.
-x runnable_status={disabled|enabled}
Specifying runnable_status=disabled prevents the guest from being started. It also prevents other guests from booting if they share devices with a disabled guest whose devices are marked SHARE=NO. Specifying enabled allows guest to be started again.
Set -x runnable_status=disabled only with the hpvmmodify command. An error message is printed if it is specified with the hpvmcreate or the hpvmclone commands. In addition, specify -x runnable_status=disabled only if the guest is not being managed by Serviceguard. If the hpvmcreate, ,hpvmmodify, or the hpvmclone command specifies -i SG, -i GWLM,SG, or I SG_packagename, an error message is printed if an attempt is made to disable the guest.
-x not_runnable_reason="string"
Displays the specified string in a message printed by the hpvmstart command when the guest is disabled. If no reason is given for disabling the guest, a default string is used. This parameter is ignored when -x runnable=enabled is specified on the command line. An error message is displayed if this parameter is specified by itself and the guest is enabled.
-x graceful_stop_timeout={0 | number}
Specifies that a graceful stop occurs in the number of seconds indicated; the default is 30 seconds.
-x sched_preference={none|cell|ilm}
where:
- none — The default preference. If your application is predominantly CPU bound, specifying either ilm or cell will perform the same.
- cell — The cell with the most CPU and memory space is chosen. When that guest is active, the scheduler then optimizes where the guest runs, so that it can be closest to its memory.
- ilm — Indicates that guests that are larger than any single cell and contain highly threaded applications.

RETURN VALUES

The hpvmmodify command exits with one of the following values:

0: Successful completion.
1: One or more error conditions occurred.

DIAGNOSTICS

The hpvmmodify command displays error messages on stderr for any of the following conditions:

An invalid option is specified.
An invalid value is specified for an option, or a value is omitted.
The vm_name or vm_number does not exist, cannot be accessed, is not a virtual machine, or is corrupt.
The new_vm_name already exists.
One or more options other than -a, -m, -d, -g or -u have been specified more than once.
The same resource was allocated more than once.
A resource allocated to another virtual machine was specified, and the force flag (-F) was not used.
A resource exceeded an available resource limit, and the force flag (-F) was not used.
A value was omitted for an argument that requires one, or a value was supplied for an argument that does not take one.
For the modified (-m) or delete (-d) options, the specified resource is not presently assigned to the vm_name.
The hpvmmodify command and Integrity VM are at different revision levels.

Using a colon (:), semicolon (;), or comma (,) when entering device names causes the machine-readable format of hpvmstatus to be misaligned.

EXAMPLES

Change the name of the virtual machine called myguest1 to myguest2:

# hpvmmodify -P myguest1 -N myguest2

Set the autoboot attribute for the virtual machine myguest1:

# hpvmmodify -P myguest1 -B auto

Add a new virtual DVD backed by a file to virtual machine myguest2:

# hpvmmodify -P myguest2 -a dvd:scsi::file:/var/opt/myguest.file

Change the virtual disk with hardware address 0,0,4 to a different physical device, /dev/rdisk/disk1:

# hpvmmodify -P myguest2x -m disk:scsi::0,0,4:disk:/dev/rdsk/c2t2d1

Change the network device at hardware address 0,2 to a different vswitch, (called myswitch), thereby preserving its original virtual MAC address:

# hpvmmodify -P myguest2 -m network:avio_lan:0,2,1a-01-5a-8e-99-fa:vswitch:myswitch

Delete the virtual disk at hardware address 0,0,2 from the virtual machine myguest2:

# hpvmmodify -P myguest2 -d disk::scsi::0,0,2

Delete the network device at hardware address 0,1 from the virtual machine myguest2:

# hpvmmodify -P myguest2 -d network:avio_lan:0,1

Cap myguest2 with a the CPU entitlement of 20% with a minimum of 10%:

# hpvmmodify -P myguest2 -e 10:20

Temporarily change the CPU entitlement to 50% until virtual machine myguest2 is rebooted:

# hpvmmodify -A -P myguest2 -e 50

The following are sample warning messages returned when the hpvmmodify command is executed with various configuration problems on the guest myguest1:

HPVM guest myguest1 configuration problems:
Warning 1: Guest needs more vcpus than server supports.
Warning 2: Insufficient free memory for guest.
Warning 3: Insufficient swap resource for guest.
Warning 4: Insufficient cpu resource for guest.
Warning 5 on item /dev/rdisk/disk0: Device file '/dev/rdisk/disk0' in use by another guest.
Warning 6 on item /dev/vg00/rswap: Device file '/dev/vg00/rswap' in use by server.
Warning 7 on item /dev/rdisk/disk3 backing device does not exist.
Warning 8 on item /dev/rdisk/disk4: Device file '/dev/rdisk/disk4' in use by another guest.
Warning 9 on item hostnet: MAC address in use for switch hostnet.
Warning 10 on item offnet: Vswitch offnet is not active.
Warning 11 on item badnet: 'badnet' backing device does not exist.

These problems will prevent HPVM guest myguest1 from booting.

The following example shows how to enable dynamic memory control for the guest myguest1:

# hpvmmodify -P myguest1 -x dynamic_memory_control=1

AUTHORS

The hpvmmodify command was developed by HP.

hpvmmodify(1M)

Technical documentation

» Table of Contents

» Glossary

» Index

NAME

SYNOPSIS

DESCRIPTION

Options

RETURN VALUES

DIAGNOSTICS

EXAMPLES

AUTHORS

SEE ALSO