Go to main content

man pages section 1M: System Administration Commands

Exit Print View

Updated: July 2017



poolcfg - create and modify resource pool configuration files


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


The poolcfg utility provides configuration operations on pools, sets, 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 before pools configuration files can be created or committed. The service can be enabled throught svcadm(1M), or by the –e option to the pooladm(1M) 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(1M) utility. This is referred to as committing the pools configuration. When the configuration is committed, 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.

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

Pools configuration files are structured files that must be constructed and edited using poolcfg(1m) 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.


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.


Operate directly on the kernel state. The kernel state is also known as the pools dynamic configuration.

No filename argument is allowed. The commands are executed against the kernel state, as seen by the pooladm(1M) 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.


Display extended information about the syntax of editing commands.


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.

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

Assign a specific set of cpus, cores, or sockets to a pset. A pset must be assigned cpu resources of all the same type.

If, in the pools configuration file, the cpu resources 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.

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 resources. A configuration will fail to commit if all cpu resources are unassigned and the pset has one or more processes bound to it.

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

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

Transfer one or more specific cpus. Only cpu resource types are supported.

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.

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.

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 cpu resources 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 cpu resources than it has assigned, or allocated through the pset.min and pset.max properties.


Create a new pools configuration file matching the current kernel pools configuration, as ouput by the pooladm(1M) utility.

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

You should avoid use of this command. The preferred method for creating a configuration is to export the dynamic configuration using pooladm(1M) 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 poolcfg commands use the following tokens:


It can be any one of the following:


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


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.


An object representing a collection of processor resources.


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


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.


It can be any one of the following:


Takes one of two values true or false.


A 64–bit signed integer value.


A 64–bit unsigned integer value.


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


Scientific notation is not supported.


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.


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


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>

An object representing a cpu resource. It can be any one of the following:


A virtual cpu, also known as a hardware thread.


A group of virtual cpus sharing compute resources.


A group of cores contained within a physical processor.


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


A list of one or more cpu resources. All resources in a list must be the same cpu-type.

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

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


A single positive integer value.


Example 1 Enabling Pools and Creating a New Configuration File

The following commands will enable the pools service and create a new pools 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 processor set, small-1. The processor set is created first, then the pool is created and associated with the set. Finally, the configuration is committed to create the pool and pset on the running system.

# cat command-file.txt 
create pset Small-1 (uint pset.min = 2; uint pset.max = 2)
create pool associate pool Accounting ( pset Small-1 )
# 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
        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
                       int     cpu.sys_id 1
                       string  cpu.comment
                       string  cpu.status on-line
                       int     cpu.sys_id 0
                       string  cpu.comment
                       string  cpu.status on-line
Example 6 Moving cpu with ID 2 to Processor Set pset1 in the Kernel

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 Processor Set pset1 to Processor Set pset2 in the Kernel

The following command moves 2 cpus from processor set pset1 to processor set pset2 in the kernel:

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

Example 8 Configure a Pool to Have a Specific List of Cores

The following commands 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 )'


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

Interface Stability
See below.

The invocation is Committed. The output is Uncommitted.

See Also

pooladm(1M), poolbind(1M), poold(1M), libpool(3LIB), attributes(5), formats(5)

Administering Resource Management in Oracle Solaris 11.3

Creating and Using Oracle Solaris Zones