poolcfg - create and modify a resource pool configuration file
/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, 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.
The svc:/system/pools:default service must be enabled for the default pool configuration to be applied at boot. The service can be enabled through 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 runtime 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".
The following options are supported:
Specify a poolcfg command. Multiple –c options are supported, and will be processed in order. See USAGE section below.
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.
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:
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'.
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.
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".
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 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 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.
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 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 a quantity of cpus from pset src-pset-name to pset tgt-pset-name. See "transfer constraints" below.
Transfer a quantity of cpus to pset tgt-pset-name to pset src-pset-name. See "transfer constraints" below.
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).
Create a new pools configuration file matching the current running pools configuration, as output 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.
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:
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 cpus.
An object representing a single virtual processor, also known as a hardware thread or strand.
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(7).
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, core, or socket. It can be any one of the following:
A virtual cpu, also known as a hardware thread or strand.
A group of virtual cpus sharing physical 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 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 ]
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.
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 -sExample 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 -cExample 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
string 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 )'
See attributes(7) for descriptions of the following attributes:
|
The invocation is Committed. The output is Uncommitted.
libpool(3LIB), attributes(7), formats(7), resource-management(7), pooladm(8), poolbind(8), poold(8)