Using IPS Commands (Tasks)
The following section provides information for end users to install, upgrade, search, and
manage packages in the IPS repository.
Installing, Upgrading, and Managing Packages
The pkg(1) command is the retrieval client for the image packaging system.
pkg(1) can be invoked to perform the following actions :
Refer to the Chapter 8, pkg(1) Command Reference and the pkg(1) man page to learn more
about the subcommands and options for the pkg(1) command.
pkg(1) Uses FMRIs
Each IPS package is represented by a Fault Management Resource Identifier (FMRI). The
pkg(1) command uses valid FMRI package information to perform its command actions.
The FMRI includes descriptive information about the package, such as the package name,
version information, and date.
For example, the FMRI, pkg://opensolaris.org/library/[email protected],5.11-0.75:20071001T163427Z, consists of the following sequence of information
:
Creating Images
The pkg(1) command is used to create an image.
An installed OpenSolaris 2008.11 release on your system, constitutes an image. Packages can
be installed directly within this image. New images are created to mark a
boundary between the packages installed in different images.
The image-create command sets up a relationship between the image and a server
that can be accessed to add packages to the image.
Images can be of three types:
Full images, capable of providing a complete system.
Partial images, which are linked to a full image (parent image), but do not provide a complete system on their own.
User images, which contain only relocatable packages.
Note - Refer to the Table 8-1 for a table of all the options and their
descriptions associated with the pkg(1) commands.
How to Create an Image
Before You Begin
Ensure that you have write privileges to the directory where you are attempting
to create an image.
Example 2-1 Creating a Full Image
In this example, a full image is created with a repository server,
https://pkg.example.com set as the preferred authority. The image is created in the directory,
/aux0/example_root. The -a option is used to specify a server such as
https://pkg.example.com:10000.
$ pfexec pkg image-create -F -a example.com=https://pkg.example.com:10000 /aux0/example_root
Image Creation: Important Considerations
It is recommended that users do not create multiple images in the same directory.
It is recommended that users do not create an image under root (/).
A preferred authority must be set when creating an image. Use the -a option to set the preferred authority.
When you have multiple images on your system, use the PKG_IMAGE environment variable to specify what image you're operating on.
The current design of IPS assumes that only one version of a package is installed at once in a single image. To install multiple versions of the same package, the name of the package should include the version number, and dependencies should reflect the version number and bind to the appropriate package version.
How to Display Image Property
Example 2-2 Displaying Image Property
$ pkg property
PROPERTY VALUE
send-uuid False
require-optional False
lush-content-cache-on-success False
display-copyrights True
preferred-authority opensolaris.org
pursue-latest True
How to Set An Image Property
Example 2-3 Set the Value of an Image Property
This example sets the value of the send-uuid property.
pkg property
PROPERTY VALUE
send-uuid False
require-optional False
flush-content-cache-on-success False
display-copyrights True
preferred-authority opensolaris.org
pursue-latest True
pkg -R set-property send-uuid True
pkg property
PROPERTY VALUE
send-uuid True
require-optional False
flush-content-cache-on-success False
display-copyrights True
preferred-authority local
pursue-latest True
How to Remove an Image Property
- Use the following command to remove a property of an image.
$ pfexec pkg unset-property propname
The pkg unset-property command removes the specified property and resets the property to the
default value the next time a pkg(1) command is executed.
Note - The following properties are read-only and cannot be removed using this command.
display-copyrights
preferred-authority
pursue-latest
Example 2-4 Remove an Image Property
This example removes the send-uuid property.
$ pkg unset-property send-uuid
$ pkg property
PROPERTY VALUE
send-uuid False
require-optional False
flush-content-cache-on-success False
display-copyrights True
preferred-authority local
pursue-latest True
How to Perform a Dry-Run Installation Inside a New Image
Before installing packages, you have the option to perform a dry run installation.
A dry run enables you to execute the command without making persistent changes
to the image. The dry run option does not install any packages and only
shows the changes that are made if the packages are installed.
- Use the following command to execute a dry-run installation.
$ pkg install -n [-v] pkg_fmri
Note - pkg_fmri refers to a package name along with a version number and a
subversion number, if applicable.
Example 2-5 Performing a Dry-Run Installation of the SUNWzsh Package
The following example shows a dry-run installation of the SUNWzsh package with
verbose (-v) output.
$ pkg install --nv SUNWzsh
UNEVALUATED:+pkg:/[email protected],5.11-0.75:20071019T203321Z
one -> pkg:/[email protected],5.11-0.75:20071024T204210Z
[dir, file, link, and other actions for each resource delivered by
this package and succeeding packages omitted]
None -> pkg:/[email protected],5.11-0.75:20071024T204906Z
None -> pkg:/[email protected],5.11-0.75:20071024T204221Z
None -> pkg:/[email protected],5.11-0.75:20071024T204717Z
None -> pkg:/[email protected],5.11-0.75:20071024T204720Z
None -> pkg:/[email protected],5.11-0.75:20071024T204217Z
None -> pkg:/[email protected],5.11-0.75:20071024T202854Z
None -> pkg:/[email protected],5.11-0.75:20071024T204623Z
None -> pkg:/[email protected],5.11-0.75:20071024T202529Z
None -> pkg:/[email protected],5.11-0.75:20071024T204202Z
None -> pkg:/[email protected],5.11-0.75:20071019T202909Z
None -> pkg:/[email protected],5.11-0.75:20071019T203321Z
How to Install a Package
- Use the following command to install a package.
$ pfexec pkg install [-v] pkg_fmri
Note - The pkg install command is also used to update specific packages on the system.
The pkg install command automatically checks for newer versions of specific packages or package
groups and installs them if they are available. Any dependent packages are also
automatically updated.
Example 2-6 Install a Package
This example installs a SUNWphp524-mysql package. The output displays the status of the
download, number of packages that were installed, number of files that were installed
and the size (in megabytes) of the download.
$ pfexec pkg install SUNWphp524-mysql
DOWNLOAD PKGS FILES XFER (MB)
Completed 3/3 301/301 123.70/123.70
PHASE ACTIONS
Update Phase 2/2
Install Phase 404/404
Example 2-7 Install a Package From a Different Repository
When an image is created, a preferred authority is set and this
is the default authority from which packages are downloaded and installed.
See the How to Add or Update an Authority section to set an authority. The package is then installed
from the set authority.
This example installs the SUNWphp524-mysql package from the https://example.opensolaris.org authority.
$ pfexec pkg install pkg:/example.opensolaris.org/SUNWphp524-mysql
Example 2-8 Install a package in a Mounted, Inactive Boot Environment
This example installs a package in a boot environment that is mounted at
/mnt.
# beadm mount BE1 /mnt
# pkg -R /mnt install SUNWphp524-mysql
See the Getting Started with OpenSolaris 2008.11 to learn about the beadm command and boot environments.
How to Verify a Package Installation
Example 2-9 Verify Package Installation
In this example, the installation of SUNWphp524-mysql package is verified.
$ pkg verify -v SUNWphp524-mysql
PACKAGE STATUS
pkg:/SUNWphp524-mysql OK
How to Fix a Package
Example 2-10 Fix a Package
In this example, the package SUNWfreetype2 does not install correctly and pkg verify reports
the errors in the package contents.
$ pkg verify SUNWfreetype2
PACKAGE STATUS
pkg:/SUNWfreetype2 ERROR
[ ... some lines removed ... ]
file: usr/include/freetype2/freetype/ftxf86.h
Group: 'root' should be 'bin'
Mode: 0644 should be 0444
file: usr/include/freetype2/freetype/t1tables.h
Group: 'root' should be 'bin'
Mode: 0644 should be 0444
file: usr/include/freetype2/freetype/ttnameid.h
Group: 'root' should be 'bin'
Mode: 0644 should be 0444
file: usr/include/freetype2/freetype/tttables.h
Group: 'root' should be 'bin'
Mode: 0644 should be 0444
file: usr/include/freetype2/freetype/tttags.h
Group: 'root' should be 'bin'
Mode: 0644 should be 0444
file: usr/include/freetype2/freetype/ttunpat.h
Group: 'root' should be 'bin'
Mode: 0644 should be 0444
file: usr/include/ft2build.h
Group: 'root' should be 'bin'
Mode: 0644 should be 0444
file: usr/lib/amd64/libfreetype.so.6
Elfhash: c1a90b38212c745d0698adfa66e4b644aefef154 should be
efd14575d6af7df5dd8022d03d4766a8e6129c08
file: usr/lib/libfreetype.so.6
usr/lib/libfreetype.so.6 is not a regular file
Group: 'root' should be 'bin'
Mode: 0777 should be 0755
Elfhash: 1db8340c2119903fad4833579b7187e671c96ba6 should be
10a061f9241ce83d86369cef4f7d174b61cb5021
file: usr/lib/pkgconfig/freetype2.pc
Group: 'root' should be 'bin'
Size: 278 bytes should be 284
Hash: b7d784e06c03bd90d87cf96f79f6753b9e683390 should be
ee16a04987cbb9f0b5c4d21cf1333e167427917a
file: usr/share/aclocal/freetype2.m4
Group: 'root' should be 'bin'
Mode: 0644 should be 0444$ pfexec pkg fix SUNWfreetype2
How to Search for Packages
- Use the following command to search for packages based on the various properties
indexed by the packaging system.
$ pkg search [-lr] [-s repository_url] token
The search command searches in the installed image if no options are specified.
With the --r option, the command searches for the package in the repository
or repositories associated with the current image.
Example 2-11 Search for a Package in the Installed Image
The following example searches and locates the SUNWbash package in the installed image.
$ pkg search SUNWbash
INDEX ACTION VALUE PACKAGE
fmri set fmri pkg:/[email protected]
legacy_pkg legacy SUNWbash pkg:/[email protected]
Example 2-12 Search For a Package in a Remote Repository
If you want to install the WebStack development package , search for the
amp package in the remote (-r) repository associated with the current image.
$ pkg search -r amp
INDEX ACTION VALUE PACKAGE
description set AMP pkg:/[email protected]
description set AMP pkg:/[email protected]
description set AMP pkg:/[email protected]
description set AMP pkg:/[email protected]
description set AMP pkg:/[email protected]
description set AMP pkg:/[email protected]
description set AMP pkg:/[email protected]
description set AMP pkg:/[email protected]
How to Update An Image (Update All Installed Packages)
This task will update all installed packages in the current image to the
latest available version.
Note - All packages that have been updated in the repository will be downloaded and
installed.
Example 2-13 Update an Image in a Mounted, Inactive Boot Environment
This example updates an image in a boot environment that is mounted at
/mnt. See the Getting Started with OpenSolaris 2008.11 to learn about the beadm command and boot
environments.
# beadm mount BE1 /mnt
# pkg -R /mnt image-update
See Also
The pkg image-update command can also be used to upgrade an installed boot environment.
For more information, see the Upgrading and Managing Your Boot Environment section.
How to Display the State of Packages
- Use the following command to see the state of packages.
$ pkg list [-aHsuvf] pkg_fmri
By default, the pkg list shows the most recent version of a package, and,
if the package is installed, the installed version.
Example 2-14 Displaying the State of an Installed Package
The following example shows the status of the SUNWbash package with the -v
option, which displays the full FMRI information. This example shows information only about
the installed SUNWbash package.
$ pkg list -v SUNWbash
FMRI STATE UFIX
pkg:/[email protected],5.11-0.79:20080205T152506Z installed ----
Example 2-15 Displaying the State of All Instances of a Package
This example shows the state of all instances of the SUNWbash package.
$ pkg list -a SUNWbash
NAME (AUTHORITY) VERSION STATE UFIX
SUNWbash 3.2.25-0.86 installed ----
SUNWbash 3.2.25-0.79 known u---
SUNWbash 3.2.25-0.75 known u---
SUNWbash 3.2.25-0.75 known u---
How to List the Contents of a Package
Example 2-16 Listing the Contents of a Package
In this example, we will list the name, mode of the file,
size, path and the target of the following actions in the zfs package:
$ pkg contents -t dir,file,link,hardlink -o action.name,mode,pkg.size,path,target zfs
NAME MODE SIZE PATH TARGET
dir 0755 etc
dir 0755 etc/fs
dir 0755 etc/fs/zfs
link etc/fs/zfs/mount ../../../sbin/zfs
link etc/fs/zfs/umount ../../../sbin/zfs
dir 0755 etc/zfs
dir 0755 lib
dir 0755 lib/amd64
link lib/amd64/libzfs.so libzfs.so.1
file 0755 469616 lib/amd64/libzfs.so.1
file 0644 62057 lib/amd64/llib-lzfs.ln
link lib/libzfs.so libzfs.so.1
[ ... ]Example 2-17 Displaying Complete Contents of a Package
This example uses the -m option with the pkg contents command to display
all actions of the SUNWbash package.
$ pkg contents -m SUNWbash
set fmri = pkg://opensolaris.org
/[email protected],5.11-0.79:20080205T152506Z
dir owner=root path=usr group=sys mode=0755
dir owner=root path=usr/bin group=bin mode=0755
dir owner=root path=usr/gnu group=bin mode=0755
dir owner=root path=usr/gnu/bin group=bin mode=0755
depend fmri=pkg:/[email protected] type=require
file 66d09735123ad3a7bdcf7640dd60acbe843d8a13
elfhash=28106285f73f97274cf99b1a7e63d7d73c31c153 elfarch=i386 mode=0555
pkg.size=730604 owner=root group=bin path=usr/bin/bash elfbits=32
legacy category=system vendor="Sun Microsystems, Inc."
name="GNU Bourne-Again shell (bash)"
version=11.11.0,REV=2007.11.29.14.44 hotline="Please contact your local service provider"
pkg=SUNWbash arch=i386 desc="GNU Bourne-Again shell (bash) version 3.2"
license ed881c52c54b67457db33ba23a1d53615e366440 path=copyright
license=SUNWbash.copyright
transaction_id=1202253906_pkg%3A%2FSUNWbash%
403.2.25%2C5.11-0.79%3A20080205T152506Z pkg.size=1207
link path=usr/gnu/bin/sh target=../../bin/bash
set name=description value="GNU Bourne-Again shell (bash)"
set fmri = pkg://VERSION_1
/[email protected],5.11-0.79:20080205T152506Z
dir owner=root path=usr group=sys mode=0755
dir owner=root path=usr/bin group=bin mode=0755
dir owner=root path=usr/gnu group=bin mode=0755
dir owner=root path=usr/gnu/bin group=bin mode=0755
depend fmri=pkg:/[email protected] type=require
file 66d09735123ad3a7bdcf7640dd60acbe843d8a13
elfhash=28106285f73f97274cf99b1a7e63d7d73c31c153
elfarch=i386 mode=0555 pkg.size=730604 owner=root group=bin path=usr/bin/bash elfbits=32
legacy category=system vendor="Sun Microsystems, Inc."
name="GNU Bourne-Again shell (bash)" version=11.11.0,REV=2007.11.29.14.44
hotline="Please contact your local service provider"
pkg=SUNWbash arch=i386 desc="GNU Bourne-Again shell (bash) version 3.2"
license ed881c52c54b67457db33ba23a1d53615e366440 path=copyright
license=SUNWbash.copyright
transaction_id=1202253906_pkg%3A%2FSUNWbash%403.2.25
%2C5.11-0.79%3A20080205T152506Z
pkg.size=1207
link path=usr/gnu/bin/sh target=../../bin/bash
set name=description value="GNU Bourne-Again shell (bash)"
How to List Information About a Package
Example 2-18 Display Package Information
This example displays information about the SUNWbash package.
Name: SUNWbash
Summary: GNU Bourne-Again shell (bash)
Authority: pkg.com (preferred)
Version: 3.2.25
Build Release: 5.11
Branch: 0.79
Packaging Date: Tue Feb 5 15:25:06 2008
Size: 714 kB
FMRI: pkg:/[email protected],5.11-0.79:20080205T152506Z
Example 2-19 Display Copyright and License Information About a Package
This example displays the copyright and license information about the SUNWGlib package.
$ pkg info --license -r SUNWGlib
Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
Modified by the GLib Team and others 1997-1999. See the AUTHORS
file for a list of people on the GLib Team. See the ChangeLog
files for a list of changes. These files are distributed with
GLib at ftp://ftp.gtk.org/pub/gtk/.
How to Uninstall Packages
Example 2-20 Uninstalling a Package
This example uninstalls the SUNWphp524-mysqlpackage.
$ pfexec pkg uninstall SUNWphp524-mysql
PHASE ACTIONS
Removal Phase 39/39
How to Add or Update an Authority
Example 2-21 Adding an Additional Package Authority
$ pfexec pkg set-authority -O https://pkg.sunfreeware.com:9000 sunfreeware.com
$ pkg authority
AUTHORITY URL
opensolaris.org (preferred) https://pkg.opensolaris.org:80/
sunfreeware.com https://pkg.sunfreeware.com:9000/
Example 2-22 Setting a Preferred Authority
Use the -P option along with the -O option to set an authority
as the preferred authority. This is the default authority from which packages are
downloaded and installed.
$ pfexec pkg set-authority -P -O https://pkg.sunfreeware.com:80 sunfreeware.com
$ pkg authority
AUTHORITY
opensolaris.org https://pkg.opensolaris.org:80/
sunfreeware.com (preferred) https://pkg.sunfreeware.com:80/
See Also
The pkg set-authority command is also used to add and remove mirror repositories. See
the Chapter 6, Mirroring Repositories section for more information.
How to Remove Authority Configuration
Example 2-23 Removing an Authority
$ pfexec pkg unset-authority sunfreeware.com
$ pkg authority
AUTHORITY URL
opensolaris.org (preferred) https://pkg.opensolaris.org:80/
How to Display Authority Information
Example 2-24 Displaying Authority Information
$ pkg authority
AUTHORITY URL
opensolaris.org (preferred) https://pkg.opensolaris.org:80/
How to View the Command History
- Type the following command to view the command history in the current image.
$ pkg history [-Hl]
Example 2-25 View Detailed Command History
$ pkg history -l
Operation: purge-history
Outcome: Succeeded
Client: pkg
Version: 71eab3488987
User: root (0)
Start Time: 2008-10-28T09:00:35
End Time: 2008-10-28T09:00:35
Command: /usr/bin/pkg -R /export/home/dc/build_data/pkg_image purge-history
Operation: uninstall
Outcome: Succeeded
Client: pkg
Version: 71eab3488987
User: jack (65432)
Start Time: 2008-10-29T11:15:09
End Time: 2008-10-29T11:16:41
Command: /usr/bin/pkg -R /a uninstall -q SUNWslim-utils
Start State:
UNEVALUATED:
-pkg:/[email protected],5.11-0.100:20081025T020505Z
End State:
pkg:/[email protected],5.11-0.100:20081025T020505Z -> None
Operation: install
Outcome: Failed (Unknown)
Client: packagemanager
Version: 71eab3488987
User: jack (101)
Start Time: 2008-10-29T11:31:13
End Time: 2008-10-29T11:32:04
Command: /usr/bin/packagemanager
How to Delete The Command History Information
How to View The List of Available Commands
- Type the following command to view the list of available commands.
$ pkg help
Authority vs Repository
An authority and a repository definition are sometimes used interchangeably in IPS and
have different meanings at other times. The following points expound upon the definitions
and clarify their usage.
An authority is a person, groups of persons, or a corporation that publishes a package.
A repository is a location from where packages are downloaded from . The location constitutes an address (URL) of a machine .
A repository can contain packages from many authorities. Conversely many repositories can contain packages from a single authority.
A default or preferred authority is similar to a default catalog. Any package chosen for installation is first searched for in the preferred authority's catalog. This package may be available for download from different repositories.
You can have many repositories and one default authority. In this case, the default authority becomes the default repository.
If there is only one default repository, it also becomes the default authority.
