Dealing with repositories

At the current point in time, there are not too many public IPS repositories running. That said, it is good to know how to query them. As briefly mentioned just now, the pkgrepo tool is the command to interact with repositories at the top level.

To find the repositories that your system is currently using, you can use the following command:

pkg publisher

You can then take the URI field from each of the output lines and run pkgrepo against it.

Official Oracle URIs for repositories are usually of the following format:

http://host.on.network/publisher/XXXXXXX

Once you have the URI of the repository you are interested in, you can query it for high-level information such as how many total packages are in the repository and the last time it was updated, as shown in the following output:

pkgrepo info -s http://pkg.oracle.com/solaris/release

This command will lead to the following output:

PUBLISHER    PACKAGES  STATUS    UPDATED
solaris      4292      online    2011-11-09T15:23:27.281209Z

Do note that, for some reason, Oracle has chosen the publisher in this case to be solaris, rather than oracle, so there is some unexpectedness in naming choices to get used to.

One advantage of using the pkgrepo command over the pkg command is that you can query packages from repos that are not currently configured as your current installation source.

pkgrepo list -s http://pkg.oracle.com/solaris/release \
'group/system/*'

While it is also possible to do a similar search with the pkg search -s http://... command, the output format of pkgrepo, in this case, is more readable, at least to me.

You can also use pkgrepo to get a list of potentially useful properties that the administrators of the repo may have set (somewhat akin to ZFS properties, using zfs get).

For example, the following command lets you know that there is a mirror of the Oracle repository available:

pkgrepo get -p all  -s http://pkg.oracle.com/solaris/release \
repository/mirrors

The preceding command will lead to the following output:

PUBLISHER  SECTION     PROPERTY  VALUE
solaris    repository  mirrors   (http://pkg-cdn1.oracle/com/solaris/release/)

Creating your own IPS repository and packages

At some point, you may wish to create your own IPS repository, particularly if you wish to have some custom scripts applied to automated installs. The old jumpstart "finish script" concept no longer exists; instead, hooks are given to load in custom services, which must be referenced through custom packages. Or, you may simply wish to have a local copy of the Solaris packages available.

Before you can create a package, you must first create a local repository. The old workflow of generating a single file.pkg to distribute is gone. The new tools are geared towards uploading files directly into a repository.

Creating a local repo

Happily, creating a simple repository with no access controls is relatively easy, so long as you follow the guidelines of always doing your packaging work on the same system that your repository lives on.

To make a repo in a designated directory, such as /var/pkgrepo, you just need to initialize the directory with the magic tool, as follows:

pkgrepo create /var/pkgrepo

This creates the directory, and a single master file inside it, called pkg5.repository.

If you plan on serving many files to many machines, Oracle recommends that you create a separate zfs filesystem for it, with access time (atime) turned off, for example:

zfs create somepool/repo
zfs set atime=off somepool/repo

Once you have created the basic top-level repo, you will want to create a publisher section. This can be done for your own company or for a copy of outside repositories, or both.

Copying the Oracle Solaris repository

The publisher designation for Solaris packages is not oracle.com but solaris. Therefore, if you plan to create a local copy of Solaris packages, you will effectively be setting up a mirror for the publisher named solaris.

Once you have created the top-level repository, use the pkgrecv command to mirror all packages in the Oracle repository to it. We can use the following command:

pkgrecv -s http://pkg.oracle.com/solaris/release -d /var/pkgrepo '*

Once that is done, you can override the default settings for where the system gets the Solaris packages by using the following command:

pkg set-publisher -g http://your.repo.url solaris

Creating your own company repository

Creating a namespace for your own company is easy. You simply need to set aside a designated publisher area for it, as shown in the following command:

pkgrepo add-publisher -s /var/pkgrepo "yourcompany.com"

Creating a package

Unlike the SVR4 pkg creation tools, you should normally dedicate an entire, untouched directory tree for your package creation efforts.

For clarity, let's presume a standard location for this that we'll call /stageroot.

Then, when you would normally install a program to /usr/local/bin/prog, for packaging purposes, it will get installed to /stageroot/usr/local/bin/prog.

Once you have assembled all the contents of your potential package under /stageroot, you must then generate a manifest for it with the following command:

pkgsend generate /stageroot >mypkg.mf

Next, you need to give the package an identity. This can be done by adding a single line, such as the following command, anywhere in the mypkg.mf file to designate its identity:

set name=pkg.fmri value=pkg://yourcompany.com/prog@1.0

Keep in mind that the value field can be as simple, or as complicated, as you like, within the boundaries of the IPS package naming scheme previously mentioned. For example, you may instead choose it to be pkg://yourcompany.com/utils/lowlevel/prog@1.0.1-75.

Uploading packages to the repository

Now that you have a complete manifest file and a staged tree of files for your package contents, you may integrate your package into your repository. This only takes one command, as follows:

pkgsend publish -s /var/pkgrepo -d /stageroot mypkg.mf

Tip

The pkgsend command will happily publish the exact same package collection multiple times, resulting in redundant packages in your repository. Be sure you have your versioning correct.

If the publish subcommand is completed successfully, you should be able to see the new version of your package, with the following command:

pkgrepo -s /var/pkgrepo list

Technically, it is quite possible to publish a package from normally installed program locations (that is to say, without a /stageroot prefix). Unfortunately, the IPS tools do not support the same functionality as the old pkgproto utility, which used to let you pass it a simple list of files and would then do the rest. This was allowed for relatively safe automated strategies such as:

find /usr/local -newer xyz | pkgproto >prog.template

Instead, with IPS, you would be required to hand-edit the manifest to have the needed paths in it, after which you could run the publish step without the -d option. However, this may lead to the creation of incomplete packages. Therefore, it is recommended that you use the method just explained, using the full but previously empty /stageroot.

Configuring machines to use your local repository

Once you can see your new packages successfully with a local test via pkgrepo, it is appropriate to open up access to the repository for other machines that need it.

The simplest way to do that is to share that directory via NFS and allow machines in your network to use your new repository. This can be done with the help of the following command:

pkg set-publisher -O /net/servername/var/pkgrepo yourcompany.com

Alternatively, you can set up a full IPS package server by configuring and enabling the application/pkg/server SMF service, as follows:

svccfg -s application/pkg/server setprop pkg/inst_root=/var/pkgrepo
svccfg -s application/pkg/server setprop pkg/readonly=true
//optionally, change the port number it runs on, with
svccfg -s application/pkg/server setprop pkg/port=(someportnum)

svcadm refresh application/pkg/server
svcadm enable application/pkg/server

Tip

If you have stuck with our example location of /var/pkgrepo, you will not actually have to mess around with svccfg properties. The default pkg/inst_root location is /var/pkgrepo. The default port is 80.

If you follow the SMF route, you will be able to configure clients with the following command:

pkg set-publisher -O http://your.server yourcompany.com

Once you have set a publisher entry for your custom repository, you should be able to run normal pkg commands on any client machines, thus:

pkg install prog

Or, you can use:

pkg install pkg://yourcompany.com/prog