1.\" $OpenBSD: package.5,v 1.33 2023/11/29 14:32:01 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: November 29 2023 $ 16.Dt PACKAGE 5 17.Os 18.Sh NAME 19.Nm package , 20.Nm packing-list , 21.Nm plist 22.Nd format for OpenBSD binary packages and packing-lists 23.Sh DESCRIPTION 24Binary packages for 25.Ox 26can be created using 27.Xr pkg_create 1 28and are usually manipulated using 29.Xr pkg_add 1 , 30.Xr pkg_mklocatedb 1 , 31or 32.Xr pkg_info 1 . 33.Pp 34The basic underlying format is an archive following the ustar specification 35that can be handled with 36.Xr tar 1 37and compressed using 38.Xr gzip 1 . 39.Pp 40Package names always end in 41.Dq .tgz ; 42the file name itself should conform to 43.Xr packages-specs 7 . 44.Pp 45Note that the base distribution tarballs of 46.Ox 47(e.g.\& 48.Pa baseXX.tgz , 49.Pa compXX.tgz , 50\&...) are not binary packages fit for 51.Xr pkg_add 1 . 52.Pp 53All types of archive contents can be present in a package, 54including files, directories, hardlinks, symlinks, fifos, block and character 55devices. 56.Pp 57In order to allow just-in-time extraction, 58packages always begin with a table of contents, named 59.Pa +CONTENTS , 60nicknamed 61.Nm packing-list 62.Po 63.Nm plist 64for short 65.Pc . 66This table of contents can be read using the API described in 67.Xr OpenBSD::PackingList 3p . 68.Pp 69All the remaining information in the archive should be referenced in the 70.Nm packing-list , 71including symlinks destinations, 72special permissions, and file owners 73.Po 74.Xr pkg_create 1 75and 76.Xr pkg_add 1 77actually enforce this 78.Pc . 79See 80.Xr pkg_create 1 81for annotation details. 82.Pp 83This table of contents is always followed by a few special files, some of 84which are optional: the package description (+DESC), 85a display message (+DISPLAY), etc. 86.Pp 87The basic ustar format has some limitations with respect to file names. 88Packages now use the 89.Qq extended record specification 90(header type x) 91for long links and long file names. 92Other extended ustar headers are currently recognized, but not supported. 93.Pp 94Starting with 95.Ox 5.5 , 96the compressed archive may be composed of several 97.Xr gzip 1 98archives concatenated together. 99.Xr gzip 1 100doesn't mind, and 101.Xr tar 1 102is happy as long as the uncompressed stream is sane. 103This allows for faster signing and better rsync properties. 104.Pp 105Starting with 106.Ox 5.6 , 107tarballs are stored 108.Qq out-of-order : 109each archive entry will match an entry in the 110.Nm packing-list 111(and all file-like entries will be matched), but the order will be adjusted 112so that most recently changed files come first, in order to allow 113faster updates. 114.Pp 115Starting with 116.Ox 5.7 , 117by default, timestamps are stored directly in the 118.Nm packing-list 119as 120.Cm @ts 121annotations. 122The files in the archive will have a null timestamp. 123.Pp 124The combination of the LRU archive order, null timestamps and compression 125in fixed chunks starting from the end, means a substantial amount of data 126doesn't change from snapshot to snapshot, thus reducing the pressure on 127mirroring bandwidth. 128.Sh PACKING LIST ANNOTATIONS 129User annotations are described in 130.Xr pkg_create 1 . 131The following annotations are automatically inserted during package creation 132and installation: 133.Pp 134.Bl -tag -width Ds -compact 135.It Cm @arch Ar arches 136List of architectures for which this package is intended. 137This corresponds to 138.Fl A Ar arches 139of 140.Xr pkg_create 1 141.Pp 142.It Cm @comment pkgpath=path ftp=yes/no 143Historical accident. 144This specific comment encodes the actual 145.Fl D Ar FULLPKGPATH , 146and 147.Fl D Ar FTP 148arguments to 149.Xr pkg_create 1 . 150.Pp 151.It Xo 152.Cm @depend 153.Sm off 154.Ar pkgpath : 155.Ar pkgspec : 156.Ar default 157.Sm on 158.Xc 159Record a dependency declared using the option 160.Fl P 161of 162.Xr pkg_create 1 . 163.Pp 164.It Xo 165.Cm @digital-signature 166.Sm off 167.Ar signify2 : 168.Ar date : 169.Ar external 170.Sm on 171.Xc 172Record the date of signature of a package, synthesized by 173.Xr pkg_add 1 174from 175.Xr signify 1 176output. 177.Pp 178.It Cm @link Ar name 179Added after a file entry by 180.Nm 181to record that the entry is actually a hard link. 182.Pp 183.It Cm @localbase Ar base 184Used internally to record the settings of 185.Fl L 186option. 187.Pp 188.It Cm @name Ar pkgname 189Set the name of the package. 190This name is potentially different than the name of 191the file it came in, and is used when keeping track of the package 192for later deinstallation. 193.Xr pkg_create 1 194will derive this field from the package file name. 195.Pp 196.It Cm @option Ar name 197Some options are automatically inserted/modified by the package tools: 198.Bl -tag -width indent 199.It Ar always-update 200.Xr pkg_create 1 201will complete the option line with a sha256 digest of the whole 202.Nm packing-list 203encoded in base64. 204.It Ar firmware 205Set by 206.Xr fw_update 8 207to trigger firmware-specific handling. 208In particular, firmware is hidden from normal updates. 209.It Ar manual-installation 210Record that a package has been explicitly installed by the user, 211and not as a result of a dependency look-up. 212Refer to 213.Xr pkg_add 1 Ns 's 214.Fl a 215option for details. 216.El 217.Pp 218.It Cm @sha 219Added after a file entry by 220.Xr pkg_create 1 221to record the files's cryptographic checksum, 222as a sha256 digest encoded in base64. 223.Pp 224.It Cm @signer 225Record the signing key for a package, synthesized by 226.Xr pkg_add 1 227from 228.Xr signify 1 229output. 230.Pp 231.It Cm @size 232Added after a file entry by 233.Xr pkg_create 1 234to record a file size. 235.Pp 236.It Cm @symlink Ar name 237Added after a file entry by 238.Xr pkg_create 1 239to record that the entry is actually a symbolic link. 240.Pp 241.It Cm @url 242Original location of the package, synthesized by 243.Xr pkg_add 1 244during installation. 245.Pp 246.It Cm @ts Ar timestamp 247Added after a file entry to record the actual file timestamp, instead 248of storing it as tarball meta-info. 249The package tools read and process that annotation correctly, whereas 250.Xr tar 1 251will only see files dated from the epoch. 252.Pp 253.It Cm @version Ar number 254Record a global (system) version number for the package. 255This is built adding together 256.Fl V 257options from 258.Xr pkg_create 1 , 259and triggers updates when it changes. 260.Pp 261.It Cm @wantlib Ar libspec 262Record a library requirement declared using the option 263.Fl W 264of 265.Xr pkg_create 1 . 266.El 267.Pp 268Note that most of these annotations cannot be added manually, as 269.Xr pkg_create 1 270will error out. 271.Sh PACKAGE SIGNATURES 272All information within a package is checksummed, using SHA256 since 273.Ox 4.4 . 274During creation and installation, meta-information, such as file owners and 275permissions, are also checked: any important stuff that isn't recorded 276in the 277.Nm packing-list 278is an error. 279.Pp 280Starting with 281.Ox 6.1 , 282.Xr signify 1 283.Fl zS 284.Xr gzip 1 285header signatures are the only supported format. 286This allows for 287.Sq just-in-time 288signature checking, as the binary data is checked in 64K bytes long chunks. 289.Sh SEE ALSO 290.Xr pkg_add 1 , 291.Xr pkg_create 1 , 292.Xr pkg_info 1 , 293.Xr pkg_sign 1 , 294.Xr packages 7 , 295.Xr packages-specs 7 296.Sh STANDARDS 297Packages are valid gzip'ed ustar archives that can be extracted using 298.Xr tar 1 . 299In particular, hardlink names should be valid, and all items will 300extract to different names. 301However, it may be a bit difficult to make sense of the package contents 302without peeking at the 303.Nm packing-list . 304