mkwpar Command

Purpose

Creates a system workload partition (WPAR), or a WPAR specification file.

Syntax

/usr/sbin/mkwpar [-a] [-A] [-b devexportsfile ] [-c] [-C] [-E directory] [-d directory ] [-B wparbackupdevice] [-D attribute=value ...] ... [-F] [-g vg ] [-h hostname] [-i] [-I attribute=value ...] [ -k]... [-l] [-L attribute=value...] [-M attribute=value ...] ... [-N attribute=value ...] ... [-P] [-r] [-R attribute=value ...] [-S attribute[+|-]=value ...] [-s] [-u userscript] [ -X attribute=value ...] [-U [uuid]] { -n wparname [-p [name]] [ -e existingwparname | -f infile] [-o outfile [-w]] | -p [name] [-n wparname] [ -e existingwparname | -f infile] [-o outfile [-w]] | -f infile [-n wparname] [-p [name]] [-o outfile [-w]] | -w -o outfile [-n wparname] [-p [name]] [ -e existingwparname | -f infile] }

Note: White space must be included between a flag and its argument for attribute=value type flags. The mkwpar command is not supported on the TCB systems. Regardless of locale, only ASCII characters are allowed as arguments to mkwpar, chwpar, or wparexec

In addition to the previous command restrictions, more restrictions follow for the WPAR name:

Must not be more than 25 bytes.
Must not contain white space or any of the following symbols:
```
= : / ! ; ` ' " < > ~ & ( ) * + [ ] , . ^ 0 { } | \
```
Must not start with hyphen (-) or 0.

Description

The mkwpar command builds the infrastructure to prepare a system workload partition for use. This command includes the following tasks:

Creating the configuration data of the workload partition in the workload partition database
Creating and populating file systems of the workload partition
Creating an SRC subsystem for the init process of the workload partition
Defining the resource control profile of the workload partition through Workload Manager

The following options are also available:

Writing a specification file to simplify creation of other, similar workload partitions
Starting the workload partitions
Specifying whether the workload partitions must be automatically started on system start or when /etc/rc.wpars is started

The mkwpar command supports advanced logical volume and file system options by specifying the image.data file as an argument to the mkwpar -L flag.

The mkwpar command supports creating a Rootvg WPAR, in which the root file systems are located solely in WPAR storage devices.

Flags

Item	Description
-a	Automatically resolves conflicting static settings if required. Resolvable settings are base directory, host name, and network configuration.
-A	Specifies that the workload partition must be started each time /etc/rc.wpars is run, which is added to the global /etc/inittab to run each time that the system starts. The default is not to start the workload partition automatically. Tip: The workload partition is started immediately upon completion of the mkwpar command. To start the workload partition immediately, use the -s flag.
-b devexportsfile	Specifies an alternate file to use as the master device exports file. This file must match the format of a Device Exports File. If you do not specify a file name, /etc/wpars/devexports is used.
-B wparbackupdevice	Specifies a device containing a workload partition backup image. This image is used to populate the workload partition file systems. The wparBackupDevice parameter is a workload partition image that is created with the savewpar, mkcd, or mkdvd command. The -B flag is used by the restwpar command as part of the process of creating a workload partition from a backup image. Note: The -B flag is mutually exclusive with the -p flag.
-c	Configures the workload partition to be checkpointable. This option is valid only when more checkpoints or restart software are installed and configured. When you specify this flag, any file systems that are associated with only this flag (for example, through the -M flag) must be remote (for example, vfs=nfs).
-C	Creates a versioned workload partition. This option is valid only when more versioned workload partition software are installed.
-d directory	Specifies a base directory for the workload partition. If you do not specify a directory name, /wpars/<wparname> is used.
-D [devname=device name \| devid=device identifier] [rootvg=yes \| no] [devtype=[clone \| pseudo \| disk \| adapter \| 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 command is the full path to the device (that is, /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 applies only to disk, cdrom, or tape type devices. devtype=[clone \| pseudo \| disk \| adapter \| cdrom \| tape] Specifies the device type of the device to allocate to the workload partition. rootvg= [yes \| no] Used to indicate whether the specified disk device is to be used as a rootvg workload partition device. If the rootvg attribute is not specified, the command takes the default of number.
-e existingwparname	Specifies a directory which contains more filesets to install when a versioned workload partition is created. If you do not specify a directory name, `/usr/sys/inst.images` is used. This option is used only during creation of a versioned WPAR.
-f infile	Indicates a specification file from which default values are read. This flag is mutually exclusive with the -e flag. Any values that you specify by using other mkwpar flags override those flagsfrom the loaded specification file.
-F	Forces the command to continue rather than fail for most error conditions.
-g vg	Indicates the default volume group. If you do not specify a value, rootvg is used. This volume group is used for each localfs file system whose volume group is not specified by using the vg parameter of the -M flag. Volume group specifications for file systems that you specified in the image.data file supersede the volume group that is specified with the -g flag.
-h hostname	Specifies a hostname for the workload partition. you do not specify a value, the mkwpar command uses the workload partition name for the host name.
-i	Enables WPAR specific routing for the workload partition. By default, outgoing network traffic from a workload partition is routed as if it is being sent from the global environment: Traffic between addresses that are 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 if wanted, because no default route is created automatically.
-I attribute=value ...	Adds routing table entries to those tables 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:
	rtdest=destination		(Required) Identifies the host or network to which you are directing the route. You can specify the value by using either symbolic name or 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		(Required) Identifies the gateway to which packets are addressed. You can specify the value using either symbolic name or 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.
-k	Specifies the path to a user provided postinstallation customization script. The script is run in the global environment after the WPAR is created while WPAR filesystems are mounted. The postcustomization script is called with the WPAR name as the first argument, and the WPAR base directory as the second argument. If the script exits with a nonzero return code, a warning is printed, but the mkwpar command has not failed.
-l	Creates private and writable versions of the /usr and /opt file systems.
-L [image_data= imagedatafile ] [shrink= {yes\|no}] [ignore_maps= {yes\|no}]	image_data Specifies the path to the image.data file to be used for logical volume and file system options. The format of the image.data file is described in AIX® Version 7.1 Files Reference and the /usr/lpp/bosinst/image.template file. File system specifications in the image.data file supersede file system specifications in the Specifications File. The -c flag and -L image_data= flags are mutually exclusive. shrink Specifies that the LV_MIN_LPS attribute, rather than the LPs attribute, must be used to determine the number of logical partitions for the logical volume. The LV_MIN_LPS attribute is from the lv_data stanzas from the file that the image_data attribute specifies. This attribute can minimize the amount of disk space that is required for a workload partition file system. This attribute has no effect if the image_data attribute is not specified. ignore_maps Specifies that the MAPFILES attribute must not be used to provide a disk mapping for the logical volumes that are associated with a workload partition. The MAPFILES attribute is from the lv_data stanzas from the file that the image_data attribute specifies. This attribute has no effect if the image_data attribute is not specified. ignore_lvs Specifies that the information from the lv_data stanzas is not used when the image.data file is being processed. The logical volumes are created with the default characteristics when the file systems are created. This attribute has no effect if the image.dita attribute is not specified. If this attribute is specified, the ignore_maps attribute is ignored.
-M directory=dir [ vfs=type ] [ size=sizespec ] [ vg=volumegroup ] [ logname=loglv ] [ dev=devicepath ] [ host=remotehost ] [ = ] [ mountopts=mountopts ]	Specifies mount configuration attributes. Attributes must be separated by a blank space. You can specify more than one -M flag. By default, the /usr and /opt file systems of the workload partition are mounted over the global /usr and /opt file systems in read-only mode. The /proc file system of the workload partition is mounted over the global /proc file system in read-write mode. New logical volumes that are created in rootvg for /, /var, /tmp, and /home. The default settings for a specified file system can be overridden byusing the -M flag with the directory attribute set to the file system name. You can specify more file systems with additional -M flags. The directory attribute denotes the directory within the workload partition where the device must be mounted. File system specifications in the -M flag supersede file system specifications in the image.data file. There are four basic workload partition mount forms:
	localfs	Disk-based file system (vfs=jfs or vfs=jfs2) to be created at the location that is specified by the value of the directory within the directory structure of the workload partition. If you specify a dev attribute, it denotes an existing logical volume in the global environment, which is to be used to host the file system. For localfs file systems, you must specify the size attribute. Other optional attributes, which are of the form attr=value, include those attributes in the following list:
		logname	Specifies the log device to use for this file system. This attribute must be specified only if the default log device that the file system uses is insufficient. For vfs=jfs2, the default is to use an inline log. For vfs=jfs, the default is that the file system uses an existing log device if available. Otherwise, it creates one. When the logname attribute is being specified, make sure that the named log device exists.
		mode	Specifies the octal permission mode to assign to the base directory of this file system. The default is 755.
		size	Specifies the size of the file system that is created in a format acceptable to the crfs command.
		vg	Specifies the volume group in which the file system (if no existing logical volume device is specified by using the dev attribute) is created. If you do not specify a value, the volume group that is specified in the -g flag is used. If you do not specify the -g flag, rootvg is assumed.
			Specifies other options to pass to the crfs command when the file system is being created. Options are passed directly to the crfs command so the value must be in the form that is required by the crfs command.
-M directory=dir [ vfs=type ] [ size=sizespec ] [ vg=volumegroup ] [ logname=loglv ] [ dev=devicepath ] [ host=RemoteHost ] [ = ] [ mountopts=mountopts ] (continued)			Restriction: Do not specify any options to the crfs command that correspond to the flags in the mkwpar command must not be specified by using the attribute because incorrect results might occur. The following options can be used: -a logname=lvname (logname) -a size=value (size) -d device (dev) -g volumegroup (vg) -m mountpoint (directory) -v vfstype (vfs) For more information, see crfs documentation for further information about the crfs command.
		mountopts	Specifies the mount options (corresponding to the "options" attribute in an /etc/filesystems stanza). If you do not specify a mount option, by default, no mount flags are used. Option values that you can specify correspond to the -o options of the mount command.
	namefs	Specifies that the global directory that is specified by the dev attribute is mounted over the directory that is specified by the directory attribute in the file system structure of the workload partition. The only other attribute that is applicable to a namefs mount is mountopts. For the namefs type, you cannot map the /, /var, /opt, or /usr file system of a workload partition with write privileges to a real /, /var, /opt or /usr file system.
	nfs	Specifies that the directory that is specified by the dev attribute on the system exported by the host attribute is mounted over the workload partition directory. The only other attribute that is applicable to an nfs mount is mountopts. Requirement: The global system and the workload partition must both have root permissions to the NFS device. You can give the global and the WPAR root permission to the NFS device, when exporting the NFS mount, by specifying the root access for the host names of both the global system and the workload partition. When an NFS device is mounted, you cannot map the /, /var, /opt, or /usr file system of a workload partition with write privileges to a real /, /var, /opt, or /usr file system.
	directory	Specifies that the directory that is specified by the directory attribute is added to the file system structure of the workload partition. No file system is created. Use this attribute to reduce the number of file systems to manage in a workload partition, such as by eliminating the separate file systems for /tmp and /var. Ensure that the size of the containing file system is adjusted accordingly. Note: A directory mount cannot be used for /usr or /opt.
-n wparname	Specifies the name for the workload partition to be created. You must specify a name, either by using the -n flag, or in a specification file by using the -f flag, unless the -p name or both -w and -o flags are used.
-N attribute=value	Specifies network configuration attributes. Separate the attribute=value pairs by blank spaces. You can specify more than one -N flag to configure multiple IP addresses. You must always specify the address or the address6 attribute when you use the -N flag. Any other values that are not specified are taken from the settings of the global system. If you do not specify the -N flag, the mkwpar command attempts to discover an appropriate IP address for the workload partition. To do that, the mkwpar command performs the gethostbyname subroutine on the workload partition hostname (specified with the -h flag). If no -N flag is specified and no hostname is specified, the mkwpar command attempts to discover the IP address by performing the gethostbyname subroutine on the workload partition name (specified with the -n flag). If you can find an address on the same subnet as any global interface, use that interface settings with the resolved IP address to create the default network entry. You can specify the following attributes for the -N flag: 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` To define an IPv6 network configuration, specify the -N flag with the address6, prefixlen, and interface attributes. 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 4 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 which to write specification data. This specification file can then be used to create a workload partition at a later time using the -f flag.
-O	This flag is used to force an existing volume group to be overwritten on a particular set of devices, specified with the -D rootvg=yes flag directive. If not specified, the overwrite value defaults to FALSE. This flag must be specified only once, as its setting is applied to all devices specified with the -D rootvg=yes flag directive.
-p [name]	Indicates that the workload partition's file systems exist and must be preserved, which means the root part must not be populated. You must specify the existing file systems to the mkwpar command in one of the following two ways: Use the name parameter to specify an existing mount group in /etc/filesystems. Such a mount group usually exists because a previous workload partition was removed by using rmwpar -p. If you specify the name parameter, it cannot match the name of an existing workload partition on the system. If you specify the -d flag, the mount points of the file systems are adjusted accordingly. If you do not specify the -d flag, the workload partition's base directory is determined based on the mount points that are associated with the discovered file systems. If the file systems are not defined in /etc/filesystems, use the -p flag with the -M flag or mount stanzas in the specification file to define the attributes of the file systems. If you specify the -p flag with the name parameter, and no workload partition name is provided by using other means (for example, the -n flag or general.name in the specification file), you can also use the name parameter as the workload partition name. Note: The -p flag is mutually exclusive with the -B flag.
-P	Sets the root password for the workload partition. The mkwpar command prompts you for the password interactively.
-r	Duplicates the network name resolution configuration from the global system. The following files, if they exist, are copied into the workload partition: /etc/resolv.conf /etc/hosts /etc/netsvc.conf /etc/irs.conf /etc/networks If the NSORDER environment variable is defined in the calling environment, it is added to the workload partition's /etc/environment file.
-R attribute=value	Allows specification of resource control attributes. You specify only one -R flag. Most resource controls are similar to those resource control attributes that are supported by Workload Manager. You can use the following attributes:
	active={yes\|no}
		Active=no means that the resource attributes are defined but the resource controls are not activated when the WPAR is started. Active=yes means that the resource control attributes are activated when the WPAR starts. Tip: If this field is set to 'no', performance metrics such as CPU and memory usage are not available by using such commands as topas and wlmstat, either inside and outside of the workload partition.
	rset=rset
		Configures the workload partition to use a resource set that was created by the mkrset command.
	shares_CPU=n
		Specifies the number of processor shares that are available to the workload partition.
	CPU=m%-SM%,HM%
		Specifies the percentage processor limits for the processes of the workload partition.
	shares_memory=n
		Specifies the number of memory shares that are available to the workload partition.
	memory=m%-SM%,HM%
		Specifies the percentage memory limits for the processes of the workload partition.
	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 that is allowed is 1 MB. 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 Manager limits File.
	totalVirtMem=n[M\|MB\|G\|GB\|T\|TB]
		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 are terminated. The valid range and units are the same as procVirtMem. If you set the value to -1 (no units), the limit is disabled. See Workload Manager limits File.
	totalProcesses=n
		Specifies the total number of processes that are allowed in the workload partition. See Workload Manager 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 can be 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. See Workload Manager limits File.
rootvg=yes\|no	Used to indicate whether the specified disk device is to be used as a rootvg WPAR device. If the rootvg option is not specified, the command takes the default of no.
-s	Starts the workload partition after it is created.
-S secfile = /path/to/secattrs privs[+\|-] = list	Configures the set of privileges that can be assigned to processes that are running in a system workload partition. You can provide privileges in a specification file (see the -f flag), in a separate security attributes file through -S secfile=/path/to/secattrs, or on the command line by using the -S privs=list flag. If you do not provide security attributes through one of these mechanisms, the /etc/wpars/secattrs file is used by default. When you use a separate security attributes file (either the default file or the file that is supplied through -S secfile), this file is read once when the workload partition is created to determine the privileges that are associated with the workload partition. Subsequent changes to the file have no effect on existing workload partitions. The default security attributes file /etc/wpars/secattrs must not be modified directly as it might be overwritten in the future. If you use a base list of privileges from a specification file or security attributes file (including the default), individual privileges can be added to or removed from the list by specifying -S privs+=list, -S privs-=list, or both. Separate attributes must be separated by a blank space and must be unique, which means secfile=, privs=, privs+=, and privs-= cannot be specified more than once. Privileges must be comma-separated (without spaces) and must be unique. Attributes are processed in the following order regardless of the order that is specified in either the command line or the specification file: The first attribute to be processed is the privs attribute without the + or - modifier. For example, privs=PV_AZ_READ,PV_AZ_ADMIN. If this attribute is found, no other attributes can be used. The next attribute to be processed is the secfile attribute. See the security stanza of the Specification File Format for details on the format of this file. If none of the attributes that are listed previously are specified, the /etc/wpars/secattrs file is used to populate the list of privileges. The next attribute to be processed is an attribute with the + modifier. For example, privs+=PV_DAC_UID,PV_AZ_ROOT. This command adds the specified privileges to the list of privileges that are specified in the security file. The final attribute to be processed is an attribute with the - modifier. For example, privs-=PV_AZ_ROOT. This command removes the specified privileges from the list of privileges that are specified in the security file. Tip: If you specify the -S flag on the command line, any security attributes in the specification file are ignored.
-u userscript	Specifies the path to a user script to be run by workload partition commands at various administration points. The parameter of the -u flag can be a string that is enclosed in quotation marks, including more arguments to be passed to the script. The first component of the parameter of the -u flag must be an absolute path to an existing executable file. The script is invoked in the following manner: `/path/to/userScript <action> <wparName>` The first argument indicates the administrative action that is being performed, as follows: WPAR_LOAD A script runs in the global environment after the kernel is configured, and before the tracked process is created. If the script returns a value other than zero, the workload partition cannot be started. WPAR_START A script runs in the global environment as soon as the workload partition becomes active. For system workload partitions, the script runs after the device configuration is complete. For application workload partitions, the script runs as soon as the tracked process is started. In the latter case, 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 other than zero, a warning is logged, but no other behavior changes. WPAR_STOP A script runs in the global environment after all workload partition processes finish, before the kernel is unconfigured. Note: This code path can be started by a dissociated process with its standard I/O streams closed or redirected to SRC logs. If the script returns a value other than zero, a warning is logged, but no other behavior changes The second argument is the name of the workload partition. The script can use the lswpar command to obtain any other necessary configuration data.
-U [Workload Partition UUID]	Specifies the Workload Partition UUID. If you do not specify the value, the UUID is automatically generated for the corresponding Workload Partition.
-w	Writes the specification file only. Used with the -o flag, the -w flag causes the mkwpar command to quit after the new specification file is written, without actually creating the workload partition.

Security

Access Control: Only the root user can run this command.

Examples

To create a workload partition called roy, enter the following command:
```
mkwpar -n roy -N address=192.168.0.51
```
All values that are not specified are generated or discovered from the global system settings.
To create a workload partition based on an existing specification file, enter the following command:
```
mkwpar -f /tmp/wpar1.spec
```
To create a modified copy of a specification file with a new IP address, host name, and workload partition name (without creating a workload partition), enter the following command:
```
mkwpar -f /tmp/wpar1.spec -N address=219.168.45.132 -h www.flowers.com -n wpar2 
-o /tmp/wpar2.spec -w
```
To create a specification file, which is based on an existing workload partition, enter the following command:
```
mkwpar -e wpar1 -o /tmp/wpar2.spec -w
```
To re-create a workload partition that was previously removed with the rmwpar -p command, enter the following command:
```
mkwpar -p wparname
```
To create a rootvg workload partition, enter the following command:
```
mkwpar -n test -D devname=hdisk1 rootvg=yes -O
```
To create a rootvg workload partition called wpar1 with the storage device on an adapter, enter the following command (assuming that hdisk3 is attached to the adapter, fcs2):
```
mkwpar -n wpar1 -D devname=fcs2 -D devname=hdisk3 rootvg=yes
```

Files

Item	Description
/etc/wpars/devexports	Default device export control file for workload partitions.
/etc/wpars/secattrs	Default security file for workload partitions.
/usr/samples/wpars/sample.spec	An annotated workload partition specification file.