1.\" $OpenBSD: package.5,v 1.12 2011/09/29 17:57:09 jmc 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 29 2011 $ 16.Dt PACKAGE 5 17.Os 18.Sh NAME 19.Nm package 20.Nd format for 21.Ox 22binary packages 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 baseXXX.tgz , 49.Pa compXXX.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 . 60This table of contents can be read using the API described in 61.Xr OpenBSD::PackingList 3p . 62.Pp 63All the remaining information in the archive should be referenced in 64the packing-list, including all relevant information: symlinks destinations, 65special permissions, and file owners. 66See 67.Xr pkg_create 1 68for annotation details. 69.Pp 70This table of contents is always followed by a few special files, some of 71which are optional: the package description (+DESC), 72a display message (+DISPLAY), etc. 73.Pp 74The ustar format has some limitations with respect to file names. 75Accordingly, the package tools will replace very long names with 76.Pa LongName#n 77and long link names with 78.Pa LongLink#n . 79The packing-list will hold the real file names, and the package tools 80will reconstitute the correct names behind the scenes. 81.Sh PACKAGE SIGNATURES 82All information within a package is checksummed, using SHA256 since 83.Ox 4.4 . 84During creation and installation, meta-information, such as file owners and 85permissions, are also checked: any important stuff that isn't recorded 86in the packing-list is an error. 87.Pp 88Packing-lists can be signed. 89If a signature is found, then it will be checked 90during installation, and failure to verify will prevent the package from 91installing correctly. 92Currently, only X.509-style signatures are supported. 93They rely on a certificate authority file being present as 94.Pa /etc/ssl/pkgca.pem 95and all signatures will be checked against it. 96Once the packing-list signature is checked, all individual packing elements 97will be checksummed, resulting in a 98.Sq just-in-time 99signature checking. 100.Pp 101Fat packages were removed in 102.Ox 5.1 , 103since no practical application was found. 104.Sh SEE ALSO 105.Xr pkg_add 1 , 106.Xr pkg_create 1 , 107.Xr pkg_info 1 , 108.Xr packages 7 , 109.Xr packages-specs 7 110.Sh STANDARDS 111Packages are valid gzip'ed ustar archives that can be extracted using 112.Xr tar 1 . 113In particular, hardlink names should be valid, and all items will 114extract to different names. 115However, it may be a bit difficult to make sense of the package contents 116without peeking at the packing-list. 117