'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH POOLCFG 1M "Nov 29, 2007"
.SH NAME
poolcfg \- create and modify resource pool configuration files
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/poolcfg\fR \fB-c\fR \fIcommand\fR [\fB-d\fR | [\fIfilename\fR]]
.fi

.LP
.nf
\fB/usr/sbin/poolcfg\fR \fB-f\fR \fIcommand_file\fR [\fB-d\fR | [\fIfilename\fR]]
.fi

.LP
.nf
\fB/usr/sbin/poolcfg\fR \fB-h\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpoolcfg\fR utility provides configuration operations on pools and sets.
These operations are performed upon an existing configuration and take the form
of modifications to the specified configuration file. If you use the \fB-d\fR
option, the modifications occur to the kernel state. Actual activation of the
resulting configuration is achieved by way of the \fBpooladm\fR(1M) utility.
.sp
.LP
Pools configuration files are structured files that must have been constructed
using \fBpoolcfg\fR itself or \fBlibpool\fR(3LIB) directly.
.sp
.LP
An invocation of \fBpoolcfg\fR with the pool dynamic location and write
permission will hang if the dynamic location has already been opened for
writing.
.sp
.LP
The configurations which are created by this utility can be used by
\fBpooladm\fR to instantiate the configuration upon a target host.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-c\fR \fIcommand\fR\fR
.ad
.RS 19n
Specify \fIcommand\fR as an editing command. See \fBUSAGE\fR.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 19n
Operate directly on the kernel state. No \fIfilename\fR is allowed.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fIcommand_file\fR\fR
.ad
.RS 19n
Take the commands from \fIcommand_file\fR. \fIcommand_file\fR consists of
editing commands, one per line.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.RS 19n
Display extended information about the syntax of editing commands.
.RE

.SH USAGE
.SS "Scripts"
.sp
.LP
A script consists of editing commands, one per line, of the following:
.sp
.ne 2
.na
\fBinfo [\fIentity-name\fR]\fR
.ad
.sp .6
.RS 4n
Display configuration (or specified portion) in human readable form to standard
output. If no entity is specified, system information is displayed. Therefore,
\fBpoolcfg\fR \fB-c\fR \fB\&'info' afile\fR is an equivalent invocation to
\fBpoolcfg\fR \fB-c\fR \fB\&'info system name' afile\fR.
.RE

.sp
.ne 2
.na
\fBcreate \fIentity-name\fR [\fIproperty-list\fR]\fR
.ad
.sp .6
.RS 4n
Make an entity of the specified type and name.
.RE

.sp
.ne 2
.na
\fBdestroy \fIentity-name\fR\fR
.ad
.sp .6
.RS 4n
Remove the specified entity.
.RE

.sp
.ne 2
.na
\fBmodify \fIentity-name\fR [\fIproperty-list\fR]\fR
.ad
.sp .6
.RS 4n
Change the listed properties on the named entity.
.RE

.sp
.ne 2
.na
\fBassociate \fIpool-name\fR [\fIresource-list\fR]\fR
.ad
.sp .6
.RS 4n
Connect one or more resources to a pool, or replace one or more existing
connections.
.RE

.sp
.ne 2
.na
\fBtransfer to [\fIresourcetype\fR] \fIname\fR[\fIcomponent-list\fR]\fR
.ad
.sp .6
.RS 4n
Transfer one or more discrete components to a resource .
.RE

.sp
.ne 2
.na
\fBtransfer [\fIquantity\fR] from [\fIresourcetype\fR] [\fIsrc\fR] to
[\fItgt\fR]\fR
.ad
.sp .6
.RS 4n
Transfer a resource quantity from \fIsrc\fR to \fItgt\fR.
.RE

.sp
.ne 2
.na
\fBtransfer [\fIquantity\fR] to [\fIresourcetype\fR] [\fItgt\fR] from
[\fIsrc\fR]\fR
.ad
.sp .6
.RS 4n
Transfer a resource quantity to \fItgt\fR from \fIsrc\fR.
.RE

.sp
.ne 2
.na
\fBdiscover\fR
.ad
.sp .6
.RS 4n
Create a system entity, with one pool entity and resources to match current
system configuration. All discovered resources of each resource type are
recorded in the file, with the single pool referring to the default resource
for each resource type.
.sp
This command is a NO-OP when \fBpoolcfg\fR operates directly on the kernel. See
the \fB-d\fR option.
.sp
You should avoid use of this command. The preferred method for creating a
configuration is to export the dynamic configuration using \fBpooladm\fR(1M)
with the \fB-s\fR option.
.RE

.sp
.ne 2
.na
\fBrename \fIentity-name\fR to \fInew-name\fR\fR
.ad
.sp .6
.RS 4n
Change the name of an entity on the system to its new name.
.RE

.SS "Property Lists"
.sp
.LP
The property list is specified by:
.sp
.in +2
.nf
( proptype name = value [ ; proptype name = value ]* )
.fi
.in -2

.sp
.LP
where the last definition in the sequence for a given proptype, name pair is
the one that holds. For property deletion, use \fB~ proptype name\fR.
.SS "Resource Lists"
.sp
.LP
A resource list is specified by:
.sp
.in +2
.nf
( resourcetype name [ ; resourcetype name ]* )
.fi
.in -2

.sp
.LP
where the last specification in the sequence for a resource is the one that
holds. There is no deletion syntax for resource lists.
.SS "Component Lists"
.sp
.LP
A component list is specified by:
.sp
.in +2
.nf
( componenttype name [ ; componenttype name ]* )
.fi
.in -2

.sp
.LP
where the last specification in the sequence for a component is the one that
holds. There is no deletion syntax for component lists.
.SS "Recognized Entities"
.sp
.ne 2
.na
\fBsystem\fR
.ad
.RS 10n
Machine level entity
.RE

.sp
.ne 2
.na
\fBpool\fR
.ad
.RS 10n
Named collection of resource associations
.RE

.SS "Resource Types"
.sp
.ne 2
.na
\fBpset\fR
.ad
.RS 8n
Processor set resource
.RE

.SS "Property Types"
.sp
.ne 2
.na
\fBboolean\fR
.ad
.RS 11n
Takes one of two values true or false.
.RE

.sp
.ne 2
.na
\fBint\fR
.ad
.RS 11n
A 64-bit signed integer value.
.RE

.sp
.ne 2
.na
\fBuint\fR
.ad
.RS 11n
A 64-bit unsigned integer value.
.RE

.sp
.ne 2
.na
\fBstring\fR
.ad
.RS 11n
Strings are delimited by quotes (\fB"\fR), and support the character escape
sequences defined in \fBformats\fR(5).
.RE

.sp
.ne 2
.na
\fBfloat\fR
.ad
.RS 11n
Scientific notation is not supported.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRWriting a poolcfg Script
.sp
.LP
The following \fBpoolcfg\fR script creates a pool named \fBAccounting\fR, and a
processor set, \fBsmall-1\fR. The processor set is created first, then the pool
is created and associated with the set.

.sp
.in +2
.nf
create pset small-1 ( uint pset.min = 1 ; uint pset.max = 4)
create pool Accounting
associate pool Accounting ( pset small-1 )
.fi
.in -2

.LP
\fBExample 2 \fRReporting on \fBpool_0\fR
.sp
.LP
The following command reports on \fBpool_0\fR to standard output in human
readable form:

.sp
.in +2
.nf
 # poolcfg -c 'info pool pool_0' /etc/pooladm.conf
.fi
.in -2
.sp

.LP
\fBExample 3 \fRDestroying pool_0 and Its Associations
.sp
.LP
The following command destroys \fBpool_0\fR and associations, but not the
formerly associated resources:

.sp
.in +2
.nf
# poolcfg -c 'destroy pool pool_0' /etc/pooladm.conf
.fi
.in -2
.sp

.LP
\fBExample 4 \fRDisplaying the Current Configuration
.sp
.LP
The following command displays the current configuration:

.sp
.in +2
.nf
$ poolcfg -c 'info' /etc/pooladm.conf
system example_system
               int system.version 1
               boolean system.bind-default true
               string system.comment Discovered by libpool

               pool pool_default
                    boolean pool.default true
                    boolean pool.active true
                    int pool.importance 5
                    string pool.comment
                    string.pool.scheduler FSS
                    pset pset_default

               pset pset_default
                    int pset.sys_id -1
                    string pset.units population
                    boolean pset.default true
                    uint pset.max 4294967295
                    uint pset.min 1
                    string pset.comment
                    boolean pset.escapable false
                    uint pset.load 0
                    uint pset.size 2

                    cpu
                         int cpu.sys_id 0
                         string cpu.comment

                    cpu
                         int cpu.sys_id 2
                         string cpu.comment
.fi
.in -2
.sp

.LP
\fBExample 5 \fRMoving cpu with ID 2 to Processor Set pset1 in the Kernel
.sp
.LP
The following command moves \fBcpu\fR with ID \fB2\fR to processor set
\fBpset1\fR in the kernel:

.sp
.in +2
.nf
# poolcfg -dc 'transfer to pset pset1 ( cpu 2 )'
.fi
.in -2
.sp

.LP
\fBExample 6 \fRMoving 2 cpus from Processor Set pset1 to Processor Set pset2
in the Kernel
.sp
.LP
The following command moves 2 \fBcpu\fRs from processor set \fBpset1\fR to
processor set \fBpset2\fR in the kernel:

.sp
.in +2
.nf
# poolcfg -dc 'transfer 2 from pset pset1 to pset2'
.fi
.in -2
.sp

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below.
.TE

.sp
.LP
The invocation is Committed. The output is Uncommitted.
.SH SEE ALSO
.sp
.LP
\fBpooladm\fR(1M), \fBpoolbind\fR(1M), \fBlibpool\fR(3LIB),
\fBattributes\fR(5), \fBformats\fR(5)
.sp
.LP
\fI\fR