You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

308 lines
8.4 KiB

  1. .\"
  2. .\" FreeBSD pkg - a next generation package for the installation and
  3. .\" maintenance of non-core utilities.
  4. .\"
  5. .\" Redistribution and use in source and binary forms, with or without
  6. .\" modification, are permitted provided that the following conditions
  7. .\" are met:
  8. .\" 1. Redistributions of source code must retain the above copyright
  9. .\" notice, this list of conditions and the following disclaimer.
  10. .\" 2. Redistributions in binary form must reproduce the above copyright
  11. .\" notice, this list of conditions and the following disclaimer in the
  12. .\" documentation and/or other materials provided with the distribution.
  13. .\"
  14. .\"
  15. .\" @(#)pkg-repository.5
  16. .\" $FreeBSD$
  17. .\"
  18. .Dd November 18, 2014
  19. .Dt PKG-REPOSITORY 5
  20. .Os
  21. .Sh NAME
  22. .Nm "package repository"
  23. .Nd format and operation of package repositories used by
  24. .Xr pkg 8 .
  25. .Sh DESCRIPTION
  26. .Nm "Package repositories"
  27. used by the
  28. .Xr pkg 8
  29. program consist of one or more collections of
  30. .Dq package tarballs
  31. together with package catalogues and optionally various other
  32. collected package metadata.
  33. .Pp
  34. Each collection consists of packages suitable for installation on a
  35. specific system
  36. .Sy ABI :
  37. a combination of operating system, CPU architecture, OS version, word
  38. size, and for certain processors endianness or similar attributes.
  39. .Pp
  40. The package collections are typically made available to users for
  41. download via a web or FTP server although various other means of access
  42. may be employed.
  43. Encoding the
  44. .Sy ABI
  45. value into the repository URL allows
  46. .Nm pkg
  47. to automatically select the correct package collection by expanding the
  48. special token
  49. .Cm ${ABI}
  50. in
  51. .Pa pkg.conf .
  52. .Pp
  53. Repositories may be mirrored over several sites:
  54. .Nm pkg
  55. has built-in support for discovering available mirrors dynamically
  56. given a common URL by several mechanisms.
  57. .Sh FILESYSTEM ORGANIZATION
  58. Only very minimal constraints on repository layout are prescribed by
  59. .Nm pkg .
  60. The following constraints are all that must be met:
  61. .Bl -bullet
  62. .It
  63. A repository may contain several package collections with parallel
  64. .Cm REPOSITORY_ROOTs
  65. in order to support diverse system
  66. .Cm ABIs .
  67. .It
  68. All of the content for one
  69. .Sy ABI
  70. should be accessible in a filesystem or URL hierarchy beneath the
  71. .Cm REPOSITORY_ROOT .
  72. .It
  73. All packages available beneath one
  74. .Cm REPOSITORY_ROOT
  75. should be binary compatible with a specific system
  76. .Cm ABI .
  77. .It
  78. The repository catalogue is located at the apex of the
  79. repository, at a specific location relative to the
  80. .Cm REPOSITORY_ROOT .
  81. .El
  82. .Pp
  83. Package catalogues contain the paths relative to the
  84. .Cm REPOSITORY_ROOT
  85. for each package, allowing the full URL for downloading the
  86. package to be constructed.
  87. .Pp
  88. Where a package may be applicable to more than one
  89. .Sy ABI
  90. (e.g., it contains only text files) symbolic or hard links, URL mappings
  91. or other techniques may be utilised to avoid duplication of storage.
  92. .Pp
  93. Although no specific filesystem organization is required, the usual
  94. convention (inherited from
  95. .Xr pkg-install 8 )
  96. is to create a filesystem hierarchy thus:
  97. .Bl -tag -width "REPOSITORY"
  98. .It Pa $REPOSITORY_ROOT/All
  99. One directory that contains every package available from the
  100. repository for that
  101. .Sy ABI .
  102. Packages are stored as package tarballs identified by name and
  103. version.
  104. This directory may contain several different versions of each package
  105. accumulated over time, but the repository catalogue will only record
  106. the latest version for each distinct package origin.
  107. .It Pa $REPOSITORY_ROOT/Latest/
  108. May contains symbolic links to the latest versions of packages in the
  109. .Pa All
  110. directory.
  111. Symbolic links contain a
  112. .Sq latest link
  113. style name only, without version.
  114. As the whole
  115. .Sq latest link
  116. concept is rendered obsolete by
  117. .Nm pkg ,
  118. this will usually contain only the
  119. .Pa pkg.txz
  120. link, used for bootstrapping
  121. .Nm pkg
  122. itself on a new system.
  123. .It Pa $REPOSITORY_ROOT/digests.txz
  124. Package checksum data and optionally package signatures.
  125. .It Pa $REPOSITORY_ROOT/packagesite.txz
  126. Contains one
  127. .Cm YAML
  128. document, which is the concatenation of the
  129. .Pa +MANIFEST
  130. files from each of the packages in the repository.
  131. This is used by
  132. .Nm pkg-1.1
  133. or later.
  134. .It Pa $REPOSITORY_ROOT/repo.txz
  135. (Deprecated).
  136. Contains the package manifest data as above, but pre-loaded into
  137. an SQLite database.
  138. This is supplied for backwards compatibility with
  139. .Nm pkg-1.0 .
  140. .It Pa $REPOSITORY_ROOT/filesite.txz
  141. (Optional).
  142. Contains a YAML document listing all of the files contained in all
  143. of the packages within the repository.
  144. .Pp
  145. The repository may optionally contain sub-directories corresponding to
  146. the package origins within the
  147. .Os
  148. ports tree.
  149. .El
  150. .Pp
  151. Each of the packages listed in the repository catalogue must have a
  152. unique
  153. .Cm origin .
  154. There are no other constraints: package sets are not required to be
  155. either complete (i.e., with all dependencies satisfied) or
  156. self-consistent within a single repository.
  157. .Sh REPOSITORY ACCESS METHODS
  158. .Nm pkg
  159. uses standard network protocols for repository access.
  160. Any URL scheme understood by the
  161. .Xr fetch 3
  162. library may be used
  163. .Cm ( HTTP ,
  164. .Cm HTTPS ,
  165. .Cm FTP
  166. or
  167. .Cm FILE )
  168. as well as remote access over
  169. .Cm SSH .
  170. See
  171. .Xr fetch 3
  172. for a description of additional environment variables, including
  173. .Ev FETCH_BIND_ADDRESS ,
  174. .Ev FTP_LOGIN ,
  175. .Ev FTP_PASSIVE_MODE ,
  176. .Ev FTP_PASSWORD ,
  177. .Ev FTP_PROXY ,
  178. .Ev ftp_proxy ,
  179. .Ev HTTP_AUTH ,
  180. .Ev HTTP_PROXY ,
  181. .Ev http_proxy ,
  182. .Ev HTTP_PROXY_AUTH ,
  183. .Ev HTTP_REFERER ,
  184. .Ev HTTP_USER_AGENT ,
  185. .Ev NETRC ,
  186. .Ev NO_PROXY No and
  187. .Ev no_proxy .
  188. .Sh REPOSITORY MIRRORING
  189. Multiple copies of a repository can be provided for resilience or
  190. to scale up site capacity.
  191. Two schemes are provided to auto-discover sets of mirrors given a
  192. single repository URL.
  193. .Bl -tag -width "HTTP"
  194. .It Cm HTTP
  195. The repository URL should download a text document containing a sequence
  196. of lines beginning with
  197. .Sq URL:
  198. followed by any amount of while space and one URL for a repository
  199. mirror.
  200. Any lines not matching this pattern are ignored.
  201. Mirrors are tried in the order listed until a download succeeds.
  202. .It Cm SRV
  203. For an SRV mirrored repository where the URL is specified as
  204. .Pa http://pkgrepo.example.org/
  205. .Cm SRV
  206. records should be set up in the DNS:
  207. .Bd -literal -offset indent
  208. $ORIGIN example.com
  209. _http._tcp.pkgrepo IN SRV 10 1 80 mirror0
  210. IN SRV 20 1 80 mirror1
  211. .Ed
  212. .Pp
  213. where the
  214. .Cm SRV
  215. priority and weight parameters are used to control search order and
  216. traffic weighting between sites, and the port number and hostname are
  217. used to construct the individual mirror URLs.
  218. .El
  219. .Pp
  220. Mirrored repositories are assumed to have identical content, and only
  221. one copy of the repository catalogue will be downloaded to apply to
  222. all mirror sites.
  223. .Sh WORKING WITH MULTIPLE REPOSITORIES
  224. Where several different repositories are configured
  225. .Nm pkg
  226. will search amongst them all in the order specified,
  227. unless directed to use a single repository by the
  228. .Fl r
  229. flag to
  230. .Xr pkg-fetch 8 ,
  231. .Xr pkg-install 8 ,
  232. .Xr pkg-upgrade 8 ,
  233. .Xr pkg-search 8
  234. or
  235. .Xr pkg-rquery 8 .
  236. The search order is as displayed in the output of
  237. .Bd -literal -offset indent
  238. pkg -v -v
  239. .Ed
  240. .Pp
  241. Where several different versions of the same package are available,
  242. .Nm pkg
  243. will select the one with the highest version to install or to upgrade
  244. an installed package to, even if a lower numbered version can be found
  245. in a repository earlier in the list.
  246. This applies even if an explicit version is stated on the command line.
  247. Thus if packages
  248. .Pa example-1.0.0
  249. and
  250. .Pa example-1.0.1
  251. are available in configured repositories, then
  252. .Bd -literal -offset indent
  253. pkg install example-1.0.0
  254. .Ed
  255. .Pp
  256. will actually result in
  257. .Pa example-1.0.1
  258. being installed.
  259. To override this behaviour, on first installation of the package
  260. select the repository with the appropriate version:
  261. .Bd -literal -offset indent
  262. pkg install -r repo-a example-1.0.0
  263. .Ed
  264. .Pp
  265. and then to make updates to that package
  266. .Dq sticky
  267. to the same repository, add an annotation to the package:
  268. .Bd -literal -offset indent
  269. pkg annotate -A example repository repo-a
  270. .Ed
  271. .Pp
  272. .Sh SEE ALSO
  273. .Xr fetch 3 ,
  274. .Xr pkg_printf 3 ,
  275. .Xr pkg_repos 3 ,
  276. .Xr pkg.conf 5 ,
  277. .Xr pkg 8 ,
  278. .Xr pkg-add 8 ,
  279. .Xr pkg-annotate 8 ,
  280. .Xr pkg-audit 8 ,
  281. .Xr pkg-autoremove 8 ,
  282. .Xr pkg-backup 8 ,
  283. .Xr pkg-check 8 ,
  284. .Xr pkg-clean 8 ,
  285. .Xr pkg-config 8 ,
  286. .Xr pkg-convert 8 ,
  287. .Xr pkg-create 8 ,
  288. .Xr pkg-delete 8 ,
  289. .Xr pkg-fetch 8 ,
  290. .Xr pkg-info 8 ,
  291. .Xr pkg-install 8 ,
  292. .Xr pkg-lock 8 ,
  293. .Xr pkg-query 8 ,
  294. .Xr pkg-register 8 ,
  295. .Xr pkg-repo 8 ,
  296. .Xr pkg-rquery 8 ,
  297. .Xr pkg-search 8 ,
  298. .Xr pkg-set 8 ,
  299. .Xr pkg-shell 8 ,
  300. .Xr pkg-shlib 8 ,
  301. .Xr pkg-ssh 8 ,
  302. .Xr pkg-stats 8 ,
  303. .Xr pkg-update 8 ,
  304. .Xr pkg-updating 8 ,
  305. .Xr pkg-upgrade 8 ,
  306. .Xr pkg-version 8 ,
  307. .Xr pkg-which 8