vparmodify(1M)

NAME

vparmodify — rename a virtual partition or modify the attributes of a virtual partition

SYNOPSIS

vparmodify -p vp_name [-B boot_attr] [-D db_file] [-S static_attr] [-b kernel_path] [-o boot_opts] [-P new_vp_name] [-a rsrc]... [-m rsrc]... [-d rsrc]...

DESCRIPTION

The vparmodify command modifies attributes and resources of the specified virtual partition (vPar). The command can also rename the virtual partition. vp_name is a symbolic name for an existing virtual partition and must be used in all references to it. vparmodify cannot create a virtual partition. Use the vparcreate command for that purpose.

Some CPU resources have special requirements when being added to a virtual partition. These special CPU resource requirements are described below Table 1.

Only a superuser can execute the vparmodify command. In a secure virtual partition environment only a Primary-Admin vPar can modify resources on other virtual partitions.

Options

If the -D option is specified, vp_name in db_file is modified; otherwise vp_name in the virtual partition monitor database is modified.
If the static attribute has been configured in vp_name, none of its resources may be added, modified, or deleted. Attributes (all options except -a, -m, and -d) may be modified. Refer to the -S option description.
Only the -S, -a, -m, and/or -d options may be specified more than once in a command.
If any of the following options are specified: -B, -P, -S, -b, or -o, the virtual partition to be modified must be in the Up, Down, or Hung state. Refer to the vparstatus(1M) manpage for a complete list of vPar states and their definitions.
Resources allocated with the -a option must be available, that is, not already allocated to a virtual partition, and they must NOT exceed the overall limits of the resources.
Resources to be modified (-m) or deleted (-d) must be owned by vp_name.

Violation of any condition is a command error.

vparmodify recognizes the following command line options and arguments. The options are processed from left to right.

-p vp_name

Specifies the symbolic name of the existing virtual partition which is to be modified. Required.

-B boot_attr

Specifies the autoboot and autosearch attribute of the virtual partition. boot_attr can have the following case-insensitive values:

auto: sets the autoboot attribute.
manual: clears the autoboot and autosearch attributes.
search: sets the autosearch attribute.
nosearch: clears the autosearch attribute.

If the autoboot attribute is set to auto, the virtual partition is rebooted after a successful vparreset command or when the virtual partition monitor is first loaded, if appropriate monitor options have been specified.

If the attribute is set to manual, the virtual partition halts after a vparreset and does not boot when the monitor is loaded. It must then be booted manually with the vparboot command.

If the autosearch attribute is set to search, then the combination of autoboot(auto) and autosearch(search) decides the boot action to be taken. The interpretation of autoboot and autosearch has changed for systems that support hardware partitions. Refer to setboot(1M) for details.

On hard partitioned systems with vpars the boot action corresponds to the autoboot and autosearch flags in the following manner:

 AutoBoot   AutoSearch  Boot Action
______________________________________________________

 off        off         Halt the virtual partition for
                        manual boot.
 on         off         Attempt the primary path;
                        on failure halt the virtual
                        partition.
 on         on          Attempt the primary path;
                        on failure try alternate path.
 off        on          Skip the primary path and try
                        alternate path. If the
                        alternate path is not
                        configured to boot or the 
                        boot fails then halt the 
                        virtual partition.
______________________________________________________

If the -B option is omitted, the attributes are not changed.

-D db_file

Apply changes to the vp_name contained in db_file. The virtual partition monitor need not be running. If it is, it is not notified of the modification.

Although db_file can reside in any path when accessed as an alternate database, it must be placed in the /stand directory before it can be loaded by the virtual partition monitor as its live database.

If the -D option is omitted, the virtual partition monitor must be running. Changes are applied to vp_name in the monitor's database. A vp_name in the monitor database must be in the Down state, with one exception: Unbound cpu resources can be added to or deleted from a running virtual partition. This restriction may be relaxed for other types of resource management in a future release.

-S static_attr

Specifies the static virtual partition attribute. static_attr can have the following values:

static: sets the static attribute.
dynamic: resets the static attribute.

If the -S option is omitted, the attribute is not changed.

No hardware resource changes can be made to a static virtual partition, that is, the -a, -m, and -d options are not allowed. This restriction applies to all virtual partitions, whether in an alternate database file, or in the monitor's database.

Since command line options are processed left-to-right, you can modify resources in a static partition by specifying -S dynamic on the command line before any resource options, then specifying -S static after all resource options to prevent further resource modifications.

-b kernel_path

Specifies the absolute path to a bootable kernel for the partition. If the option is omitted, the kernel_path is not changed.

-o boot_opts

Specifies the command-line string, except for the kernel path, applied when the virtual partition is booted. For example, if a non-partitioned system start string at the ISL prompt is:

ISL> hpux -iS /stand/vmunix

the boot_opts string is the -iS portion of this string. Note that if the string includes a space, the string must be quoted.

Refer to "Monitor and Shell Commands" in Installing and Managing HP-UX Virtual Partitions for a full list of supported boot option strings.

If the -o option is omitted, the boot_opts is not changed.

-P new_vp_name

Specifies the new name for the virtual partition being modified, that is, after all modifications are successfully applied to vp_name, it is renamed to new_vp_name, assuming no virtual partition with that name already exists in the monitor database or specified alternate database file. The name can consist of alpha-numeric characters A-Z, a-z, 0-9, the underbar character (_), and period (.). The maximum length of the name is 239 characters.

-a rsrc

-a adds resources to a virtual partition.

-d rsrc

-d deletes resources from a virtual partition.

-m rsrc

-m modifies existing resources in a virtual partition. rsrc is a hardware resource specification, as described in detail in the vparresources(5) manpage. A summary of resource syntax forms is shown in Table 1. Multiple resource specifications in the same command are allowed, but some syntax forms are restricted to specific options, and some are only allowed once. Both are indicated in Table 1. In any case, resources in multiple specifications must not repeat or conflict with each other.

Table 1. Resource syntax summary

Resource	Forms	Options	# times/command
CPU	cpu:`path`	`-a`, `-d`	Multiple
	cpu::`num`	`-a`, `-m`, `-d`	Once
	cpu:::[`min`]:[`max`]	`-m`	Once
I/O	io:`path`[:`attr1`[,`attr2`]]	`-a`, `-m`, `-d`	Multiple
Memory	mem::`size`	`-a`, `-m`, `-d`	Once
	mem:::`base`:`range`	`-a`, `-d`	Multiple

Certain tasks can affect the outcome of others. To avoid errors, see the detailed description of the dependencies in the vparresources(5) manpage.

Dynamically increasing or decreasing the number of floating CPUs in a running virtual partition results in an asynchronous request to the OS. The OS requires an indeterminate time to complete the operation, based on overall system load and (for CPU deletion) the time required to migrate all threads on that CPU on to one or more of the remaining CPUs. During this time, the CPU is said to be undergoing migration into or out of the vPar. The CPU is assigned to its vPar throughout the migration process. For migration out, the CPU is not available for assignment to another vPar until the migration has completed.

The vparstatus command shows migrating CPUs. Refer to the vparstatus(1M) manpage.

RETURN VALUE

The vparmodify command exits with one of the following values:

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

EXAMPLES

Change the name of the virtual partition called Oslo to Bergen:

vparmodify -p Oslo -P Bergen 

Turn on autosearch attribute for the virtual partition Bergen:

vparmodify -p Oslo -B search 

Turn off the autoboot and autosearch attributes for the virtual partition Oslo:

vparmodify -p Oslo -B manual 

Add two processors to the virtual partition Bergen in alternate database file /stand/Norway:

vparmodify -p Bergen -D /stand/Norway -a cpu::2 

ERRORS

vparmodify 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 db_file does not exist, cannot be accessed, or has been corrupted.
vp_name does not exist in the specified db_file or in the monitor database.
new_vp_name already exists in the monitor database or specified db_file.
vp_name is static and you have attempted to change a resource.
One or more options other than -S, -a, -m, -d is specified more than once.
For the -a or -m option, an unavailable resource (allocated to another virtual partition or exceeding the available resource limit) is specified.
For the -m or -d option, the specified resource is not presently assigned to vp_name.
The vparmodify command and the virtual partition monitor are at different revision levels.

The state of the modified vPar following an error depends on the following factors:

If the error is detected during syntax and semantic checks of the command line, the vPar is not changed.
If the error is detected while actually modifying the vPar, AND you are modifying an alternate database, the vPar is not changed. This is because changes are not committed until the end of the command.
If the error is detected while modifying the vPar, AND you are modifying the database currently loaded into the monitor, then any changes made to the point of the error (working left-to-right on the command line) will remain. This is because changes to the live database are made incrementally, as they are requested.

AUTHOR

vparmodify was developed by the Hewlett-Packard Company.