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
Note: Regardless of locale, only ASCII characters
are allowed as arguments to mkwpar, chwpar, or wparexec
In addition to this, there are more restrictions for a
WPAR's name:
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
Item |
Description |
wparname |
The name of the system
or application workload partition to be changed. The wparname parameter must be the last parameter
on a command line. |
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
- To modify the host name of the workload partition called roy, enter the following command:
chwpar -h roy.com roy
- To remove a network address from the workload partition called dale, enter the following command:
chwpar -K -N address=219.81.45.65 dale
- 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
- To unexport a device from a workload partition, enter the following
command:
chwpar -K -D devname=hdisk1 <wpar name>
- To export a device, enter the following command:
chwpar -D devname=hdisk1 devtype=disk <wpar name>
- To rename the workload partition from moore to hart, enter the following command:
chwpar -n hart moore
- To add an adapter, fcs2, to a workload partition named 'roy',
enter the following command:
chwpar -D devname=fcs2 roy
- To remove an adapter, fcs2, from a workload partition named 'roy',
enter the following command:
chwpar -K -D devname=fcs2 roy
Files
Item |
Description |
/etc/wpars/devexports |
Default device export control file for workload partitions. |