1.\" $OpenBSD: package.5,v 1.28 2019/12/04 11:01:37 espie 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: December 4 2019 $ 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 installation: 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 ftp=yes/no 118Historical accident. 119This specific comment encodes the actual 120.Fl D Ar FULLPKGPATH , 121and 122.Fl D Ar FTP 123arguments to 124.Xr pkg_create 1 . 125.Pp 126.It Xo 127.Cm @depend 128.Sm off 129.Ar pkgpath : 130.Ar pkgspec : 131.Ar default 132.Sm on 133.Xc 134Record a dependency declared using the option 135.Fl P 136of 137.Xr pkg_create 1 . 138.Pp 139.It Xo 140.Cm @digital-signature 141.Sm off 142.Ar style : 143.Ar date : 144.Ar details 145.Sm on 146.Xc 147Record a digital signature of the packing-list, synthetized by 148.Xr pkg_add 1 149from 150.Xr signify 1 151output. 152.Pp 153.It Cm @link Ar name 154Added after a file entry by 155.Nm 156to record that the entry is actually a hard link. 157.Pp 158.It Cm @localbase Ar base 159Used internally to record the settings of 160.Fl L 161option. 162.Pp 163.It Cm @name Ar pkgname 164Set the name of the package. 165This name is potentially different than the name of 166the file it came in, and is used when keeping track of the package 167for later deinstallation. 168.Xr pkg_create 1 169will derive this field from the package file name. 170.Pp 171.It Cm @option Ar name 172Some options are automatically inserted by the package tools: 173.Bl -tag -width indent 174.It Ar firmware 175Set by 176.Xr fw_update 1 177to trigger firmware-specific handling. 178In particular, firmware is hidden from normal updates. 179.It Ar manual-installation 180Record that a package has been explicitly installed by the user, 181and not as a result of a dependency look-up. 182Refer to 183.Xr pkg_add 1 Ns 's 184.Fl a 185option for details. 186.El 187.Pp 188.It Cm @sha 189Added after a file entry by 190.Xr pkg_create 1 191to record the files's cryptographic checksum, 192as a sha256 digest encoded in base64. 193.Pp 194.It Cm @signer 195Internal annotation necessary to identify packages signed with 196.Xr signify 1 197keys, as those keys don't carry any identity. 198.Pp 199.It Cm @size 200Added after a file entry by 201.Xr pkg_create 1 202to record a file size. 203.Pp 204.It Cm @symlink Ar name 205Added after a file entry by 206.Xr pkg_create 1 207to record that the entry is actually a symbolic link. 208.Pp 209.It Cm @url 210Original location of the package, automatically recorded in installed packages 211by 212.Xr pkg_add 1 . 213.Pp 214.It Cm @ts Ar timestamp 215Added after a file entry to record the actual file timestamp. 216The package tools read and process that annotation correctly. 217Starting with 218.Ox 5.7 , 219.Xr pkg_create 1 220will migrate timestamps from the tarball meta-info to the packing-list 221to better create unchanging archive chunks. 222.Pp 223.It Cm @version Ar number 224Record a global (system) version number for the package. 225This is built adding together 226.Fl V 227options from 228.Xr pkg_create 1 , 229and triggers updates when it changes. 230.Pp 231.It Cm @wantlib Ar libspec 232Record a library requirement declared using the option 233.Fl W 234of 235.Xr pkg_create 1 . 236.El 237.Pp 238Note that most of these annotations cannot be added manually, as 239.Xr pkg_create 1 240will error out. 241.Sh PACKAGE SIGNATURES 242All information within a package is checksummed, using SHA256 since 243.Ox 4.4 . 244During creation and installation, meta-information, such as file owners and 245permissions, are also checked: any important stuff that isn't recorded 246in the packing-list is an error. 247.Pp 248Packing-lists can be signed. 249If a signature is found, then it will be checked 250during installation, and failure to verify will prevent the package from 251installing correctly. 252.Pp 253Starting with 254.Ox 6.1 , 255.Xr signify 1 256.Fl zS 257.Xr gzip 1 258header signatures are the only supported format. 259This allows for 260.Sq just-in-time 261signature checking, as the binary data is checked in 64K bytes long chunks. 262.Sh SEE ALSO 263.Xr pkg_add 1 , 264.Xr pkg_create 1 , 265.Xr pkg_info 1 , 266.Xr pkg_sign 1 , 267.Xr packages 7 , 268.Xr packages-specs 7 269.Sh STANDARDS 270Packages are valid gzip'ed ustar archives that can be extracted using 271.Xr tar 1 . 272In particular, hardlink names should be valid, and all items will 273extract to different names. 274However, it may be a bit difficult to make sense of the package contents 275without peeking at the packing-list. 276