unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

PACKAGE(5)                  BSD File Formats Manual                 PACKAGE(5)

NAME
     package -- format for OpenBSD binary packages

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

     The basic underlying format is an archive following the ustar specifica-
     tion 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. baseXX.tgz,
     compXX.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.

     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 (pkg_create(1) and pkg_add(1)
     actually enforce this).  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), a display message
     (+DISPLAY), etc.

     The basic ustar format has some limitations with respect to file names.
     Packages now use the "extended record specification" (header type x) for
     long links and long file names.  Other extended ustar headers are cur-
     rently recognized, but not supported.

     Starting with OpenBSD 5.5, the compressed archive may be composed of sev-
     eral gzip(1) archives concatenated together.  gzip(1) doesn't mind, and
     tar(1) is happy as long as the uncompressed stream is sane.  This allows
     for faster signing and better rsync properties.

     Starting with OpenBSD 5.6, tarballs are stored "out-of-order": each ar-
     chive entry will match an entry in the packing-list (and all file-like
     entries will be matched), but the order will be adjusted so that most
     recently changed files come first, in order to allow faster updates.

PACKING LIST ANNOTATIONS
     User annotations are described in pkg_create(1).  The following annota-
     tions are automatically inserted during package creation and installa-
     tions:

     @arch arches
             List of architectures for which this package is intended.  This
             corresponds to -A arches of pkg_create(1)

     @comment pkgpath=path cdrom=yes/no ftp=yes/no
             Historical accident.  This specific comment encodes the actual -D
             FULLPKGPATH, -D CDROM, and -D FTP arguments to pkg_create(1).

     @depend pkgpath:pkgspec:default
             Record a dependency declared using the option -P of
             pkg_create(1).

     @digital-signature style:date:b64sig
             Record a digital signature of the packing-list, corresponding to
             pkg_create(1)'s -s option.

     @link name
             Added after a file entry by package to record that the entry is
             actually a hard link.

     @localbase base
             Used internally to record the settings of -L option.

     @name pkgname
             Set the name of the package.  This name is potentially different
             than the name of the file it came in, and is used when keeping
             track of the package for later deinstallation.  pkg_create(1)
             will derive this field from the package file name.

     @option name
             Some options are automatically inserted by the package tools:

             firmware
                     Set by fw_update(1) to trigger firmware-specific han-
                     dling.  In particular, firmwares are hidden from normal
                     updates.

             manual-installation
                     Record that a package has been explicitly installed by
                     the user, and not as a result of a dependency look-up.
                     Refer to pkg_add(1)'s -a option for details.

     @sha    Added after a file entry by pkg_create(1) to record the files's
             cryptographic checksum, as a sha256 digest encoded in base64.

     @signer
             Internal annotation necessary to identify packages signed with
             signify(1) keys, as those keys don't carry any identity.

     @size   Added after a file entry by pkg_create(1) to record a file size.

     @symlink name
             Added after a file entry by pkg_create(1) to record that the
             entry is actually a symbolic link.

     @url    Original location of the package, automatically recorded in
             installed packages by pkg_add(1).

     @ts timestamp
             Added after a file entry to record the actual file timestamp.
             The package tools read and process that annotation correctly.
             Starting with OpenBSD 5.7, pkg_create(1) will migrate timestamps
             from the tarball meta-info to the packing-list to better create
             unchanging archive chunks.

     @wantlib libspec
             Record a library requirement declared using the option -W of
             pkg_create(1).

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 pack-
     age from installing correctly.  Currently, signify(1) and X.509-style
     signatures are supported.  X.509 signatures rely on a certificate author-
     ity 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 were removed in OpenBSD 5.1, since no practical application
     was found.

SEE ALSO
     pkg_add(1), pkg_create(1), pkg_info(1), pkg_sign(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.

BSD                             March 23, 2017                             BSD