1 Standards, Environments, and Macros pkg(5) 2 3 4 NAME 5 pkg - image packaging system 6 7 DESCRIPTION 8 The image packaging system, pkg(5), is a framework which provides for 9 software lifecycle management (installation, upgrade, and removal). 10 Image packaging manages software in units of packages, which are 11 collections of 'actions', defined by a set of key/value pairs and 12 possibly a data payload. In many cases, actions are files found in 13 a filesystem, but they also represent other installable objects, 14 such as drivers, services, and users. 15 16 Package FMRIs and Versions 17 18 Each package is represented by a fault management resource identifier 19 (FMRI) with the scheme 'pkg:'. The full FMRI for a package consists 20 of the scheme, a publisher, the package name, and a version string in 21 the following format: 22 23 pkg://opensolaris.org/library/libc@5.11,5.11-0.75:20071001T163427Z 24 25 'opensolaris.org' is the publisher. 'library/libc' is the package 26 name. Although the namespace is hierarchical and arbitrarily deep, 27 there is no enforced containment -- the name is essentially arbitrary. 28 29 The version follows the package name, separated by an '@'. It 30 consists of four sequences of numbers, separated by punctuation. The 31 elements in the first three sequences are separated by dots, and the 32 sequences are arbitrarily long. 33 34 The first part is the component version. For components tightly bound 35 to OpenSolaris, this will usually be the value of 'uname -r' for that 36 version of OpenSolaris. For a component with its own development 37 lifecycle, this sequence will be the dotted release number, such as 38 '2.4.10'. 39 40 The second part, following the comma, is the build version, specifying 41 what version of OpenSolaris the contents of the package were built on, 42 providing a minimum bound on which OpenSolaris version the contents can be 43 expected to run successfully. 44 45 The third part, following the dash, is the branch version, a 46 versioning component, providing vendor-specific information. This may 47 be incremented when the packaging metadata is changed, independently 48 of the component, may contain a build number, or some other 49 information. 50 51 The fourth part, following the colon, is a timestamp. It represents 52 when the package was published. 53 54 Many parts of the system, when appropriate, will contract FMRIs when 55 displaying them to reduce the volume of information provided. 56 Typically, the scheme, publisher, build version, and timestamp will be 57 elided, and sometimes the versioning information altogether. 58 59 Actions 60 Actions represent the installable objects on a system. They are 61 described in a package's manifest. Every action consists primarily of 62 its name and a key attribute. Together, these refer to a unique 63 object as it follows a version history. Actions may have other 64 attributes. Some of these will be interpreted directly by the 65 packaging system, others may be useful only to the system 66 administrator or the end-user. 67 68 The attributes listed below are not an exhaustive set; indeed, the 69 attributes which may be attached to an action are arbitrary, and 70 indeed, the standard sets are easily augmented to incorporate future 71 developments. 72 73 Certain action attributes cause additional operations to be 74 executed outside of the packaging context. These are documented 75 below, under the topic "Actuators". 76 77 File Actions 78 The 'file' action is perhaps the most common action, and represents an 79 'ordinary file'. It references a payload, and has four standard 80 attributes: 81 82 path The filesystem path where the file is installed. This is a 83 file action's key attribute. 84 85 mode The access permissions (in numeric form) of the file. These 86 are simple permissions only, not ACLs. 87 88 owner The name of the user which owns the file. 89 90 group The name of the group which owns the file. 91 92 Other attributes include: 93 94 preserve This specifies that the file's contents should not be 95 overwritten on upgrade if they are determined to have 96 changed since it was installed or last upgraded. 97 98 If the value of this attribute is 'renameold', then the 99 existing file will be renamed, and the new file will be put 100 in its place. 101 102 If the value of this attribute is 'renamenew', then the 103 existing file will be left alone, and the new file will be 104 installed with a new name. 105 106 If the value of this attribute is 'strawberry', then the 107 existing file will be left alone, and the new file will not 108 be installed. 109 110 Files may also be 'tasted', and depending on the flavor, may have 111 additional interesting attributes. For ELF files, the following 112 attributes are recognized: 113 114 elfarch The architecture of the ELF file. This will be the output of 115 'uname -p' on the architecture for which the file is built. 116 117 elfbits This will be '32' or '64'. 118 119 elfhash This is the hash of the 'interesting' ELF sections in the 120 file. These sections are the ones that are mapped into 121 memory when the binary is loaded, except for the section 122 containing the CTF data. These sections are the only ones 123 necessary to consider when determining whether two binaries' 124 executable behavior will differ. 125 126 original_name This attribute is used to handle editable files moving 127 from package to package or from place to place, or both. 128 The form this takes is the name of the originating package, 129 followed by a colon and the original path to the file. 130 Any file being deleted is recorded either with its 131 package and path, or with the value of the original_name 132 attribute if specified. Any editable file being installed 133 that has the original_name attribute set will use the 134 file of that name if it is deleted as part of the same 135 packaging operation. 136 137 Directory Actions 138 The 'directory' action is like the file action in that it represents a 139 filesystem object, but a directory instead of an ordinary file. It 140 has the same four standard attributes as the file action, and 'path' 141 is the key attribute. 142 143 Link Actions 144 The 'link' action represents a symbolic link. It has two standard 145 attributes: 146 147 path The filesystem path where the symlink is installed. This is a 148 link action's key attribute. 149 150 target The target of the symlink; the filesystem object to which the 151 link resolves. 152 153 Hardlink actions 154 The 'hardlink' action represents a hard link. It has the same 155 attributes as the link action, and 'path' is also its key attribute. 156 157 Driver actions 158 The 'driver' action represents a device driver. It does not reference 159 a payload: the driver files themselves must be installed as file 160 actions. The following attributes are recognized (see add_drv(1m) for 161 more information): 162 163 name The name of the driver. This is usually, but not always, 164 the filename of the driver binary. This is the driver 165 action's key attribute. 166 167 alias This represents an alias for the driver. There may be 168 more than one alias attribute for any given driver. 169 There are no special quoting rules necessary. 170 171 class This represents a driver class. There may be more than 172 one class attribute for any given driver. 173 174 perms This represents the filesystem permissions for the 175 driver's device nodes. 176 177 clone_perms This represents the filesystem permissions for the 178 "clone" driver's minor nodes for this driver. 179 180 policy This specifies additional security policy for the device. 181 There may be more than one policy attribute for any given 182 driver, but no minor device specification may be present in 183 more than one attribute. 184 185 privs This specifies privileges used by the driver. There may 186 be more than one privs attribute for any given driver. 187 188 devlink This specifies an entry in /etc/devlink.tab. The value 189 is the exact line to go into the file, with tabs denoted 190 by "\t". See devlinks(1M) for more information. There 191 may be more than one devlink attribute for any given 192 driver. 193 194 Depend actions 195 The 'depend' action represents an inter-package dependency. A package 196 may depend on another package because the first requires functionality 197 in the second for the functionality in the first to work, or even to 198 install. Dependencies may be optional. 199 200 The following attributes are recognized: 201 202 type The type of the dependency. If the value is 'require', then the 203 dependency is required. A package cannot be installed if any of 204 its required dependencies cannot be satisfied. 205 206 If the value is 'optional', then the dependency is optional. 207 Optional dependencies are followed or not depending on image 208 policy (see 'Policy' below). 209 210 If the value is 'exclude', then the package is non-functional if 211 the dependent package is present on the system. 212 213 If the value is 'incorporate', then the dependency is required, 214 but in addition, the version of the dependent package is 215 constrained. See 'Constraints and Freezing' below. 216 217 fmri The FMRI representing the depended-upon package. 218 219 There is no key attribute for depend actions. 220 221 License actions 222 The 'license' action represents a license or other informational 223 file associated with the package contents. A package may deliver 224 licenses, disclaimers, or other guidance to the package installer 225 through the use of the license action. The payload of the license 226 action will be delivered into the image metadata directory 227 associated with the package. 228 229 The following attributes are recognized: 230 231 license The keyword identifying the license type, for use in 232 filter and query operations. 233 234 The 'license' attribute is the key attribute for the license action. 235 236 Legacy actions 237 The 'legacy' action represents package data used by a legacy 238 packaging system. The attributes associated with this action are 239 added into the legacy system's databases in order that the tools 240 querying those databases might operate as if the legacy package were 241 actually installed. In particular, this should be sufficient to 242 convince the legacy system that the package named by the 'pkg' 243 attribute is installed on the system, so that it may be used to 244 satisfy dependencies. 245 246 The following attributes, named in accordance with the parameters on 247 pkginfo(4), are recognized: 248 249 category The value for the CATEGORY parameter. The default value 250 is "system". 251 252 desc The value for the DESC parameter. 253 254 hotline The value for the HOTLINE parameter. 255 256 name The value for the NAME parameter. The default value is 257 "none provided". 258 259 pkg The abbreviation for the package being installed. The 260 default value is the name from the package's FMRI. 261 262 vendor The value for the VENDOR parameter. 263 264 version The value for the VERSION parameter. The default value is 265 the version from the package's FMRI. 266 267 The 'pkg' attribute is the key attribute for the legacy action. 268 269 Set actions 270 The 'set' action represents a package-level attribute, such as the 271 package description. 272 273 The following attributes are recognized: 274 275 name The name of the attribute. 276 277 value The value given to the attribute. 278 279 Group actions 280 The 'group' action define a unix group as defined in group(4). No support 281 is present for group passwords. Groups defined with this action initially 282 have no user-list; users may be added with the 'user' action. The following 283 attributes are recognized: 284 285 groupname The value for the name of the group. 286 gid The groups unique numerical id. The default value is the first 287 free group under 100. 288 289 User actions 290 The 'user' action defines a Unix user as defined in /etc/passwd, /etc/shadow, 291 /etc/group and /etc/ftpd/ftpusers files. Users defined with this attribute 292 have entries added to the appropriate files. 293 294 The following attributes are recognized: 295 296 username The unique name of the user 297 298 password The encryped password of the user. Default value is '*LK*'. See 299 shadow(4). 300 301 uid The unique uid of the user. Default value is first free value 302 under 100. 303 304 group The name of the users primary group. Must be 305 found in /etc/group 306 307 gcos-field The value of the gecos field in /etc/passwd. Default value is 308 username. 309 310 home-dir The user's home directory. Default value is '/'. 311 312 login-shell The user's default shell. Default value is empty. 313 314 315 group-list secondary groups to which the user belongs. See group(4). 316 317 ftpuser Can be set to "true" or "false". Determines whether 318 user is allowed to use ftp. See ftpusers(4). 319 320 lastchng The number of days between January 1, 1970, and 321 the date that the password was last modified. 322 Default value is empty. See shadow(4). 323 324 min The minimum number of days required between 325 password changes. This field must be set to 0 or 326 above to enable password aging. Default value is 327 empty. See shadow(4). 328 329 max The maximum number of days the password is 330 valid. Default value is empty. See shadow(4). 331 332 warn The number of days before password expires that 333 the user is warned. See shadow(4). 334 335 inactive The number of days of inactivity allowed for 336 that user. This is counted on a per-machine 337 basis; the information about the last login is 338 taken from the machine's lastlog file. See 339 shadow(4). 340 341 expire An absolute date expressed as the number of days 342 since the Unix Epoch (January 1, 1970). When 343 this number is reached the login can no longer 344 be used. For example, an expire value of 13514 345 specifies a login expiration of January 1, 2007. 346 See shadow(4). 347 348 flag set to empty. See shadow(4). 349 350 351 Actuators 352 353 In certain contexts, additional operations may be appropriate to 354 execute in preparation for or following the introduction of a 355 particular action. These additional operations are generally 356 needed only on a live system image, and are operating 357 system-specific. When multiple actions involved in a package 358 installation or removal have identical actuators, then the 359 operation corresponding to actuator presence is executed once for 360 that installation or removal. 361 362 Incorrectly specified actuators may result in package installation 363 failure, if the actuator cannot determine a means of making 364 safe installation progress. 365 366 The following actuators are defined: 367 368 reboot_on_update Can be set to "true" or "false". If an action 369 with this actuator set to "true" is installed or 370 updated during a package installation, then the 371 packaging transaction can be advertised as requiring a 372 reboot. Certain client implementations may take 373 additional steps, such as performing the entire package 374 operation using a clone of the image, in the case that 375 the image is the live system image. 376 377 disable_fmri 378 refresh_fmri 379 restart_fmri 380 suspend_fmri Each of these actuators take the value of an FMRI of 381 a service instance to operate upon during the package 382 installation or removal. disable_fmri causes the 383 mentioned FMRI to be disabled prior to action removal, per 384 the disable subcommand to svcadm(1M). refresh_fmri and 385 restart_fmri cause the given FMRI to be refreshed or 386 restarted after action installation or update, per the 387 respective subcommands of svcadm(1M). Finally, 388 suspend_fmri causes the given FMRI to be disabled 389 temporarily prior to the action install phase, and then 390 enabled after the completion of that phase. 391 392 393 Constraints and Freezing 394 TBD 395 396 Client-Server Operation 397 TBD 398 399 Publishers and Mirroring 400 TBD 401 402 Images and Substrates 403 TBD 404 405 Properties 406 Images can have one or more properties associated with them. 407 These properties can be used to store information about the purpose, 408 content and behavior of the image. 409 410 Policy 411 Policies are defined by image properties with boolean values. The 412 supported policies include: 413 414 flush-content-cache-on-success 415 When true, the cache of downloaded files is erased after a 416 successful install of a package. Default value: False 417 418 send-uuid 419 When true, a unique identifier (UUID) that identifies the image 420 to the publisher is sent on all requests. Default value: False 421 422 ATTRIBUTES 423 See attributes(5) for descriptions of the following attri- 424 butes: 425 ____________________________________________________________ 426 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 427 |_____________________________|_____________________________| 428 | Availability | | 429 |_____________________________|_____________________________| 430 431 SEE ALSO 432 pkg(1), pkgsend(1), pkg.depotd(1M), svcadm(1M), pkginfo(4), 433 attributes(5) 434 435 NOTES 436 The image packaging system is an under-development feature. 437 Command names, invocation, formats, and operations are all subject 438 to change. Development is hosted in the OpenSolaris community 439 at 440 441 http://opensolaris.org/os/project/pkg/ 442
Indexes created Mon May 21 02:10:52 UTC 2012
Terms of Use
|
Privacy
|
Trademarks
|
Copyright Policy
|
Site Guidelines
|
Site Map
|
Help
Your use of this web site or any of its content or software indicates your agreement to be bound by these Terms of Use.
© 2012, Oracle Corporation and/or its affiliates.