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.
 
 
 
 

226 lines
5.8 KiB

  1. .\"
  2. .\" FreeBSD pkg - a next generation package for the installation and maintenance
  3. .\" 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.8
  16. .\" $FreeBSD$
  17. .\"
  18. .Dd November 18, 2014
  19. .Dt PKG-REPO 8
  20. .Os
  21. .Sh NAME
  22. .Nm "pkg repo"
  23. .Nd create a package repository catalogue
  24. .Sh SYNOPSIS
  25. .Nm
  26. .Op Fl lqL
  27. .Op Fl o Ar output-dir
  28. .Op Fl m Ar meta-file
  29. .Ao Ar repo-path Ac Op Ao Ar rsa-key Ac | signing_command: Ao Ar the command Ac
  30. .Pp
  31. .Nm
  32. .Op Cm --{list-files,quiet,legacy}
  33. .Op Cm --output-dir Ar output-dir
  34. .Op Cm --meta-file Ar meta-file
  35. .Ao Ar repo-path Ac Op Ao Ar rsa-key Ac | signing_command: Ao Ar the command Ac
  36. .Sh DESCRIPTION
  37. .Nm
  38. is used for creating a catalogue of the available
  39. packages in a repository.
  40. .Nm
  41. catalogues are necessary for sharing your package repository with
  42. other people.
  43. .Pp
  44. When
  45. .Nm
  46. is invoked it creates a package repository catalogue (repo.sqlite),
  47. with an optional cryptographic signature, as a compressed tarball
  48. (repo.txz).
  49. Repository users download and cache this on their local machines,
  50. for fast lookup of available packages by programs such as
  51. .Xr pkg-install 8 .
  52. .Pp
  53. To create a package repository catalogue you must specify the
  54. top-level directory where all the packages are stored as
  55. .Ar repo-path .
  56. .Nm
  57. will search the filesystem beneath
  58. .Ar repo-path
  59. to find all the packages it contains.
  60. Symbolic links are ignored.
  61. .Pp
  62. The repository will be created in the package directory unless the
  63. .Fl o Ar output-dir
  64. or
  65. .Cm --output-dir Ar output-dir
  66. is specified, in which case it will be created there.
  67. .Pp
  68. Optionally you may sign the repository catalogue by specifying the
  69. path to an RSA private key as the
  70. .Ar rsa-key
  71. argument or an external command.
  72. .Pp
  73. If
  74. .Ar rsa-key
  75. is used, the SHA256 of the repository is signed using the provided key.
  76. The signature is added into the repository catalogue.
  77. The client side should use
  78. .Sy SIGNATURE_TYPE
  79. set to
  80. .Dv PUBKEY
  81. and
  82. .Sy PUBKEY
  83. set to a local path of the public key in its repository configuration file.
  84. .Pp
  85. An external command can be useful to create a signing server to keep the
  86. private key separate from the repository.
  87. The external command is passed the SHA256 of the repository
  88. catalogue on its stdin.
  89. It should output the following format:
  90. .Bd -literal -offset indent
  91. SIGNATURE
  92. signature data here
  93. CERT
  94. public key data here
  95. END
  96. .Ed
  97. .Pp
  98. When using an external command, the client's
  99. .Pa pkg.conf
  100. must have
  101. .Sy SIGNATURE_TYPE
  102. set to
  103. .Dv FINGERPRINTS
  104. and
  105. .Sy FINGERPRINTS
  106. set to a directory having a
  107. .Pa trusted/myrepo
  108. containing a fingerprint style representation of the public key:
  109. .Bd -literal -offset indent
  110. function: sha256
  111. fingerprint: sha256_representation_of_the_public_key
  112. .Ed
  113. .Pp
  114. See the
  115. .Sx EXAMPLES
  116. section and
  117. .Xr pkg.conf 5
  118. for more information.
  119. .Pp
  120. Signing the catalogue is strongly recommended.
  121. .Sh OPTIONS
  122. The following options are supported by
  123. .Nm :
  124. .Bl -tag -width quiet
  125. .It Fl q , Cm --quiet
  126. Force quiet output.
  127. .It Fl L , Cm --legacy
  128. Create repository compatible with pkg 1.2.
  129. .It Fl m Ar meta-file , Cm --meta-file Ar meta-file
  130. Use the specified file as repository meta file instead of the default settings.
  131. .It Fl l , Cm --list-files
  132. Generate list of all files in repo as filesite.txz archive.
  133. .It Fl o Ar output-dir , Cm --output-dir Ar output-dir
  134. Create the repository in the specified directory instead of the package directory.
  135. .El
  136. .Sh FILES
  137. See
  138. .Xr pkg.conf 5 .
  139. .Sh SEE ALSO
  140. .Xr pkg_printf 3 ,
  141. .Xr pkg_repos 3 ,
  142. .Xr pkg-repository 5 ,
  143. .Xr pkg.conf 5 ,
  144. .Xr pkg 8 ,
  145. .Xr pkg-add 8 ,
  146. .Xr pkg-annotate 8 ,
  147. .Xr pkg-audit 8 ,
  148. .Xr pkg-autoremove 8 ,
  149. .Xr pkg-backup 8 ,
  150. .Xr pkg-check 8 ,
  151. .Xr pkg-clean 8 ,
  152. .Xr pkg-config 8 ,
  153. .Xr pkg-convert 8 ,
  154. .Xr pkg-create 8 ,
  155. .Xr pkg-delete 8 ,
  156. .Xr pkg-fetch 8 ,
  157. .Xr pkg-info 8 ,
  158. .Xr pkg-install 8 ,
  159. .Xr pkg-lock 8 ,
  160. .Xr pkg-query 8 ,
  161. .Xr pkg-register 8 ,
  162. .Xr pkg-rquery 8 ,
  163. .Xr pkg-search 8 ,
  164. .Xr pkg-set 8 ,
  165. .Xr pkg-shell 8 ,
  166. .Xr pkg-shlib 8 ,
  167. .Xr pkg-ssh 8 ,
  168. .Xr pkg-stats 8 ,
  169. .Xr pkg-update 8 ,
  170. .Xr pkg-updating 8 ,
  171. .Xr pkg-upgrade 8 ,
  172. .Xr pkg-version 8 ,
  173. .Xr pkg-which 8
  174. .Sh EXAMPLES
  175. Create an RSA key pair:
  176. .Bd -literal -offset indent
  177. % openssl genrsa -out repo.key 2048
  178. % chmod 0400 repo.key
  179. % openssl rsa -in repo.key -out repo.pub -pubout
  180. .Ed
  181. .Pp
  182. Create a repository and sign it with a local RSA key.
  183. The public key would be shared on all client servers with
  184. .Sy SIGNATURE_TYPE
  185. set to
  186. .Dv PUBKEY
  187. and its path set via
  188. .Sy PUBKEY
  189. setting in the repository configuration file:
  190. .Pp
  191. .Dl pkg repo /usr/ports/packages repo.key
  192. .Pp
  193. Create a repository and sign it with an external command.
  194. The client should set, via the repository configuration file,
  195. .Sy SIGNATURE_TYPE
  196. to
  197. .Dv FINGERPRINTS
  198. and
  199. .Sy FINGERPRINTS
  200. to a path containing a file with the SHA256 of the public key:
  201. .Bd -literal -offset indent
  202. # On signing server:
  203. % cat > sign.sh << EOF
  204. #!/bin/sh
  205. read -t 2 sum
  206. [ -z "$sum" ] && exit 1
  207. echo SIGNATURE
  208. echo -n $sum | /usr/bin/openssl dgst -sign repo.key -sha256 -binary
  209. echo
  210. echo CERT
  211. cat repo.pub
  212. echo END
  213. EOF
  214. # On package server:
  215. % pkg repo /usr/ports/packages signing_command: ssh signing-server sign.sh
  216. # Generate fingerprint for sharing with clients
  217. % sh -c '( echo "function: sha256"; echo "fingerprint: $(sha256 -q repo.pub)"; ) > fingerprint'
  218. # The 'fingerprint' file should be distributed to all clients.
  219. # On clients with FINGERPRINTS: /usr/local/etc/pkg/fingerprints/myrepo:
  220. $ mkdir -p /usr/local/etc/pkg/fingerprints/myrepo/trusted
  221. # Add 'fingerprint' into /usr/local/etc/pkg/fingerprints/myrepo/trusted
  222. .Ed