hpvmcreate — Create a new Integrity VM virtual machine.

[giraffelife]

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.

SEE ALSO
On the VM Host:

hpvm(5), hpvmclone(1M), hpvmcollect(1M), hpvmconsole(1M), hpvmdevmgmt(1M), 
hpvmdevtranslate(1M), hpvmhostrdev(1M), hpvminfo(1M), hpvmmigrate(1M), 
hpvmmodify(1M), hpvmnet(1M), hpvmpubapi(3), hpvmremove(1M), hpvmresources(5), 
hpvmsar(1M), hpvmstart(1M), hpvmstatus(1M), hpvmstop(1M), hpvmupgrade(1M), 
p2vassist(1M)

On the Integrity VM guest:

hpvmcollect(1M), hpvminfo(1M), hpvmmgmt(1M), hpvmpubapi(3)