share/man/man8/poolcfg.8

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH POOLCFG 8 "Nov 29, 2007"
   7 .SH NAME
   8 poolcfg \- create and modify resource pool configuration files
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB/usr/sbin/poolcfg\fR \fB-c\fR \fIcommand\fR [\fB-d\fR | [\fIfilename\fR]]
  13 .fi
  14
  15 .LP
  16 .nf
  17 \fB/usr/sbin/poolcfg\fR \fB-f\fR \fIcommand_file\fR [\fB-d\fR | [\fIfilename\fR]]
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fB/usr/sbin/poolcfg\fR \fB-h\fR
  23 .fi
  24
  25 .SH DESCRIPTION
  26 .sp
  27 .LP
  28 The \fBpoolcfg\fR utility provides configuration operations on pools and sets.
  29 These operations are performed upon an existing configuration and take the form
  30 of modifications to the specified configuration file. If you use the \fB-d\fR
  31 option, the modifications occur to the kernel state. Actual activation of the
  32 resulting configuration is achieved by way of the \fBpooladm\fR(8) utility.
  33 .sp
  34 .LP
  35 Pools configuration files are structured files that must have been constructed
  36 using \fBpoolcfg\fR itself or \fBlibpool\fR(3LIB) directly.
  37 .sp
  38 .LP
  39 An invocation of \fBpoolcfg\fR with the pool dynamic location and write
  40 permission will hang if the dynamic location has already been opened for
  41 writing.
  42 .sp
  43 .LP
  44 The configurations which are created by this utility can be used by
  45 \fBpooladm\fR to instantiate the configuration upon a target host.
  46 .SH OPTIONS
  47 .sp
  48 .LP
  49 The following options are supported:
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fB-c\fR \fIcommand\fR\fR
  54 .ad
  55 .RS 19n
  56 Specify \fIcommand\fR as an editing command. See \fBUSAGE\fR.
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fB-d\fR\fR
  63 .ad
  64 .RS 19n
  65 Operate directly on the kernel state. No \fIfilename\fR is allowed.
  66 .RE
  67
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fB-f\fR \fIcommand_file\fR\fR
  72 .ad
  73 .RS 19n
  74 Take the commands from \fIcommand_file\fR. \fIcommand_file\fR consists of
  75 editing commands, one per line.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fB-h\fR\fR
  82 .ad
  83 .RS 19n
  84 Display extended information about the syntax of editing commands.
  85 .RE
  86
  87 .SH USAGE
  88 .SS "Scripts"
  89 .sp
  90 .LP
  91 A script consists of editing commands, one per line, of the following:
  92 .sp
  93 .ne 2
  94 .na
  95 \fBinfo [\fIentity-name\fR]\fR
  96 .ad
  97 .sp .6
  98 .RS 4n
  99 Display configuration (or specified portion) in human readable form to standard
 100 output. If no entity is specified, system information is displayed. Therefore,
 101 \fBpoolcfg\fR \fB-c\fR \fB\&'info' afile\fR is an equivalent invocation to
 102 \fBpoolcfg\fR \fB-c\fR \fB\&'info system name' afile\fR.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fBcreate \fIentity-name\fR [\fIproperty-list\fR]\fR
 109 .ad
 110 .sp .6
 111 .RS 4n
 112 Make an entity of the specified type and name.
 113 .RE
 114
 115 .sp
 116 .ne 2
 117 .na
 118 \fBdestroy \fIentity-name\fR\fR
 119 .ad
 120 .sp .6
 121 .RS 4n
 122 Remove the specified entity.
 123 .RE
 124
 125 .sp
 126 .ne 2
 127 .na
 128 \fBmodify \fIentity-name\fR [\fIproperty-list\fR]\fR
 129 .ad
 130 .sp .6
 131 .RS 4n
 132 Change the listed properties on the named entity.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fBassociate \fIpool-name\fR [\fIresource-list\fR]\fR
 139 .ad
 140 .sp .6
 141 .RS 4n
 142 Connect one or more resources to a pool, or replace one or more existing
 143 connections.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fBtransfer to\fR [\fIresourcetype\fR] \fIname\fR[\fIcomponent-list\fR]
 150 .ad
 151 .sp .6
 152 .RS 4n
 153 Transfer one or more discrete components to a resource .
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fBtransfer [\fIquantity\fR] from [\fIresourcetype\fR] [\fIsrc\fR] to
 160 [\fItgt\fR]\fR
 161 .ad
 162 .sp .6
 163 .RS 4n
 164 Transfer a resource quantity from \fIsrc\fR to \fItgt\fR.
 165 .RE
 166
 167 .sp
 168 .ne 2
 169 .na
 170 \fBtransfer [\fIquantity\fR] to [\fIresourcetype\fR] [\fItgt\fR] from
 171 [\fIsrc\fR]\fR
 172 .ad
 173 .sp .6
 174 .RS 4n
 175 Transfer a resource quantity to \fItgt\fR from \fIsrc\fR.
 176 .RE
 177
 178 .sp
 179 .ne 2
 180 .na
 181 \fBdiscover\fR
 182 .ad
 183 .sp .6
 184 .RS 4n
 185 Create a system entity, with one pool entity and resources to match current
 186 system configuration. All discovered resources of each resource type are
 187 recorded in the file, with the single pool referring to the default resource
 188 for each resource type.
 189 .sp
 190 This command is a NO-OP when \fBpoolcfg\fR operates directly on the kernel. See
 191 the \fB-d\fR option.
 192 .sp
 193 You should avoid use of this command. The preferred method for creating a
 194 configuration is to export the dynamic configuration using \fBpooladm\fR(8)
 195 with the \fB-s\fR option.
 196 .RE
 197
 198 .sp
 199 .ne 2
 200 .na
 201 \fBrename \fIentity-name\fR to \fInew-name\fR\fR
 202 .ad
 203 .sp .6
 204 .RS 4n
 205 Change the name of an entity on the system to its new name.
 206 .RE
 207
 208 .SS "Property Lists"
 209 .sp
 210 .LP
 211 The property list is specified by:
 212 .sp
 213 .in +2
 214 .nf
 215 ( proptype name = value [ ; proptype name = value ]* )
 216 .fi
 217 .in -2
 218
 219 .sp
 220 .LP
 221 where the last definition in the sequence for a given proptype, name pair is
 222 the one that holds. For property deletion, use \fB~ proptype name\fR.
 223 .SS "Resource Lists"
 224 .sp
 225 .LP
 226 A resource list is specified by:
 227 .sp
 228 .in +2
 229 .nf
 230 ( resourcetype name [ ; resourcetype name ]* )
 231 .fi
 232 .in -2
 233
 234 .sp
 235 .LP
 236 where the last specification in the sequence for a resource is the one that
 237 holds. There is no deletion syntax for resource lists.
 238 .SS "Component Lists"
 239 .sp
 240 .LP
 241 A component list is specified by:
 242 .sp
 243 .in +2
 244 .nf
 245 ( componenttype name [ ; componenttype name ]* )
 246 .fi
 247 .in -2
 248
 249 .sp
 250 .LP
 251 where the last specification in the sequence for a component is the one that
 252 holds. There is no deletion syntax for component lists.
 253 .SS "Recognized Entities"
 254 .sp
 255 .ne 2
 256 .na
 257 \fBsystem\fR
 258 .ad
 259 .RS 10n
 260 Machine level entity
 261 .RE
 262
 263 .sp
 264 .ne 2
 265 .na
 266 \fBpool\fR
 267 .ad
 268 .RS 10n
 269 Named collection of resource associations
 270 .RE
 271
 272 .SS "Resource Types"
 273 .sp
 274 .ne 2
 275 .na
 276 \fBpset\fR
 277 .ad
 278 .RS 8n
 279 Processor set resource
 280 .RE
 281
 282 .SS "Property Types"
 283 .sp
 284 .ne 2
 285 .na
 286 \fBboolean\fR
 287 .ad
 288 .RS 11n
 289 Takes one of two values true or false.
 290 .RE
 291
 292 .sp
 293 .ne 2
 294 .na
 295 \fBint\fR
 296 .ad
 297 .RS 11n
 298 A 64-bit signed integer value.
 299 .RE
 300
 301 .sp
 302 .ne 2
 303 .na
 304 \fBuint\fR
 305 .ad
 306 .RS 11n
 307 A 64-bit unsigned integer value.
 308 .RE
 309
 310 .sp
 311 .ne 2
 312 .na
 313 \fBstring\fR
 314 .ad
 315 .RS 11n
 316 Strings are delimited by quotes (\fB"\fR), and support the character escape
 317 sequences defined in \fBformats\fR(5).
 318 .RE
 319
 320 .sp
 321 .ne 2
 322 .na
 323 \fBfloat\fR
 324 .ad
 325 .RS 11n
 326 Scientific notation is not supported.
 327 .RE
 328
 329 .SH EXAMPLES
 330 .LP
 331 \fBExample 1 \fRWriting a poolcfg Script
 332 .sp
 333 .LP
 334 The following \fBpoolcfg\fR script creates a pool named \fBAccounting\fR, and a
 335 processor set, \fBsmall-1\fR. The processor set is created first, then the pool
 336 is created and associated with the set.
 337
 338 .sp
 339 .in +2
 340 .nf
 341 create pset small-1 ( uint pset.min = 1 ; uint pset.max = 4)
 342 create pool Accounting
 343 associate pool Accounting ( pset small-1 )
 344 .fi
 345 .in -2
 346
 347 .LP
 348 \fBExample 2 \fRReporting on \fBpool_0\fR
 349 .sp
 350 .LP
 351 The following command reports on \fBpool_0\fR to standard output in human
 352 readable form:
 353
 354 .sp
 355 .in +2
 356 .nf
 357  # poolcfg -c 'info pool pool_0' /etc/pooladm.conf
 358 .fi
 359 .in -2
 360 .sp
 361
 362 .LP
 363 \fBExample 3 \fRDestroying pool_0 and Its Associations
 364 .sp
 365 .LP
 366 The following command destroys \fBpool_0\fR and associations, but not the
 367 formerly associated resources:
 368
 369 .sp
 370 .in +2
 371 .nf
 372 # poolcfg -c 'destroy pool pool_0' /etc/pooladm.conf
 373 .fi
 374 .in -2
 375 .sp
 376
 377 .LP
 378 \fBExample 4 \fRDisplaying the Current Configuration
 379 .sp
 380 .LP
 381 The following command displays the current configuration:
 382
 383 .sp
 384 .in +2
 385 .nf
 386 $ poolcfg -c 'info' /etc/pooladm.conf
 387 system example_system
 388                int system.version 1
 389                boolean system.bind-default true
 390                string system.comment Discovered by libpool
 391
 392                pool pool_default
 393                     boolean pool.default true
 394                     boolean pool.active true
 395                     int pool.importance 5
 396                     string pool.comment
 397                     string.pool.scheduler FSS
 398                     pset pset_default
 399
 400                pset pset_default
 401                     int pset.sys_id -1
 402                     string pset.units population
 403                     boolean pset.default true
 404                     uint pset.max 4294967295
 405                     uint pset.min 1
 406                     string pset.comment
 407                     boolean pset.escapable false
 408                     uint pset.load 0
 409                     uint pset.size 2
 410
 411                     cpu
 412                          int cpu.sys_id 0
 413                          string cpu.comment
 414
 415                     cpu
 416                          int cpu.sys_id 2
 417                          string cpu.comment
 418 .fi
 419 .in -2
 420 .sp
 421
 422 .LP
 423 \fBExample 5 \fRMoving cpu with ID 2 to Processor Set pset1 in the Kernel
 424 .sp
 425 .LP
 426 The following command moves \fBcpu\fR with ID \fB2\fR to processor set
 427 \fBpset1\fR in the kernel:
 428
 429 .sp
 430 .in +2
 431 .nf
 432 # poolcfg -dc 'transfer to pset pset1 ( cpu 2 )'
 433 .fi
 434 .in -2
 435 .sp
 436
 437 .LP
 438 \fBExample 6 \fRMoving 2 cpus from Processor Set pset1 to Processor Set pset2
 439 in the Kernel
 440 .sp
 441 .LP
 442 The following command moves 2 \fBcpu\fRs from processor set \fBpset1\fR to
 443 processor set \fBpset2\fR in the kernel:
 444
 445 .sp
 446 .in +2
 447 .nf
 448 # poolcfg -dc 'transfer 2 from pset pset1 to pset2'
 449 .fi
 450 .in -2
 451 .sp
 452
 453 .SH ATTRIBUTES
 454 .sp
 455 .LP
 456 See \fBattributes\fR(5) for descriptions of the following attributes:
 457 .sp
 458
 459 .sp
 460 .TS
 461 box;
 462 c | c
 463 l | l .
 464 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 465 _
 466 Interface Stability     See below.
 467 .TE
 468
 469 .sp
 470 .LP
 471 The invocation is Committed. The output is Uncommitted.
 472 .SH SEE ALSO
 473 .sp
 474 .LP
 475 \fBpooladm\fR(8), \fBpoolbind\fR(8), \fBlibpool\fR(3LIB),
 476 \fBattributes\fR(5), \fBformats\fR(5)
 477 .sp
 478 .LP
 479 \fI\fR