lswpar Command

Purpose

Lists characteristics of workload partitions.

Syntax

Tabular Formats:

lswpar [-D | -I | -M | -N ] [ -X ] [-a fieldname [,...]] [-q] [-s state] [-t type] [wparname ...]

Paragraph Formats:

lswpar {-G | -L | -R | -S | -T} [-s state] [-t type] [wparname ...]

Delimited Formats:

lswpar {-c | -d delim} [-a fieldname [,...] | -G | {-D | -X -I | -M | -N} [-a fieldname [,...]] | -R | -S | -T] [-q] [-s state] [-t type] [wparname ...]

Description

The lswpar command prints information about one or more specified workload partition (or all workload partitions if none are specified) to standard output.

You can filter all listings according to the following workload partition states using the -s flag:

Item Description
Defined The workload partition has been defined by the mkwpar command and is ready for use, but is not active. Start workload partitions in this state with the startwpar command.
Loaded The workload partition has been configured in the kernel, but processes have not yet been started.
Note: This state is visible only to programmatic consumers that use the lswpar command to start a workload partition.
Active The workload partition is running normally.
Frozen A checkpoint operation is initiated, and the processes of the workload partition are quiesced, awaiting the storing phase.
Note: The Frozen state is only visible when you use the lswpar command to checkpoint a workload partition. The checkpoint or restart function requires additional software package other than base WPAR.
Paused A checkpoint or restart operation has been performed, and the processes of the workload partition are ready to be resumed or killed. The checkpoint or restart functionality requires additional software.
Maintenance A workload partition can be put into maintenance mode with the startwpar command. During maintenance mode, the workload partition has been configured in the kernel and the file systems have been mounted, but processes do not start.
Moving An asynchronous checkpoint-restart operation has been performed. Although the workload partition is Active on the arrival server, the workload partition appears in the Moving state on the departure server until all resources have been successfully transferred. The checkpoint or restart functionality requires additional software.
Transitional An administrative operation is in progress. The workload partition is in the process of being created, started, stopped, configured, and so on.
Broken An administrative operation failed, leaving this workload partition in an unusable state.
Error An error occurred due to invalid elements such as workload partition name and flags.

You can filter all listings according to the following workload partition types using the -t flag:

Item Description
Application This is an application workload partition, running a single process (or a group of processes invoked by that means) without isolated system services. The process or group of processes inherits its operating environment (file systems, security, devices. and so on) from the environment where the application workload partition was created.
System This is a system workload partition, emulating an independent, fully-functional instance of the operating system.

If additional checkpoint or restart software is installed, you can also specify the following type:

Item Description
Checkpointable This workload partition is enabled for checkpoint or restart functions.
Tip: This is not a mutually exclusive workload partition type. Checkpointable workload partitions are still either System or Application workload partitions.
If additional versioned workload partition software is installed, you can also specify the following type:
Item Description
Versioned This workload partition is running in operating system compatibility mode.
Tip: This is not a mutually exclusive workload partition type. Versioned workload partitions are still System workload partitions.
Versioned

Tabular Formats

If no options are used, the output is tabular as shown in the following example:

Name         State    Type    Hostname    Directory   RootVG WPAR
-------------------------------------------------------------------
wpar name    state    type  hostname    root directory   yes/no
...            ...    ...   ...           ...             ...

In tabular formats, there might be multiple records per WPAR. The -D, -I, -M and -N flags display in a tabular format, but can be combined with the -c and -d flags to generate a delimited format. You can use the -a flag to customize which fields appear in tabular formats. You can use the -q flag to suppress the table headers.
Tip: Do not rely on the exact format and content of tabular output for automated purposes. Delimited formats are provided for output that can be parsed.
The width of each field in a tabular format is expanded according to the longest value in that column. Therefore, the output might wrap on narrow screens, depending on the fields requested.

Paragraph Formats

In paragraph formats, each field has one value for one WPAR. You can use the -G, -R, -S, and -T flags to display paragraph-style subsets of workload partition configurations. The -L flag displays a long listing, which is a combination of the data presented by the -D, -G, -I, -M, -N, -R, -S, and -T flags. Otherwise, formats cannot be combined.

Delimited Formats

Delimited formats is used to produce machine-readable formats. You can select any delimiting characters. You can generate delimited formats using the -c or -d flag. You can use the -a flag to customize which fields are displayed. You can use the -q flag to suppress the header line. The paragraph format flags (-G, -R, -S, and -T) and tabular format flags (-D, -I, -M and -N) can be used individually to limit the display to the corresponding predefined set of fields.

Flags

Item Description
-a fieldname

Limits tabular or delimited displays to the specified one or more fields. Multiple field names must be separated by commas with no spaces. This flag is mutually exclusive with the -G, -R, -S, -L, or -T flag.

By default, the display consists of one WPAR per line. You can specify any of the following fields:

General
  • Name (the WPAR name)
  • Cid (the ID of aWPAR
  • Key (the key of a WPAR
  • Rootvgwpar RootVG WPAR (A yes/no value is displayed to identify whether the WPAR is a RootVG WPAR
  • Uuid (the UUID of a WPAR
  • Vipwpar VIP WPAR (A yes/no value is displayed to identify whether the WPAR is a VIP WPAR. This field only applicable for an Application WPAR
  • State
  • Type (system or application)
  • Hostname
  • Routing
  • Directory
  • Privateusr
    The sample output is displayed as following:

    0> lswpar -a name,privateusr test
    Name   Private /usr?
    --------------------
    test   no          

  • Script (user-supplied start or stop script)
  • Auto
    • If the value for this field is yes, the process is automatically started on global system boot.
    • If the value for this field is no, the process is not automatically started on global system boot.
  • Application (tracked process for application WPARs)
  • Checkpointable
  • Owner
  • OStype (a non-zero value indicates a versioned WPAR, a value of 0 or null indicates a native WPAR)
Resource Controls
  • Active
    • If the value for this field is yes, resource controls are active
    • If the value for this field is no, resource controls are inactive
  • Rset
  • Shares_CPU
  • CPU
  • Shares_memory
  • Memory
  • ProcVirtMem
  • TotalProcesses
  • TotalThreads
  • totalPTYs
  • totalLargePages
  • totalVirtmem
  • pct_msgIDs
  • pct_semIDs
  • pct_shmIDs
  • pct_pinMem
  (Fields that you can specify with the -a flag, are as follows)
Devices
  • Name (the name of the WPAR)
  • Devname (the name of the device)
  • Devtype (pseudo, disk, clone)
  • Rootvg
The display consists of one device per line. The following displays sample output:

0> lswpar -Da name,devname,rootvg test
Name   Device Name      RootVG
------------------------------
test hdisk1           yes  

0> lswpar test
Name   State   Type Hostname   Directory    RootVG WPAR
------------------------------------------------------
test   D     S     test       /wpars/test  yes

Kernel Extensions
  • Name (the name of the WPAR)
  • Kext (the full path to the kernel extension)
  • Local
  • Major
  • kextstatus (allocated or exported)
  • checksum (checksum of the kernel extension)
  • mtime (modification time of the kernel extension)
The display consists of one kernel extension per line.

WPAR-Specific Routes

A workload partition might have more than one route. So if you use the -I flag, you can specify the -a flag with the following fields:
  • name (the WPAR name)
  • rtdest
  • rtgateway
  • rtinterface
  • rttype
  • rtfamily
The display consists of one route per line.

Networks

A WPAR might have more than one network. So when you use the -N flag, you can specify the -a flag with the following fields:
  • Name (the WPAR name)
  • Interface
  • Address
  • Netmask
  • Broadcast
The display consists of one network per line.
 

Mounts

A workload partition might have more than one mount. So when you use the -M flag, you can specify the -a flag with the following fields:
  • Name (the WPAR name)
  • Mountpoint (the mount point name)
  • Device (the object mounted)
  • Vfs (the virtual-file-system type)
  • Nodename (node name, if the mount is remote)
  • Options (any mount options)
The display consists of one mount per line.
Security
  • Privs (the list of privileges)
Operation
  • Opname (the name of the administration operation being performed)
  • Oppid (the process ID of the operation)
  • Opstart (the start time of the operation)
-c Produces colon-separated output suitable for machine parsing. It is mutually exclusive with the -L flag. The default output format (when the -D, -G, -I, -M, -N, -R, -S, and -T flags are not used) is as follows:

name:state:type:hostname:directory

The state field is one or more of the following valid states:
D
Defined
L
Loaded
A
Active
F
Frozen
P
Paused
N
Maintenance
M
Moving
T
Transitional
B
Broken
E
Error
The type field is one or more of the following valid types:
A
Application workload partition
S
System workload partition
L
Versioned system workload partition
-d delim Produces delimiter-separated output suitable for machine parsing. It is mutually exclusive with the -L flag. The output format when the -d flag is specified is the same as with when the -c flag is specified, but with delim as the delimiter output between fields.
-D Produces detailed device information for each requested WPAR. It is mutually exclusive with the -G, -I, -L, -M, -N, -R, -S, or -T flag. If the -c or -d flag is not specified, each WPAR output has the following tabular format:

===============================
Name - Device Name - Type - Virtual Device - RootVG - Status

-G Produces detailed general setting information for each requested WPAR. It is mutually exclusive with the -I, -L, -M, -D, -N, -R, or -T flag. If you do not specify the -c or -d flag, each workload partition output has the following paragraph format:

================
Name - State
================
Type:                   {S|A}
Hostname:               HostnameWPAR
-Specific Routing:  {yes|no}
Directory:              Directory
Start/Stop Script:      /path/to/userScript
Auto Start:             {yes|no}
Private /usr:           {yes|no}
Checkpointable:         {yes|no}
Application:            /path/to/trackedProcess
Owner:
Architecture: WPAR compatibility architecture
OStype: <i>Integer value representing operating system type<i>
Cross-WPAR IPC: {yes|no}
UUID:                   String value representing universally unique ID

With the -c or -d flag, the output is as follows:

name:state:type:rootvgwpar:hostname:routing:directory:owner:script:
auto:privateusr:checkpointable:application:ostype

-I Produces detailed information about user-specified network routes. The -I flag is mutually exclusive with the -D, -G, -L, -M, -N, -R, -S, or -T flag. The -I flag only displays routing table entries that are explicitly specified with the -I flag of the mkwpar, wparexec, or chwpar command. To see the full routing table for a workload partition, use the netstat command with the -r and -@ flags. If you do not specify the -c or -d flag, tabular output is as produced as shown in the following example:
Name      Type        Destination   Gateway     Interface
---------------------------------------------------------------
name      net|host    destination   gateway     if
...       ...         ...           ...         ...
With the -c or -d flag, delimited output is produced as shown in the following example:
name:rttype:rtdest:rtgateway:rtinterface:rtfamily
You can use the -I flag with the -a flag to limit the output to any combination of the following fields:
  • name (the workload partition name)
  • rtdest
  • rtgateway
  • rtinterface
  • rttype
  • rtfamily
-L

Specifies long format. Produces detailed paragraph-formatted information for each requested workload partition. It is mutually exclusive with the -c, -d, -D, -G, -I, -M, -N, -q, -R, -S, or -T flag.

If you want to parse data, do not use the -L output. Use the delimiter-separated forms (the -c or -d flag) for generating output that can be parsed. Each workload partition has formatted output similar to the following example:

================
Name - State
================
GENERAL
Type:               {S|A}
Hostname:           HostnameWPAR
-Specific Routing:  {yes|no}
Directory:          Directory
Start/Stop Script:  /path/to/userScript
Auto Start:         {yes|no}
Private /usr:       {yes|no}
Checkpointable:     {yes|no}
Application:        /path/to/trackedProcess
Owner:
OStype: <i>Integer value representing operating system type<i>
Cross-WPAR IPC:     {yes|no}
Architecture:WPAR compatibility architecture
UUID:                  String value representing universally unique ID

NETWORK
Interface     Address           Mask/Prefix       Broadcast
---------------------------------------------------------------
if  A.B.C.D A.B.C.D        A.B.C.D
...        ...          ...            ...

USER-SPECIFIED ROUTES
Type        Destination   Gateway     Interface
---------------------------------------------------------------
net|host    destination   gateway     if
...         ...           ...         ...

FILESYSTEMS
MountPoint            Device         Vfs     Nodename   Options
-------------------------------------------------------------
mountpoint  device  vfs  node    options
...         ...     ...  ...     ...

  (A long-format example by the -L flag, is as follows)

RESOURCE CONTROLS
Active:                                  {yes|no}
RSet:                                    rset
CPU Shares:                              n
CPU Limits:                              m%-S%,H%
Memory Shares:                           n
Memory Limits:                           m%-S%,H%
Per Process Virtual Memory Limit:        nMB
Total Processes:                         n
Total Threads:                           n
Total PTYs:                              n
Total Large Pages:                       n
Max Message queue IDs:                   n%
Max Semaphore IDs:                       n%
Max Shared memory IDs:                   n%
Max Pinned memory:                       n%

OPERATION
Operation:  %c
Process ID: %p
Start time: %t


SECURITY SETTINGS
Privileges: privilege list
            

DEVICE EXPORTS
Name              Type        
Virtual Device        RootVG       Status
device name type virtual device name yes/no device status
                                

-M Produces detailed mount information for each requested workload partition. The file systems that are mounted from outside the workload partition are listed and the file systems that are defined within the workload partition are not included. The -M flag is mutually exclusive with the -G, -I, -L, -N, -R, or -T flag. If you do not specify the -c or -d flag, tabular output is produced as shown in the following example:

Name     MountPoint    Device    Vfs    Nodename  Options
----------------------------------------------------------
name   mountpoint   device   vfs   node     options
...   ...         ...     ...   ...     ...

With the -c or -d flag, delimited output is produced as shown in the following example:

name:mountpoint:device:vfs:nodename:options

It can be used with the -a flag to limit the output to any combination of the following fields:
  • Name (the workload partition name)
  • Mountpoint (the mount point name)
  • Device (the object mounted)
  • Vfs (the virtual-file-system type)
  • Nodename (node name, if the mount is remote)
  • Options (any mount options)
-N Produces detailed network information for each requested workload partition. It is mutually exclusive with the -G, -I, -L, -M, -R, -D, -S, or -T flag. If you do not specify the -c or -d flag, tabular output is produced as shown in the following example:

Name    Interface    Address(6)         Mask/Prefix       Broadcast
------------------------------------------------------------
name    if           A.B.C.D            A.B.C.D           A.B.C.D
...
name    if           S:T:U:V:W:X:Y:Z    R
...

With the -c or -d flag, delimited output is produced as shown in the following example:

name:interface:address:mask_prefix:broadcast

You can specify the -N flag with the -a flag to limit the output to any combination of the following fields:
  • Name (the WPAR name)
  • Interface
  • Address (the IPv4 or IPv6 address)
  • Mask_Prefix (the IPv4 netmask field or the IPv6 prefixlen field)
  • Broadcast

If a WPAR contains one or more name-mapped interfaces, the lswpar command shows only the information that is specified in the configuration file when the WPAR is in the Defined state. When the WPAR is in the Active state, the actual runtime network attributes are displayed.

Note: When a delimited output is expected to contain IPv6 addresses, use the -d flag to specify an alternative delimiter because IPv6 addresses contain colons.
-q Suppresses table headers (quiet). It is valid only for tabular and delimited output formats.
-R Produces detailed resource control information for each requested WPAR. It is mutually exclusive with the -G, -I, -L, -M, -N, -D, -S, or -T flag. If you do not specify the -c or -d flag, each workload partition output has the following paragraph format:

================
Name - State
================
Active:                                  {yes|no}
RSet:                                    rset
CPU Shares:                              n
CPU Limits:                              m%-S%,H%
Memory Shares:                           n
Memory Limits:                           m%-S%,H%
Per-Process Virtual Memory Limit:        nMB
Total Processes:                         n
Total Threads:                           n
Total PTYs:                              n
Total Large Pages:                       n
Max Message queue IDs:                   n%
Max Semaphore IDs:                       n%
Max Shared memory IDs:                   n%
Max Pinned memory:                       n%

With the -c or -d flag, delimited output is as shown in the following example:

name:state:active:rset:shares_CPU:CPU:shares_memory:memory:
procVirtMem:totalProcesses:totalThreads:totalPTYs:
totalLargePages:pct_msgIDs:pct_semIDs:pct_shmIDs:pct_pinMem

-s {[D] [L] [A] [F] [P] [N] [M] [T] [B]} Filters the output based on workload partition states. You can use more than one state code. See the -c flag for a description of the state codes.
-S Produces detailed security privilege information for each requested WPAR. It is mutually exclusive with the -D, -G, -I, -L, -M, -N, -R, or -T flag. If you do not specify the -c or -d flag, each workload partition output has the following paragraph format:

===============================
Name - State
===============================
Privileges:  comma-separated list of privileges assigned to the workload partition

-t {[A][S][C][L]} Filters the output based on workload partition types. You can use more than one type code. See the -c flag for a description of the type codes.
-T Produces detailed locking information for each requested workload partition. This flag is mutually exclusive with the -D, -G, -I, -L, -M, -N, -R, -S, or -s flag. It is mutually exclusive with the -q flag unless the -c flag is also specified. If you do not specify the -c flag, each workload partition output has the following format:

================
Name - State
================
Operation:  %c
Process ID: %p
Start time: %t

With the -c or -d flag, the output is as shown in the following example:

name:state:opname:oppid:opstart

-X Produces detailed kernel extension information for each requested workload partition in turn. It is mutually exclusive with the -D, -G, -I,-L, -M, -N, -R, -S, or -T flag. If the -c or -d flag is not specified, each workload partition output has the following tabular format:

Name      Extension Name     Local  Major  Status  checksum
---------------------------------------------------------------
name   /path/to/extension    local  major  status  checksum
...

wparname Specifies one or more workload partitions. It must be last on the command line. It can contain shell-style wildcards to match multiple workload partition names. (In this case, use appropriate shell quotation marks to preclude shell expansion before the lswpar command receives the metacharacters.)

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 view tabular information about all workload partitions, enter the following command:
    # lswpar
    Name        State  Type   Hostname            Directory     RootVG WPAR
    -----------------------------------------------------------------------
    bar         A      S      bar.austin.ibm.com  /wpars/bar      yes
    foo         D      S      foo.austin.ibm.com  /wpars/foo      no
    trigger     A      A      trigger             /                
  2. To view limited tabular information about application workload partitions only, enter the following command:
    # lswpar -t A -a name,application,script
    Name     Application                Script
    ------------------------------------------------------------
    trigger  /usr/sbin/apachectl start  /home/joe/trigger.script
  3. To view colon-separated general information with no headers for all active and defined workload partitions, enter the following command:
    # lswpar -G -c -q -s AD
    bar:A:S:bar.austin.ibm.com:/wpars/bar:/home/bar/wpar.scr:no:no:yes::no
    foo:D:S:foo.austin.ibm.com:/wpars/foo::no:no:no::no
    trigger:A:A:trigger:/:/home/joe/trigger.script
    :no:no:yes:/usr/sbin/apachectl start:no
  4. To view extended information about the workload partition named trigger, enter the following command:
     # lswpar -L trigger
    ================
    trigger - Active
    ================
    GENERAL
    Type:                   A
    Hostname:               triggerWPAR
    -Specific Routing:  yes
    Directory:              /
    Start/Stop Script:      /home/joe/trigger.script
    Auto Start:             no
    Private /usr:           no
    Checkpointable:         yes
    Application:            /usr/sbin/apachectl start
    
    NETWORK
    Interface    Address          Mask/Prefix      Broadcast
    -----------------------------------------------------------------
    en0          1.2.3.4          255.255.255.0    1.2.3.255
    en1          5.6.7.8          255.255.255.0    5.6.7.255
    
    USER-SPECIFIED ROUTES
    Type        Destination   Gateway     Interface
    ---------------------------------------------------------------
    net         9.1.2.24      1.2.3.1     en0
    host        192.168.1.2   1.2.3.1     en1
    
    FILESYSTEMS
    MountPoint              Device          Vfs    Nodename  Options
    -----------------------------------------------------------------
    /share                  /nfs2/share     nfs    nfsserver rw
    
    RESOURCE CONTROLS
    Active:                              yes
    RSet:                                isp1
    CPU Shares:                          2
    CPU Limits:                          5%-10%,50%
    Memory Shares:                       3
    Memory Limits:                       10%-20%,30%
    Per-Process Virtual Memory Limit:    1024MB
    Total Processes:                     64
    Total Threads:                       1024
    Total PTYs:                          8
    Total Large Pages:                   16
    Max Message queue IDs:               20%
    Max Semaphore IDs:                   30%
    Max Shared memory IDs:               50%
    Max Pinned memory:                   20%
    OPERATION:
    Operation:                           restart
    Process ID:                          905266
    Start time:                          11:19
    
    
    Privileges:                          PV_AU_,PV_AU_ADD,PV_AU_ADMIN,PV_AU_PROC,
                                         PV_AU_READ,PV_AU_WRITE,PV_AZ_ADMIN,
                                         PV_AZ_CHECK,PV_AZ_READ,PV_AZ_ROOT,PV_DAC_,
                                         PV_DAC_GID,PV_DAC_O,PV_DAC_R,PV_DAC_RID,
                                         PV_DAC_UID,PV_DAC_W,PV_DAC_X,PV_DEV_CONFIG,
                                         PV_DEV_QUERY,PV_FS_CHOWN,PV_FS_CHROOT
    
    DEVICE EXPORTS
    Name                                 Type         Virtual Device    RootVG      Status
    -----------------------------------------------------------------------------------------
    hdisk4                               disk                            yes        ALLOCATED
    /dev/null                            pseudo                                     ALLOCATED
    /dev/tty                             pseudo                                     ALLOCATED
    /dev/random                          pseudo                                     ALLOCATED
    /dev/urandom                         pseudo                                     ALLOCATED
    /dev/console                         pseudo                                     ALLOCATED
    /dev/zero                            pseudo                                     ALLOCATED
    /dev/clone                           pseudo                                     ALLOCATED
    /dev/sad                             clone                                      ALLOCATED
  5. To view machine-readable network information separated by pipes for workload partitions called roy,
  6. enter the following command:
    # lswpar -d'|' -N roy
    #name|interface|address|mask_prefix|broadcast
    roy|en0|192.168.1.50|255.255.255.128|192.168.1.127
    roy|en1|2001:DB8::|32|
  7. To view machine-readable, resource-control information for all workload partitions, enter the following command:
    # lswpar -cR
    #name:state:active:rset:shares_CPU:CPU:shares_memory:memory:procVirtMem:
    totalProcesses:totalThreads:totalPTYs:
    totalLargePages:pct_msgIDs:pct_semIDs:pct_shmIDs:pct_pinMem
    dale:A:no:::::::
    roy:A:yes:rogers:3::2::32:128
    trigger:A:yes:isp1:2:5%-10%,50%:3:10%-20%,30%:1024MB:64:1024:8:
    16:20%:30%:50%:20%
  8. To view operation information about the workload partition named foo, enter the following command:
    # lswpar –T foo
    =================================================================
    foo - Transitional
    =================================================================
    Operation: restart
    Process ID: 905266
    Start time: 11:19
  9. To view information about devices that are exported and allocated in the workload partitions named roy , enter the following command:
  10. # lswpar -D roy
    Name  Device Name      Type    Virtual Device  RootVG    Status   
    ------------------------------------------------------------------
    roy   /dev/null       pseudo                  	         EXPORTED
    ...  
    roy   fcs0            adapter                           EXPORTED 
    roy   hdisk2          disk      hdisk0          yes