Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

poolcfg(8)

Name

poolcfg - create and modify a resource pool configuration file

Synopsis

/usr/sbin/poolcfg -c command [-d | [filename]]
/usr/sbin/poolcfg -f command-file [-d | [filename]]
/usr/sbin/poolcfg -h

Description

The poolcfg utility provides configuration operations on pools, psets, and system wide pools properties. These operations are performed upon an existing configuration file. If the file arguments are not specified, the default configuration file, /etc/pooladm.conf, is used.

Type svc:/system/pools:default service must be enabled for the default pool configuration to be applied at boot. The service can be enabled through the svcadm(8), or by the –e option to the pooladm(8) utility.

/etc/pooladm.conf does not exist by default. See example 1 below for instructions on how to create it.

If the svc:/system/pools:default service is enabled, this configuration file is applied during system boot. The configuration file can also be applied using the –c option of the pooladm(8) utility. This is referred to as applying the pool configuration. When the configuration is applied, pools and psets are created in the kernel, and processes can be bound to them. This kernel state is referred to as the pools dynamic configuration, or the running configuration.

If you use the –d option to poolcfg, the operations will be performed directly on the running configuration rather than on a configuration file. These changes will not persist on reboot, and will be clobbered by a future application of a pool configuration file. To capture run-time changes made through poolcfg -d to a configuration file, use the –s option to the pooladm(8) utility.

Pools configuration files are structured files that must be constructed and edited using poolcfg or libpool(3LIB).

An invocation of poolcfg -d using any modifying operations will hang if the dynamic configuration has already been opened for writing by another process, such as another poolcfg -d, or a process utilizing libpool.so.1. The hang will persist until the writing process closes the file.

This command cannot be used to modify psets created by psrset(8). This includes assigning or transferring CPUs that are already assigned to psrset(8) psets. See psrset(8) to manipulate such psets. Psets created by poolcfg are referred to as "pool psets".

Options

The following options are supported:

–c command

Specify a poolcfg command. Multiple –c options are supported, and will be processed in order. See USAGE section below.

–d

Operate directly on the running configuration. This is also known as the pools dynamic configuration in libpool(3LIB).

No filename argument is allowed. The commands are executed against running configuration, as seen by the pooladm(8) command, and any modifications are immediately committed.

–f command-file

Take the commands from command-file. command-file consists of poolcfg commands, one per line.

–h

Display extended information about the syntax of editing commands.

Usage

The following poolcfg commands are supported:

info [<entity-type> <entity-name> ]

Display configuration (or specified portion) in human readable form to standard output. If no entity is specified, system information is displayed. Therefore, poolcfg –c 'info' is an equivalent invocation to poolcfg –c 'info system default'.

create <entity-type> <entity-name> [(property-list)]

Make an entity of the specified type and name. Entities of type pool and pset can be created. A created pset will be associated to pool_default. A created pool will be associated to pset_default.

A property-list can optionally be supplied to provide initial values for one or more properties.

destroy <entity-type> <entity-name>

Remove the specified entity. Entities of type pool and pset can be destroyed. If a pset is destroyed, any pools associated with that pset will become associated with the pool "pool_default".

modify <entity-type> <entity-name> [(property-list)]

Change the listed properties on the named entity. Modifying the pset.min and pset.max properties will remove any configuration set by a previous assign command.

associate pool <entity-name> ( pset <entity-name> )

Associate a pool to a pset. Both the pool and pset must exist. The prior pset association is removed, as a pool may only be associated to a single pset.

The target pool of this command may not be pool_default or the pool of a pset created by psrset(8). The target pset of this command may not be a pset created by psrset(8).

assign to pset <entity-name> ( <cpu-resource-list> )

Assign a specific set of cpus, cores, or sockets to a pset. A pset can be assigned only one of cpus, cores, or sockets, and not a mix of these types.

If, in the pool configuration file, the cpus, cores, or sockets are already assigned to another pset the assign command will fail.

For a given pset, the assign command replaces the configuration set by any prior modify command. Previous assign commands are preserved if they are of the same type. For example, assigning cores to a pset that already has cores assigned will add to the already assigned cores, but not replace them.

CPUs that are assigned to psets through the psrset(8) utility will fail to assign to pool psets when a pools configuration containing such assignments is applied with pooladm -c. Assigning such CPUs directly to pool psets in the running configuration through poolcfg -dc will also fail. In general, CPUs in use by psrset(8) psets may not be used by pool psets. They must first be removed using psrset -r.

unassign from pset <entity-name> ( [ <cpu-resource-list> | all ] )

Remove cpu, core, or socket assignments from a pset. The special token "all" can be used to unassign all cpus, cores, or sockets. A configuration will fail to apply if all cpus, cores, or sockets are being unassigned and the pset has one or more processes bound to it.

The unassign command can only succeed after a successful assign command.

Psets created by the psrset(8) utility are not valid targets of this command. Use psrset(8) to manipulate such psets.

transfer to pset <tgt-pset-name> ( <cpu-resource-list> )

Transfer one or more specific cpus to the target pset. The source pset is the pset where the specific cpus currently reside. See "transfer constraints" below.

transfer <quantity> from pset <src-pset-name> to <tgt-pset-name>

Transfer a quantity of cpus from pset src-pset-name to pset tgt-pset-name. See "transfer constraints" below.

transfer <quantity> to pset <tgt-pset-name> from <src-pset-name>

Transfer a quantity of cpus to pset tgt-pset-name to pset src-pset-name. See "transfer constraints" below.

transfer constraints

The transfer command fails if either the source or target pset is configured using the assign command. This rule does not apply to pset_default because pset_default can have more cpus, cores, or sockets than it has been assigned.

The transfer command will fail if it would cause the minimum or maximum number of cpus configured for the source or target pset to be exceeded. This rule does not apply to the maximum size of pset_default, as it can have more cpus, cores, or sockets than it has assigned, or allocated through the pset.min and pset.max properties.

Neither pset may be a pset created by psrset(8).

discover

Create a new pools configuration file matching the current running pools configuration, as ouput by the pooladm(8) utility.

This command has no effect when poolcfg operates directly on the running configuration. See the –d option.

The preferred method for creating a configuration is to export the dynamic configuration using pooladm(8) with the –s option.

rename <entity-type> <entity-name> to <entity-name>

Change the name of an entity on the system to its new name.

The target of this command may not be "pool_default", "pset_default", or a pool or pset created by psrset(8).

The poolcfg commands use the following tokens:

entity-type

It can be any one of the following:

system

Machine level entity. There is only one system entity with name "default".

pool

Named object associated with a pset. Multiple pools may be associated with the same processor set, but a pset can only be associated with a single pool.

pset

An object representing a collection of cpus.

cpu

An object representing a single virtual processor, also known as a hardware thread or strand.

entity-name

The entity names vary by entity type.

For type "system", only one entity exists, with name "default". The system entity stores the system-wide pools properties.

For type "pool", there is always a "pool_default", and zero or more user defined pools.

For type "pset", there is always a "pset_default", and zero or more user defined psets.

For type "cpu", there is a cpu entity for each cpu on the system, each of which has a numeric name equal to its cpuid.

prop-type

It can be any one of the following:

boolean

Takes one of two values true or false.

int

A 64–bit signed integer value.

uint

A 64–bit unsigned integer value.

string

Strings are delimited by quotes ("), and support the character escape sequences defined in formats(7).

float

Scientific notation is not supported.

prop-name

A name of a property on the entity being manipulated. See the libpool(3LIB) manpage for a list of properties understood by the resource pools framework. User defined properties can also be set and deleted.

value

A valid value as defined by the preceding prop-type.

property-list

The property list is a list of one or more property value assignments.

<prop-type> <prop-name> = <value>
  [ ; <prop-type> <prop-name> = <value> ]*

Property deletions can also be specified using the following syntax within a property-list.

~ <prop-type> <prop-name>
cpu-res-type

An object representing a cpu, core, or socket. It can be any one of the following:

cpu

A virtual cpu, also known as a hardware thread or strand.

core

A group of virtual cpus sharing physical compute resources.

socket

A group of cores contained within a physical processor.

cpu-res-id

A numeric id for a cpu, core, or socket, as listed by psrinfo -c.

cpu-resource-list

A list of one or more cpus, cores, or sockets. All items in a list must be the same cpu-res-type.

cpu-res-type cpu-res-id [ ; cpu-res-type cpu-res-id ]
range

A minimum and maximum value separated by a -. For example, a range of two to four is represented as "2-4".

quantity

A single positive integer value.

Examples

Example 1 Enabling Pools and Creating a New Configuration File

The following commands will enable the pools service and create a new pool configuration file. The file created is /etc/pooladm.conf. It will contain pool_default and pset_default.

# pooladm -e
# pooladm -s
Example 2 Creating a pool and pset

The following poolcfg script creates a pool named Accounting, and a pset: Small. The pset is created first, then the pool is created and associated with the set. Finally, the configuration is applied to create the pool and pset on the running system.

# cat command-file.txt 
create pset Small (uint pset.min = 2; uint pset.max = 2)
create pool associate pool Accounting ( pset Small )
  
# poolcfg -f command-file.txt
# pooladm -c
Example 3 Reporting on pool_0

The following command reports on pool_0 to standard output in human readable form:


 # poolcfg -c 'info pool pool_0'

Example 4 Destroying pool_0 and Its Associations

The following command destroys pool_0. The pset associated with pool_0 is not destroyed.


# poolcfg -c 'destroy pool pool_0'

Example 5 Displaying the Current Configuration

The following command displays the current configuration that will be applied at system boot or the next pooladm -c command.

       $ poolcfg -c 'info'
       system default
        string  system.comment
        int     system.version 1
        boolean system.bind-default true
        boolean system.project-fallback-to-default true
        boolean system.zone-fallback-to-default false
        string  system.poold.objectives wt-load
  
        pool pool_default
                int     pool.sys_id 0
                boolean pool.active true
                boolean pool.default true
                int     pool.importance 1
                string  pool.comment
                pset    pset_default
  
       pset pset_default
               int     pset.sys_id -1
               boolean pset.default true
               uint    pset.min 1
               uint    pset.max 65536
               string  pset.units population
               string  pset.policy minmax
               string  pset.restype cpu
               strintg pset.reslist
               uint    pset.load 0
               uint    pset.size 2
               string  pset.comment
  
               cpu
                       int     cpu.sys_id 1
                       string  cpu.comment
                       string  cpu.status on-line
  
              cpu
                       int     cpu.sys_id 0
                       string  cpu.comment
                       string  cpu.status on-line
Example 6 Moving cpu with ID 2 to pset pset1 in the running configuration

The following command moves cpu with ID 2 to processor set pset1 in the kernel:


# poolcfg -dc 'transfer to pset pset1 ( cpu 2 )'

Example 7 Moving 2 cpus from pset pset1 to Processor Set pset2 in the running configuration

# poolcfg -dc 'transfer 2 from pset pset1 to pset2'

Example 8 Configure a Pool to Have a Specific List of Cores
# poolcfg -c 'create pset pset1'
# poolcfg -c 'assign to pset pset1 (core 0-3)'
Example 9 Delete a Pool Property

This following command deletes a property previously set on a pool by the user.

# poolcfg -c 'modify pool pset1 ( ~ string userprop1 )'

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/resource-mgmt/resource-pools
Interface Stability
See below.

The invocation is Committed. The output is Uncommitted.

See Also

libpool(3LIB), attributes(7), formats(7), resource-management(7), pooladm(8), poolbind(8), poold(8)