chwpar Command

Purpose

Changes the characteristics of a workload partition.

Syntax

/usr/sbin/chwpar [-a] [-A] [-c] [-d directory] [-D attribute=value ...] ... [-F] [-h hostname] [-i] [-I attribute=value ...] ... [-n newname] [-H architecture][-N attribute=value ...] ... [-P] [-R attribute=value ...] [-S attribute[+|-]=value...] [-u userscript] [-x ][-U [uuid]] [ -v ] [-X attribute=value …]wparname

/usr/sbin/chwpar -K [-A] [-c] [-D devname=devicepathname ] ... [-F] [-i] [-I rtdest=destination rtgateway=gateway [attribute=value ...]] ... [-N address=A.B.C.D] ... [-R [attribute ...] ] [-S] [-u] [-x ] [ -v ] [-X kext=value …]wparname

Description

The chwpar command modifies the configuration options of the workload partition specified by the wparname parameter. You can change most options whether the workload partition is running. Some changes to the running workload partitions are detected and disallowed (see the -d and -n options). Other changes, such as unexporting a busy device or removing a mounted file system, might generate errors on a running workload partition, but you can make these changes.

Use the -K flag to remove characteristics from the configuration of a workload partition. For an attribute with a default option, removing the value for the attribute restores the default setting for the option.

Flags

-a

Automatically resolves conflicting static settings if required. Settings that can be resolved are hostname and network configuration.

-A

Configures the workload partition to be started at system boot through the /etc/rc.wpars command by setting the auto attribute value of the workload partition to yes. When you specify the -A flag with the -K flag, the auto attribute value is set to no. The -A flag takes effect the next time the global system boots. The -A flag is not valid for application workload partitions.

-c

The workload partition is enabled for checkpoint.

Note: The capability to enable a workload partition for checkpoint depends on additional software.

-d directory

Changes the base directory for the workload partition. The -d flag can not be used on a running workload partition. This flag is not valid for application workload partitions.

-D [devname=device name | devid=device identifier] [rootvg=yes | no] [devtype=[clone | pseudo | adapter |disk | cdrom | tape]]

Configures exporting or virtualization of a global device into the workload partition every time the system starts. You can specify more than one -D flag to allocate multiple devices. Separate the attribute=value by blank spaces. You can specify the following attributes for the -D flag:

devname=device name

Specifies the device name to allocate to the workload partition. For pseudo and clone type devices, this is the full path to the device (i.e. /dev/pty10). For storage type devices, it is the logical device short name.

devid=device identifier

Specifies the unique device identifier of a disk type device to allocate to the workload partition. This attribute only applies to disk, cdrom, or tape type devices.

rootvg= [yes | no]

Used to indicate if the specified disk device is to be used as a rootvg workload partition device. If the rootvg attribute is not specified, the command will take the default of no.

devtype=[ clone | pseudo | adapter | disk | cdrom | tape]

Specifies the device type of the device to allocate to the workload partition.

-F

Suppresses failures due to settings that are not valid.

-h hostname

Modifies the kernel host name of the workload partition.

-H architecture

Changes or removes the architecture of a workload partition. The valid architecture values are: {pwr4 |ppc970|pwr5|pwr6|pwr7}. The special value, none disables the compatibility of the workload partition architecture. The -H flag can not be used on a running workload partition.

Note: The -H flag is valid along with the -K flag.

-i

Enables WPAR-specific routing for the workload partition. When WPAR-specific routing is enabled on a running workload partition, any explicit routing table entries that were configured using the -I flag with the mkwpar, wparexec, or chwpar command are added to the routing table of the workload partition. Running the chwpar -i command on a workload partition with enabled WPAR-specific routing refreshes the routing table of the workload partition. You can use the -i flag, for example, to restore the routing table after a global route flush. You can use the -i flag with the -K flag to disable WPAR-specific routing for the workload partition. For more information about the -i flag, see the description of the -i flag of the mkwpar command.

-I attribute=value ...

Modifies explicit routing table entries. Entries are matched based on the combination of the rtdest, rtgateway, and rtinterface (if specified) attributes. If a matching entry is found, the remaining attributes are used to update that routing table entry. If no match is found, a new entry is created in the workload partition routing table. For more information about the -I flag, see the description of the -i flag and the -I flag of the mkwpar command. However, unlike the mkwpar command or the wparexec command, using the -I flag with the chwpar command does not change whether WPAR-specific routing is enabled or disabled. Use the -i flag (with or without the -K flag) to disable or enable WPAR-specific routing.

You can specify the following attributes with the -I flag:

rtdest=destination

(Required) Identifies the host or network to which you are directing the route. You can specify the value using either a symbolic name or a numeric address. You can use the keyword default to specify a default route. For more information about the rtdest attribute, see the Destination parameter of the route command.

rtgateway=gateway

(Required) Identifies the gateway to which packets are addressed. You can specify the value using either a symbolic name or a numeric address.

rtnetmask=A.B.C.D

Specifies the network mask to the destination address.

rtprefixlen=n

Specifies the length of a destination prefix, which is the number of bits in the netmask. The value must be a positive integer.

rttype={net|host}

Forces the rtdest attribute to be interpreted as the specified type.

rtinterface=if

Specifies the interface, for example, en0, to associate with the route so that packets are sent using the interface when the route is chosen.

rtfamily={inet|inet6}

Specifies the address family. For information about the parameters of the rtfamily flag, see the parameter section of the route command.

-K

Deletes the specified attributes from the configuration of the workload partition. You can use the -K flag with the following flags:

-A

Changes the general auto option value of the workload partition to no, causing the workload partition not to be started when the /etc/rc.wpars command is running. This flag is not valid for application workload partitions.

-c

The workload partition is disabled for checkpoint.

-D [devname=device name | devid=device identifier]

Removes an explicit entry concerning an exported device, causing either a device that is not exported previously to be exported, or a previously exported device to be removed. This flag is not valid for application workload partitions.

You can specify the following attributes for the -D flag:

devname=device name

Specifies the device name to allocate to the workload partition. For pseudo and clone type devices, this is the full path to the device (i.e. /dev/pty10). For storage type devices, it is the logical device short name.

devid=device identifier

Specifies the unique device identifier of a disk type device to allocate to the workload partition. This attribute only applies to disk, cdrom, or tape type devices. When the devid attribute is used, the devtype attribute must also be specified.

-X [kext=/path/to/extension|ALL]

Removes an explicit entry for an exported kernel extension. Removing a kernel extension will prevent it from being loaded inside a workload partition. If the kernel extension is loaded inside a workload partition, the kernel extension will not be unloaded. A restart of the workload partition will be required to completely unexport the kernel extension from the workload partition. This flag is not valid for application workload partitions. The following attribute must be specified:

kext=/path/to/extension|ALL

Specify the kernel extension to remove. This must match a value inside the workload partition's configuration file. This must either be a fully qualified path or ALL if the kext=ALL had previously been used.

Deletes the specified attributes from the configuration of the workload partition. You can use the -K flag with the following flags:

-i

Disables WPAR-specific routing for the workload partition. Any explicit routing table directives that are supplied using the -I flag with the mkwpar, wparexec, or chwpar command are maintained (but inactive) in the configuration of the workload partition. The explicit entries are created automatically the next time WPAR-specific routing is enabled.

-I rtdest=destination rtgateway=gateway [attribute=value ...]

Removes an explicit entry from the routing table of the workload partition. You must specify at least the rtdest attribute and the rtgateway attribute to identify the entry to be deleted.

-N address=A.B.C.D

Removes the specified IPv4 address from the configuration of the workload partition.

-N address6=S:T:U:V:W:X:Y:Z

Removes the specified IPv6 address from the configuration of the workload partition.

-R [attribute ...]

Removes specific fields from the resource control configuration of the workload partition. The -R flag can restore each field to its default state. For fields such as totalProcesses, the default state is unlimited. The following attributes can be restored to the default handling:

• rset
• shares_CPU
• CPU
• shares_memory
• memory
• procVirtMem
• totalVirtMem
• totalProcesses
• totalThreads
• totalPTYs
• totalLargePages
• pct_msgIDs
• pct_semIDs
• pct_shmIDs
• pct_pinMem

When no attributes are specified, the -K and -R flags restore the resource control profile of the workload partition to its default settings.

-S

Restores the security settings for the workload partition to default values.

-u

Disables the callout to the user script on administration events. (It not delete the script itself.)

-x

Disallows access to the cross-WPAR semaphores and shared memory segments.

-n newname

The new name for the workload partition. Do not specify the -n flag for a running workload partition.

-N attribute=value ...

Modifies the network configuration attributes. Entries are matched based on the address or address6 attribute. Each entry must be specified per -N flag. You can specify more than one -N flags to reconfigure multiple IP addresses. You can modify the following network configuration attributes:

• interface=if or interface=namemappedif
• address=A.B.C.D
• netmask=A.B.C.D
• broadcast=A.B.C.D
• address6=S:T:U:V:W:X:Y:Z
• prefixlen=n

The value of the prefixlen attribute ranges from 0 through 128.

The name-mapped interface is in the /etc/wpars/devmap file. You can specify the mapping between the name-mapped interface and the system interface as follows:

# The comments start with '#'
# Each line contains a pair of name-mapped interface
# and real interface separated by tab or blank spaces.
foo en0
goo en1
soo en2

-P

Interactively sets the password for the root user in the workload partition. This flag is not valid for application workload partitions.

-R attribute=value ...

Allows modification of resource control attributes. Most resource controls are similar to those used by Workload Manager. You can specify the following attributes:

active=yes|no

If you specify yes, this attribute allows resource control definitions to be retained, but they are rendered inactive. If you specify no, performance metrics such as processor and memory usage might not be available through commands such as the topas and wlmstat commands, both inside and outside of the workload partition.

rset=rset

Configures the workload partition to use a resource set that is created by the mkrset command.

shares_CPU=n

Specifies the number of processor shares that are available to the workload partition. See Workload Manager shares File.

CPU=m%-SM%,HM%

Specifies the percentage processor limits for the processes of the workload partition. See Workload Manager limits File.

shares_memory=n

Specifies the number of memory shares that are available to the workload partition. See Workload Manager shares File.

memory=m%-SM%,HM%

Specifies the percentage memory limits for the processes of the workload partition. See Workload Manager limits File.

procVirtMem=n[M|MB|G|GB|T|TB]

Specifies the maximum amount of virtual memory that a single process can consume. Processes that exceed the specified limit are terminated. The valid units are megabytes (M or MB), gigabytes (G or GB), and terabytes (T or TB). The minimum limit allowed is 1MB. The maximum limit that can be specified is 8796093022207M, 8589934591G, or 8388607T. If you set the value to -1 (no units), the limit is disabled. See workload partition limits File.

totalVirtMem=n[M|MB|G|GB|T|TB]

Specifies the maximum amount of virtual memory that can be consumed by the WPAR as a whole. Processes that cause the specified limit to be exceeded will be terminated. The valid range and units are the same as for procVirtMem. If the value is set to -1 (no units), the limit is disabled. See workload partition limits File.

totalProcesses=n

Specifies the total number of processes that are allowed in the workload partition. See workload partition limits File.

totalPTYs=n

Specifies the total number of pseudo terminals that are allowed in the workload partition. See pty Special File.

totalLargePages=n

Specifies the number of large pages that are allowed for the workload partition. See Large Pages.

pct_msgIDs=n%

Specifies the percentage of the maximum number of message queue IDs of the system that are allowed in the workload partition. See Message Queue Kernel Services.

pct_semIDs=n%

Specifies the percentage of the maximum number of semaphore IDs of the system that are allowed in the workload partition.

pct_shmIDs=n%

Specifies the percentage of the maximum number of shared memory IDs of the system that are allowed in the workload partition. See Shared Memory.

pct_pinMem=n%

Specifies the percentage of the maximum pinned memory of the system that can be allocated to the workload partition. See Support for pinned memory.

totalThreads=n

Specifies the total number of threads that are allowed in the workload partition.

-S attribute[+|-]=value...

Modifies the security settings for the workload partition. You can specify only one of the following forms of security changes:

secfile=secAttrsFile

Sets the privileges for the workload partition to the privileges listed in the specified file.

privs=priv,priv,...

Sets the privileges for the workload partition to the specified list of privileges.

privs+=priv,priv,...

Adds the specified list of privileges to the privilege set for the workload partition.

privs-=priv,priv,...

Removes the specified list of privileges from the privilege set for the workload partition.

Important: Do not change the security settings when a workload partition is active.

-u userscript

Changes the path to the user script to be run on workload partition administration events. If no user script was configured, the specified script is added to the configuration. An RBAC user cannot run this flag for a WPAR that others own.

-U [Workload Partition UUID]

Changes the Workload Partition UUID. If not given, a new UUID is automatically generated.

-v

Enables verbose output.

-x

Allows access to the cross-WPAR semaphores and shared memory segments.

-X [exportfile=/path/to/file | [kext=[/path/to/extension|ALL]] [local=yes|no] [major=yes|no]

Configures exporting kernel extensions that will be allowed to load inside a workload partition. You can specify more than one -X flag to allocate multiple kernel extensions. Separate the attribute=value by blank spaces. This flag is not valid for application workload partitions. You can specify the following attributes for the-X flag:

exportfile=/path/to/file

Specify a file containing valid extension stanza that will be exported. An extension stanza should contain at least the kext attribute. The local and major attribute can also be specified in the stanza which are described below. The exportfile attribute is mutually exclusive with the kext attribute. It is also mutually exclusive with the local and major attribute because these can be specified for each extension stanza in the exportfile. This is a file that can be created by a user to use with exportfile=/path/to/file for mkwpar and chwpar. It can contain multiple extension stanzas. The kext attribute is required for each extension stanza. The local and major are optional as they both have default values of no. The exportfile will look similar to the following:

extension:
        major = "yes"
        local = "no"
        kext = "/usr/lib/drivers/ldterm"

kext=/path/to/extension

Specify a kernel extension that will be exported. This is a kernel extension located in the global system's file system. The keyword ALL can also be specified. This will allow a workload partition to load any extension. When ALL is specified, the local and major attributes are restricted to local=yes and major=no. Additional -X flags can be specified to override the restricted local and major values. The kext attribute is mutually exclusive with the exportfile attribute.

local=yes|no

Specifying local=yes will make an instance of the kernel extension accessible to only the workload partition that is loading it. Specifying local=no will share the instance of the kernel extension loaded in the global system. By default, local=no.

major=yes|no

This attribute should only be used for kernel extensions that have an associated device major. By default, major=no.

recalc=yes

This attribute can be used to recalculate the checksum of the kernel extension.

Parameters

Security

Access Control

Only the root user can run the command.

Attention RBAC users and Trusted AIX® users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in Security. For a list of privileges and the authorizations associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

1. To modify the host name of the workload partition called roy, enter the following command:

   chwpar -h roy.com roy

2. To remove a network address from the workload partition called dale, enter the following command:

   chwpar -K -N address=219.81.45.65 dale

3. To disable resource controls in the workload partition called wayne while retaining the settings for future use, enter the following command:

   chwpar -R active=no wayne

4. To unexport a device from a workload partition, enter the following command:

   chwpar -K -D devname=hdisk1 <wpar name>

5. To export a device, enter the following command:

   chwpar -D devname=hdisk1 devtype=disk <wpar name>

6. To rename the workload partition from moore to hart, enter the following command:

   chwpar -n hart moore

7. To add an adapter, fcs2, to a workload partition named 'roy', enter the following command:

   chwpar -D devname=fcs2 roy

8. To remove an adapter, fcs2, from a workload partition named 'roy', enter the following command:

   chwpar -K -D devname=fcs2 roy

Files