wparexec Command

Purpose

Creates an application workload partition or specification file.

Syntax

wparexec [ -a ] [ -c] [ -1 ][ -F ] [ -h hostname ] [-H architecture] [-i] [-I attribute=value ...] ... [ -M attribute=value... ] ... [ -N attribute=value... ] ... [ -R attribute=value... ] [ -u userscript ] [ -v] [ -x] { -n wparname [ -e existingwpar | -f infile ] [ -o outfile [ -w ] ] | -f infile [ -n wparname ] [ -o outfile [ -w ] ] | -w -o outfile [ -n wparname] [ -e existingwpar | -f infile ] } [ [--] [ var=value ...] /path/to/command [ arg ... ] ]

Note:

Regardless of locale, only ASCII characters are allowed as arguments to the wparexec command.

In addition to this, there are more restrictions for a WPARs name:
  • May not be more than 25 bytes.
  • May not contain white space or any of the following symbols:

    = : / ! ; ` ' " < > ~ & ( ) * + [ ] , . ^ 0 { } | \

  • May not start with '-' or '0'.

Description

The wparexec command builds and starts an application workload partition, or creates a specification file to simplify the creation of future application workload partitions.

An application workload partition is an isolated execution environment that might have its own network configuration and resource control profile. Although the partition shares the global file system space, the processes that are running therein are only visible to other processes in the same partition. This isolated environment allows process monitoring, gathering of resource, accounting, and auditing data for a predetermined cluster of applications.

The wparexec command starts and monitors a single application within this isolated environment. The wparexec command returns synchronously with the return code of this tracked process only when all of the processes in the workload partition terminate. For example, if the tracked process creates a daemon and exits with the 0 return code, the wparexec command will block until the daemon and all of its children terminate, and then exit with the 0 return code, regardless of the return code of the daemon or its children.

Flags

Item Description
-1 Creates the configuration only. Causes the wparexec command to stop after creating the configuration of the application WPAR. The startwpar command must then be used to start the WPAR. Only advanced users can use the -1 option.
-a

Automatically resolves conflicting static settings if required. Resolvable settings are name, hostname, and network configuration.
-c Enables this workload partition to be checkpointed. This option is only valid when additional checkpoint-restart software is installed and configured. When this option is used, any file systems associated with this workload partition (for example, with the -M option) must be remote (for example, vfs=nfs).
-e existingwpar Uses an existing application workload partition as the source for specification data. Do not use the -e flag with the -f flag. Any values specified by other wparexec flags override those values from the existing workload partition.
-f infile Indicates the specification file to read default values from. Do not use with the -e flag. Any values specified by other wparexec flags override those values from the loaded specification file.
-F Suppresses or overrides most error conditions. With the -F flag, the wparexec command continues with a warning.
-h hostname Specifies a host name for this workload partition. If not specified, the wparexec command uses the workload partition name as host name.
-H architecture Creates an architecture-compatible workload partition. Valid architecture values are pwr4, ppc970, pwr5, pwr6, and pwr7. The architecture value must be earlier, or equal to, the system hardware version. The applications in the workload partition are presented with the lowest common denominator of the specified architecture. If the workload partition can create a checkpoint, the workload partition is able to migrate between systems with hardware levels greater than, or equal to, the workload partition architecture.
Note: The POWER5 processor-based systems and BladeCenter JS21 Express systems are not compatible with each other. You cannot create a JS21-compatible (ppc970) WPAR on a POWER5 processor-based system even though the JS21 using an earlier processor than a POWER5 processor-based systems.
-i Enables WPAR-specific routing for the workload partition. By default, outgoing network traffic from a workload partition is routed like it is being sent from the global environment, notably in the following ways:
  • Traffic between addresses that were hosted on the same global system is sent through the loopback interface.
  • Routing table entries that are configured in the global system, including the default route, are used to transmit workload partition traffic.
If you enable WPAR-specific routing by specifying the -i flag, the workload partition creates and uses its own routing table for outgoing traffic. Routing entries are created automatically for each of the network addresses of the workload partition to accommodate broadcast, loopback, and subnet routes. For more information about the network attributes, see the -N flag. You can create explicit additions to the routing table of the workload partition using the -I flag. In particular, you can use the -I flag to configure the default route, as no default route is created automatically.
-I attribute=value ... Adds routing table entries to the entries that are automatically created when WPAR-specific routing is in effect. You can specify more than one -I flag to configure multiple routes. Using the -I flag automatically enables WPAR-specific routing as described under the -i flag.

You can specify the following attributes with the -I flag. The rtdest attribute and the rtgateway attribute are required to be specified.
rtdest=destination 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 route rtdest attribute, see the Destination parameter of the route command.
rtgateway=gateway 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.

61Vrtfamily ={inet|inet6}

 Specifies the address family. For information about the parameters of the rtfamily flag, see the parameter section of the route command.
-M directory=dir [ vfs=type ] [ dev=devicepath ] [ host=remotehost ] [ mountopts=mountopts ] Specifies file system dependencies only. Attributes must be space-separated. By default, an application workload partition has the same level of access to all of the global file systems and mounts as the user who created the workload partition. Use the -M flag with the directory attribute that is set to the file system name to specify additional file systems. More than one -M flag can be specified.
Note: All of the mounts and all of the directories are created and available at global level. File systems that are based on disk, such as the vfs=jfs and the vfs=jfs2, will not be created for application workload partitions.

A local file system dependency can be added by defining only the directory attribute. However, the directory specified must exist in the /etc/filesystems.

If an error occurs during the process of creating the workload partition, any file systems mounted by the wparexec command are unmounted. After the creation succeeds, the file systems are not unmounted, regardless of the return status of the user application.

The following are the valid values for the vfs attribute for application workload partitions:

nos
The directory specified by the dev attribute on the system specified by the host attribute is mounted at the location that is specified by the directory attribute. If the mount point does not exist, it will be created. The only other attributes that are applicable to an nfs mount are the mountopt attributes, corresponding to the -o option of the mount command or the options attribute in an /etc/filesystems stanza. If not specified, no mount options are used by default. Acceptable option values correspond to the -o options to the mount command. For more information, see the mount Command in AIX® Version 7.1 Commands Reference, Volume 3.
namefs
The global directory specified by the dev attribute is mounted over the directory specified by the directory attribute.

The only other attributes that are applicable to a namefs mount are the mountopt attributes.

directory
The global directory specified by the directory attribute is created if it does not exist. No mounting is performed.
-n wparname Specifies the name for the workload partition to be created. If no name is supplied, a name is generated.
-N attribute=value Allows specification of 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 name-mapped interface is defined 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

The attribute=value pairs must be separated by spaces. More than one -N flag can be used to configure multiple IP addresses. At minimum, the address or the address6 attribute must be specified. The wparexec command collects any other values that are not specified from the global system settings. If no -N flag is specified, the wparexec command will attempt to discover an appropriate IP address for the workload partition by running the gethostbyname subroutine on the workload partition name specified with the -n flag. If an address is found on the same subnet as any global interface, the settings of that interface will be used with the resolved IP address to create the default network entry.

To define an IPv6 network configuration, specify the -N flag with the address6 attribute, the prefixlen attribute, and the interface attribute:
  • The address6 attribute is a 128-bit address. The address is represented by eight 16-bit integers that are separated by colons. Each integer is represented by four hex digits. Leading zeros can be skipped, and consecutive null 16-bit integers can be replaced by two colons (one time per address).
  • The prefixlen attribute is the number of high-order bits that are used to mask the IPv6 address and to comprise the prefix. The value of the prefixlen attribute ranges from 0 through 128. Each -N flag can accept either IPv4 attributes, or IPv6 attributes, but not both.
-o outfile Indicates an output path and file name to write specification data to. This specification file can be used to create an application workload partition later with the -f flag.
-R attribute=value Allows specification of resource control attributes. Only one -R flag can be specified. Most resource controls are similar to those supported by the Workload Manager (WLM). See the listed WLM pages for descriptions of these attributes. Valid attributes are as follows:
active
Allows resource control definitions to be retained, but rendered inactive. This attribute can take the yes or no values.
rset
Configures this workload partition to use a resource set created by the mkrset command. For more information about the mkrset command, see mkrset Command in AIX Version 7.1 Commands Reference, Volume 3.
shares_CPU
The number of processor shares available to this workload partition. For more information about processor shares, see Workload Managershares File in in AIX Version 7.1 Files Reference.
CPU
The percentage of processor limits for this workload partition's processes. This attribute uses the following format to definite the limits values: 
CPU=<m>%-<SM>%,<HM>%

The m value represents the minimum limit. The SM value represents the soft maximum limit. The HM value represents the hard maximum limit. For more information about limited values, see the Workload Manager limits File in in AIX Version 7.1 Files Reference.

shares_memory
The number of memory shares available to this workload partition. For more information about memory shares, see Workload Managershares File in in AIX Version 7.1 Files Reference.
memory
The percentage of memory limits for this workload partition's processes. For more information about memory limit, see the Workload Manager limits File in in AIX Version 7.1 Files Reference.
procVirtMem
The maximum amount of virtual memory that a single process can use. 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 1M. The maximum limit that can be specified is 8796093022207M, 8589934591G, or 8388607T. If the value is set to -1 (no units), the limit is disabled. For more information about limit values, see Workload Managerlimits File in in AIX Version 7.1 Files Reference.
totalVirtMem
The maximum amount of virtual memory that can be used 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 Managerlimits File in AIX Version 7.1 Files Reference.
totalProcesses
The total number of processes that are allowed in this workload partition. For more information about allowed processor number, see Workload Manager limits File in in AIX Version 7.1 Files Reference.
  (Attributes for the -R flag, continued):
totalPTYs=n
The total number of pseudo terminals that are allowed in the workload partition. For more information about the allowed pseudo terminals, see pty Special File.
totalLargePages=n
The number of large pages that can be allowed for the workload partition. For more information about the allowed large pages, see Large Pages.
pct_msgIDs=n%
The percentage of the maximum number of message queue IDs of the system that are allowed in the workload partition. For more information about the allowed number of message queue IDs, see Message Queue Kernel Services.
pct_semIDs=n%
The percentage of the maximum number of semaphore IDs of the system that are allowed in the workload partition.
pct_shmIDs=n%
The percentage of the maximum number of shared memory IDs of the system that are allowed in the workload partition. For more information about the allowed number of shared memory IDs, see Shared Memory.
pct_pinMem=n%
The percentage of the maximum pinned memory of the system that can be allocated to the workload partition. For more information about pinned memory, see Support for pinned memory.
totalThreads
The total number of threads that are allowed in this workload partition. For more information about allowed number of threads, see Workload Manager limits File in in AIX Version 7.1 Files Reference.
-u userscript Specifies the path to a user script to be run by the workload partition commands at various administration points. The parameter of the -u flag can be a quoted string including additional arguments to be passed to the script. In all cases, the first component of the parameter of the -u flag must be an absolute path to an existing executable file. The script is invoked as follows: 
/path/to/userScript<action><WAPR>

The action argument indicates the administrative action being performed, as follows:

  • WPAR_LOAD: A script runs in the global environment after kernel configuration, before the tracked process is created. If the script returns a value of non-zero, the workload partition will not be started.
  • WPAR_START: A script runs in the global environment after the workload partition becomes active. For application workload partitions, the script runs once the tracked process is started.
    Note: This code path can be run asynchronously by a dissociated process with its standard I/O streams closed or redirected. Internal messaging must be handled accordingly, and the script must account for the fact that short-lived workload partitions might be stopped or stopping at any point during the execution of the script.

    If the script returns a value of nonzero, a warning is logged, but no other behavior changes.

  • WPAR_STOP: A script runs in the global environment after all of the workload partition processes finish, and before the kernel is unconfigured.
Note: This code path can be executed by a dissociated process with its standard I/O streams closed. Internal messaging should be handled accordingly.

If the script returns a value of non-zero, a warning will be logged, but no other behavior will change.
-v

Specifies the command to run in the verbose mode.
-x

Allows access to cross-WPAR semaphores and shared memory segments.
-w Writes the specification file. When it is used with the -o flag, the -w flag causes the wparexec command to quit after writing the new specification file without actually creating the workload partition.
[--] [var=value] /path/to/command [arg ...]

Specifies the application (tracked process) to be run within the workload partition, along with any necessary environment variable settings and arguments.

The command is required, either by this command-line syntax or the general.application attribute in the specification file, unless the command is only creating a specification file (with -w flag). When it is started, the command line provided is always shell-expanded within the workload partition. When using the command line, shell metacharacters should be escaped appropriately to prevent premature expansion.

The special double-minus separator (--) is used to signify that all subsequent command-line arguments comprise the tracked process. For example, use this separator to remove ambiguity between attributes to the -N flag and assignment of environment variables to the tracked process.

Only one tracked process per workload partition is supported, but this application might create other processes. The workload partition is automatically stopped and removed when all of the processes therein terminate. A workload partition might be stopped and removed prematurely by the stopwpar command.

Security

Access Control: Only the root user can run this 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 AIX Version 7.1 Security. For a list of privileges and the authorizations associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

  1. To create an application workload partition that is running a benchmark program, enter: 
    wparexec -n tpcc -N address=192.168.0.51 /u/tpcc/benchmark -f /tmp/logfile
    Note: The -f flag is passed to the /u/tpcc/benchmark file and is not processed by the wparexec command as a flag.
  2. To create a workload partition based on an existing specification file, enter: 
    wparexec -f /tmp/wparexec1.spec
  3. To override the default minimal PATH variable provided by the wparexec command, enter: 
    wparexec PATH=/usr/opt/bin:/usr/bin:/usr/sbin /home/joe/runapp

Files

Item Description
/usr/samples/wpars/sample.spec An annotated workload partition specification file.