IPS for Developers (Commands)

The following section provides an overview of the pkgsend(1) and pkg.depotd(1) commands. These commands enable you to create and administer an IPS repository. Additionally, this section describes the role of actions in IPS.

The Publication Client pkgsend(1)

The image packaging system publication client, pkgsend, allows the publication of new packages and new package versions to an image packaging repository. Each publication is structured as a transaction. Transactions may contain actions as described in the section Actions in IPS.

The pkgsend(1) command supports the following subcommands :

Note - The default repository server is http://localhost:10000. To specify a different repository server , use the -s repository-server option with the pkgsend subcommands.

Table 2-1 pkgsend(1) Subcommands

Subcommand	Description
`open`	Begins a transaction on the package specified by pkg_fmri. A `transaction_id` is outputted when the command executes successfully. Syntax : `pkgsend open -en pkg_fmri` `-e`– Use this option to prepend `export PKG_TRANS_ID=` to the `transaction_id`. This can be used by the shell to evaluate the output and set the environment variable `PKG_TANS_ID`. This environment variable can be used when executing future `pkgsend` commands within the same transaction. For information about FMRI, see the Solaris Basic Administration Guide.
add	Adds a resource associated with an action to the current transaction. Syntax : `pkgsend add actions pkg_fmri`
include	Adds resources associated with the multiple actions present in each manifest file to the current transaction. Each line in the file should be the string representation of an action. Do not use this sub command with the `add`, `open` or `close` sub-commands. Syntax : `pkgsend include filename`
import bundlefile	Adds each given bundle file into the current transaction.
close	Close the current transaction. Syntax : `pkgsend close [-a]` The `-a` option abandons the current transaction.
send bundlefile	Sends each given bundlefile as a new package version, in an appropriate series of transactions Syntax : `pkgsend send bundlefile`

Limitations of the pkgsend(1) Command

Note the following limitations of using the pkgsend command:

Use the pkgsend command only if one or two packages at a time are being published to the repository.
The pkgsend command does not resolve dependencies. If more than one package is being published to the repository, the user must manually resolve all package dependencies.
Note the following points when publishing a newer version of a package to the repository.
- Specify the FMRI of the package correctly. The new version of the package will coexist with any prior version already in the repository.
- Use the same command such as pkgsend send or pkgsend include to publish the newer version, as that was used to publish the previous version of the package.

Actions in IPS

IPS manages software in units of packages. Packaging a product aids in easy distribution and installation of the software product.

A package is a collection of files, directories, links, drivers, and dependencies in a defined format. This collection represents the installable objects of a package. In IPS terminology, this collection is referred to as actions.

Actions are described in a package's manifest. Every action consists primarily of its name and a key attribute. Together, these attributes refer to a unique object and include a version history. Actions can have other attributes. Some of these attributes are interpreted directly by the packaging system, others are useful only to the system administrator or the end user.

Note - The attributes of a package are different from the attributes of an action. See the Package Attributes and Tags section to learn about the supported tags and attributes for a package.

Typically, only an action's key attribute is required, though some actions might work properly only with a more complete set of attributes.

The following list provides an overview of the type of actions and their standard attributes that are available with IPS. For additional details, see the pkg(5) man page.

Note - pkg(5) refers to the image packaging system and is different from the pkg(1) command, which is the retrieval client and is used to create, install, and manage images on the system

Note - The following table shows a list of the actions and their key attributes. For a complete list, refer to the pkg(5) man page.

Table 2-2 Actions and Key Attributes

Action	Description and Key Attributes
Directory	The directory action represents a directory as a file system object. path – The filesystem path where the file is installed.
File	The file action represents an ordinary file as a file system object. path – The file system path where the file is installed.
Link	The link action represents a symbolic link. path – The file system path where the `symlink` is installed.
Hardlink	The hardlink action represents a physical link. path – The file system path where the link is installed.
Driver	The driver action represents a device driver. It does not reference a payload, the driver files must be installed as file actions. name – The name of the driver. This is usually, but not always, the file name of the driver binary.
Depend	The depend action represents a dependency between packages. A package might depend on another package to work or to install. Dependencies are optional. No key attribute defined.
License	The license action represents a license or other information associated with the package contents. A package can deliver licenses or disclaimers to the package installer through the use of the license action. The payload of the license action is delivered into the image metadata directory associated with the package. license – The keyword identifying the license type, for use in filter and query operations
Legacy	The legacy action represents package data used by a legacy packaging system. The attributes associated with this action are added to the legacy system's databases so that the tools querying those databases might operate as if the legacy package were actually installed. pkg – The abbreviation for the package being installed. The name of the package in the package FMRI is the default value.
Set	The set action represents a package-level attribute, such as the package description. No key attribute defined.
Group	The group action defines a UNIX^® group as defined in `group(4)`. No support is present for group passwords. Groups defined with this action initially have no user-list. Users can be added with the user action. No key attribute defined.
User	The User action defines a UNIX user as defined in `/etc/passwd`, `/etc/shadow`, `/etc/group` and `/etc/ftpd/ftpusers` files. Users defined with this attribute have entries added to the appropriate files. No key attribute defined.

Package Attributes and Tags

The attributes and tags of a package can be set with the set action.

Packages carry information about themselves in the form of metadata, which is also informally known as attributes and tags. Attributes refer to settings that apply to an entire package. Tags are the settings that affect individual files within a package. The package developer provides specific information about the package through the tags and attributes.

The pkg attribute is the attribute that is common to all packages, regardless of any particular OS platforms that a specific package might target.

The IPS packages can contain the following set of tags and attributes.

Table 2-3 Package Attributes

Attribute	Description
Package Name : `pkg.name`	Short, descriptive name of the package.
Package Description : `pkg.description`	A short paragraph describing the package.
Package URL: `pkg.detailed_url`	Used to provide links to sites with further information about the package.

Table 2-4 Tags

Tag	Description
Debug Information: `pkg.debug`	Used to specify if the package needs to be installed in a debug configuration.
`ISA`	Distinguishes between different x86 platforms.

The opensolaris attribute is the attribute that is common to all OpenSolaris packages.

Note - In the following table, except ISA attribute, all atributes have opensolaris appended to them. For example, the attribute arc.url should be specified as opensolaris.arc_url.

Table 2-5 OpenSolaris Attributes

OpenSolaris Attribute	Description
`arc_url`	One or more URLs associated with the ARC case(s) associated with the component(s) delivered by the package.
`maintainer`	A human readable string describing the entity that provides the package. For an individual, this string is their name, or name and email address.
`ISA`	Distinguishes between different x86 platforms.
`upstream`	A human—readable string describing the entity that creates the software. For an individual, this string is expected to be the individual's name, or name and email.
`upstream_url`	A URL associated with the entity that creates the software delivered within the package.
`source_url`	A URL to the source code bundle, if appropriate, for the package.
`repository_url`	A URL to the source code repository, if appropriate, for the package.
`repository_changeset`	A changeset ID for the version of the source code contained in `opensolaris.repository_url` attribute.
`gui.classification`	A list of labels classifying the package into the categories shared among `pkg(5)`graphical clients.

Overview of the Depot Server `pkg.depotd`

The pkg(1) command makes requests of the repository, also called the depot server, for catalogs and packages. The pkgsend(1) command sends new versions of packages to the depot server. The depot server is typically run as a service on the system. Package and software developers can run private copies for various testing purposes. The pkg.depotd service is managed by the service management facility, smf(5), under the service identifier: svc:/application/pkg/server. Because the depot server expects to be run by a smf(5) restarter, it does not run daemon processes. Error messages are generally sent to standard output, or to the syslogd(1M) system.

The pkg.depotd server is usually configured through the smf(5) properties associated with its service instance. The following properties are recognized.

Table 2-6 `pkg.depotd(1M)` Properties

Property	Description
pkg/inst_root	The file system path where this instance of the depot server should look for its repository data. The default value is `/var/pkg/repo`.
pkg/port	The port number on which this instance of the depot server should listen to for incoming package requests. The default value is 80.

The pkg.depotd(1M) command has the following options to alter the default settings from the service instance.

Table 2-7 `pkg.depotd(1M)` Options

Option	Description
`-d` repo_dir	Specify a different repository directory. Overrides `pkg/inst_root` with the value given by repo_dir.
`-p` port	Specify a different port number. Overrides `pkg/port` with the value given by port.

For further information, see the pkg.depotd(1M) man page.

Example 2-18 Enabling the Depot Server

Type the following command as root user to enable the depot server. In this example, application/pkg/server is the depot server.

# svcadm enable application/pkg/server

Example 2-19 Changing the Listening Port of The Depot Server

Type the following sequence of commands as root user to change the listening port of the depot server. This example sets the listening port of the depot server to 9999.

# svccfg -s application/pkg/server set pkg/port = 9999
# svcadm refresh application/pkg/server
# svcadm restart application/pkg/server