PACKAGE(5)

NAME
package - format for OpenBSD binary packages

DESCRIPTION
Binary packages for OpenBSD can be created using pkg_create(1) and pkg_merge(1), and are usually manipulated using pkg_add(1), pkg_merge(1), pkg_mklocatedb(1), or pkg_info(1).

The basic underlying format is an archive following the ustar specification that can be handled with tar(1) and compressed using gzip(1).

Package names always end in “.tgz”; the file name itself should conform to packages-specs(7).

Note that the base distribution tarballs of OpenBSD (e.g. baseXXX.tgz, compXXX.tgz, ...) are not binary packages fit for pkg_add(1).

All types of archive contents can be present in a package, including files, directories, hardlinks, symlinks, fifos, block and character devices.

A special extension to the format, dubbed fat packages, is described in the next section.

In order to allow just-in-time extraction, packages always begin with a table of contents, named +CONTENTS. This table of contents can be read using the API described in OpenBSD::PackingList(3p).

All the remaining information in the archive should be referenced in the packing-list, including all relevant information: symlinks destinations, special permissions, and file owners. See pkg_create(1) for annotation details.

This table of contents is always followed by a few special files, some of which are optional: the package description (+DESC), an installation script (+INSTALL), a display message (+DISPLAY), etc.

The ustar format has some limitations with respect to file names. Accordingly, the package tools will replace very long names with LongName#n and long link names with LongLink#n. The packing-list will hold the real file names, and the package tools will reconstitute the correct names behind the scenes.

PACKAGE SIGNATURES
All information within a package is checksummed, using SHA256 since OpenBSD 4.4. During creation and installation, meta-information, such as file owners and permissions, are also checked: any important stuff that isn't recorded in the packing-list is an error.

Packing-lists can be signed. If a signature is found, then it will be checked during installation, and failure to verify will prevent the package from installing correctly. Currently, only x509-style signatures are supported. They rely on a certificate authority file being present as /etc/ssl/pkgca.pem and all signatures will be checked against it. Once the packing-list signature is checked, all individual packing elements will be checksummed, resulting in a ‘just-in-time’ signature checking.

FAT PACKAGES DESCRIPTION
The pkg_merge(1) command can create fat packages, which coalesce several normal packages in a single ustar archive, by interleaving their contents.

Other tools, such as pkg_add(1), are aware of fat packages and can handle them transparently.

In a fat package, every item has a small prefix that identifies the original package. For instance, after merging two packages, the package will usually begin with a/+CONTENTS and b/+CONTENTS. Individual items will then begin with ab/file, for a file common to both packages; a/file for a file belonging to the first package; and b/file for a file belonging to the second package.

SEE ALSO
pkg_add(1), pkg_create(1), pkg_info(1), pkg_merge(1), packages(7), packages-specs(7)

STANDARDS
Packages are valid gzip'ed ustar archives that can be extracted using tar(1). In particular, hardlink names should be valid, and all items will extract to different names. However, it may be a bit difficult to make sense of the package contents without peeking at the packing-list.