1.\" $OpenBSD: package.5,v 1.24 2015/09/10 15:16:44 schwarze Exp $ 2.\" Copyright (c) 2005-2006 Marc Espie <espie@openbsd.org> 3.\" 4.\" Permission to use, copy, modify, and distribute this software for any 5.\" purpose with or without fee is hereby granted, provided that the above 6.\" copyright notice and this permission notice appear in all copies. 7.\" 8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15.Dd $Mdocdate: September 10 2015 $ 16.Dt PACKAGE 5 17.Os 18.Sh NAME 19.Nm package 20.Nd format for OpenBSD binary packages 21.Sh DESCRIPTION 22Binary packages for 23.Ox 24can be created using 25.Xr pkg_create 1 26and are usually manipulated using 27.Xr pkg_add 1 , 28.Xr pkg_mklocatedb 1 , 29or 30.Xr pkg_info 1 . 31.Pp 32The basic underlying format is an archive following the ustar specification 33that can be handled with 34.Xr tar 1 35and compressed using 36.Xr gzip 1 . 37.Pp 38Package names always end in 39.Dq .tgz ; 40the file name itself should conform to 41.Xr packages-specs 7 . 42.Pp 43Note that the base distribution tarballs of 44.Ox 45(e.g.\& 46.Pa baseXX.tgz , 47.Pa compXX.tgz , 48\&...) are not binary packages fit for 49.Xr pkg_add 1 . 50.Pp 51All types of archive contents can be present in a package, 52including files, directories, hardlinks, symlinks, fifos, block and character 53devices. 54.Pp 55In order to allow just-in-time extraction, 56packages always begin with a table of contents, named 57.Pa +CONTENTS . 58This table of contents can be read using the API described in 59.Xr OpenBSD::PackingList 3p . 60.Pp 61All the remaining information in the archive should be referenced in 62the packing-list, including all relevant information: symlinks destinations, 63special permissions, and file owners 64.Po 65.Xr pkg_create 1 66and 67.Xr pkg_add 1 68actually enforce this 69.Pc . 70See 71.Xr pkg_create 1 72for annotation details. 73.Pp 74This table of contents is always followed by a few special files, some of 75which are optional: the package description (+DESC), 76a display message (+DISPLAY), etc. 77.Pp 78The basic ustar format has some limitations with respect to file names. 79Packages now use the 80.Qq extended record specification 81(header type x) 82for long links and long file names. 83Other extended ustar headers are currently recognized, but not supported. 84.Pp 85Starting with 86.Ox 5.5 , 87the compressed archive may be composed of several 88.Xr gzip 1 89archives concatenated together. 90.Xr gzip 1 91doesn't mind, and 92.Xr tar 1 93is happy as long as the uncompressed stream is sane. 94This allows for faster signing and better rsync properties. 95.Pp 96Starting with 97.Ox 5.6 , 98tarballs are stored 99.Qq out-of-order : 100each archive entry will match an entry in the packing-list (and all file-like 101entries will be matched), but the order will be adjusted so that most recently 102changed files come first, in order to allow faster updates. 103.Sh PACKING LIST ANNOTATIONS 104User annotations are described in 105.Xr pkg_create 1 . 106The following annotations are automatically inserted during package creation 107and installations: 108.Pp 109.Bl -tag -width Ds -compact 110.It Cm @arch Ar arches 111List of architectures for which this package is intended. 112This corresponds to 113.Fl A Ar arches 114of 115.Xr pkg_create 1 116.Pp 117.It Cm @comment pkgpath=path cdrom=yes/no ftp=yes/no 118Historical accident. 119This specific comment encodes the actual 120.Fl D Ar FULLPKGPATH , 121.Fl D Ar CDROM , 122and 123.Fl D Ar FTP 124arguments to 125.Xr pkg_create 1 . 126.Pp 127.It Xo 128.Cm @depend 129.Sm off 130.Ar pkgpath : 131.Ar pkgspec : 132.Ar default 133.Sm on 134.Xc 135Record a dependency declared using the option 136.Fl P 137of 138.Xr pkg_create 1 . 139.Pp 140.It Xo 141.Cm @digital-signature 142.Sm off 143.Ar style : 144.Ar date : 145.Ar b64sig 146.Sm on 147.Xc 148Record a digital signature of the packing-list, corresponding 149to 150.Xr pkg_create 1 Ns 's 151.Fl s 152option. 153.Pp 154.It Cm @link Ar name 155Added after a file entry by 156.Nm 157to record that the entry is actually a hard link. 158.Pp 159.It Cm @localbase Ar base 160Used internally to record the settings of 161.Fl L 162option. 163.Pp 164.It Cm @name Ar pkgname 165Set the name of the package. 166This name is potentially different than the name of 167the file it came in, and is used when keeping track of the package 168for later deinstallation. 169.Xr pkg_create 1 170will derive this field from the package file name. 171.Pp 172.It Cm @option Ar name 173Some options are automatically inserted by the package tools: 174.Bl -tag -width indent 175.It Ar firmware 176Set by 177.Xr fw_update 1 178to trigger firmware-specific handling. 179In particular, firmware is hidden from normal updates. 180.It Ar manual-installation 181Record that a package has been explicitly installed by the user, 182and not as a result of a dependency look-up. 183Refer to 184.Xr pkg_add 1 Ns 's 185.Fl a 186option for details. 187.El 188.Pp 189.It Cm @sha 190Added after a file entry by 191.Xr pkg_create 1 192to record the files's cryptographic checksum, 193as a sha256 digest encoded in base64. 194.Pp 195.It Cm @signer 196Internal annotation necessary to identify packages signed with 197.Xr signify 1 198keys, as those keys don't carry any identity. 199.Pp 200.It Cm @size 201Added after a file entry by 202.Xr pkg_create 1 203to record a file size. 204.Pp 205.It Cm @symlink Ar name 206Added after a file entry by 207.Xr pkg_create 1 208to record that the entry is actually a symbolic link. 209.Pp 210.It Cm @url 211Original location of the package, automatically recorded in installed packages 212by 213.Xr pkg_add 1 . 214.Pp 215.It Cm @ts Ar timestamp 216Added after a file entry to record the actual file timestamp. 217The package tools read and process that annotation correctly. 218Starting with 219.Ox 5.7 , 220.Xr pkg_create 1 221will migrate timestamps from the tarball meta-info to the packing-list 222to better create unchanging archive chunks. 223.Pp 224.It Cm @wantlib Ar libspec 225Record a library requirement declared using the option 226.Fl W 227of 228.Xr pkg_create 1 . 229.El 230.Sh PACKAGE SIGNATURES 231All information within a package is checksummed, using SHA256 since 232.Ox 4.4 . 233During creation and installation, meta-information, such as file owners and 234permissions, are also checked: any important stuff that isn't recorded 235in the packing-list is an error. 236.Pp 237Packing-lists can be signed. 238If a signature is found, then it will be checked 239during installation, and failure to verify will prevent the package from 240installing correctly. 241Currently, 242.Xr signify 1 243and X.509-style signatures are supported. 244X.509 signatures rely on a certificate authority file being present as 245.Pa /etc/ssl/pkgca.pem 246and all signatures will be checked against it. 247Once the packing-list signature is checked, all individual packing elements 248will be checksummed, resulting in a 249.Sq just-in-time 250signature checking. 251.Pp 252Fat packages were removed in 253.Ox 5.1 , 254since no practical application was found. 255.Sh SEE ALSO 256.Xr pkg_add 1 , 257.Xr pkg_create 1 , 258.Xr pkg_info 1 , 259.Xr pkg_sign 1 , 260.Xr packages 7 , 261.Xr packages-specs 7 262.Sh STANDARDS 263Packages are valid gzip'ed ustar archives that can be extracted using 264.Xr tar 1 . 265In particular, hardlink names should be valid, and all items will 266extract to different names. 267However, it may be a bit difficult to make sense of the package contents 268without peeking at the packing-list. 269