hpvmcreate(1M)

NAME

hpvmcreate — Create a new Integrity VM virtual machine.

SYNOPSIS

hpvmcreate -P vm-name [ -F -s ] [-l vm-label] [-B start-attr] [[-O os-type[:version]] -c number-vcpus ] [ -e percent[:max_percent] -E cycles[:max_cycles] ] [-r amount] [-g group [ {:adminoper}]] [-u user[ {:adminoper}]] [-a rsrc] [-i { SG SG-pkgname GWLM SG-pkgname , GWLM NONE }] [-j { 0 1 }] [[-x name=value [:name=value]]]

DESCRIPTION

The hpvmcreate command creates a new virtual machine (a guest) and assigns the specified attributes and resources to it. This command creates an association between the virtual devices seen by the guest and the physical devices managed by the VM Host.

Only superusers can execute the hpvmcreate command.

Virtual machine creation is designed for flexibility and assumes that not all created virtual machines are necessarily running at the same time or on the current VM Host. Therefore, the hpvmcreate command allows the creation of virtual machines that cannot boot on the current system. A guest configuration receives a warning at creation 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 creating the guest, use the -s option.

Options

-P vm-name

Specifies the name of the virtual machine. This name must be unique on the VM Host. This virtual machine name is used in other Integrity VM commands to specify which virtual machine the command affects. If you plan to allow remote access to the virtual machine's console, the virtual machine name must be a legal UNIX account name.

The name can consist of up to 256 alphanumeric characters including A-Z, a-z, 0-9, the dash (—), the underscore (_), and the period (.). The virtual machine name cannot start with a dash (—). The -P option is required.

-e percent[:max_percent]

Specifies the percentage of CPU resources to which each of the guest's virtual CPUs is entitled. 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, then the virtual machine is allocated the minimum percentage of 5%. The default entitlement 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. You can view the current settings by using the hpvmstatus -r command.

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

The -e and -E options are mutually exclusive.

-E cycles[:max_cycles]

Specifies the virtual machine's CPU entitlement in CPU cycles.

The cycles are expressed as an integer, followed by one of these units:

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

The -e and -E options are mutually exclusive.

-F

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

The -F and -s options are mutually exclusive.

-a

Specifies the mapping of a guest virtual device to a VM Host backing store. A virtual device is instantiated on physical entities that are 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 DVDs, which can be backed by filess in a VM Host file system or by physical DVD drives.
Virtual disks, which can be backed by files in a VM Host file system, by logical volumes or by whole disks.
Attached I/O devices (DVD, tape, media changer, and other peripheral device types).
Virtual network devices, which are created using the hpvmnet command and backed by physical LAN cards. See the hpvmnet manpage for more information about virtual network devices.

For information about specifying storage and network resources for guests, see hpvmresources(5).

-i package-name

Specifies whether the virtual machine is managed by Serviceguard or gWLM (or both). For the argument, specify the Serviceguard package name, GWLM, both, or NONE. This option is used by Integrity VM software; do not use this option without express instruction by 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 express instruction by HP.

-l vm-label

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

-B start-attr

Specifies the startup behavior of the virtual machine. The start_attr attribute 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 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 may fail to start.

If the attribute is set to manual, the virtual machine will not be started automatically when Integrity VM is initialized on the VM Host. This is the default behavior. 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 will affect 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 (.). If white space is desired then version must be quoted.

-c number-vcpus

Specifies the number of virtual CPUs this virtual machine sees at boot time. If unspecified, the number defaults to one.

The maximum number of virtual CPUs that can be allocated to a guest is eight.

-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 unspecified, the unit defaults to megabytes. If the -r option is omitted, the size defaults to 2 GB.

-g [+]group[:kind]

Specifies the group authorization. A VM Host user account that is a member of this group can use the hpvmconsole command to manage this guest. The group attribute specifies the name of the group. The kind argument specifies the privilege level available at the virtual console: either admin or oper (the default).

This option can be specified more than once.

-u [+]user[:kind]

Specifies the user authorization. A VM Host user account specified here can use the hpvmconsole command to manage this guest.The user attribute specifies the user name. The kind argument specifies the privilege level available at the virtual console: either admin or oper (the default).

This option can be specified more than once.

-s

Verifies the virtual machine configuration and returns warnings or errors but does not create the virtual machine.

This option is used to start the hpvmcreate command's resource checking for a virtual machine configuration without actually creating the virtual machine. If the -s option is not specified, the virtual machine is created even if resource warnings occur.

The -F and -s options are mutually exclusive.

-x

Specifies whether the new 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 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 hpvmcreate command exits with one of the following values:

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

DIAGNOSTICS

The hpvmcreate 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 specified vm-name already exists. Use the hpvmmodify command to modify an existing guest.
One or more options other than -a, -g or -u were specified more than once or the same resource was allocated more than once.
An unavailable resource (allocated to another virtual machine, or exceeding the available resource limit) was specified.
A value was omitted for an argument that requires one, or a value was supplied for an argument that does not take one.
The hpvmcreate command and the Integrity VM software are at different version levels.

EXAMPLES

The following example creates a virtual machine named myguest1, specifying 4 virtual CPUs, and 2 GB of memory, and /dev/rdisk/disk0 as a SCSI disk device:

# hpvmcreate -P myguest1 -c 4 -r 2G -a disk:scsi::disk:/dev/rdisk/disk0

The following example creates a virtual machine named myguest2, specifying 2 virtual CPUs and a virtual switch named vswitch1. Each virtual CPU has a 50% entitlement.

# hpvmcreate -P myguest2 -c 2 -e 50 -a disk:scsi::disk:/dev/rdisk/disk0 \
-a network:avio_lan::vswitch:vswitch1

The following example creates a virtual machine named cougar with 2 virtual CPUs, 2 GB memory, a virtual disk backed by a whole disk, a virtual disk backed by a partition, a virtual disk backed by an LVM volume, a virtual DVD backed by an ISO file, a virtual network interface backed by virtual switch localnet, and an accelerated virtual network interface backed by virtual switch hostnet:

# hpvmcreate -P cougar -c 2 -r 2G \
-a disk:scsi::disk:/dev/rdisk/disk0 \
-a disk:scsi::disk:/dev/rdisk/disk1 \
-a disk:scsi::lv:/dev/vg00/rguestvol1 \
-a dvd:scsi::file:/var/opt/hpvm/ISO-images/hpux/1123505GOLD.ISO \
-a network:lan::vswitch:localnet \
-a network:avio_lan::vswitch:hostnet

The following are sample warning messages that are returned when the hpvmcreate command is executed with various configuration problems on the guest myguest3:

HPVM guest myguest3 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/disk3: Device file '/dev/rdisk/disk3' 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 myguest3 from booting.

The following example shows how to create the guest myguest1 and specify dynamic memory control.

# hpvmcreate -P myguest1 -c 4 -r 2G -a disk:scsi::disk:/dev/rdisk/disk0 -x dynamic_memory_control=1

The following example creates a guest named testguest with a 100 Mhz minimum and a cap of 250 Mhz.

#hpvmcreate -P testguest -E 100:250

AUTHORS

The hpvmcreate command was developed by HP.

hpvmcreate(1M)

Technical documentation

» Table of Contents

» Glossary

» Index